> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose the brain that answers your buyers

> Which brain answers your buyers' proposal requests: Chef, Prime or your own proposal agent, and an optional shadow brain. Read it with get and change it with the proposalAgent field on save_seller.

When a buyer asks your storefront for proposals, a brain composes the answer
from your Library: your products, prices, playbook and rules. You choose which
brain that is:

| Brain | `proposalAgent` value | Who runs it |
| - | - | - |
| Chef | `chef` | Apostra. The default. |
| Prime | `prime` | Apostra: your account's own Prime, which runs inside Apostra and answers from your Library. Open to Apostra's own accounts for now (see below). |
| Your own proposal agent | `own` | You, or your host. Open to Apostra's own accounts for now (see below). |

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.

> [!WARNING]
>
> Apostra sends buyers' `request_proposals` calls to the brain you choose: Chef,
> your account's own Prime, or your own proposal agent. A Chef shadow never runs,
> because Chef already answers. A buyer's `request_proposals` reaches your brain
> whether the buyer calls your storefront directly over AdCP or asks through
> Apostra's V3 API (Murph, the widgets and API clients). A direct `get_products`
> brief and a refinement are still answered by Chef.

> [!NOTE]
>
> 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](https://docs.apostra.com/v3/seller-account-type.md)).

## Read the setting

`get(kind: "seller")` returns `proposalAgent`:

| Field | Meaning |
| - | - |
| `answering` | `chef`, `prime` or `own`. Chef when you never saved a setting. |
| `shadow` | The shadow brain, or `null` for none. |
| `ownAgent` | Your proposal agent when a brain is `own`: its `id`, `name`, `endpointHost` and `state` (`verified`, `unverified` or `archived`). Otherwise `null`. |
| `updatedAt` | When the setting was last saved, or `null` if it never was. |
| `updatedBy` | The email of the administrator who saved it, or `null`. |

## Change it

Send the whole setting with `save_seller`, on its own, with the `updatedAt` you
read:

```json theme={null}
{
  "proposalAgent": {
    "answering": "chef",
    "shadow": null,
    "ownAgentId": null,
    "expectedUpdatedAt": null
  }
}
```

* `expectedUpdatedAt` is required. Send the `updatedAt` you read, or `null`
  while the setting was never saved. If someone saved a change since you read
  it, the call is refused with `CONFLICT` and names the setting now in force,
  so two administrators never overwrite each other.
* `shadow` must differ from `answering`.
* `ownAgentId` is required when `answering` or `shadow` is `own`, and must be
  `null` otherwise. It must be a proposal agent your organization connected and
  verified as its own. See
  [Connect your own proposal agent](https://docs.apostra.com/v3/connect-a-proposal-agent.md).
* Prime and your own proposal agent are not open to sellers yet, as
  `answering` or `shadow`. They open when the choice of brain launches to
  sellers. Until then `prime` and `own` are refused with
  `FEATURE_NOT_ENABLED` and `reason: "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.

A change applies to new requests. A negotiation that is already open finishes
with the brain that opened it, so a buyer partway through a negotiation never
sees the answering brain change under them. Every change is recorded with the
administrator who made it.

## When your own agent answers

When your setting names your own proposal agent, Apostra sends each new
`request_proposals` call for your storefront to the agent's endpoint, signed as
Apostra (see
[How your agent knows a request is from Apostra](https://docs.apostra.com/v3/connect-a-proposal-agent.md#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:

| Check | A proposal passes when |
| - | - |
| Unique ids | Its `proposal_id` is used by no other proposal in the answer; every proposal that shares one is withheld (`duplicate_proposal_id`) |
| Lineage | Its `terms_digest` verifies, and it is a new draft for a new media buy, with no `parent_proposal_id` |
| Grounding | Every purchase names a product, a pricing option and format options that your storefront's catalog offers this buyer |
| Pricing currency | Every purchase is priced in the currency of the pricing option it names, and the proposal uses that one currency throughout: every purchase, `total_budget`, bidding, budget guidance and forecast |
| Formats | Every product the agent describes for a purchase declares canonical `format_kind` and `params` options only, with no `agent_url` |

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 with `prime`, 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.

## Refusals

| Case | Code |
| - | - |
| Your account is not on the beta | `FEATURE_NOT_ENABLED` |
| You are not a direct administrator, or the caller is an agent | `ACCESS_DENIED` |
| `own` or `prime`, before the choice of brain opens to sellers | `FEATURE_NOT_ENABLED`, `reason: "own_proposal_agent_unavailable"` |
| `own` without `ownAgentId`, or an id that is not a verified proposal agent of your organization | `VALIDATION_ERROR` |
| `shadow` equals `answering` | `VALIDATION_ERROR` |
| The account sells as a Listing | `CONFLICT`, `reason: "selling_mode_listing"` |
| `expectedUpdatedAt` is missing | `VALIDATION_ERROR` |
| `expectedUpdatedAt` is stale, or `null` once the setting exists | `CONFLICT`, `reason: "proposal_agent_changed"` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.