> ## 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, set up for you. Not available yet (see below). |
| Your own proposal agent | `own` | You, or your host. |

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. Once shadow brains run, they run at no charge
during the beta.

> [!WARNING]
>
> Apostra does not yet send requests to any brain but Chef. Until it does, **Chef
> answers every request, and no shadow brain runs**, whatever this setting says.
> The setting is saved and recorded now, so your choice takes effect, for new
> requests, once Apostra can send them to the brain you chose.

> [!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.
* Your own proposal agent is not open to sellers yet, as `answering` or
  `shadow`. It opens when the choice of brain launches to sellers. Until then
  `own` is refused with `FEATURE_NOT_ENABLED` and
  `reason: "own_proposal_agent_unavailable"`, and only Apostra's own accounts
  can choose it.
* Saving the setting already in force changes nothing.

Once Apostra sends requests to the brain you chose, 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.

## Prime is not available yet

Prime needs your Seller account to have its own agent, which Apostra does not
offer yet. Until it does, `prime` is refused, as `answering` or `shadow`, with
`VALIDATION_ERROR` and `reason: "seller_agent_unavailable"`.

## 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`, before your own proposal agent 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` |
| `prime` | `VALIDATION_ERROR`, `reason: "seller_agent_unavailable"` |
| 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.