Skip to main content
A proposal agent answers buyers’ proposal requests for a seller. When a seller wants its own model to answer, instead of Chef, it connects that model to Apostra as a proposal agent with 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’s name, 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.com is refused, and pinnaclenews.com passes. 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.
Apostra checks the last rule twice: first against known patterns, then with a model that reads each field and says whether it is written for the human buyer. If that model cannot answer, for example because it is unavailable, the words are refused rather than sent unchecked. A proposal with any refused word is withheld, and if none remains, Chef answers. A rejection with a refused reason or suggestion reaches the buyer as the storefront’s standard decline. Each refusal is recorded on your decision record with the check that refused it: 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’s get_adcp_capabilities without credentials and connects it as a proposal agent only when:
  • supported_protocols contains media_buy, and
  • media_buy.lifecycle_tools lists all four proposal tasks: request_proposals, refine_proposals, decline_proposals and accept_proposal.
When a task is missing, the call is refused with 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 lists control_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: Service tokens, delegated sessions and impersonation cannot connect an agent.

Connect it

First preview what Apostra reads. Nothing is saved:
The preview returns the reading and inferred.kind: "proposal". Then connect it with an idempotencyKey, so a retry finds the first agent instead of making a second one:
You may send 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’s request_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:
Run more than one replica and the replay store must be shared between them, so a signature accepted on one is refused on the others.

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 the Apostra-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 the brand.json on its own host lists it. AdCP’s brand.json has no proposal agent type, so list a proposal agent with "type": "sales":
Everything else follows the same rules as any agent: the exact URL, the file on the agent’s own host, and a host on a domain your organization has verified. See Prove your agent is yours.