save_agent.
For now, only Apostra’s own accounts in the modular sales agent beta can
register a proposal agent. Any other account, including a seller in the beta,
that sends
kind: "proposal" gets FEATURE_NOT_ENABLED with details.reason
own_proposal_agent_unavailable, for a dryRun: true preview too, before
Apostra reads the agent. For such an account, an agent that answers the four
proposal tasks reads as a sales agent, and every other kind of agent connects
as before. Registering your own opens to sellers later, as its own release,
when you can choose which agent answers your buyers’ proposal requests.What changes for buyers
Connecting a proposal agent registers it and checks it; it does not send it any buyer’s request. Choosing it is what sends it requests:save_seller with
proposalAgent.answering (or proposalAgent.shadow) set to own and the
agent’s id in proposalAgent.ownAgentId. From then on Apostra sends your
storefront’s request_proposals calls to the agent, checks its answers, and
lets Chef answer when it cannot. Choosing own is also open only to Apostra’s
own accounts for now. See
Choose the brain that answers your buyers.
Buyers get your agent’s terms and pricing on your catalog’s own products, and
its own words once Apostra has screened them. Buyers deal with your storefront,
and never learn that a proposal agent was involved.
What your agent may write
Apostra screens every word your agent writes for the buyer: each proposal’sname, description and brief_alignment, and a rejection’s reason and
suggestions. The buyer’s AI reads these words, so they must not reveal the
agent or carry instructions to that AI. Your agent must not:
- Name itself. That means the agent’s registered name, its endpoint’s host
or domain, and its operator’s domains, in any letter case or spelt with
letters that only look like them, such as a Cyrillic “с” for a Latin “c”.
Apostra compares letters by Unicode’s list of confusable characters, so
letters that list calls alike, such as “rn” and “m”, count as the same. A
word that mixes Latin letters with Cyrillic, Greek or another script whose
letters look Latin is refused whatever it spells. Your storefront’s own
name, brand domain and organization domains are fine, because they name
your storefront:
agent.pinnaclenews.comis refused, andpinnaclenews.compasses. An agent registered under your storefront’s own name may use it. - Use its registered name as an ordinary word. The name is matched as a whole word wherever it appears. An agent named “Atlas” cannot write “the Atlas Mountains”, though “Atlassian” is fine. Register a distinctive name.
- Quote your storefront’s operating instructions, or repeat the request’s
idempotency_key. - Write more than 500 characters in any one field.
- Write to an AI model instead of the buyer, in any language: no
instructions such as “ignore previous instructions”, no
system:role header, no tool-call tag, and no note addressed to the buyer’s assistant.
names_agent,
quotes_operating_instructions, names_internal_id, text_too_long,
reads_as_instructions or model_safety_unverified.
What the agent must answer
Apostra reads the agent’sget_adcp_capabilities without credentials and
connects it as a proposal agent only when:
supported_protocolscontainsmedia_buy, andmedia_buy.lifecycle_toolslists all four proposal tasks:request_proposals,refine_proposals,decline_proposalsandaccept_proposal.
VALIDATION_ERROR.
details.reason is proposal_tasks_missing and details.missingTasks names
each task the agent does not list. Add them to the agent and try again.
An agent that also lists control_media_buy reads as a sales agent that also
answers proposals, so its preview shows kind: "sales" with proposal in
alternativeKinds. An agent without it reads as a proposal agent, with sales
as the alternative. Either way, send kind: "proposal" to connect it as a
proposal agent.
get_adcp_capabilities must answer without credentials. Apostra does not
connect a proposal agent it could not read, because it cannot check the four
tasks.
Connect it from the Connect an agent task
In an Agents account, choose Proposal agent on the first screen of the Connect an agent task. Accounts that cannot connect a proposal agent yet see the choice turned off, with a line saying why. Enter the URL and Apostra reads the agent. If the agent also listscontrol_media_buy, Apostra reads it as a sales agent, tells you so
before you connect, and connects it as a sales agent. Otherwise confirm the
name and connect it. A connected proposal agent has no sales mode and no first
test.
The task then says Apostra checked the agent and has not sent it any buyer’s
request. It does not choose the agent for you: to have it shadow Chef first,
choose it in your Seller account, as in
Choose the brain that answers your buyers.
Who can connect one
For now, only Apostra’s own accounts in the beta qualify (see the note above). In such an account, a person who directly administers it, signed in as themselves:- in your Seller account, which owns the agent, or
- in your organization’s Agents account, as for any other agent. See Connect an agent in an Agents account.
Connect it
First preview what Apostra reads. Nothing is saved:inferred.kind: "proposal". Then connect it
with an idempotencyKey, so a retry finds the first agent instead of making a
second one:
displayName to replace the name Apostra suggests. A proposal
agent has no sales mode and no first test.
How your agent knows a request is from Apostra
Apostra signs every call to your proposal agent as Apostra, with RFC 9421 HTTP message signatures, whatever your agent’srequest_signing says. Apostra keeps no credential for
your proposal agent, and you never give it one: the signature is how your agent
knows a request is ours.
Your agent must verify the signature, and refuse a proposal task that is not
signed by Apostra. Our keys are published at our agent URL,
https://api.apostra.com: its /.well-known/brand.json names
https://api.apostra.com/.well-known/jwks.json, and the keyid in each
signature selects the key there. The steps, and what to check, are in
Verifying our signed requests.
Answer discovery without credentials: MCP initialize and tools/list, and
get_adcp_capabilities, which Apostra also reads when you connect the agent.
Require a valid signature on request_proposals, refine_proposals,
accept_proposal and decline_proposals. A request that carries a signature
that does not verify must be refused, whatever else it carries.
With @adcp/sdk, the server scaffold does this for you:
Where Apostra calls your agent
Apostra calls the exact URL you connected, over HTTPS, and only when its host resolves to a public address. Apostra does not follow redirects: a redirect counts as a failed call, and the storefront answers the buyer itself. Serve the proposal tasks at the URL you connect.What your agent reads while it answers
When Apostra sends your agent a buyer’s request, it sends a read token with it, in theApostra-Read-Token HTTP header, never in the AdCP body. The token
starts with art_. Your agent calls /mcp/v3 with it as its bearer token to
read what it needs to answer. Until Chef stops answering every request (see
above), no request carries a token.
A token is for one request and one buyer, the buyer that sent the request. It
reads through get, search and get_rfp_performance only:
A rate card you keep for one buyer is not part of the Library a token reads:
search leaves it out and get answers NOT_FOUND. The token reads its own
buyer’s rate card through that buyer’s account, as above. The Library
browser’s page and sheet view (include: ["browse"], or a scope on
kind: "material") is refused with purpose_out_of_scope.
The token works only in your Seller account, which it names itself: a call
that names another account is refused with ACCESS_DENIED. It cannot write,
and cannot read your agent’s decisions, Sessions or anything else.
Each call returns at most 20 products (and so at most 20 products of
price_paid), 10 Library passages, 5 past briefs or 5 history rows, with
truncated: true and a cursor when there is more. A call’s text and its
structured content are each at most 16 KB: a page that would be larger comes
back with fewer results and a cursor to the rest, and a single result larger
than 16 KB is refused, with a cursor past it when it is one of a page. A
result is never returned twice in one page. A token makes at most 10 calls.
What a refused call returns:
The token expires when the request’s compose window closes, about 2 minutes
after Apostra sends it, and is revoked as soon as your agent answers. Apostra
records every call a token makes, refused calls too, so your agent’s
decisions can show what it read. Two exceptions: once a token is expired or
used up, Apostra records the first refusal for that reason and not the
repeats; and if Apostra cannot write a record, a read is refused with
SERVICE_UNAVAILABLE rather than answered unrecorded, while a call that was
already being refused is still refused.
Prove the agent is yours
Like every connected agent, a proposal agent is not verified as yours until thebrand.json on its own host lists it. AdCP’s brand.json has no proposal
agent type, so list a proposal agent with "type": "sales":