> ## 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.

# Connect your own proposal agent

> How a seller registers its own model as a proposal agent: the four proposal tasks it must answer, the brand.json entry that proves it is yours, and what changes for buyers.

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`.

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

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](https://docs.apostra.com/v3/connect-an-agent.md#what-the-task-asks). 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](https://docs.apostra.com/v3/seller-proposal-agent.md).

## 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](https://docs.apostra.com/v3/connect-an-agent.md).

Service tokens, delegated sessions and impersonation cannot connect an agent.

## Connect it

First preview what Apostra reads. Nothing is saved:

```json theme={null}
{
  "tool": "save_agent",
  "arguments": {
    "kind": "proposal",
    "agentUrl": "https://brain.northstar.example/mcp",
    "dryRun": true
  }
}
```

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:

```json theme={null}
{
  "tool": "save_agent",
  "arguments": {
    "kind": "proposal",
    "agentUrl": "https://brain.northstar.example/mcp",
    "idempotencyKey": "7c1f0e2a-5b8d-4c39-9a61-2f4e8d0b1c73"
  }
}
```

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](https://www.rfc-editor.org/rfc/rfc9421) 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](https://docs.apostra.com/v2/authentication.md#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:

```ts theme={null}
import {
  adcpOperationResolver,
  type Authenticator,
  requireAuthenticatedOrSigned,
  serve,
  verifySignatureAsAuthenticator,
} from '@adcp/sdk/server'
import {
  HttpsJwksResolver,
  InMemoryReplayStore,
} from '@adcp/sdk/signing/server'

const PROPOSAL_TASKS = [
  'request_proposals',
  'refine_proposals',
  'accept_proposal',
  'decline_proposals',
]

// Discovery answers anyone; a proposal task with no signature is refused.
const discoveryOnly: Authenticator = async (req) => {
  const operation = adcpOperationResolver(req)
  return operation === undefined || operation === 'get_adcp_capabilities'
    ? { principal: 'anonymous' }
    : null
}

serve(createAgent, {
  authenticate: requireAuthenticatedOrSigned({
    signature: verifySignatureAsAuthenticator({
      jwks: new HttpsJwksResolver('https://api.apostra.com/.well-known/jwks.json'),
      replayStore: new InMemoryReplayStore(),
      capability: {
        supported: true,
        covers_content_digest: 'either',
        required_for: PROPOSAL_TASKS,
      },
      resolveOperation: adcpOperationResolver,
    }),
    fallback: discoveryOnly,
    requiredFor: PROPOSAL_TASKS,
    resolveOperation: adcpOperationResolver,
  }),
})
```

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:

| What the agent reads | The call |
| - | - |
| Your catalog | `get` or `search`, `kind: "wholesale_product"`, with `version` and `forecast` |
| This buyer's rate card | `get`, `kind: "account_relationship"`, `include: ["rate_card"]`, for this buyer's account only |
| Pricing across buyers | `include: ["price_paid"]` on `wholesale_product` |
| Your Library | `get` or `search`, `kind: "material"`, without any buyer's own rate card |
| This buyer's past briefs | `search`, `kind: "rfp"`, which returns only this buyer's own |
| This buyer's history | `get_rfp_performance`, which counts only this buyer's own RFPs |

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:

| Case | Code | `details.reason` |
| - | - | - |
| The token expired or the answer already arrived | `ACCESS_DENIED` | `read_token_expired` |
| A read for another buyer | `ACCESS_DENIED` | `buyer_out_of_scope` |
| A tool or kind the token does not read | `ACCESS_DENIED` | `purpose_out_of_scope` |
| The 11th call | `RATE_LIMITED` | `tool_call_limit` |
| Too little time left in the request's window for another read | `ACCESS_DENIED` | `compose_window_closed` |
| A product or rate-card line changed since the agent first read it | `CONFLICT` | `catalog_stale` |
| One result larger than 16 KB | `VALIDATION_ERROR` | `response_too_large`, with `details.nextCursor` to read past it |

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"`:

```json theme={null}
{
  "brands": [{ "id": "northstar", "names": [{ "en": "Northstar" }] }],
  "agents": [
    { "id": "northstar_brain", "type": "sales", "url": "https://brain.northstar.example/mcp" }
  ]
}
```

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](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours).


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