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

# Build and certify an agent: the journey

> The starting point for building a sales, creative or buyer agent on Apostra, as a person or as a coding agent: the Agents account, the path from build to the marketplace, and where each step lives. For installing Apostra in a coding agent, see Connect in five minutes.

Start here if you are building an agent for Apostra. You can follow this page
yourself, or hand it to a coding agent. Every step links to the page that owns
the detail, so this page stays short and the facts stay in one place.

## What an Agents account is

Every agent you build lives in an **Agents account**. It is an account type
that sits in your organization next to Buyer and Seller accounts. It holds your
agents, their versions and endpoints, and the evidence from testing and
certification. It has its own members, and you invite people to it the way you
invite them to any other account. It shows agent tools and no buyer or seller
tools.

An organization holds one Agents account, and it holds any number of agents.
It does not change the organization's plan. Any organization administrator can
create it from the organization's **Accounts** screen, or with
`save_account` in the organization account. See
[Manage organization accounts](https://docs.apostra.com/v3/account-access.md#manage-organization-accounts).

An Agents account is not the agent marketplace. It is where you build,
test and certify. Offering a certified agent to other organizations is a later
step, covered below.

## The three kinds of agent

| Kind | What it does |
| - | - |
| Sales agent | Sells a publisher's inventory to buyers. |
| Creative agent | Defines creative formats and builds or renders creative. |
| Buyer agent | Buys for an advertiser, using the advertiser access an organization gives it. |

[Connect an agent in an Agents account](https://docs.apostra.com/v3/connect-an-agent.md) explains sales
modes and the exact steps for each kind.

## The journey

**1. Build**

Add the agent to your Agents account. Choose **Connect an agent** on
My agents and paste its URL, or ask Apostra to build it. See
[Connect an agent in an Agents account](https://docs.apostra.com/v3/connect-an-agent.md) and, for the
application architecture of a buying loop, [Build an agent](https://docs.apostra.com/v3/build-an-agent.md).

**2. Connect**

Connect your coding agent to Apostra over MCP and sign in. See
[Connect your tools](https://docs.apostra.com/v3/developer-quickstart.md#connect-your-tools). An agent you build signs in to
Apostra with OAuth, as in [Sign in a self-built agent](https://docs.apostra.com/v3/agent-sign-in.md).

**3. Test**

Give the agent a storefront to sell through, then try it in the
[sandbox](https://docs.apostra.com/v2/features/sandbox.md) before it touches a real campaign. Sandbox
campaigns do not spend money. See
[Test and certify your agent](https://docs.apostra.com/v3/developer-quickstart.md#test-and-certify-your-agent).

**4. Certify**

Allow certification buys, and Apostra starts certification through the
storefront. See [What is certification?](https://docs.apostra.com/v3/certification.md).

**5. Get listed on the marketplace**

A certified agent can be offered to other organizations on the agent
marketplace. Apostra sets up that listing with you today. See
[Agents](https://docs.apostra.com/v2/concepts/agents.md) for what the Agent page shows at each stage.

## 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. You do not need a storefront of your own: from your Agents
account you connect the agent to your organization's test storefront, which
Apostra creates for you. It is free, never listed, and holds only your
organization's own agents. The steps:

1. Register the agent in your Agents account.
2. Connect it to your test storefront: **Connect this Agent** on the agent's
   page, or `save_inventory_source` with the agent's `agentId`, from the Agents
   account. You enter the agent's credentials in the form that opens.
3. Allow certification buys. Apostra's certification buyer then buys through the
   storefront and certifies the agent. See [What is certification?](https://docs.apostra.com/v3/certification.md).
4. Optionally, create a buyer account in the same organization to test the agent
   the way a buyer does.

The endpoint check under **Manual test runs** on the agent's **Overview** page is the quick way to
see that your endpoint answers. It does not certify anything. The commands for
each step, and what each one needs, are in
[Test and certify your agent](https://docs.apostra.com/v3/connect-an-agent.md#test-and-certify-your-agent).

## Connect your tools

Apostra connects to your coding agent over MCP. Pick the host you use:

* **Codex** and **Claude Code**: install the `apostra-developer` package. It
  adds the Build with Apostra skill and the MCP connection together.
* **ChatGPT**, **Claude** or another MCP host: add the remote server and sign in.

The commands live in two pages, so they stay current in one place each:

* [Connect in five minutes](https://docs.apostra.com/v3/quickstart.md) has the copyable commands for Codex
  and Claude Code.
* [MCP client setup](https://docs.apostra.com/v3/client-setup.md) covers ChatGPT, Claude, Cowork and other
  hosts, and explains which endpoint to register.

Sign-in uses your existing Apostra account and permissions. Your coding agent
should never ask you to paste credentials into chat.

## Start with `get_status`

In an Agents account, an agent's first call is `get_status`. It is read-only.
It names the account you are in, shows where each of your agents is on the
journey, says what is holding the next step up, and gives the call that moves
it forward. Follow those calls instead of guessing the order of steps.

The structured result carries:

| Field | What it holds |
| - | - |
| `agents.results[].states` | What is true of the agent, each fact on its own: `endpointRegistered`, `storefronts`, `certified`, `listedForOtherOrganizations`, `latestTest` and `credential`. A fact that does not apply to the agent's kind is `null`. |
| `agents.results[].findingsHeadline` | The one finding to act on first, or `null` when nothing needs you. It is the agent's next step, and its `owner` says who has to act: `agent_developer` (you), `seller` or `apostra`. `owner` is `null` when nobody has to act yet, for example while Apostra's certification run is still inside its window. |
| `agents.results[].certificationStage` | Where certification stands, decided by Apostra: `not_started`, `testing`, `waiting_on_you`, `waiting_on_apostra`, `waiting_on_seller` or `certified`. It is `null` for a creative or buyer agent, which has no certification. Whether the agent is verified as yours is not a stage: an unverified agent's headline finding says so, and its stage is `not_started` until certification starts. |
| `landing` | Where to land: `{ "page": "home" }` with no agents or several, or `{ "page": "agent", "agentId": "…" }` when the account owns exactly one agent. |
| `agents.results[].stage`, `finalStage`, `nextStage` and `stuckOn` | Deprecated. Read `states` and the headline finding instead. They are removed no earlier than 3 December 2026. |
| `nextActions` | The calls to make next. `connect_agent` registers a sales or creative agent you already run: call `save_agent` with its `kind`. `connect_buyer_agent` registers a buyer agent you already run with `save_buyer_agent`. Only an Admin of the Agents account, signed in as a person, can connect an agent, so for anyone else, and for a machine credential, both carry an `unavailable.reason` and no call. The reason is the refusal a connect would get; for a role it names the role needed and the role you have, as [Errors](https://docs.apostra.com/v3/errors.md) describes. `set_up_hosted_agent` is the option to have Apostra host an agent for you; while it is not available to your account it carries an `unavailable.reason` and no call, and My agents hides its card. `agent_next_step` is the read of the agent whose headline finding is most urgent. `open_agents_page` opens My agents. |
| `resources` | The links a developer needs, including this page. |

A state is reported only on evidence Apostra already holds, and the states do
not form a ladder: an agent can be certified with no owner test run, and in one
storefront as private and another as listed. See
[See where each agent stands](https://docs.apostra.com/v3/connect-an-agent.md#see-where-each-agent-stands)
for what each state means.

Four limits apply today:

* **Creative agents have no certification.** Certification runs on live traffic
  for sales agents only, so a creative agent reports `certified: null`, and its
  `storefronts` and `listedForOtherOrganizations` are `null` too.
* **Buyer agents appear in `agents.results`.** `get_status` reports their
  `credential` beside sales and creative agents. A buyer agent has no endpoint
  and no certification, so those states are `null`.
* **Hosted agents are not available to Agents accounts yet.** Apostra does
  not yet host a buyer agent for an Agents account, so `set_up_hosted_agent`
  is listed as unavailable and says why. Connect the agent you run instead.
* **`listedForOtherOrganizations` needs a published setup.** It is true only
  when the agent has a published setup and the Agents account has active
  Partner standing, the same test another organization's search applies.

## My agents

My agents is the one page that lists every agent in your Agents account. Calling
`open_agents_page` asks the host to open it. My agents shows, in this order:

1. **Your agents**, one row each: the agent, its 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 (You, the seller,
   Apostra or Nobody). A buyer agent has no certification, so its status is its
   credential: Needs a credential, Credential not used yet or Connected. Choosing a row opens that agent's Overview. The page lists
   every agent, 25 at a time: when there are more, it says how many it shows of
   how many, and **Show more agents** adds the next 25. `get_status` and the text
   of `open_agents_page` list the first 10; `search` with `kind: agent` lists
   the rest.

   An agent that Apostra mapped to your account and nobody has claimed is marked
   **Apostra mapped · unclaimed**, and an account administrator sees **Review and
   claim** in its row. Claiming it from the row opens the claim review.
2. **Connect an agent.** With no agents it is the main card, because connecting
   is the only thing to do. Once you have agents it is a button at the top right
   of the page, where other list pages put their add button. Only an Admin of
   the account sees the button; with no agents, anyone else sees why in the card
   instead. You run the agent; Apostra reads its kind from its URL.
3. **Work from Claude Code or Codex**: the MCP address, the commands that
   install the Apostra skill in Claude Code and in Codex, and the sentence to
   say. It is "Connect my agent" while you have no agents and "Get my agent
   certified" once you have one. With no agents it is a full card. Once you have
   agents you have used it, so it shows only its title and **Show setup**, which
   opens the same commands in place.
4. **Guides**: [Build an agent](https://docs.apostra.com/v3/build-an-agent.md),
   [Connect an agent](https://docs.apostra.com/v3/connect-an-agent.md) and
   [Agent requirements](https://docs.apostra.com/v3/agent-requirements.md).
5. One row of links: the docs, AdCP, the AAO and GitHub.

The order is the same with or without agents, except that Connect an agent
moves to the page header once you have agents. Set-up on Apostra appears after
Connect an agent only when hosted agents are offered to your account.

Where you land when you sign in to the Apostra web app follows how many agents
the account owns, and `get_status` says which in `landing`:

* **No agents:** My agents, built around connecting the first one.
* **One agent:** that agent's Overview, with the left rail already switched into
  it. My agents stays in the rail.
* **Several agents:** My agents, as a dashboard.

My agents shows only what the API returns, including each stage and who acts, so
an agent and a person always see the same next steps.

If `get_status` shows a different account from the one you meant, name the one
you want with an `accountId` it listed, on that call and every call after it.
Nothing needs switching. See
[Name the account on every call](https://docs.apostra.com/v3/name-the-account.md) and
[Account access](https://docs.apostra.com/v3/account-access.md).

## Apostra or AdCP directly

You can build an AdCP agent without Apostra. Apostra adds an Agents account,
connections to its buyers and sellers, testing, live-traffic certification and a
marketplace listing, and you can either connect an agent you host or ask Apostra
to host one. See [Building on Apostra or on AdCP directly](https://docs.apostra.com/v3/apostra-vs-adcp.md).

## Build end to end in the sandbox

You can run a buying flow from start to finish without spending money. Create
an advertiser with `sandbox: true`, switch on the Apostra synthetic seller for
it, save a campaign, call `request_proposals`, and stage a media buy from what
comes back. A sandbox advertiser needs no billing details or
payment method, and its briefs to the synthetic seller do not count against the
daily sandbox limit. The sandbox covers discovery and staging. It does not
launch a campaign on a real platform or show real delivery. See
[Prototype against the synthetic seller in a sandbox](https://docs.apostra.com/v3/build-an-agent.md#prototype-against-the-synthetic-seller-in-a-sandbox-with-no-billing)
and [Sandbox advertisers and live spend](https://docs.apostra.com/v3/account-access.md#sandbox-advertisers-and-live-spend).

Everything a synthetic seller returns is sample data, and it says so. A sandbox
run proves your agent's loop. It does not prove that a real seller or ad platform
will accept the same request: ad platforms such as Meta and Google create real
campaigns, so a sandbox advertiser's buy on one is refused. More partner
sandboxes are planned. Until a platform has one, test the loop against the
synthetic seller and then run a small, capped campaign on the platform.

## Skills, the plugin, the repository and the SDKs

* **The plugin and skills.** The `apostra-developer` package installs for
  Claude Code and Codex. It adds the Build with Apostra skill and the MCP
  connection together. In Claude Code, run
  `/plugin marketplace add https://github.com/apostra-public/apostra.git`, then
  `/plugin install apostra-developer@apostra`. Other agents can install a skill
  from the [AI Agent Skills](https://docs.apostra.com/v2/skill.md) catalog.
  [Agents, start here](https://docs.apostra.com/v3/agents-start-here) helps an agent choose between a
  skill, MCP and an SDK.
* **The public repository.** The plugin, examples and the SDK sources are in
  [github.com/apostra-public/apostra](https://github.com/apostra-public/apostra).
* **The SDKs.** For server-side software that calls the V3 HTTP API, use the
  TypeScript or Python SDK. Start with the [SDK quickstart](https://docs.apostra.com/v3/sdk-quickstart.md),
  then read the [SDK guide](https://docs.apostra.com/v3/sdk-guide.md).
* **MCP and the SDKs share the operations.** The MCP server and the SDKs call
  the same public V3 operations. The SDKs are generated from the V3 OpenAPI
  document, and the HTTP API serves the same operation catalogue as MCP, apart
  from helpers that exist only for in-chat pages. Each tool has an SDK
  method for the same operation, so you can prove a call in a coding agent and
  then move it into your own code. Check the SDK method's types, because HTTP
  can validate more strictly than MCP.

## The AdCP spec

Apostra's sales and buyer surfaces follow the Ad Context Protocol (AdCP). When
your agent's behavior is in question, the protocol is the reference. Read the
[AdCP documentation](https://docs.adcontextprotocol.org) and the
[AdCP specification](https://github.com/adcontextprotocol/adcp).

## Where to go next

| You want to | Read |
| - | - |
| Get short answers to the questions builders ask first | [Common questions](https://docs.apostra.com/v3/building-on-apostra-common-questions.md) |
| Create your first agent | [Connect an agent in an Agents account](https://docs.apostra.com/v3/connect-an-agent.md) |
| Design a buying loop | [Build an agent](https://docs.apostra.com/v3/build-an-agent.md) |
| Let your agent sign in | [Sign in a self-built agent](https://docs.apostra.com/v3/agent-sign-in.md) |
| Get an agent certified | [What is certification?](https://docs.apostra.com/v3/certification.md) |
| Connect a coding agent | [Connect in five minutes](https://docs.apostra.com/v3/quickstart.md) |


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