> ## 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 an agent in an Agents account

> The kinds of agent you can connect, what a sales mode is, and how to start from My agents, Ask Apostra, the Agents screen or MCP.

New to building on Apostra? Start with [Build and certify an agent](https://docs.apostra.com/v3/developer-quickstart.md).

Every agent you build lives in your organization's **Agents account**. An
organization holds one Agents account, and it holds any number of agents.
Name it with `accountId` on every call you make to create an agent. If the
organization has none, create it from the organization's **Accounts** screen or
with `save_account` in the organization account. A second Agents account is
refused.

## Who can do what with an agent

Your role in the Agents account decides what you can do with its agents. The
roles are the ones on the account's member list:

| Role | What it can do with agents |
| - | - |
| **Member** | See the account's agents, their status and findings, the calls Apostra made to them, and the sessions that record their [live certification runs](https://docs.apostra.com/v3/certification.md#read-a-run-and-the-calls-apostra-made-to-your-agent), with the steps and calls each run made. A Member takes no action. |
| **Operator** | Everything a Member can, and run an agent's tests: the endpoint check, the runs of the [Test a Sales Agent skill](https://api.apostra.com/skills/test-sales-agent/SKILL.md) and the creative conformance test. Turn [Allow certification buys](https://docs.apostra.com/v3/connect-an-agent.md#allow-certification-buys) on or off. Connect one of this account's agents to your organization's [test storefront](https://docs.apostra.com/v3/connect-an-agent.md#test-and-certify-your-agent) once it exists. In a storefront account of your organization where they are an Operator, connect one of your organization's agents to a Source. |
| **Admin** | Everything an Operator can, and create, register, claim, rename and archive agents, change an agent's URL, read an agent again at its URL, and add or remove the account's members. Connect the first agent to your organization's test storefront, which creates it. In a storefront account, connect a partner's agent, one another organization owns. |

Each of these actions needs a person signed in as themselves. Service tokens,
delegated sessions and impersonation cannot take them, whatever role the person
behind them holds. On the agent's Overview page, a button that runs a test or
the **Allow certification buys** switch shows to Operators and Admins, and the
other buttons that change something show to Admins only.

A member of the organization who has not been added to the Agents account does
not reach it; an Admin adds them as a member.

An administrator of the organization is an administrator of every account in
it, so you do not need to be added to the Agents account as a member. Open
it on the web or name it with `accountId`, and you can create, read and
register agents there. See
[Name the account on every call](https://docs.apostra.com/v3/name-the-account.md). An Apostra support person
sees the agents read-only unless a staff elevation is active.

The Agents account's **Account members** page lists everyone with access to
the account: the people added to it and the administrators of the organization.
An organization administrator has access without being added, so the page tags
them **Organization admin** and offers no Remove or permission control on them.
An organization administrator opens **Organization members** from the page to
manage that access. A session that may see the members but not change them,
such as a read-only Apostra support session, sees the list without
**Invite members** or the other member controls. A session that may not see
them is told so instead of being shown an empty list. An agent reads the same
list with `search` and `get` for `kind: "member"`, where each member says in
`accessSource` whether it was added to the account or comes from the
organization. See [Who an account's member list shows](https://docs.apostra.com/v3/account-access.md#who-an-accounts-member-list-shows)
and [Inviting members](https://docs.apostra.com/v2/ui-guide.md#inviting-members).

## Start building

Building a sales agent? [What a great sales agent does](https://docs.apostra.com/v3/sales-agent-ladder.md) puts everything it has to do
in order, step by step, and the [sales agent checklist](https://docs.apostra.com/v3/seller-agent-checklist.md) lists what to declare before
you connect it.

Any of these opens the same **Connect an agent** task:

* **My agents.** Choose **Connect an agent**.
* **Ask Apostra.** In the Agents account, ask for the agent you want, for
  example "build a sales agent for my publisher". Apostra opens the Connect an
  agent task. Ask Apostra's starter prompts in an Agents account cover building
  a sales, creative or buyer agent, testing an agent and getting it certified.
  In an Agents account Ask Apostra has the same tools as the account's `/mcp/v3`
  connection, so it can also connect an agent's URL, read an agent's findings
  and open its pages. It works on the agent you name or have open; when the
  account holds several and it is not clear which you mean, it asks.
* **The Agents screen.** Choose **Connect an agent**.
* **MCP.** Call `open_create_agent_task` on the organization MCP surface. From an
  Agents account's `/mcp/v3` connection, call `open_agents_page`, then choose
  **Connect an agent**. To connect an agent without the task, call `save_agent` with
  the agent's URL: see
  [Connect an agent from its URL](https://docs.apostra.com/v3/connect-an-agent.md#connect-an-agent-from-its-url).
  To register a sales or creative agent that has no URL yet, call `save_agent`
  with no `agentId`, and send `kind`, `displayName` and an `idempotencyKey`. For
  a sales agent you can also send `salesMode`. A buyer agent is created with
  `save_buyer_agent`.
* **REST.** `POST /api/v2/agents`. See [Create an Agent](https://docs.apostra.com/v2/storefront/agents/tasks/create-agent.md)
  for the request and errors.

### What the task asks

The task first asks what you are connecting, then asks for the agent's URL and
shows you what Apostra read. The agent belongs to your organization. Everything
it shows, and every field it makes required, comes from the `save_agent`
response, so an assistant calling `save_agent` sees the same answers.

1. **Choose what you are connecting.** The first screen, **What are you
   connecting?**, offers three choices. Your choice decides the next steps. It is
   never sent to Apostra, and it does not change what Apostra reads: Apostra
   works out what the agent is from what it serves, and tells you when that is
   not what you chose.

   | Choice | What happens next |
   | - | - |
   | **Inventory agent** | Your ad server's or platform's AdCP agent. You enter its URL, Apostra reads it and connects it as a sales agent, then **Add it as a source** opens the secure form where you enter its credential. It becomes a source of your storefront. |
   | **Sales agent** | An agent that sells to buyers as its own storefront. The steps below, unchanged: its URL, how it sells, then a first test. |
   | **Proposal agent** | Your own model that answers buyers' briefs for your storefront. You enter its URL and Apostra checks that it answers the four proposal tasks. The task ends on a hand-off: you choose the agent in your Seller account. See [Connect your own proposal agent](https://docs.apostra.com/v3/connect-a-proposal-agent.md). Accounts that cannot connect a proposal agent yet see this choice turned off, with the reason. |

   **Another kind of agent** skips the choice for a creative agent, a buyer agent
   or an agent you have not built yet. Opening the task with a kind already
   chosen starts on the URL step.
2. **Enter the URL.** Paste the agent's address and choose **Read agent**.
   Beside it are two other choices: **It's a buyer agent** and **I haven't built
   it yet**. **Change what I'm connecting** returns to the first screen.
3. **Confirm.** The task shows the kind, the sales mode if it is a sales agent,
   a suggested name, what the agent also declares and what Apostra read. You can
   change the name. If the agent declares no buying mode, you choose its sales
   mode. A field the agent did not declare is empty and required. If the agent
   declares both a sales and a creative role, you choose the kind first.
   If your Agents account already has an agent of the same kind that you
   registered with no URL, the task lists it as **Connect this URL to \[name]**,
   with **Register a new agent** beside it. Nothing is chosen for you. Choosing
   an existing agent connects the URL to it and keeps its name. A buying mode
   declared by the agent replaces its saved mode; without a declaration, the
   saved mode stays. Choosing **Register a new agent** works as described below.
4. **Connect.** Apostra records the agent and its URL, then starts its first
   test. The task shows **Connected** while a creative agent's test runs, and
   **Tested** when the test passes. If the test fails, times out or does not
   run, the agent stays connected, the task says which, and a failed creative
   test can be run again from the task. A sales agent's check runs again from
   its Agent page.
5. **Connect as the other kind.** When the agent also declares the other offered
   kind, the task offers **Connect as sales agent too** or **Connect as creative
   agent too**. Each kind is its own agent and its own confirm, so connecting
   one never connects the other, and the task reads the agent again for the kind
   you choose.

If a read fails, the task shows the reason for it in plain words and keeps the
address you typed, so you can correct it or try again. The reasons are listed in
[When a read fails](https://docs.apostra.com/v3/connect-an-agent.md#when-a-read-fails).

If the agent needs credentials before it will describe itself, the read does
not fail. The task says **Apostra could not read this agent**, offers it as a
sales agent named after its host, and shows **Register sales agent** in place of
**Connect**. Registering saves its address without a read, and the task ends at
**Registered, not read yet**, with the next step: connect the agent from your
Seller account and store its credentials there. See
[Register an agent that needs credentials](https://docs.apostra.com/v3/connect-an-agent.md#register-an-agent-that-needs-credentials).

**It's a buyer agent** skips the read. A buyer agent calls Apostra with a
credential and Apostra never calls it, so it needs no address. You give it a
name, which is only a label you'll recognize it by, such as a person's or a
team's name. The task creates it and opens the credential step, where you set
up the credential it uses to call Apostra. Apostra stores no URL for a buyer
agent. **I haven't built it yet** registers an agent by kind and name only, so
you can connect its URL later from its Agent page.

Registering an agent by kind and name records its identity only. It does not
publish the agent, connect a source or request credentials. See [Agents](https://docs.apostra.com/v2/concepts/agents.md).

## Connect an agent from its URL

You can paste an agent's URL and let Apostra read what it is, then save it.
Apostra calls the agent's `get_adcp_capabilities` tool, works out the kind of
agent it is, how a sales agent sells and what to call it, and shows you the
result for you to confirm or correct. Saving it creates the agent in your
Agents account and records its URL, so the agent moves from Built to
Connected. To register an agent that has no URL yet, use a kind and a name, as in
[Start building](https://docs.apostra.com/v3/connect-an-agent.md#start-building), and connect it later.

### Preview what Apostra reads

Call `save_agent` with the agent's URL and `dryRun: true`. A preview needs no
`idempotencyKey`, saves nothing and creates no agent.

```json theme={null}
{
  "agentUrl": "https://agent.example.com/mcp",
  "dryRun": true
}
```

You can send three optional fields to confirm or correct what Apostra read:
`kind` (`sales` or `creative`), `salesMode` (`WHOLESALE`, `COMPOSING` or `BOTH`,
for a sales agent only) and `displayName`. `salesMode` supplies the answer when
the agent declares no buying mode; it cannot replace an explicit declaration.
A correction can change the name. It can never add a role the agent does not
declare: a `kind` the agent does not declare is refused with the reason
`kind_changed`.

### What Apostra reads

Apostra reads the agent with no credentials. It finds the agent's MCP endpoint,
lists its tools, and calls `get_adcp_capabilities`. The preview returns what the
agent declared, under `reading`:

| Field | What it is |
| - | - |
| `agentUrl` | The address that answered. It can be the address you pasted with `/mcp` added. It is never the address after a redirect. |
| `transport` | `mcp`. Only MCP agents can be connected today. |
| `protocols` | The agent's `supported_protocols`, as it declared them. |
| `adcpVersions` | The AdCP releases the agent declares. |
| `buyingModes` | The agent's `media_buy.buying_modes`, when it declares any. |
| `alsoDeclares` | Other protocols the agent declares besides sales and creative, such as `signals`. They are shown to you and decide nothing. |
| `brandJsonUrl` | The agent's own pointer to its owner's `brand.json`, kept as evidence. It does not decide the kind, the mode or the name. |

The preview also returns `waitingAgents`, outside `reading` and `inferred`: your
Agents account's agents of the inferred kind that have no URL, each with its
`agentId` and `displayName`. It is empty while the kind is not chosen, for a buyer
agent, and when nothing is waiting. See
[Connect an agent you already registered](https://docs.apostra.com/v3/connect-an-agent.md#connect-an-agent-you-already-registered).

### What Apostra infers

What Apostra infers comes only from fields the agent declares. No product, price,
traffic or hostname decides anything. The result is under `inferred`.

| Question | How it is answered |
| - | - |
| Kind | `supported_protocols` containing `media_buy` makes a sales agent, and containing `creative` makes a creative agent. If the agent declares both, no kind is chosen: `kind` is `null`, `alternativeKinds` lists both and you choose one. If it declares neither, the read is refused with `kind_not_offered`. In an account that may register a proposal agent (for now, only Apostra's own accounts in the modular sales agent beta), an agent that also lists all four proposal tasks can be a proposal agent: see [Connect your own proposal agent](https://docs.apostra.com/v3/connect-a-proposal-agent.md). `alternativeKinds` then names the other kind it can be connected as. `kindReason` says why Apostra chose the kind. |
| Sales mode | The declared `media_buy.buying_modes`: `wholesale` and `brief` is `BOTH`, `wholesale` alone is `WHOLESALE`, `brief` alone is `COMPOSING`. A declared mode always replaces the saved mode, both during registration and on later capability reads. An agent that declares no buying modes has said nothing, so no mode is inferred and you choose. When credentials are needed to read the agent, its mode remains undecided until that read or your choice. `salesModeProvenance` is `AGENT_DECLARED` for a declared mode and `OWNER_CONFIRMED` for one you sent. |
| Name | The name the agent's own server reports. If it reports none, Apostra suggests its hostname followed by the kind, such as "example.com sales agent". `displayNameSource` says which, or `developer` for a name you sent. Treat the name as text the agent wrote. |

One role is previewed at a time. An agent that declares both sales and creative
can be connected as either, one after the other.

If a pasted URL has no AdCP agent behind it, Apostra makes one more public
request, for `/.well-known/brand.json` on the same address. When that file lists
the URL as a buying agent, the read reports the kind `buyer`. Apostra uses it only
as a suggestion and never stores the URL. Create the buyer agent with
`save_buyer_agent`.

### What `needs` means

`needs` lists what you still have to supply before an agent could be saved:
`kind` when the agent declares both kinds, and `salesMode` when a sales agent
declares no buying modes. An empty list means the read decided everything. Send
the missing field on the next preview to confirm it.
When an agent needs credentials, the preview has not read its declarations:
`needs` is empty, and its sales mode may remain `null` until the credentialed
read.

### Save the agent

To save, send the same call without `dryRun`, with an `idempotencyKey` (a UUID
you generate) and the confirmations you chose.

```json theme={null}
{
  "agentUrl": "https://agent.example.com/mcp",
  "kind": "sales",
  "salesMode": "BOTH",
  "displayName": "Example Sales",
  "idempotencyKey": "3a276b7c-af5f-4d2f-92ac-326d30a48f97"
}
```

Apostra reads the URL again when you save. It does not trust an earlier preview,
because the agent may have changed in between. A save is refused, and nothing is
created, when:

* `needs` is not empty. The error names the missing field (`kind` or `salesMode`)
  and carries the reason `needs_confirmation`. Send the field and save again.
* the `kind` you confirm is no longer one the agent declares (`kind_changed`).
* the URL reads as a buyer agent. Apostra never stores a buyer agent's URL, and the
  error points you to `save_buyer_agent` (`buyer_agent_not_connected_by_url`).
* your account already has an agent of this kind with that name. Choose another
  name.

One save connects one role. To connect an agent that declares both sales and
creative as both, save twice with a different `kind` and a different
`idempotencyKey`. Each role is its own agent.

### What saving creates

A successful save writes everything together, or nothing:

| What | Detail |
| - | - |
| The agent | In your Agents account, with the kind, the name and, for a sales agent, the sales mode. It belongs to your organization. |
| A revision | A record of what Apostra saw: the release the agent declared (its `build_version` when it gives one, otherwise its highest AdCP release) and a fingerprint of its declarations and tools. |
| The endpoint | The URL that answered. |
| A production deployment | The revision is the agent's current production revision, and the endpoint is its current endpoint. |
| A record that the URL is not yet verified as yours | See [Connected, Tested and not yet verified as yours](https://docs.apostra.com/v3/connect-an-agent.md#connected-tested-and-not-yet-verified-as-yours). |

The response is the `developer_created` outcome. It carries `agentId`, `created`,
`stage`, `reading`, `inferred`, `connection`, `test` and `endpointControl`. `connection.state` is
`connected` and `connection.revision` is the revision's id. `endpointControl`
is `unverified` or `verified`, as [Prove your agent is yours](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours)
explains. `stage` is the agent's
stage as `get_status` reports it, so the two always agree. `test` says which test
applies to the agent and what happened to it, as the next section explains.

### What happens right after connecting

Saving connects the agent first and tests it second. The test runs after the
connect has committed, so a test that fails, times out or cannot run never undoes
the connect: the agent stays **Connected**.

**A sales agent is checked inside the same call.** Apostra runs the endpoint
check against the URL it just read: one `get_products` call with a fixed no-spend
brief, sent with no credentials. The check may spend up to 10 seconds on
`get_products`, and it must be over within 25 seconds of the start of the
`save_agent` call. Reading the URL counts against those 25 seconds, so a slow read
leaves the check less time. The quick reads that build the response afterwards
are not counted. `test` carries `profile: "endpoint-brief"` and
one of these states:

| `test.state` | What it means | What the agent's stage is |
| - | - | - |
| `passed` | The agent answered `get_products`. | `tested` |
| `failed` | The agent answered with an error or an unusable reply. `test.finding` carries the check's own reason, as the agent reported it, and the text version of the response shows it fenced as untrusted. Nothing is undone. | `connected` |
| `timed_out` | The agent did not answer inside the budget. Apostra records no result, because a slow agent has not been shown to fail. | `connected` |
| `not_started` | The check was not run. `test.reason` says why: `rate_limited` when the agent already used its 10 endpoint checks for the hour, or `unavailable` when Apostra could not run or record the check. | `connected` |

For `failed`, `timed_out` and `not_started`, fix anything slow or failing at the
agent URL, then re-run the endpoint check from the agent's Agent page. `stuckOn` on
`get_status` names the same next step.

**A creative agent is handed off.** Creative conformance can take up to 90
seconds, which no tool call should wait for, so the response returns
`test: { "profile": "creative-conformance", "state": "not_started" }` and names how
it starts in `test.start`. The Connect an agent task starts it with
`POST /api/v2/agents/{agentId}/creative-conformance`, the call the Agent page
already makes. An assistant opens the Agent page with `open_agent_page`, because
there is no typed V3 call that starts a test yet. The creative agent stays
**Connected** until a conformance run passes.

**What Tested means.** An agent is **Tested** when its latest test run passed. A
passing sales endpoint check is recorded for 30 days, and a passing creative
conformance run for 7 days. Re-run the test before then to keep a current result.

### Connected, Tested and not yet verified as yours

An agent is **Connected** once Apostra holds its URL and has read it. It is
**Tested** when its latest test run passes. Saving runs the first test for a sales
agent and hands it off for a creative agent (see
[What happens right after connecting](https://docs.apostra.com/v3/connect-an-agent.md#what-happens-right-after-connecting)),
and later runs start from the agent's **Overview** page. Connected and Tested
are statements about the URL: Apostra read it, and it answered as an AdCP agent.

They do not say that you run the agent. Apostra cannot tell, from reading a URL,
who controls it, so every agent connected from a URL starts **not yet verified as
yours**: `endpointControl` is `unverified`. Until you
[prove you control the URL](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours), the
agent:

* cannot be given Partner standing or listed in the marketplace.
* cannot be used by another organization.

An unverified agent can still be certified through your own organization's
storefront: **Allow certification buys** and certification need no proof, because
an agent behind its owner's storefront is reached only through Apostra.

Only your own account can see the agent, so a connected URL never appears as
another company's agent.

### Prove your agent is yours

Apostra checks that you control an agent's URL by reading a file on the agent's own
host. It checks right after every connect, and again each time you connect the same
agent again with its `agentId` and `agentUrl`. There is no separate call and no new
input.

**What to publish, and where.** Serve a `brand.json` at
`https://<your agent's host>/.well-known/brand.json`, on the same host as the agent's
URL and nowhere else. Add an entry to its `agents` list for the agent:

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

* `url` is the agent's URL exactly as Apostra stores it, character for character:
  the same case, the same path, the same presence or absence of a trailing slash.
  The response of the connect names it as `reading.agentUrl`, and `stuckOn` repeats it.
* `type` is `sales` for a sales agent and `creative` for a creative agent. A
  proposal agent is listed as `sales`, because AdCP's `brand.json` has no proposal
  agent type.
* The file is a valid AdCP `brand.json`, which also gives each entry an `id` of lowercase letters, digits and underscores.

**The domain rule.** The agent's host must be a domain your organization has already
verified, or a subdomain of one. That is the domain registered on your account or
organization once Apostra has approved it: an email on the domain, a DNS TXT record,
or an Apostra review. See [Which domain is which](https://docs.apostra.com/v3/domains.md). A host on
another domain does not verify, even if its file lists the agent. If your agent runs
on a domain you have not verified, verify the domain first. A domain that only
resembles yours, such as `evilnorthstar.example`, does not count as `northstar.example`.

When the agent's host is not on a verified domain, the `endpoint_control.unverified`
finding and `stuckOn` name the host's domain, for example "The agent's host is on
`wapo.pub`, which is not a domain your organization has verified. If `wapo.pub` is
yours, verify it for your organization. If it belongs to someone else, move the agent
to a stable host on a domain your organization has verified, then reconnect it."
An organization verifies one registered domain today, with one
approval, so the host must be on that domain or a subdomain of it. If your agent runs on
a different domain from the one your organization verified, host it on a subdomain of the
verified domain. Apostra cannot yet verify a second domain for an organization. Your brand
domain does not widen this: verifying a brand domain that differs from the registered
domain proves the brand, not the agent's host.

**A shared or temporary host cannot be verified.** A host on a domain that many
unrelated people publish under, such as a tunnel (`trycloudflare.com`) or a hosting
platform's subdomain, is not a domain your organization can own, so there is nothing
to verify. The finding says so: "a shared or temporary domain that your organization
cannot verify. Move the agent to a stable host on a domain your organization has
verified, then reconnect it." A tunnel host can also stop resolving without notice,
which makes Apostra unable to reach the agent at all (see
[When Apostra cannot reach your agent](https://docs.apostra.com/v3/connect-an-agent.md#when-apostra-cannot-reach-your-agent)).
The same applies to a domain that belongs to a third party, such as another
organization's website: move the agent to a host on your own verified domain.

**How Apostra reads it.** Apostra fetches the file from that exact host. It follows
no redirect at all, so a file served from another host, or from a path the host
redirects to, does not count. It does not read the file `identity.brand_json_url`
points to. It reads from public addresses only, waits at most 8 seconds, and reads at
most 1 MB.

**How to re-check.** Publish the file, then connect the agent again. The finding gives
the call: `save_agent` with the agent's `agentId`, its `agentUrl` and a new
`idempotencyKey` (any value you have not used before). The response shows
`endpointControl`, and the text version says why a check did not pass. A check counts
against the same hourly limits as reading the URL, when it fetches the file.

**What stays true afterwards.**

* Verification belongs to the URL it proved. Connect a different URL and the agent
  returns to `unverified`, until the file on the new host lists it.
* A check that fails because the file is briefly unreachable, missing or wrong
  leaves a `verified` agent verified. Only connecting a different URL, or losing
  the domain approval, ends the verification.
* Verification lasts only while the agent's host is on a domain your organization
  has verified. If the approval is withdrawn, for example the DNS record is
  removed or the member whose email proved the domain leaves, the agent reads as
  `unverified` at once in `get`, `get_status` and `stuckOn`, and Partner standing,
  listing and use by other organizations are refused again, with no re-check.
  Certification through your own storefront is not affected. If the approval returns, the agent reads as `verified` again. If you
  connect the agent again while the approval is missing, Apostra records it as
  `unverified`, and it becomes `verified` again when you connect it again after the
  domain is approved.
* Until the agent is verified, `get_status` and `get` show `endpointControl:
  unverified`, and the `endpoint_control.unverified` finding tells you what to
  publish and where: the file URL, the entry with its `url` and `type`, and the
  domain rule. For a creative agent, which has no certification stage, `stuckOn`
  names the same step once the agent has passed its conformance test. An agent
  that was not connected from a URL carries no `endpointControl` at all.

**What verification unlocks.** A verified agent can be given Partner standing and
listed, and can be used by another organization. Certification through your own
organization's storefront, and **Allow certification buys**, never need it.
Publisher authorization (`adagents.json`) still decides whose inventory a
storefront may sell.

### Register an agent that needs credentials

Some agents refuse every call without a credential, including the call that
describes them. Apostra never takes credentials on the Agents account and never
in chat, so it cannot read such an agent when you save its URL. A save that
reaches an agent like this does not create the agent unless you send `kind: "sales"`.
An agent does not have to answer `get_adcp_capabilities` without credentials to
be connected. If it does, Apostra can show what it declares before you save it.

In the **Connect an agent** task, choose **Read agent** and then **Register
sales agent**. Then, in your Seller account, connect the agent as a source and
enter its credentials in the secure credential form, as the steps below
describe.

Send the same `save_agent` call with `kind: "sales"`, and optionally
`displayName` and `salesMode`. Only a sales agent can be registered this way,
because only a sales agent is read by connecting it in a Seller account; a
creative agent that needs credentials is refused. Without `displayName` Apostra
names the agent after its host, and without `salesMode` its mode is `null` (not
decided). The first credentialed refresh sets the mode from the agent's declared
buying modes; if it declares none, choose a mode. Apostra
records the URL as the agent's address and returns the agent with
`notReadYet: { "reason": "authentication_required" }`.

An agent that has not been read has had no check run, and a check from the Agents
account can never pass for it, because Apostra holds no credential there. So the
agent's `validationSkill` lists the `endpoint-brief` profile as `UNAVAILABLE`, its
`day_one_test.sales_validation` finding says Apostra has not read it, and no
**Run the test again** action is offered. Connect it from your Seller account
(`save_inventory_source` with `accountId` and the agent's `agentId`), where its
credentials are stored. Apostra reads it then, and `refresh_inventory_source_health`
runs the credentialed check on the connected source.

A preview (`dryRun: true`) of an agent like this is not refused. It returns the
preview outcome with `notReadYet: { "reason": "authentication_required" }` and
saves nothing. Its `reading` holds only the URL, because nothing was read, and
`inferred` offers a sales agent named after the host. It lists `waitingAgents`
as for any preview: if one of your sales agents was registered with no URL, send
that agent's `agentId` with the `agentUrl` and an `idempotencyKey` to connect the
URL to it, which records it as not read yet. Without a waiting agent, send
`kind: "sales"` to register a new one.
Nothing about the agent was read, so its declared protocols, AdCP releases and
sales mode are not recorded, and no endpoint check runs. Apostra still checks
whether your organization controls the URL, which needs no credential, so the
agent is `unverified` until you prove it.

Only an authentication refusal (an HTTP 401 or 403, an OAuth challenge, or the
AdCP authentication error) takes this path. A URL that cannot be reached, a
timeout, a TLS failure and an answer that is not an AdCP agent fail as they do
for any save, and create nothing.

The agent is read when your Seller account connects it:

1. In the Seller account, call `save_inventory_source` with the `accountId` and
   the agent's `agentId`. The address is the one you registered.
2. Store the agent's credentials on the source in the secure credential form.
   Credentials stay on the source.
3. Apostra reads the agent with those credentials and records what it read on
   the agent: its capabilities, name and AdCP release. `notReadYet` becomes
   `null`, and the agent's stage and test results follow from what was read.

Apostra reads the agent through the source when the credentials are stored, and
again on an hourly check, including while the source is pending and waiting for
certification. A read that was missed, for example because the agent was
connected again after the source was, is recorded within about two hours.

A source's read is recorded on the agent only when the source calls the agent's
registered URL; a read of another URL is a read of another endpoint. A source
keeps the address it was connected at, so if you connect the agent again at a
new URL, the source still calls the old one and the agent stays not read yet.
Point the source at the new URL from the Seller account (`save_inventory_source`
with the source's `id` and the new `endpointUrl`, then store the credentials
that URL takes in the source's settings), or connect the agent at the source's
URL again.

While the agent is not read yet, its next step in `get_status` and in its
`day_one_test.sales_validation` finding follows from the source of your
organization that connects it:

| Source | Next step |
| - | - |
| None | Connect the agent from your Seller account, as above. |
| Calls another URL than the agent's | Names both URLs and says to point the source at the agent's URL, or to connect the agent at the source's URL. |
| Holds no credentials | Store the agent's credentials in the source's settings, on the source diagnostics Page. |
| Its read with its credentials fails | Read the source's diagnostics for what the agent answered, and update the credentials if it refused them. |
| Holds credentials and has not read the agent yet | Nothing: Apostra reads the agent through the source on its own. |

If the read with credentials fails, the source reports the failure as for any
agent, and the agent stays not read yet. Saving the same URL again for an agent
that has already been read changes nothing: a refused read never replaces what an
earlier read recorded.

### Retries and parallel saves

A save needs an `idempotencyKey`. Send the same key with the same request again
and Apostra returns the first agent with `created: false`, without reading the URL
again. Because nothing is read, `reading` and `inferred` are `null` in that
response, and no test runs again: `test` is the result already recorded for the
agent (`not_started` when none is recorded, for example after a `timed_out`).
Send the same key with a different request and the call is refused with a
conflict.

A key only protects a retry. If you save the same URL as the same kind twice with
different keys, even at the same moment, Apostra makes one agent and returns it
with `created: false` the second time.

### Connect an agent you already registered

To connect an agent you registered with a kind and a name, send its `agentId`
with the `agentUrl` and an `idempotencyKey`. A `dryRun` is not accepted here:
preview by omitting `agentId`.

Without an `agentId`, `save_agent` makes a new agent unless one of your agents
already has that URL, so a URL saved alone never lands on the agent you
registered earlier. To avoid a duplicate,
preview the URL first. The preview's `waitingAgents` lists the agents of the
same kind in your account that have no URL yet. If the URL belongs to one of
them, send that agent's `agentId` with the `agentUrl` and an `idempotencyKey`;
to make a new agent, send the call with no `agentId`. The Connect an agent task
asks you the same question: **Connect this URL to \[name]** for each waiting
agent, or **Register a new agent**.

* An agent with no endpoint yet gets its revision, endpoint and deployment.
* An agent that is already connected records a new revision when what Apostra
  reads from it changed. If nothing changed it keeps the revision it has. If the
  URL changed, the new URL becomes the agent's endpoint, for example after you
  restart a tunnel, and the agent returns to not yet verified as yours until the new
  URL is [proved](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours).
* The kind Apostra reads must be the agent's kind, and you must own the agent.
  The agent keeps its name. Its declared buying mode replaces the saved mode;
  without a declaration, the saved mode stays. A call that sends `displayName`
  or `salesMode` with an `agentId` is refused. Rename an agent with `displayName`
  and no `agentUrl`.

### Which URLs Apostra accepts

* An `https` address, up to 2048 characters, with no username, password, query
  string or fragment, on the default port (443). A bare host such as
  `agent.example.com` is read as `https://agent.example.com`.
* A name, not an IP address.
* An address on the public internet. Apostra refuses `localhost`, private and
  internal addresses and any name that resolves to one.
* No redirect to another address. Apostra follows redirects that stay on the
  address you pasted.

Apostra limits a read to 8 seconds for each call, 20 seconds in all, and 1 MB for
any reply. It limits you to 20 reads an hour for the Agents account and 5 an
hour for the same URL. A preview counts as a read. Only a directly authenticated
Admin of the Agents account can read a URL, because the read makes requests in
Apostra's name and can change where Apostra sends the agent's calls. An Operator
re-runs the endpoint check from the agent's **Manual test runs** instead. Service tokens,
delegated sessions and impersonation cannot.

### Test an agent running on your own machine

Apostra can only read agents reachable on the public internet, and there is no
override. To connect an agent that runs locally, expose it through a public
tunnel: a tunnelling service, or a reverse tunnel to a host you control. Paste the
tunnel's `https` address. When you restart the tunnel its address changes, so
paste the new address.

### When a read fails

A failed read creates nothing. A read that fails when you save creates nothing
either. In the Connect an agent task, the message for the reason appears under
the address field or in an alert on the confirm step, and the address you typed
stays in the field, so you can correct it or try again. A reason Apostra returns
that the task has no message for shows the server's own message. The error carries a closed `details.reason`, the
AdCP `recovery` (`correctable`, `transient` or `terminal`) and, where it applies,
`retry_after` in seconds.

| `details.reason` | What happened | What to do |
| - | - | - |
| `url_invalid` | The address is not a plain `https` address as described above, or it is an IP address. | Correct the address and read again. |
| `url_not_public` | The address is `localhost`, or a private or internal address, or a name that resolves to one. Apostra does not say which address it resolved to. | Use a public address. For a local agent, use a public tunnel. |
| `agent_unreachable` | The name did not resolve, the connection was refused or the TLS handshake failed. Apostra does not say which. | Check the address and that the agent is running, then try again. |
| `agent_timeout` | The agent did not answer in time. | Try again after `retry_after` seconds. |
| `authentication_required` | The agent needs credentials before it will describe itself. Apostra reads without credentials. A preview of a sales agent returns a preview with `notReadYet` instead of this refusal. | Save a sales agent with `kind: "sales"`, or send the `agentId` of a sales agent you registered with no URL. Apostra [records the URL as not read yet](https://docs.apostra.com/v3/connect-an-agent.md#register-an-agent-that-needs-credentials) and reads the agent when your Seller account connects it with its credentials. A creative agent, or a save of a new agent with no `kind`, is refused with this reason. |
| `no_adcp_server` | The address answers, but it is not an MCP server with `get_adcp_capabilities`. | Check that you pasted the agent's URL. |
| `adcp_version_unsupported` | The agent does not declare AdCP 3 or later. | Update the agent to support AdCP 3. |
| `transport_unsupported` | The address looks like an A2A agent. | Only MCP agents can be connected today. |
| `redirected_off_origin` | The address redirects to a different address. Apostra does not say which. | Paste the final address yourself. |
| `response_too_large` | The agent's reply was over 1 MB. | Make the agent's capabilities reply or tool list smaller. See [Tool list page size finding](https://docs.apostra.com/v3/agent-requirements.md#tool-list-page-size-finding). |
| `kind_not_offered` | The agent declares only protocols Apostra does not connect yet. The error lists them. | Apostra connects sales, creative and buyer agents. |
| `read_rate_limited` | You have read too many URLs. | Try again after `retry_after` seconds. |
| `kind_changed` | You sent a `kind` the agent does not declare. | Send the kind Apostra read, or leave `kind` out. |
| `needs_confirmation` | You saved before supplying a field in `needs`. | Send the field named in the error and save again. |
| `buyer_agent_not_connected_by_url` | The URL reads as a buyer agent, which Apostra does not connect by URL. | Create it with `save_buyer_agent`. |
| `agent_kind_mismatch` | The agent you named is not the kind the URL was read as, or is not a sales or creative agent. | Connect the agent with the URL that serves its kind. |
| `endpoint_control_unproven` | You asked for something an agent that is not yet verified as yours cannot have: Partner standing, a marketplace listing, use by another organization, or certification through another organization's source. | [Prove you control the URL](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours), then ask again. |

## Find your agent's places

In the web app, an Agents account lands on **My agents** when it owns no agents or
several, and on the **Overview** of its agent, with the left rail already
switched into it, when it owns exactly one. My agents stays in the rail. The chat box
is under the page, as everywhere else.

My agents lists **your agents**, one row each, with the agent's kind, its
certification stage (Not started, Testing, Waiting on you, Waiting on Apostra,
Waiting on the seller or Certified), its next step and who acts on it. A buyer
agent has no certification, so its status is its credential (Needs a
credential, Credential not used yet or Connected; see
[Buyer agents](https://docs.apostra.com/v3/connect-an-agent.md#buyer-agents)). Choosing
a row opens that agent. It lists every agent the account owns, including any Signal or Outcome agent it already holds,
25 at a time, and **Show more
agents** adds the next 25. An agent Apostra mapped to your account that nobody
has claimed is marked **Apostra mapped · unclaimed**, and an account administrator
can choose **Review and claim** in its row. Under the agents are, in this order:

* **Connect an agent** is for an agent you already run, whether it is a sales,
  creative or buyer agent. It opens the Connect an agent task. With no agents it
  is the main card. Once you have agents it is a button at the top right of the
  page instead, above the list. It shows only to an Admin of the account, who
  can connect agents; with no agents, anyone else sees the reason in the card.
* **Set up an agent on Apostra** is for an agent Apostra hosts for you, starting
  with a buyer agent that plans and buys media for your advertisers. The card is
  hidden until hosted agents are offered to your account, and appears on its own
  when they are.
* **Work from Claude Code or Codex** has the MCP address, the commands that
  install the Apostra skill in Claude Code and in Codex, and the sentence to say:
  "Connect my agent" with no agents, "Get my agent certified" after. Once you
  have agents it shows only its title, and **Show setup** opens the same
  commands in place.

The last rows are the guides ([Build an agent](https://docs.apostra.com/v3/build-an-agent.md), Connect an
agent and [Agent requirements](https://docs.apostra.com/v3/agent-requirements.md)) and links to the docs,
AdCP, the AAO and GitHub.

Whether an agent is verified as yours is not a status. An unverified agent's
proof is an attention finding ("Publish brand.json at your agent's domain to
prove you own this agent") that says what it still holds back: listing, Partner
standing and use by another organization. It does not stop certification
through your own storefront.

To work on one agent, choose it from the picker at the top of the left rail. The
picker works like the advertiser picker: each agent has a kind label, the agents
you chose most recently come first, you can search, and **My agents** returns
you to My agents. Under the picker are only that agent's places:

* **Overview**: what needs your attention, the agent's states, the checklist
  with the evidence behind it (live certification results, manual test runs,
  AdCP 4.0 readiness, capability declarations and, for a creative agent,
  conformance), the **Allow certification buys** switch and the agent's endpoint
  and protocol details.
* **Activity**: the calls Apostra made to the agent, grouped into certification
  runs. See [Read the calls Apostra made to your agent](https://docs.apostra.com/v3/connect-an-agent.md#read-the-calls-apostra-made-to-your-agent).
* **Inventory sources**: the sources connected to the agent.
* **Webhooks**: the recent inbound webhook outcomes, each refusal with its
  reason.

**API calls** stays under Account in both views. Each place is its own page.
Overview links to the agent's Activity, Inventory sources (Connections for an
agent that has no sources) and Webhooks pages, and each of those links back to
Overview. The changes you can make from a page are the **Allow certification
buys** switch and the one button each finding on Overview can carry (see
[Open the Overview page](https://docs.apostra.com/v3/connect-an-agent.md#open-the-overview-page)); the
other pages only read. Claude, ChatGPT and other MCP hosts open the same page
for the same place, so the web app and your assistant show you the same thing.
To change anything else about an agent, ask your assistant or call
`save_agent`.

`get_status` in an Agents account also returns, for each agent,
`findingsHeadline` (the finding the server chose to lead with, with its
severity and a summary), `findingCount` (how many findings have not passed yet,
whether they failed or Apostra has not checked them yet) and `findingCounts`
(the same findings by outcome). If the findings cannot be read, all three are
left out and the agent is still listed.

## See which sources an agent is attached to

`get` with `kind: "agent"` returns `relationships`: `count` is every source
attached to the agent, `items` lists the sources in your own organization by
name, and `hiddenCount` is the attached sources the read does not list, which
belong to other organizations' accounts and stay private to them. A source that
is still waiting for certification is listed like any other. Each item carries
its `state` (`ACTIVE`, `PENDING` or `DISABLED`) and, when the source is not
active, a `reason`, for example `pending: waiting for certification`. The same
`state` reads the same on the source itself: `get` with `kind: "inventory_source"`
returns `selling.blockers` with the same reason for a source that is not active,
`poweredByAgent.agent.currentSource.state` is the source's own state, and
`refresh_inventory_source_health` returns the blocking reason in
`readiness.reason`.

## Read the calls Apostra made to your agent

Apostra records the calls it makes to your agent, and you can read each one that
went through a source bound to your agent when the call was made. A call
recorded with no source, or through a source that was not bound to your agent at
that time, is not shown. The **Activity** page shows them for one agent, in two
parts.

* **Certification runs.** Each [live certification run](https://docs.apostra.com/v3/certification.md#read-a-run-and-the-calls-apostra-made-to-your-agent)
  is one session, newest first. Its steps run from the first read of your
  products to the evaluation, in the order they happened. Each step shows when
  it happened, whether its calls succeeded, failed or are still pending, and a
  **View call** action for each call. The step that reads your products has no
  call to view, because Apostra reads them from its stored copy of your catalogue
  instead of calling your agent.
* **Other calls.** The calls that belong to no certification step, newest first,
  such as `get_adcp_capabilities` and `get_products`. Each has a **View call**
  action.

**View call** opens one call in place with a way back to the list. It shows what
Apostra sent, what your agent returned, the HTTP status, the status your agent
reported, how long the call took and the error. Apostra removes its own
credentials and the values under keys that look like credentials, such as
`token`, `secret` or `password`, and shows them as `[REDACTED]`. Each body is
capped at 32,768 characters and marked as cut short when it is longer. Apostra
keeps request and response bodies for 90 days. After that a call still shows its
timing and status, with no body.

You see every call Apostra made to your agent, whichever seller's storefront it
came from. Beside the calls, a certification run shows the facts listed under
[Read a run and the calls Apostra made to your agent](https://docs.apostra.com/v3/certification.md#read-a-run-and-the-calls-apostra-made-to-your-agent).
You never see another seller's prices, buyers or settings, or anything else that
was never sent to your agent. The history starts when your organization took the
agent. Moving the agent between accounts of one organization keeps it. A call
made before your organization took the agent, because Apostra staff assigned it
to you or it moved from another organization, is not shown. The seller whose
storefront the agent serves does not read this page.

On the Overview page, a certification finding that comes from a run has a
**View session in Activity** action. It opens the Activity page at that run.

To open the page, ask your assistant to open your agent's activity, or call
`open_agent_activity_page` with the agent's `agentId`. Only the account that owns
the agent can open it, and only while the agent is not archived. It changes
nothing. Archiving an agent does not remove its certification sessions: you can
still find and read them with `search` and `get`. To read the same runs and calls
without the page, use `search` and `get` with `kind: "session"`, as
[Read a run and the calls Apostra made to your agent](https://docs.apostra.com/v3/certification.md#read-a-run-and-the-calls-apostra-made-to-your-agent)
describes.

## Kinds of agent

| Kind | What it does |
| - | - |
| Sales agent | Sells a publisher's inventory to buyers. It needs a sales mode. |
| Creative agent | Defines creative formats and builds or renders creative for buyers and sellers. It has no sales mode. |
| Buyer agent | Buys on behalf of an advertiser, using the advertiser grants an organization gives it. |
| Proposal agent | Answers buyers' proposal requests for a seller. For now, only Apostra's own accounts in the modular sales agent beta can register one, and only from its URL. See [Connect your own proposal agent](https://docs.apostra.com/v3/connect-a-proposal-agent.md). |

When the agent is connected, the task reads it back for its sales role
(`salesRole` on the agent read: `storefront`, `inventory` or `proposal`) and
compares it with what you chose:

* **It matches.** The task shows the role Apostra read. A sales agent that
  serves buying without proposals reads as an inventory agent and counts as a
  match, because an inventory agent is a sales agent.
* **It differs.** The task shows a note, not an error: "You chose an inventory
  agent, but this agent serves something else", with what Apostra reads it as.
  Apostra connects the agent as what it serves. A proposal agent that also books reads as a sales agent: the
  note appears before you connect, and it connects as a sales agent.
* **No role.** When the agent has not been read, or serves neither proposals
  nor buying, the task shows no role and no note.

The Connect an agent task registers sales, creative and buyer agents. A buyer agent
also needs a credential before it can call Apostra: follow
[Manage buyer agents](https://docs.apostra.com/v3/buyer-agents.md).

## Sales modes

A sales agent declares how it sells. The mode follows the AdCP buying modes the
agent supports.

| Mode | Meaning |
| - | - |
| Wholesale | The agent lists its products as a catalog, and a buyer can browse and buy them as declared. |
| Composing | The agent builds products to answer a buyer's brief. |
| Both | The agent does both. |

When Apostra refreshes a connected sales agent's capabilities, the agent's own
declaration keeps the mode current. An organization administrator can confirm or
override the mode with `save_agent`, recording a reason.

## The role an agent plays

An agent's kind says what you registered it as. Its **sales role** says which half
of the sales job it actually does. `get` for an agent returns it as `salesRole`.

| `salesRole` | What the agent serves |
| - | - |
| `storefront` | It answers buyers: proposals and buying, or buying alone when it takes briefs and does not publish a wholesale catalog. A storefront books through one or more inventory agents. |
| `inventory` | It holds the inventory: it buys and declares `wholesale` in `media_buy.buying_modes`, publishing its products so a storefront can build its catalog from them. |
| `proposal` | It only proposes. It answers `request_proposals`, `refine_proposals`, `decline_proposals` and `accept_proposal`, and books nothing. |

Apostra works the role out each time you read the agent, from the capabilities
and tool list it last returned, so it follows the agent when the agent changes.
You never set it, and it is not a certification: it says what the agent serves,
not that the agent is certified in that role.

`salesRole` is `null` when:

* Apostra has not read the agent yet, for example because it needs credentials for
  every call;
* the agent serves neither proposals nor buying;
* the agent is attached to several sources and their stored capabilities give
  different roles; or
* Apostra only has a snapshot of the agent's tools, which carries no buying modes,
  and the agent buys without proposals. Such an agent could be an inventory agent or
  a storefront that takes briefs, and the snapshot cannot say which.

`role` is a different field: it still holds the kind, such as `SALES`.

## Test and certify your agent

A sales agent reaches buyers, testing and certification through a storefront.
The agent stays in your Agents account, and a storefront uses it as an
inventory source. Apostra's certification buyer buys through each source that
uses your agent that is active, or pending in your own organization with
healthy or degraded health, so an agent with no such source cannot be
certified. A source you connect starts pending, and you do not have to
activate it first: turn on **Allow certification buys** and Apostra certifies
through your pending source. When the agent passes, the source goes live.

You do not need a storefront of your own to do this. From your Agents account
you connect the agent to your organization's **test storefront**, which
Apostra creates for you:

* It is free and is never listed on Apostra. Nothing on it is offered
  to anyone outside your organization.
* It holds only your organization's own agents. It cannot take an ad server, a
  partner's agent or a linked storefront.
* It needs no plan change and no approval from an organization admin, and it
  has none of the go-live checks for listing on Apostra (brand domain, billing, currency,
  accepted countries).
* Your organization has one. Apostra creates it the first time an Admin of the
  Agents account connects an agent.

Follow these steps in order. Steps 1 to 3 take an agent from registered to
certified. Step 4 is optional, and step 5 is a quick check you can run at any
point.

1. **Register the agent.** In your Agents account, create a sales agent as
   described in [Start building](https://docs.apostra.com/v3/connect-an-agent.md#start-building). See [Sales modes](https://docs.apostra.com/v3/connect-an-agent.md#sales-modes)
   for the choice it asks you to make.
2. **Connect the agent to your test storefront.** Stay in your Agents account.
   Choose **Connect this Agent** on the agent's page, or call
   `save_inventory_source` with only the agent's `agentId`. It opens the
   connection form with the agent's registered address already filled in, and
   you enter its credentials there. Credentials never pass through chat.
   Submitting the form creates the source, pending, on your organization's test
   storefront.
   * **Who can do it.** An Operator or Admin of the Agents account that holds
     the agent, signed in as themselves. The role that counts is your role on
     the Agents account: you need no role on the test storefront. The first
     connection, which creates the test storefront, needs an Admin. Until then
     an Operator is told that an Admin of the Agents account creates it the
     first time they connect an agent.
   * **Which agents.** Only agents your Agents account holds. From an Agents
     account, `save_inventory_source` takes `agentId` and nothing else.
   * **Credentials.** The form takes an API key, a bearer token, a username and
     password, or no authentication. Connecting without authentication is
     allowed here, as in an Agents account, because the test storefront is for
     testing.
   * **OAuth.** An agent that signs in with OAuth cannot be connected from the
     Agents account yet. An organization admin can connect it from the
     organization's test storefront account: name that account with its
     `accountId` (see [Name the account on every call](https://docs.apostra.com/v3/name-the-account.md))
     and call `save_inventory_source` with the agent's `agentId` there.
     If you would rather certify through a storefront your organization sells
     through, connect the agent there instead: in that Seller account, call
     `save_inventory_source` with the agent's `agentId`. You need to be an
     Operator or Admin of that account. To create a Seller account, an
     organization administrator calls `save_account` with `accountType: "seller"`
     and approves the request on the website; the organization's plan must allow
     the type of account you choose. See
     [Manage organization accounts](https://docs.apostra.com/v3/account-access.md#manage-organization-accounts).
     Connecting your own agent to your own storefront does not by itself change
     your organization's plan. Your organization counts as offering agents to
     other organizations only once its Partner standing is active.
3. **Allow certification buys.** You do not need to
   [prove control of the agent's URL](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours)
   first: an agent behind your own storefront is reached only through Apostra.
   Turn on **Allow certification buys**, or send
   `certificationRequested: true` with `save_agent`. See
   [Allow certification buys](https://docs.apostra.com/v3/connect-an-agent.md#allow-certification-buys).
   Apostra then starts certification on its own, through its certification
   buyer, on each active source that uses the agent and on each pending source
   of your own organization whose health is not failing. When the agent passes,
   the pending source goes live. Setting the source to `ACTIVE` yourself is
   refused until then. See
   [When Apostra starts a run](https://docs.apostra.com/v3/certification.md#when-apostra-starts-a-run),
   [Test buy size](https://docs.apostra.com/v3/certification.md#test-buy-size) and
   [What is certification?](https://docs.apostra.com/v3/certification.md).
4. **Optional: test as a buyer.** To see your agent the way a buyer does, create
   a buyer account in the same organization with `save_account` and
   `accountType: "buyer"`. Create a sandbox advertiser in it, which spends
   nothing. Your organization's storefronts, the test storefront included, are
   available to its own advertisers whether they are listed or not, but the
   storefront still has to be ready to take a buy. Name your storefront with
   `sellerAccountIds` when the buyer calls `request_proposals`. The test
   storefront is never listed, so the buyer reaches it only by naming it this
   way. A request that names no sellers does not contact it, and a buyer in
   another organization cannot reach it. See
   [Sandbox advertisers and live spend](https://docs.apostra.com/v3/account-access.md#sandbox-advertisers-and-live-spend)
   and [Storefronts](https://docs.apostra.com/v2/buyer/storefronts/overview.md). This test is not a
   certification run, and it does not replace step 3.
5. **Check that the endpoint is alive.** On the agent's **Overview** page, open
   **Manual test runs** in the checklist and choose the endpoint check. It calls the agent's endpoint with
   `get_adcp_capabilities` and `get_products` and a fixed discovery brief, and it
   creates no buy and spends nothing. It is offered while the agent has no
   source, and Apostra limits it to 10 runs an hour for each agent. Once the agent
   has a source, use **Test product discovery** in that source's diagnostics
   instead. A pass shows that the endpoint answers. It is not a certification
   result. When the check cannot run, the agent read's `validationSkill` lists
   the `endpoint-brief` profile as `UNAVAILABLE`, and its `reason` says why and
   what to do: a source uses the agent, no endpoint is registered for its
   production version (connect it from its URL), Apostra has not read it yet
   (connect it from your Seller account), or the agent is not claimed yet.

While an agent has no active source and no pending source of your own organization
with healthy or degraded health, the agent read says so with the finding
`certification.no_source`. If the agent is attached to no source, its action is
step 2 above: connect the agent to your test storefront. If it is already
attached to a source in your own organization that cannot be certified through
yet, because the source is `DISABLED` or is `PENDING` with health that is not
healthy or degraded, the finding names that source and its state and says the
agent is already attached, so there is nothing to attach again. Bring a pending
source's health up with `refresh_inventory_source_health`, then turn on Allow
certification buys; Apostra certifies through your pending source, then the
source goes live. A disabled source has to be turned back on with
`save_inventory_source`. When the agent also has an `implementation.not_reachable`
or `implementation.agent_error` finding, fix that first: a pending source whose
health is failing because your agent does not answer, or answers with an error,
does not turn healthy until the agent answers the call. In an Agents account the
agent read lists the endpoint check (`endpoint-brief`) first, and shows the
brief and transaction tests (`brief-only`, `transaction`) as unavailable, with
the reason "Run this from a buyer account that can buy through a storefront
this agent is in." Those tests buy through a storefront.

> [!NOTE]
>
> An agent that another organization owns is a partner's agent, and a different
> route connects it: the partner publishes how publishers connect, and the agent
> must be certified first. The test storefront holds only your own
> organization's agents, and a storefront in another organization cannot use
> your agent this way. Register the agent in an Agents account in the
> storefront's organization, or ask Apostra support.

## Allow certification buys

**Allow certification buys** is the control that decides whether Apostra sends
certification buys to a Sales agent. On means Apostra sends them. Off means it
sends no new ones; a certification buy already running finishes. Set it on the agent's page, or with one field,
`certificationRequested`, on `save_agent`. Both save the same setting: you save
the value you want, and saving the value the agent already has changes nothing.

With it off, Apostra sends no certification buys, so only your real traffic can
show your agent working. See
[The certification deadline](https://docs.apostra.com/v3/certification.md#the-certification-deadline)
for when buys start to depend on a pass.

On the agent's Overview page, under **Certification buys**, **Allow certification
buys** is a switch you can turn on or off. The page shows the switch only to
someone who can save it, and shows Apostra's own message if a save is refused.
Anyone else sees whether it is on. The Overview page that an MCP host opens (see
"Open the Overview page" below) shows the same switch. You can also ask your
assistant, or call `save_agent`; to turn it off, send
`certificationRequested: false`.

```json theme={null}
{
  "agentId": "AGENT_ID",
  "certificationRequested": true
}
```

| Value | Meaning |
| - | - |
| `true` | Certification buys are allowed. Apostra starts certification runs for the agent. |
| `false` | Apostra sends no new certification buys. Buys that are already running continue. |

`search` and `get` for `kind: "agent"` return `certificationRequested` for every
agent in the account, `false` until you set it.

* **Who can set it.** An Operator or Admin of the Agents account that owns the
  agent, signed in as themselves. An Operator is enough because a certification
  buy spends nothing (see
  [Which Source certification buys through](https://docs.apostra.com/v3/certification.md#which-source-certification-buys-through)).
  A Member sees whether it is on. Service tokens, delegated sessions and
  impersonation cannot set it, and another account's agent answers as not
  found.
* **Which agents.** Sales agents. Certification runs on live traffic for Sales
  agents only, so `true` on a Creative agent is refused. Saving `false` is
  always accepted.
* **What it does.** Apostra starts certification runs on its own for each
  active Source that uses the agent, with no one at Apostra acting. If no run
  starts within a day, ask Apostra support. See
  [When Apostra starts a run](https://docs.apostra.com/v3/certification.md#when-apostra-starts-a-run).
* **With a rename.** `displayName` and `certificationRequested` can be sent in
  one call. Each is saved on its own, so if a call fails partway, repeat it with
  the same values. Renaming needs an Admin: an Operator who sends both is
  refused with a message that names `displayName`, and neither is saved. Send
  `certificationRequested` on its own instead.

## See whether Apostra exempted an agent from certification

Apostra staff can exempt a Sales agent from certification until a date. The
exemption belongs to the agent, not to any one inventory source, and until that
date it counts wherever a certification pass counts: an inventory source can go
live on the agent, including a publisher in another organization connecting to
it for the first time, as if the agent had passed, and the agent takes new buys
for every use case. Its other checks still apply. When the exemption ends, the
agent takes new buys only for the use cases it has passed. See
[What a pass unlocks](https://docs.apostra.com/v3/certification.md#what-a-pass-unlocks) and
[The certification deadline](https://docs.apostra.com/v3/certification.md#the-certification-deadline). Only Apostra
staff set, extend or clear an exemption. You cannot set it, and `save_agent`
does not accept it.

`get` for `kind: "agent"` returns `certificationExemption` beside
`certificationRequested`:

| Value | Meaning |
| - | - |
| `{ "until": "2027-01-31T00:00:00.000Z" }` | Apostra exempted the agent from certification until that date and time (UTC). |
| `null` | The agent has no exemption, or its exemption has ended. |

The field is read-only. Apostra does not show the reason for an exemption or who
set it. To ask for one, contact Apostra support.

## Archive one agent

Archive an agent you no longer want Apostra to use. An archived agent receives
nothing: Apostra sends it no buys, certification runs or requests, and it no
longer shows in `search` or `get` for `kind: "agent"`. Archiving one agent
leaves the others alone, including the agents that share its operator. To
archive an operator and all its agents at once, ask Apostra support.

Call `save_agent` with the agent's `agentId` and `isArchived: true`:

```json theme={null}
{
  "agentId": "AGENT_ID",
  "isArchived": true
}
```

Send `isArchived` on its own. If you send it with `displayName` or
`certificationRequested`, Apostra refuses the call and saves nothing. Archiving
an agent that is already archived changes nothing and succeeds.

* **Who can archive.** An Admin of the Agents account that owns the agent,
  signed in as themselves, and Apostra staff acting in your account under a
  support elevation, for example when you ask support to do it. An Operator, a
  Member, a service token or a delegated session cannot. Another account's
  agent answers as not found.
* **When Apostra refuses.** Apostra does not archive an agent while it is still
  in use. The refusal says what holds it and how many, and changes nothing:
  a Source, active or pending, that still uses it; a live buy that has not
  ended and reports through a Source the agent serves; or a binding that only
  Apostra staff can close. Disconnect the Sources and let or make the buys end,
  then archive again.
* **Restore it.** Call `save_agent` with the same `agentId` and
  `isArchived: false`. The agent comes back as it was, with its name and
  settings. Apostra does not reconnect its Sources: connect them again. If
  another agent in the account has taken the name since, rename that agent and
  restore again. If Apostra staff retired the agent's whole operator, ask Apostra
  to restore it.
* **The record.** Every archive and restore is written to the account's audit
  log.

## Add a sign-up link to your connection setup

A sales agent you run for other publishers has a published connection setup: the
non-secret definition a publisher follows to connect. The setup can carry an
optional `signupUrl`, a public `https` page where a publisher who has no
credentials from you signs up with you.

* **What it is for.** A publisher either already has credentials from you or
  follows `signupUrl` to get them. You do not approve each publisher, and
  credentials are never sent through the assistant: the publisher enters them in
  the secure credential form.
* **What is accepted.** A public `https` URL with no credentials in it, no query
  string or fragment, and no private or loopback host. Anything else is refused
  when you save the setup.
* **Where it shows.** Your own read of the setup and the connection form a
  publisher sees when it connects to your agent.
* **Leave it out** if you hand out credentials another way.

## See where each agent stands

Call `get_status` in an Agents account to see every agent's **states** and
its **headline finding**. A state is a fact Apostra holds about the agent. The
states are independent: an agent can be certified without an owner test run, and
in one storefront as private and another as listed. They are not steps on a
ladder, and no state implies another.

| State | What it says |
| - | - |
| `states.endpointRegistered` | Apostra has an endpoint for the agent: the one registered for its production version, or, when that version has none, the URL a source that uses the agent calls. An Apostra-mapped agent Apostra already calls through a source reads `true`, so you never need to connect it again. `null` for a buyer agent, which has no endpoint. `implementationHealth` on the agent read says whether Apostra has observed the implementation, and the two are read together. |
| `states.storefronts` | `{ total, listed, private }`: the storefronts with a source that uses the agent, pending sources included, how many of them Apostra lists, and how many it does not. It counts the same sources as the agent's `relationships`. Sales agents only. An agent reaches buyers only through a storefront, so `total: 0` means it cannot be certified yet. A pending source counts, so a total above 0 does not mean certification can run: `certification.no_source` says whether it can. `total` counts storefronts that use the agent, not storefronts that are connected or healthy, and `listed` counts the ones that are publicly listed. The Overview page words it as "Used by 1 storefront · 0 publicly listed". A source's health and go-live status are separate facts, on the source. |
| `states.certified` | Live certification passed on at least one path and failed on none, and the agent lacks no capability that is required from a date that has arrived. From 1 February 2027 that includes canonical creative formats, Reliable Reporting, the compact lifecycle and webhook signing: an agent without one is no longer certified on its date, and its headline finding names what it lacks. See [Getting ready for AdCP 4.0](https://docs.apostra.com/v3/adcp-4-readiness.md). `null` for creative and buyer agents, which have no certification today. |
| `states.listedForOtherOrganizations` | Another organization's Seller Account finds the agent when it searches partner sales agents: the agent has a published setup, and your account has active Partner standing. Sales agents only. |
| `states.latestTest` | `passed`, `failed`, or `null` when no test has run: creative conformance for a creative agent, the no-spend test or a transaction test for a sales agent. Live certification results are separate and do not count here. The Overview page calls it the latest manual test. `null` for a buyer agent, because Apostra does not record a test run for buyer agents yet. |
| `states.credential` | `{ issued, authenticated }` for a buyer agent: a credential is bound to it, and that credential has made an authenticated call to Apostra. `null` for other kinds. |
| `states.notReadYet` | `{ reason }` when Apostra recorded the agent's URL without reading the agent, because it needs credentials for every call (`reason: "authentication_required"`). It is `null` once the agent was read, and for a buyer agent. See [Register an agent that needs credentials](https://docs.apostra.com/v3/connect-an-agent.md#register-an-agent-that-needs-credentials). |

A state that does not apply to an agent's kind is `null`. Apostra never reports
a state it has no record of: an agent with no test run has `latestTest: null`,
not a made-up value.

**The headline finding says what to do next.** Each agent carries
`findingsHeadline`, the one finding to act on first, and `get` for the agent
returns every finding with its fix. `get_status` offers it as `agent_next_step`
for the agent whose headline is most urgent: a blocking finding first, then one
Apostra has not been able to check yet that names who acts, then the attention
finding with the nearest date, and only then a check that has not run and that
nobody has to act on yet. See [Findings: what needs your attention](https://docs.apostra.com/v3/connect-an-agent.md#findings-what-needs-your-attention) for what blocking,
attention and advisory mean.

**Count problems apart from checks that have not run.** `findingCount` counts every finding
that has not passed, so it includes findings Apostra has not checked yet, and an
agent with `findingCount: 26` may have failed only four of them. `findingCounts`
splits the same findings by outcome:

| Key | What it counts |
| - | - |
| `findingCounts.blocking` | Failing findings that stop something today. |
| `findingCounts.attention` | Failing findings that will block on a published date, or that degrade something now without stopping it. |
| `findingCounts.advisory` | Failing findings where nothing stops and a fix would still help. |
| `findingCounts.unchecked` | Findings Apostra has not checked yet, or checked without a decisive result. They are not failures. |

A finding that passed is counted in none of the four. The first three are the
problems; `unchecked` is work Apostra still owes the agent.

> [!WARNING]
>
> **`stage`, `nextStage`, `finalStage` and `stuckOn` are deprecated.** They still
> come back with the values they had, and Apostra removes them no earlier than 3
> December 2026. Read `states` for what is true of an agent and the headline
> finding for what to do next. While an agent has no headline finding, `stuckOn`
> still names its next step, so no step is lost before the removal. While one
> does, the text of `get`, `search` and `get_status`, and the Overview page, show
> only the headline: they leave out `stuckOn`, the agent's `nextAction` and
> `certificationNextStep`. The fields themselves keep coming back in the
> structured result until they are removed.

The status also lists build calls for each kind of agent and links to the developer
resources: Build and certify an agent, these guides,
the AdCP specification, the Apostra GitHub repository and the `apostra-developer`
plugin for Claude Code and Codex.

An agent connected from a URL also carries `endpointControl`, `unverified` or
`verified`. While such an agent is not yet verified, the
`endpoint_control.unverified` finding, and a creative agent's `stuckOn` once it
has passed its conformance test, name the file and entry to publish, as
[Prove your agent is yours](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours) explains.

The same `states` come back whenever you read an agent in an Agents account:
`get` with `kind: agent` and each result of `search` with `kind: agent` carry
them, with the same values `get_status` reports, beside the deprecated `stage`,
`nextStage`, `finalStage` and `stuckOn`. The text version of each read says the
states in a sentence. My agents and the Agent page show each agent's certification
stage, or a buyer agent's credential, and its next step; the Agent page still shows the deprecated stage and what is
stuck until those fields are removed, and the web app's Agent page adds a button
for the next step. In any other kind of account an
agent read carries no states.

### Buyer agents

Every buyer agent in an Agents account has an agent record of the `buying`
kind, the name AdCP gives a buyer agent in `brand.json`. `save_buyer_agent`
creates the principal and the record together (`save_agent` registers sales and
creative agents only), and `get_status` lists the buyer agent beside your sales
and creative agents.

The record is a handle for tracking the agent. The principal stays the
credential, and what the agent may do stays as advertiser grants on your Buyer
account. Creating the record grants nothing and changes no credential.

A buyer agent's state is its credential: `states.credential` says whether a
credential is bound to it (`issued`) and whether that credential has made an
authenticated call to Apostra (`authenticated`). Until then the
`credential.issued` and `credential.authenticated` findings, and `stuckOn` until
it is removed, ask for
the credential (`save_buyer_agent` with `credentialHandoff: true`) or for the
first call.

My agents shows the same state as the buyer agent's status:

| Status | What it means | What to do |
| - | - | - |
| Needs a credential | No credential is bound to the agent, so it cannot call Apostra. | Open the agent. An administrator chooses **Set up a credential**, and Apostra shows the credential once, for you to give to your agent. See [Hand off credential setup](https://docs.apostra.com/v3/buyer-agents.md#hand-off-credential-setup-after-building-an-agent). |
| Credential not used yet | A credential is bound, and the agent has not called Apostra with it. | Give the credential to your agent and have it make one call to Apostra. |
| Connected | The agent has called Apostra with its credential. | Nothing. |

Apostra does not record a test run for buyer agents yet, so
`latestTest` stays `null`. Certification for buyer agents is not available yet,
so `certified` is `null` too; [How certification works](https://docs.apostra.com/v3/certification.md)
explains what it will take. Retiring a buyer agent
removes its record from the list; renaming it renames the record.

An organization with a buyer agent that was registered before the record
existed gets the record from Apostra when the organization has exactly one
Agents account. With several, save the agent from the account that should
hold it (rename it, or request its credential handoff) and the record is created
there.

## Findings: what needs your attention

Read an agent with `get` (`kind: "agent"`) to see its `findings`. A finding is
one thing Apostra checked about the agent, in the order of the setup checklist:
declarations, behaviour, tests, certification, then the AdCP 4.0 capabilities.
Each has an `outcome` of `passed`, `failing`, or `null` when there is no
decisive result: Apostra has not checked yet, or the check ran and was
inconclusive. The `summary` says which. A behaviour finding Apostra has not
checked yet says why in `whatWeSaw`: no matching calls in the last seven days,
no evaluation yet, or no Source whose calls we judge
([Behaviour findings](https://docs.apostra.com/v3/agent-requirements.md#behaviour-findings-and-how-to-fix-them)).
An inconclusive certification use case
says when it ran, carries the reason the run recorded in `whatWeSaw`, and says
what you can do next in `howToFix`. `search` with `kind: "agent"` returns each agent's headline finding
(`findingsHeadline`) and `findingCount`, the number of findings that have not
passed. Your organization and Apostra staff, including support acting for your
organization, can read findings. A partner that only connects to your agent
cannot.

Every finding also names an `owner`, the role that has to act on it:

| `owner` | Who has to act |
| - | - |
| `agent_developer` | Whoever builds and runs the agent: its code, its declared capabilities, its settings, or the way it answers Apostra. The page shows it as "You" to this person. |
| `seller` | The seller whose storefront uses the agent, for a setting or decision only the seller can make. |
| `apostra` | Apostra, when the change is on Apostra's side. |
| `null` | Nobody has to act yet, for example a certification run still collecting live traffic, or a finding that passed. |

The two are often one company, but not always: a seller can use a partner's
agent. `owner` is a different question from `stops.by`, which says who enforces
a block.

A declaration finding (`declaration.*`) judges what the agent declared in its
last read. Apostra reads those declarations from the agent's Sources as soon as
a Source has read the agent, including a Source that is still `PENDING` because
the agent is not yet certified, so a connected agent shows each declaration as
`passed` or `failing` right after the read, with `whatWeSaw` and `howToFix`
naming the field to declare. The `creative_kind` declaration waits for the
Source's first products, and shows `null` until they arrive. While an agent has
not been read (`notReadYet` is set), each declaration finding says
`not read yet` and gives the same `howToFix`: connect the agent from your
Seller account with its credentials. The `stuckOn` of an agent that a Source
read with credentials says that no endpoint check has run, and that you start
it from the Agent page, because the read does not run it.

A failing finding has a `severity` that says what is at stake:

| Severity | What it means for you |
| - | - |
| `blocking` | Something stops today. `stops` says what (`buying` or `certification`) and who stops it. Apostra's own code stops it, or a buyer's tools fail a buying operation. |
| `attention` | It will block on a date Apostra has published (`dueAt`), or it degrades something now without stopping it. |
| `advisory` | Nothing stops. You would be better off fixing it. |

A finding's `summary` is one sentence of 120 characters or less, in Apostra's
own words, so a list or a page can show it on one line. Names and values your
agent or a seller wrote, lists such as the untested formats, and the longer
explanation of what the finding means are in `whatWeSaw`, and the change to make
is in `howToFix`. A summary says "cannot" only when its severity is `blocking`,
and only about what `stops` names.

One finding is the **headline**, marked `headline: true`, and its action is the
agent's `nextAction`. It is the missing endpoint while neither the agent's
production version nor any source that uses it has a URL, because nothing else
can happen first. Otherwise it is the first
failing blocking finding. If none blocks,
it is the first finding with no decisive result yet: not checked, or
inconclusive. If every check has a decisive result, it
is the attention finding with the nearest `dueAt`, then any attention finding
with no date. An advisory finding never becomes the headline.

Every failing finding carries `whatWeSaw`, `howToFix` and `docsUrl`. `howToFix`
names the change to make, and where the change is in your agent rather than in
Apostra, the finding's `action` is `NONE`. The code below says where each
finding is explained, and the next section says who has to act on each.
Delivery-window calendar alignment is reported as
`behaviour.reporting_window_matches_breakdown_date`; see
[Reporting window matches breakdown date finding](https://docs.apostra.com/v3/agent-requirements.md#reporting-window-matches-breakdown-date-finding).

| Code | What it checks | Severity |
| - | - | - |
| `declaration.adcp_v3` | You declare AdCP major version 3. | Attention. Buyers' tools read an agent without it as AdCP 2. |
| `declaration.supported_billing` | You list agent or operator billing. | Attention. |
| `declaration.connected_credential` | You accept the connected credential for every buyer. | Not raised. Certification runs on the connected credential whatever `account.require_operator_auth` says, because the storefront is the operator. |
| `declaration.account_requests` | You take buyer account requests. | Blocking. Certification skips an agent without `sync_accounts` and `list_accounts`. |
| `declaration.update_media_buy` | You take buy corrections: you list `update_media_buy` and run it with its optional fields. See [Takes buy corrections](https://docs.apostra.com/v3/agent-requirements.md#takes-buy-corrections). | Blocking. Certification skips an agent without `update_media_buy`. |
| `declaration.buying_modes` | You declare `media_buy.buying_modes` with `brief`, `wholesale` or both. See [Declare your buying modes](https://docs.apostra.com/v3/agent-requirements.md#declare-your-buying-modes). | Advisory. Reported only for now: no code stops on it, and it never becomes the headline. Apostra never requests the wholesale catalogue of an agent that does not declare `wholesale`, so buyers see none of its wholesale products. Briefs reach it only if the product mode its owner or Apostra set includes them. |
| `declaration.buying_modes_mismatch` | Once connected as a source, the buying modes the agent declares support the mode confirmed by its owner. See [Declare your buying modes](https://docs.apostra.com/v3/agent-requirements.md#declare-your-buying-modes). | Attention. Update the declaration or the confirmed mode so they agree. |
| `declaration.audience_targeting` | If you declare `audience_include` or `audience_exclude`, you also list `sync_audiences` or declare `media_buy.audience_targeting`. See [Declare how audiences reach you](https://docs.apostra.com/v3/agent-requirements.md#declare-how-audiences-reach-you). | Advisory. Reported only for now: it stops neither certification nor buying, and it never becomes the headline. |
| `declaration.creative_transport` | You take creatives: you list `sync_creatives`, or you allow creatives inline on a buy. See [Takes creatives](https://docs.apostra.com/v3/agent-requirements.md#takes-creatives). | Advisory. Reported only for now: it never becomes the headline. Certification skips every family of an agent that lists no `sync_creatives`, as `seller_sync_creatives_unsupported`, and buyers have no way to give the agent a creative. |
| `declaration.discovery_targeting` | Storefront discovery did not leave your products out of buyers' answers in the last 14 days for targeting your Agent does not declare. See [Declare the targeting you honour](https://docs.apostra.com/v3/agent-requirements.md#declare-the-targeting-you-honour). | Advisory. Reported only: it stops neither certification nor buying, and it never becomes the headline. |
| `declaration.creative_kind` | Your products declare a creative format Apostra can supply. | Attention. |
| `declaration.product_channels` | Your products declare AdCP channels, counted as storefront readiness counts them. | Advisory. Buyers filtering by channel do not find a product with no channel; the sources still receive requests. It never becomes the headline. |
| `declaration.product_format_declarations` | Your products declare the same formats in `format_ids` and `format_options`. A product whose lists disagree is left out of buyers' answers, or served only after Apostra reconciles the two lists. See [Keep your two format lists in agreement](https://docs.apostra.com/v3/agent-requirements.md#keep-your-two-format-lists-in-agreement). | Advisory. Reported only: it stops neither certification nor buying, and it never becomes the headline. |
| `behaviour.responsiveness`, `behaviour.async_completion`, `behaviour.call_success_rate`, `behaviour.honours_request`, `behaviour.account_resolution`, `behaviour.lifecycle_agreement`, `behaviour.changes_announced`, `behaviour.ended_buys_not_active`, `behaviour.reachability`, `behaviour.delivery_report_format` | The behaviour baseline's checks that can stop new buys. `behaviour.delivery_report_format` reads a flag when a source sends the AdCP 3.0 bare delivery report, or sends a delivery report that fails the schema, and from 1 December 2026 a blocker when two reports from one source are refused with `400` within seven days. See [Delivery report format finding](https://docs.apostra.com/v3/certification.md#delivery-report-format-finding). | Attention. A blocker stops the agent's certification pass counting; a flag stops nothing. |
| `behaviour.payment_terms`, `behaviour.idempotent_account_sync`, `behaviour.idempotent_retries_replayed`, `behaviour.reporting_configuration_echo`, `behaviour.reporting_timezone_matches_declaration`, `behaviour.declarations_match_behaviour`, `behaviour.reconciliation_not_stuck`, `behaviour.rejected_buys_not_active`, `behaviour.status_not_flapping`, `behaviour.live_buys_serving`, `behaviour.creative_approvals_after_sync`, `behaviour.creative_changes_declared`, `behaviour.creative_assignments_answered`, `behaviour.creative_assignments_on_buys_answered`, `behaviour.creative_assignments_kept`, `behaviour.creative_approvals_use_buyer_ids`, `behaviour.daily_budget_held_on_lifetime_buy`, `behaviour.property_delivery_reported`, `behaviour.audience_expansion_not_requested`, `behaviour.valid_responses`, `behaviour.unscoped_list_read_answered`, `behaviour.tool_list_page_size`, `behaviour.delivery_read_responsiveness`, `behaviour.account_calls_honour_auth_declaration`, `behaviour.wholesale_catalog_published`, `behaviour.buys_judged_on_named_products`, `behaviour.machine_readable_errors`, `behaviour.creative_errors_carry_recovery`, `behaviour.creative_review_verdict_readable`, `behaviour.delivery_by_creative`, `behaviour.delivery_unbooked_packages`, `behaviour.discovery_brief_accepted`, `behaviour.adcp_request_fields_accepted` | The behaviour baseline's reported checks. `behaviour.reporting_configuration_echo` reads a flag when `sync_accounts` or `list_accounts` does not return the requested reliable-reporting configuration exactly, including `coverage_requirement`. See [Reporting configuration echo finding](https://docs.apostra.com/v3/agent-requirements.md#reporting-configuration-echo-finding). `behaviour.reporting_timezone_matches_declaration` reads a flag when a delivery response states a reporting timezone different from the one every product on the media buy declares. See [Reporting timezone matches declaration finding](https://docs.apostra.com/v3/agent-requirements.md#reporting-timezone-matches-declaration-finding). `behaviour.idempotent_retries_replayed` reads a flag when your agent answers `IDEMPOTENCY_CONFLICT` to a request Apostra sends again, unchanged and under the same `idempotency_key`, after it answered the first send. See [Idempotent retries replay finding](https://docs.apostra.com/v3/agent-requirements.md#idempotent-retries-replay-finding). `behaviour.reconciliation_not_stuck` reads a flag when a seller-confirmed targeting, budget/bid price, name, or flight-date change your agent received has had an unknown outcome for more than 24 hours. See [Reconciliation not stuck finding](https://docs.apostra.com/v3/certification.md#reconciliation-not-stuck-finding). `behaviour.rejected_buys_not_active` reads a flag when your agent reports a buy `active` for more than 15 minutes while every package that can still serve has had all of its creatives rejected. See [Rejected buys not active finding](https://docs.apostra.com/v3/certification.md#rejected-buys-not-active-finding). `behaviour.live_buys_serving` reads a flag when your agent reports a buy `active` inside its flight for more than 15 minutes while no package that can still serve holds a creative, or while a package is paused, beside one that still serves, that Apostra never asked it to pause. See [Live buys serving finding](https://docs.apostra.com/v3/certification.md#live-buys-serving-finding). `behaviour.creative_approvals_after_sync` reads a flag when your agent answers a creative sync for a buy with success and then never lists a creative the sync carried in `creative_approvals` on any read made more than an hour later. See [Creative approvals after sync finding](https://docs.apostra.com/v3/certification.md#creative-approvals-after-sync-finding). `behaviour.creative_changes_declared` reads a flag when your agent does not declare which live creative changes it takes. See [Creative changes declared finding](https://docs.apostra.com/v3/certification.md#creative-changes-declared-finding). `behaviour.creative_assignments_kept` reads a flag when your agent accepts a creative sync that carries assignments and the buy, read back, does not hold the creative in its package. See [Package assignments are kept on the buy](https://docs.apostra.com/v3/certification.md#creative-assignments-answered-finding). `behaviour.creative_approvals_use_buyer_ids` reads a flag when your agent lists, in `creative_approvals` on `get_media_buys`, a `creative_id` that is not a creative Apostra sent it. See [Creative approvals use buyer ids finding](https://docs.apostra.com/v3/certification.md#creative-approvals-use-buyer-ids-finding). `behaviour.creative_assignments_on_buys_answered` reads a flag when your agent refuses package `creative_assignments` on `create_media_buy` or `update_media_buy` other than with `VALIDATION_ERROR`, or `UNSUPPORTED_FEATURE` for a `landing_page_url` or `trackers` it does not take, or refuses an assignment of `creative_id` alone. See [Creative assignments on buys answered finding](https://docs.apostra.com/v3/certification.md#creative-assignments-on-buys-answered-finding). `behaviour.creative_assignments_answered` reads a flag when your agent refuses package assignments on a creative sync other than with a correctable `UNSUPPORTED_FEATURE` that names `assignments`. See [Creative assignments answered finding](https://docs.apostra.com/v3/certification.md#creative-assignments-answered-finding). `behaviour.daily_budget_held_on_lifetime_buy` reads a flag when a buy booked with a total budget holds a daily budget in your ad server. See [Daily budget on a lifetime buy finding](https://docs.apostra.com/v3/agent-requirements.md#daily-budget-on-a-lifetime-buy-finding). `behaviour.audience_expansion_not_requested` reads a flag when your agent reports a buy's package as expanding beyond the buyer's audience (`audience_expansion.enabled: true`) and no request Apostra sent asked for it. See [Audience expansion finding](https://docs.apostra.com/v3/agent-requirements.md#audience-expansion-finding). `behaviour.property_delivery_reported` reads a flag when your agent declares `supports_property_breakdown` on its products, is asked for delivery by property, and does not return the `by_property` rows. See [Property delivery finding](https://docs.apostra.com/v3/agent-requirements.md#property-delivery-finding). `behaviour.valid_responses` reads a flag when Apostra refuses a `get_media_buys` or `get_media_buy_delivery` reply from your agent as not valid AdCP. See [Valid responses finding](https://docs.apostra.com/v3/agent-requirements.md#valid-responses-finding). `behaviour.account_calls_honour_auth_declaration` reads a flag when an agent declaring `require_operator_auth: false` refuses an account call with HTTP 401. See [Account auth declaration finding](https://docs.apostra.com/v3/agent-requirements.md#account-auth-declaration-finding). `behaviour.delivery_read_responsiveness` reports slow or timed-out delivery reads. See [Delivery-read responsiveness finding](https://docs.apostra.com/v3/agent-requirements.md#delivery-read-responsiveness-finding). `behaviour.tool_list_page_size` reads a flag when a tool list page is over 128 KiB. See [Tool list page size finding](https://docs.apostra.com/v3/agent-requirements.md#tool-list-page-size-finding). `behaviour.wholesale_catalog_published` reads a flag when an agent connected as an inventory source does not declare `wholesale` in `media_buy.buying_modes`, or answers a wholesale read that names no account with `cache_scope: "account"`. See [Wholesale catalog published finding](https://docs.apostra.com/v3/agent-requirements.md#wholesale-catalog-published-finding). `behaviour.discovery_brief_accepted` reads a flag when your agent refuses a `get_products` brief that passes the AdCP request schema with `INVALID_REQUEST` or `VALIDATION_ERROR` and answers none. See [Discovery brief accepted finding](https://docs.apostra.com/v3/agent-requirements.md#discovery-brief-accepted-finding). `behaviour.adcp_request_fields_accepted` reads a flag when your agent rejects a request field AdCP defines. See [AdCP request fields accepted finding](https://docs.apostra.com/v3/agent-requirements.md#adcp-request-fields-accepted-finding). `behaviour.unscoped_list_read_answered` reads a flag when your agent fails the daily `get_media_buys` read that names no account and no media buy ids. See [Unscoped media buy list read finding](https://docs.apostra.com/v3/agent-requirements.md#unscoped-media-buy-list-read-finding). `behaviour.declarations_match_behaviour` reads a flag when your agent refuses a billing model it declares, or lists a write operation (such as `update_media_buy`) that it refuses as an unsupported feature on every call. See [Declarations match behaviour finding](https://docs.apostra.com/v3/agent-requirements.md#declarations-match-behaviour-finding). `behaviour.buys_judged_on_named_products` reads a flag when buys naming different products all fail with the same error and none succeeds, or when your agent refuses a buy over a product the buy did not name. See [Buys judged on named products finding](https://docs.apostra.com/v3/agent-requirements.md#buys-judged-on-named-products-finding). `behaviour.creative_errors_carry_recovery` reads a flag when an error in your agent's answer to a creative sync carries a `recovery` that is not `transient`, `correctable` or `terminal`, or, in an answer served as AdCP 3.2 or later, carries none. See [Creative error recovery finding](https://docs.apostra.com/v3/agent-requirements.md#creative-error-recovery-finding). `behaviour.creative_review_verdict_readable` reads a flag when your agent takes a creative into review without a task and its verdict reaches Apostra neither by a callback nor by `list_creatives` before the delivery's deadline. See [Creative review verdict finding](https://docs.apostra.com/v3/agent-requirements.md#creative-review-verdict-finding). | Attention. These checks stop nothing. |
| `claim.review` | Your organization has claimed the agent. Only an organization admin reads it failing, for an agent Apostra mapped to the organization. | Blocking, for certification. See [Claim an agent Apostra mapped to your organization](https://docs.apostra.com/v3/connect-an-agent.md#claim-an-agent-apostra-mapped-to-your-organization). |
| `certification.no_source` | An active inventory source, or a pending source of your own organization with healthy or degraded health, uses the agent, and, for a source of another organization, the agent's URL is verified as yours. When the agent is attached only to a source that is `DISABLED`, or `PENDING` with health that is not healthy or degraded, the finding names the source and its state, and does not ask you to attach the agent again. When the only source that uses the agent belongs to another organization and the agent is not verified as yours, the finding says to verify the agent first. | Blocking, for certification. Certification buys through those sources that use the agent; with none it cannot start. See [Test and certify your agent](https://docs.apostra.com/v3/connect-an-agent.md#test-and-certify-your-agent). |
| `certification.no_passing_use_case` | At least one use case that counts toward certification has passed. A use case that does not decide certification, such as accounts for a seller's own storefront, does not count, and the finding names any such use case that passed. When Apostra could not start a run, it says why and whose move it is, and when a step of your sandbox account stopped it, it names that one cause and quotes your agent's own error. See [When a run cannot start](https://docs.apostra.com/v3/certification.md#when-a-run-cannot-start). | Blocking. A publisher cannot complete the Successful transaction go-live step on your agent without it, unless Apostra has exempted the agent from certification. |
| `certification.use_case` | One use case's result; `subject` is the use case. For an offered use case, the finding also checks whether a pass counts for its Source. See [Use cases](https://docs.apostra.com/v3/certification.md#use-cases). | Attention when it failed or is offered without a pass that counts, including when it has never run or its result is inconclusive. |
| `certification.format_not_tested` | Whether certification planned a buy for every format option your products offer. A format option the latest run left out is listed with its product, channel and reason. See [Formats certification does not test](https://docs.apostra.com/v3/certification.md#formats-certification-does-not-test). | Attention when the latest run left out any format option. Nothing stops: your agent stays certified once any use case passes, and the formats left out stay bookable. |
| `certification.product_withheld` | Buyers can see every product your agent sells. A product the storefront left out of the answer the latest certification run planned from, because it fails the AdCP release the buyer was served, is listed by its id in your agent, with its inventory source, the release and the field that failed. See [Products buyers cannot see](https://docs.apostra.com/v3/certification.md#products-buyers-cannot-see). | Attention when the latest run recorded any such product. Nothing stops: certification results do not change, and your other products stay bookable. |
| `certification.declared_formats_accepted` | Whether your agent accepts the certification creatives Apostra builds to what your format options declare. A refusal is listed with its Source, family, format option, what the creative was built to (for example `main_image 600x400`), and your agent's code and message. See [Accept the creatives your formats declare](https://docs.apostra.com/v3/agent-requirements.md#accept-the-creatives-your-formats-declare). | Advisory when the latest result for a format on a Source was a refusal, as not fitting, of a creative built to its declared format option. Content and policy refusals do not count. Nothing stops: it is reported only. |
| `certification.live_creative_changes` | Whether your agent handles the live creative changes certification makes on its test buy as it declared them: it takes a change it declared, and refuses a change it left out of its declared actions with an error code. See [Live creative changes finding](https://docs.apostra.com/v3/certification.md#live-creative-changes-finding). | Attention when the latest run saw your agent refuse a change it declared as self-serve, or accept, or answer without an error code, a change it left out. Nothing stops: the check never makes a use case fail and never withholds a certification pass. |
| `certification.assignment_operations_advice` | Whether your agent takes the `assignment_operations` `replace` it advises. Raised when certification sent your agent a `sync_creatives` carrying an `assignment_operations` `replace` and your agent refused it, while its refusal, in this run or on recorded traffic, names `assignment_operations` as what to send instead. See [Assignment operations finding](https://docs.apostra.com/v3/certification.md#assignment-operations-finding). | Attention. Nothing stops: the check never makes a use case fail and never withholds a certification pass. |
| `certification.assignment_operations_supported` | Whether your agent takes an `assignment_operations` `replace`. Raised when your agent refused the replace and does not name `assignment_operations` as what to send instead. Reported on its own, because AdCP 3.2 defines the list with no capability to decline it but does not say in so many words that a sales agent must take it. See [Assignment operations finding](https://docs.apostra.com/v3/certification.md#assignment-operations-finding). | Attention. Nothing stops: the check never makes a use case fail and never withholds a certification pass. |
| `certification.creative_copy_id` | Whether your agent keeps a creative id with a `~` in it exactly as sent. Raised when certification synced your agent a creative under such an id, 128 characters long, and your agent refused it, answered under another id or none, or listed no creative under it. It does not assign the creative to a package, so delivery reports and callbacks under the id are not judged here. See [Creative ids with a tilde](https://docs.apostra.com/v3/agent-requirements.md#creative-ids-with-a-tilde). | Attention. Nothing stops: the check never makes a use case fail and never withholds a certification pass. |
| `certification.storefront_accounts` | Whether your agent accepts the account request Apostra sends when a publisher whose own storefront uses your agent approves a buyer. It is judged on each inventory source of a storefront that is not a pure pass-through, with that publisher's credential. See [Use cases](https://docs.apostra.com/v3/certification.md#use-cases). | Attention when the latest check failed on any such source, because buyers billed through Apostra get no account there. Nothing stops yet. |
| `certification.publisher_authorization_url` | A publisher file of a storefront that uses your agent authorizes the exact URL your agent is connected at. Raised only when no entry names that URL but an entry names the same host with another path or trailing slash, and it names both URLs and the publishers. Nothing is raised otherwise. See [The publisher file names the URL you connect](https://docs.apostra.com/v3/agent-requirements.md#the-publisher-file-names-the-url-you-connect). | Advisory. Reported only: it stops neither certification nor buying, and it never becomes the headline. The publisher stays not authorized, so buyers do not see it in the storefront's list of publishers, and a buyer that checks the file may refuse to buy that publisher's inventory through your agent. |
| `certification.create_without_creatives` | Whether your agent accepts a media buy created with valid packages and no creatives and holds it in `pending_creatives`, as AdCP 3.3 says it must. Apostra sends one such create when your agent is first certified, when what it declares changes, after a probe that did not pass, and weekly after a pass, and cancels the buy. When your agent refused it, or reported another status, the finding shows your agent's own error code and message, or the status it reported. See [Create without creatives finding](https://docs.apostra.com/v3/certification.md#create-without-creatives-finding). | Attention when the latest probe saw your agent refuse the create, or report the buy in any status other than `pending_creatives`. Nothing stops: the check never makes a use case fail and never withholds a certification pass. A create that timed out, never reached your agent, was held for a decision or gave no status is not judged. |
| `certification.probe_buy_not_cancelled` | A test buy certification created with no creatives is still booked on your agent 12 hours after it was sent, because your agent refused the cancel or kept the buy. It names the buy, the cancel attempts and your agent's own words. See [Create without creatives finding](https://docs.apostra.com/v3/certification.md#create-without-creatives-finding). | Attention. Nothing stops: the buy carries no creative and starts a day after it was sent, so it cannot deliver. A cancel Apostra could not send is Apostra's and is not shown here. |
| `certification.awaiting_creative_approval` | Your agent holds the certification creative for review, so certification waits for you to approve it. It names the use cases that wait and when the wait ends. See [Certification-ready sandbox](https://docs.apostra.com/v3/certification.md#certification-ready-sandbox). | Attention while the wait lasts. Nothing stops: a use case still waiting when the wait ends is inconclusive. |
| `reporting.sources` | Your inventory sources report on time. | Attention when any source needs reporting action. Nothing stops. |
| `source.health` | Each inventory source in your organization that uses the agent is healthy, as its row on the Inventory sources page reads it. One finding for each source that reads unhealthy, with `subject` set to the source; it names the source, its storefront and the date it went unhealthy, and links to the source. See [When an inventory source is unhealthy](https://docs.apostra.com/v3/connect-an-agent.md#when-an-inventory-source-is-unhealthy). | Attention for each unhealthy source. Nothing stops: buyers' requests still reach the source, and Apostra's calls through it fail until it recovers. |
| `partner.program` | The agent serves other organizations as a Partner. An organization admin reads it only for a claimed agent that has passed certification. | Advisory when your organization does not yet serve other organizations: until it does, no other organization goes live on the agent, and publishers do not see it in their list of partner agents. It never becomes the headline. |
| `creative_conformance.step` | One step of the creative conformance test. `subject` is the step. | Attention when it failed. |
| `adcp_4.supported_versions`, `adcp_4.reliable_reporting`, `adcp_4.request_signing`, `adcp_4.webhook_signing`, `adcp_4.operator_identity`, `adcp_4.compact_lifecycle`, `adcp_4.canonical_creatives` | The AdCP 4.0 capability checks. | Attention with `dueAt` for a capability that becomes required on a date, and blocking once its date has arrived. Advisory for a capability with no date (`adcp_4.supported_versions`, `adcp_4.request_signing`, `adcp_4.operator_identity`): certification and buying are unaffected while your agent lacks it. See [Getting ready for AdCP 4.0](https://docs.apostra.com/v3/adcp-4-readiness.md). |
| `implementation.no_endpoint` | Apostra has an endpoint for the agent: a production endpoint is registered, or a source that uses the agent has a URL. Raised for sales and creative agents. | Attention. Nothing refuses an agent for having none, but Apostra has nothing to call. See [Connect an agent from its URL](https://docs.apostra.com/v3/connect-an-agent.md#connect-an-agent-from-its-url). |
| `implementation.not_reachable` | Apostra gets an answer from the agent's endpoint. Raised for a sales or creative agent that Apostra has never read (and that does not need credentials), or whose last recorded call failed because the endpoint did not answer. It shows the network error when one is recorded. See [When Apostra cannot reach your agent](https://docs.apostra.com/v3/connect-an-agent.md#when-apostra-cannot-reach-your-agent). | Blocking, for certification. Live certification buys through the agent's own endpoint, so Apostra cannot certify an agent it cannot call. |
| `implementation.agent_error` | The agent answers Apostra's calls without an error. It quotes the agent's own words from the newest failing call Apostra made to your agent's own endpoint (or, when its production version has none, the URL its source uses) from a storefront source in your own organization, within the last 7 days. See [When your agent returns an error](https://docs.apostra.com/v3/connect-an-agent.md#when-your-agent-returns-an-error). | Attention. |
| `endpoint_control.unverified` | An agent Apostra connected from a URL is verified as yours. An agent that was not connected from a URL has no such finding. | Attention. Certification through your own storefront does not need it, so nothing stops it. Partner standing, listing and use by another organization are refused until the agent is verified. It does not lead while a certification step is open. See [Prove your agent is yours](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours). |
| `day_one_test.sales_validation` | A sales agent's latest owner test. Raised once an endpoint is registered for the agent's production version. | Attention when the latest run failed. Advisory when no test has run: certification does not need one, so it never becomes the headline. See [Test and certify your agent](https://docs.apostra.com/v3/connect-an-agent.md#test-and-certify-your-agent). |
| `creative_conformance.not_run` | A creative agent has a conformance result. Raised once an endpoint is registered. | Not checked yet until the test has run, so it leads: the test is the only check a creative agent has. See [Creative conformance findings](https://docs.apostra.com/v3/connect-an-agent.md#creative-conformance-findings). |
| `credential.issued` | A buyer agent has a credential bound to it. | Attention. A buyer agent makes no authenticated call without one. See [Buyer agents](https://docs.apostra.com/v3/connect-an-agent.md#buyer-agents). |
| `credential.authenticated` | A buyer agent's credential has made an authenticated call to Apostra. Raised once a credential is bound. | Not checked yet until the first call, so it leads. See [Buyer agents](https://docs.apostra.com/v3/connect-an-agent.md#buyer-agents). |
| `implementation.change_detected` | Apostra tracks changes to your agent's implementation. It reads passed and, when your agent has changed, says when: "Your agent changed on 22 October; Apostra re-checked its capabilities." You do nothing: Apostra re-reads your agent's capabilities about once an hour and keeps the page current. | Never failing. |

The behaviour and declaration codes are explained in
[Agent requirements: declarations and behaviour](https://docs.apostra.com/v3/agent-requirements.md),
certification in [How certification works](https://docs.apostra.com/v3/certification.md#what-a-pass-unlocks).

### Who has to act on each code

| Code | `owner` |
| - | - |
| `declaration.*`, `behaviour.*`, `adcp_4.*` | `agent_developer`. |
| `claim.review` | `agent_developer`: an organization admin claims the agent. |
| `certification.no_source` | `agent_developer`: attach the agent to a storefront; or, when it is already attached, bring a pending source's health up and turn on Allow certification buys, or turn a disabled source back on; or, when only another organization's source uses it, verify the agent as yours. |
| `certification.no_passing_use_case` | `agent_developer` while the agent is attached to no storefront, certification buys are off, a use case failed, or the agent holds our creatives for review. When Apostra could not start a run, whoever the blocked start names: `agent_developer` or `apostra`. `null` while certification runs on live traffic. |
| `certification.use_case` | `agent_developer` when it failed or an offered use case has not run, or while your agent holds our certification creatives for review. For an inconclusive result from a skipped family, the owner of the skip reason in [Skip reasons](https://docs.apostra.com/v3/certification.md#skip-reasons). `null` while evidence is still arriving. |
| `certification.awaiting_creative_approval` | `agent_developer`. |
| `certification.format_not_tested` | `agent_developer` for a product with no channel certification can buy on. `apostra` for a format Apostra does not test yet. `null` when a later run covers it. |
| `certification.live_creative_changes`, `certification.assignment_operations_advice`, `certification.assignment_operations_supported`, `certification.creative_copy_id`, `certification.storefront_accounts`, `certification.declared_formats_accepted` | `agent_developer`. |
| `certification.product_withheld` | `agent_developer`. When the product already looks valid, tell Apostra: the storefront's own projection can leave out a product you declared correctly. |
| `certification.publisher_authorization_url` | `seller`: the seller changes the URL the inventory source connects, or asks the publisher to change its file. |
| `reporting.sources` | `seller`: the seller behind the source delivers the report. |
| `source.health` | Whoever caused the failure: `agent_developer` when your agent answered Apostra's call with an error or a response Apostra could not use, `seller` when the source's connection or the credential its seller stored failed, including your agent refusing that credential, and `apostra` when the failure is on Apostra's side. |
| `partner.program`, `implementation.no_endpoint`, `implementation.not_reachable`, `implementation.agent_error`, `endpoint_control.unverified`, `day_one_test.sales_validation`, `creative_conformance.*`, `credential.*` | `agent_developer`. |
| Any finding that passed, and `implementation.change_detected` | `null`. |

A failed certification use case's `howToFix` names the change for the check that
failed, as [What each check judges](https://docs.apostra.com/v3/certification.md#what-each-check-judges)
describes it.

### When Apostra cannot reach your agent

The `implementation.not_reachable` finding is blocking, for certification, and
the owner reads it on the agent's Overview page, in `get` and in `get_status`. It
appears when Apostra has never read the agent, or when the last call it recorded
to the agent failed because the endpoint did not answer: the name did not resolve,
the connection was refused, or the call timed out. `whatWeSaw` quotes that error and the date
of the call. When no call was recorded, it says Apostra has never received an
answer from the URL. An agent that needs credentials is not reported here: it has
not been read, and that is a different state (see
[Register an agent that needs credentials](https://docs.apostra.com/v3/connect-an-agent.md#register-an-agent-that-needs-credentials)).

To fix it, make sure the agent is running and reachable from the public internet
at its URL, then connect it again with `save_agent`, giving the agent's `agentId`,
its `agentUrl` and a new `idempotencyKey`. An agent that Apostra reaches only
through its source, with no endpoint on its production version, is not connected
again: fix it, then refresh its source's health with
`refresh_inventory_source_health` so Apostra calls it again. If the host is a tunnel or another shared
or temporary domain, move the agent to a stable host on a domain your organization
has verified first. See
[Prove your agent is yours](https://docs.apostra.com/v3/connect-an-agent.md#prove-your-agent-is-yours).

### When your agent returns an error

The `implementation.agent_error` finding quotes what your agent said. It is the
error your agent returned to the newest failing call Apostra made to your agent's
own endpoint, or to the URL its source uses when its production version has
none, in `whatWeSaw`, with the date and what Apostra was asking for
(its capabilities, products or creatives). This includes an HTTP error your
agent returns when Apostra first opens an MCP session at its URL, for example
`HTTP 503 Service Unavailable` with your agent's error body: your URL reaches
your agent, so do not change it; fix the error your agent returns. Apostra reads only calls made from
storefront sources in your own organization that use this agent, in the last 7
days. A source in another organization, a source for a different endpoint, and
any reading that is not a call to your agent are never quoted, and no source
name appears. The seller whose storefront uses the agent does not read the quote.
AdCP's correctable refusal of package `assignments` on `sync_creatives` (the code
`UNSUPPORTED_FEATURE`, the field `assignments` and the recovery `correctable`) is
not an error either: Apostra sends the creatives again without them, so it is
never quoted here. See
[Answer package assignments on a creative sync](https://docs.apostra.com/v3/agent-requirements.md#answer-package-assignments-on-a-creative-sync).

The finding clears once a later call succeeds. A network error that did not
answer clears when any later call to your agent succeeds. Any other error clears
when a later call of the same kind succeeds. The error is your agent's, not
Apostra's, so the fix is in your agent: find it in your agent's logs, change the
agent so the call succeeds, then connect it again with `save_agent` or run the
endpoint check from the Agent page. For an agent Apostra reaches only through its
source, refresh that source's health with `refresh_inventory_source_health`
instead. The `day_one_test.sales_validation` finding
quotes the same error when the latest test run failed. Your agent's endpoint host
is replaced with `[agent host]` in anything quoted.

### When an inventory source is unhealthy

The `source.health` finding shows each inventory source that uses your agent
and reads unhealthy, one finding for each, with `subject` set to the source.
Apostra reads a source's health as its row on the
[Inventory sources page](https://docs.apostra.com/v3/connect-an-agent.md#open-the-inventory-sources-page)
reads it: from the checks Apostra made through the source in the last seven
days. A source reads unhealthy when Apostra's calls through it fail, for
example because your agent answers `get_products` with an error, or because the
source's credentials no longer work. The finding names the source and its
storefront, the date it went unhealthy, and links to the source, whose own
[diagnostics](https://docs.apostra.com/v3/seller-source-diagnostics-page.md) say what failed.

It lists only sources in your own organization: an active or pending source
whose seller account is in the organization that owns the agent. A source in
another organization stays private, as on the agent read, so it never appears
here. A turned-off source is not judged. While every source with a recent
check is healthy or needs attention, the finding reads passed, and an agent
with no recent check on any source has no `source.health` finding.

Who acts follows the cause, in the finding's `owner`:

* **`agent_developer`**: your agent answered Apostra's call with an error, or
  with a response Apostra could not use. `whatWeSaw` quotes your agent's own
  words, with your agent's endpoint host replaced by `[agent host]`. Change
  your agent so the call succeeds.
* **`seller`**: the call got no answer, never left Apostra because the
  source's credential could not be used, or your agent refused the credential
  the seller stored (`AUTH_INVALID`, `AUTH_MISSING` or `AUTH_REQUIRED`).
  `whatWeSaw` gives the code Apostra recorded, never the raw error. The seller
  reconnects the source or updates its credentials.
* **`apostra`**: the failure is on Apostra's side, and there is nothing for
  you to change.

It is attention, never blocking. Buyers' requests still go to an unhealthy
source and fail there until it recovers, and your agent's other sources keep
selling. After a fix, refresh the source's health with
`refresh_inventory_source_health` so Apostra checks it again; the finding
clears once the source no longer reads unhealthy.

### Open the Overview page

In an MCP host such as Claude or ChatGPT, ask to open your agent, or call
`open_agent_page` with the agent's `agentId`. It opens the agent's Overview
page, which shows:

* **The headline finding first.** Its severity names it: Blocking, Needs
  attention, or Not ready yet when a check has not run. The page says what the
  finding stops, the date it becomes blocking when it has one, how to fix it,
  and links to the explanation. A page never reads as passed while any check has
  not run.
* **One button for each fix.** A finding that has not passed carries one button
  for its fix. A check that has not run and that nobody has to act on yet has
  no button: it is waiting for evidence, and the checklist counts it apart from
  the findings that need you. Where the fix is a change to your agent's own code, the button
  opens the finding's explanation. Where you can do it on Apostra, the button
  does it: **Review and claim** opens the claim review for an agent Apostra
  mapped to your organization, **Check the proof of control** and **Run the test
  again** have Apostra read the agent at its URL again (the second also re-runs
  the endpoint check), **Start the conformance test** and **Run the conformance
  test again** run the creative conformance test, **Set up a credential** asks
  for a buyer agent's credential and then shows a link to finish setting it up,
  and **Open the inventory sources** opens that
  page. **Start the conformance test** and **Run the conformance test again**
  show to an Operator or Admin of the account that owns the agent. Every other
  button that changes something shows only to an Admin of that account who is
  signed in as themselves. Anyone else sees the explanation links and the
  buttons that only open a page. After a change, the page reads the agent again
  and shows what Apostra now sees.
* **States.** One line for each fact Apostra read about the agent: whether an
  endpoint is registered, how many storefronts use the agent and how many of
  them are publicly listed, whether it is certified, whether other organizations can find
  it, the latest manual test, and for a buyer agent its credential. A fact that does not
  apply to the kind of agent has no line.
* **The checklist.** Every finding in the order above. Failing findings and
  findings Apostra has not checked yet are listed first, each with what we saw,
  how to fix it, when it was last checked and a link to the explanation. Findings
  that passed are collapsed under their own heading. Five findings show at a
  time.
* **Evidence.** Under the checklist, one item for each thing Apostra checks. Each
  opens to its full evidence: **Live certification** (the latest result for each
  use case, named and marked as counting toward certification or not, with its
  channel, when it was judged, each check's result and, when it did not pass,
  the reason Apostra recorded; Apostra derives the use cases from the agent's
  products and capability declarations); **Manual test runs** (for a sales agent,
  the test plan with each test mode, whether it is available and why not, and
  the recent manual test runs with the outcome, the failed stage, who is
  accountable and the next step; live certification runs separately, so an agent
  can have no manual test runs and still show live certification results);
  **AdCP 4.0 readiness** and **Capability declarations** (the same checks as
  [Getting ready for AdCP 4.0](https://docs.apostra.com/v3/adcp-4-readiness.md) and the declarations the
  agent makes, shown as declared or eligible for testing and never as passed,
  with what Apostra saw and how to fix each); and, for a creative
  agent, **Creative conformance**.
* **Certification buys.** Whether the owner has allowed certification buys. For
  someone who can change the setting, this is a switch: turn it on or off and the
  page saves it with `save_agent`, then reads itself again, so what it shows is
  what Apostra saved. Anyone else sees only whether it is on. When Apostra has
  exempted the agent from certification until a date, one line gives that date.
  See
  [See whether Apostra exempted an agent from certification](https://docs.apostra.com/v3/connect-an-agent.md#see-whether-apostra-exempted-an-agent-from-certification).
* **Actions on two findings.** For an agent Apostra mapped to your organization
  and you have not claimed, an organization admin sees **Review and claim**,
  which opens the claim review. For a claimed agent that has passed
  certification, an organization admin sees **Open Partner operations**, which
  opens the Partner page. No other finding has a button.
* **The agent and its endpoint.** Its name, kind, states, the organization it is Built by, the AdCP
  versions it declares, when Apostra last read its capabilities, its production
  revision and when it was deployed, and whether the implementation Apostra
  observes still matches.

The page shows what `get` returns for the agent, to the same people who
can read it, and opening it changes nothing. It leaves out internal fields, such
as source identifiers and the links to a run's diagnostics. Its two buttons open
other pages; its one write is the certification switch. It is available in
Agents accounts. The text Apostra writes for a finding (its summary, what we saw and
how to fix it) is in English whatever language the host uses.

### Open the Inventory sources page

In an MCP host such as Claude or ChatGPT, ask to open your agent's inventory sources, or call
`open_agent_sources_page` with the agent's `agentId`. It opens a page that shows how many inventory
sources the agent powers (connections, for an agent that is not a sales agent), and for each one its
name, the storefront it belongs to, its lane (wholesale or composing) and its latest health: healthy,
needs attention or unhealthy, with when Apostra last observed it, or that there is no recent
evidence. Each source also shows its own reporting state: no report due yet, on time, late and
recovering, needs action, or complete, or that none is available. The page shows each state as
Apostra reads it and never adds them up; [Source reporting health](https://docs.apostra.com/v3/agent-requirements.md#source-reporting-health) says what each state means. When the agent also serves other organizations, the page says how many more sources stay
private to their organizations; it never names them.

The page shows exactly what `get` returns for the agent, to the same people who can read it. It
changes nothing. Credentials, reachability, mappings and failures are not on this page: each source's
own [diagnostics](https://docs.apostra.com/v3/seller-source-diagnostics-page.md) carries them, and they do not change
the agent's certification. The tool is available in Agents accounts.

### Claim an agent Apostra mapped to your organization

Apostra can map an existing agent to your organization before you register it
yourself. That agent shows as unclaimed: it has an id, connections and history,
but your organization has not taken ownership. Until an organization admin
claims it, the agent takes no owner changes, cannot be certified and has no
Partner authority. A legacy connection that was already serving may keep
serving, and that is not a claim.

The `claim.review` finding says so, to organization admins only. Its action,
**Review and claim**, opens the claim review: you check what Apostra mapped and
claim the agent. Claiming keeps the agent's id, revisions,
connections and history. A member who is not an organization admin, a service
credential and Apostra support staff reading for you do not see the finding and
cannot claim the agent.

### Creative conformance findings

A creative agent's conformance test runs a fixed set of steps against its
endpoint. Each step is a `creative_conformance.step` finding with the step as
its `subject`: `passed`, `failing` with the agent's own error in `whatWeSaw`,
or `null` when the step was skipped. A failed step is attention, because
nothing stops a creative agent from working while a step fails.

## After you create an agent

Test it in the [sandbox](https://docs.apostra.com/v2/features/sandbox.md). A sales agent then goes on to
certification. A creative agent stops at tested, and a buyer agent has no
certification path yet. [What is certification?](https://docs.apostra.com/v3/certification.md) explains
what makes a sales agent ready, what each check judges and what every result
means. The [Agents](https://docs.apostra.com/v2/concepts/agents.md) page describes the certification state
each agent shows.


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