Skip to main content
A hosted buyer agent is a buyer agent Apostra runs for you. There are two kinds:
  • An account’s own agent. Each Buyer account has one agent of its own. It belongs to that account, and it is the account’s assistant in Apostra.
  • A hosted orchestrator. An agent your organization creates that belongs to no account. It works across your organization’s accounts through the advertiser access you give it.
An external buyer agent, one you run yourself and connect to Apostra, is neither. Both kinds are buyer_agent objects, read with search and get and changed with save_buyer_agent, the same as an external agent.
Hosted buyer agents are in beta and are switched on per organization, together with chatting with your buyer agent. Until they are on for your account, buyer_agent reads leave out accountId and hosting, get_status leaves out agent, and save_buyer_agent refuses to create a hosted agent. Ask your Apostra contact to turn them on.
While the beta is on for your organization, Apostra creates each of its Buyer accounts’ own agent, named Prime, when the beta is turned on. It runs on demand, and it is not charged while it is in beta. Until an account has its agent, get_status returns agent: null and says the account has no agent yet.If the beta is turned off, the agent stops working and is kept, with its conversations and settings. It works again when the beta is turned back on.

Reading how an agent runs and who it belongs to

get(kind: "buyer_agent") and search(kind: "buyer_agent") return two fields on each agent: hosting is the customer’s choice of how the agent’s time is paid for. On demand, the default, is charged by the hours the agent spends on work it was asked to do. Always on is a flat daily rate in place of those hours. Apostra never moves an agent between the two by itself. Choosing always on is not available yet, so every hosted agent reads on_demand, and agent work is not metered yet.

Finding a Buyer account’s own agent

In a Buyer account, get_status returns agent, a pointer to the account’s own agent, so you find it in one call without a search: While the account has no agent yet, agent is null, never an empty object, and the status text says why. If Apostra cannot read the agent at that moment, agent is left out and the text says so; call get_status again, or search(kind: "buyer_agent").

Creating a hosted orchestrator

An organization administrator creates one with save_buyer_agent, without an id:
  • idempotencyKey is required. Send a new UUID for each agent. If the call is retried with the same key and the same displayName, it returns the agent the first call created, as it is now, instead of a second agent. The same key with a different displayName is refused with CONFLICT.
  • The new agent has accountId: null and hosting: "on_demand".
  • It has no advertiser access yet. Give it access across your accounts with save_buyer_agent and access, as for any buyer agent.
  • Apostra starts the agent’s runtime separately. Until its runtime is running, the agent cannot take messages; the chat says so.
Only a directly signed-in organization administrator may create one, because it changes your bill. Creating a hosted agent in an Agents account is not available: connect a buyer agent you run yourself instead. idempotencyKey is only for hosted creation; an external create that sends one is refused.

What you cannot change on an account’s own agent

An account’s own agent exists because its account does:
  • It is retired with its account. save_buyer_agent with lifecycleState: "retired" is refused with VALIDATION_ERROR. Suspend it instead (lifecycleState: "suspended"): that switches it off without removing it, so it stops working until you resume it.
  • Its access is the account’s advertisers. Apostra keeps it to every advertiser in the account, with read and write access, so save_buyer_agent with access is refused with VALIDATION_ERROR. In its own account it needs no advertiser selected: each call is checked against the advertiser it touches. In any conversation it can still do only what the person talking to it may do, so an advertiser that person cannot reach is refused, and scheduled and event runs that nobody is watching only read.
  • kind: "hosted" without an id always creates an orchestrator, never an account’s own agent.

Sensitive actions wait for the person

An account’s own agent acts for the person talking to it, but it is never that person. When it asks for something that grants or removes access, commits money or binds your organization, the person approves it themselves on Apostra, in their own browser, and nothing changes until they do:
  • Changes that have an approval are recorded and the agent gets an approval_required result with a link, as any client does: choosing a plan, payment terms, the plan’s renewal, removing a card, paying a failed payment now and setting up payment authority. The request records the person and the agent that asked. The agent’s own credential cannot approve it.
  • Changes that have no approval yet are refused with ACCESS_DENIED, even where the person could make them directly: accepting the Terms of Service, payer details and media billing entities, creating or managing buyer agents and their credentials, revoking claimed agents, inviting people to an advertiser, advertiser grants and changing a Session’s participants. The person makes these themselves in Apostra.
Scheduled and event runs that nobody is watching never ask for an approval.

When Apostra staff post in a conversation with your agent

To help with a conversation you started with your account’s agent, an Apostra staff member may post a message into it. Their message appears in the conversation under their own name, and your agent answers it there, so you see both the next time you open the conversation.
  • Your agent only reads on that turn. It answers as your account’s agent for the person who started the conversation, and it can look things up but changes nothing, as on a scheduled or event run. Any change still needs you.
  • Only Apostra staff can post this way, and only when signed in as themselves.
  • Staff can stop the turn they started. The conversation then shows that the answer was stopped, as when you stop a turn yourself.
  • Every message is recorded. Apostra records which staff member posted, to which conversation, and when.