You can also run a second brain in shadow mode. A shadow brain gets the same
requests under the same rules, and its proposals are checked and recorded, but
never shown to a buyer. Use it to see how another brain would have answered your
real briefs before you switch. Shadow brains run at no charge during the beta.
Choosing a brain is in beta. If
get(kind: "seller") returns no
proposalAgent, your account is not on the beta.Who can change it
Only a direct administrator of your organization, signed in as themselves, can choose the brain. A call from any agent, including your own, or from a staff member impersonating someone, is refused: who answers your buyers is your decision. The account must sell as a Storefront. A Listing has no brain to choose, because Apostra does not answer its buyers’ proposal requests (see Change a Seller Account’s type).Read the setting
get(kind: "seller") returns proposalAgent:
Change it
Send the whole setting withsave_seller, on its own, with the updatedAt you
read:
expectedUpdatedAtis required. Send theupdatedAtyou read, ornullwhile the setting was never saved. If someone saved a change since you read it, the call is refused withCONFLICTand names the setting now in force, so two administrators never overwrite each other.shadowmust differ fromanswering.ownAgentIdis required whenansweringorshadowisown, and must benullotherwise. It must be a proposal agent your organization connected and verified as its own. See Connect your own proposal agent.- Prime and your own proposal agent are not open to sellers yet, as
answeringorshadow. They open when the choice of brain launches to sellers. Until thenprimeandownare refused withFEATURE_NOT_ENABLEDandreason: "own_proposal_agent_unavailable", and only Apostra’s own accounts can choose either or register a proposal agent. - Saving the setting already in force changes nothing.
When your own agent answers
When your setting names your own proposal agent, Apostra sends each newrequest_proposals call for your storefront to the agent’s endpoint, signed as
Apostra (see
How your agent knows a request is from Apostra).
Apostra calls it only while it is still a verified proposal agent of your
organization; otherwise Chef answers.
Your agent has about 85 seconds to answer. If it does not answer in time,
answers with an error, or answers submitted, Chef answers instead, in the
rest of the buyer’s two-minute window. A buyer always gets an answer. Answering
submitted and delivering later is not supported yet.
Apostra checks the answer before the buyer sees anything. The answer must
validate against the AdCP schema and be proposed or rejected, or Chef
answers. Then each proposal must pass five checks, and one that fails is
withheld:
If every proposal is withheld, Chef answers.
Your agent plans only for an account the buyer holds. Before your agent
is called, Apostra checks that the buyer holds the account its request names,
as it does for Chef, and that any brand the request names is that account’s
own. A request for an account the buyer does not hold, or for another
advertiser’s brand, is refused, and your agent never sees it. Your agent
receives the account by its id and the brand the proposal is for.
The buyer sees your storefront, not your agent. The products in the answer
are your storefront’s own, from its catalog, and each proposal gets a proposal
id your storefront assigns. Each purchase is priced at the pricing option it
names, as your catalog publishes it. Your agent’s own products, ids,
extensions (
ext) and messages are left out, so nothing in the answer names or
reveals your agent. For now none of your agent’s own words reach the buyer
either: each proposal’s name comes from your catalog’s product names, its
description and brief_alignment are left out, and a rejected answer
reaches the buyer as the storefront’s standard decline, not your agent’s
reason and suggestions. Your agent’s text will reach buyers once Apostra
screens it.
Every call is on your decision record. An answer the buyer got, a brief your
agent declined, a proposal withheld (with the check that withheld it, such as
grounding_failed or pricing_currency_mismatch) and a call that missed its time (deadline_missed) are
each a decision, with your agent as the brain. A shadow brain’s decisions are
recorded the same way, marked as shadow. Read them with
search(kind: "decision").
When Prime answers
Prime is your account’s own. It runs inside Apostra, so there is no endpoint to connect and nothing to verify: you choose it withprime, as answering or as
shadow.
Prime reads only your storefront. For each request Prime reads your catalog
and prices, your playbook and rate card, and how this buyer has dealt with you
before, and nothing about any other seller or buyer. It writes the same kind of
answer Chef writes, and that answer is checked the same way Chef’s is: your
prices and floors, your currency and the safety checks on what a buyer sees.
Prime has about 85 seconds to answer. If it does not answer in time, fails,
or gives no answer a buyer may see, Chef answers instead, in the rest of the
buyer’s two-minute window. A buyer always gets an answer. Prime answers
storefronts that Apostra composes for. A storefront composed in a hosted sales
agent is answered by Chef.
Every call is on your decision record. Each Prime call, as the answering
brain or as a shadow, is a decision with Prime as the brain, and shadow calls
are marked as shadow. Read them with search(kind: "decision"). A shadow Prime
runs at no charge during the beta.