- 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.
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 withsave_buyer_agent, without an
id:
idempotencyKeyis required. Send a new UUID for each agent. If the call is retried with the same key and the samedisplayName, it returns the agent the first call created, as it is now, instead of a second agent. The same key with a differentdisplayNameis refused withCONFLICT.- The new agent has
accountId: nullandhosting: "on_demand". - It has no advertiser access yet. Give it access across your accounts with
save_buyer_agentandaccess, 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.
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_agentwithlifecycleState: "retired"is refused withVALIDATION_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_agentwithaccessis refused withVALIDATION_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 anidalways 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_requiredresult 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.
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.