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 withsave_account in the organization account. See
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
Connect an agent in an Agents account 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 and, for the
application architecture of a buying loop, Build an agent.
2
Connect
Connect your coding agent to Apostra over MCP and sign in. See
Connect your tools. An agent you build signs in to
Apostra with OAuth, as in Sign in a self-built agent.
3
Test
Give the agent a storefront to sell through, then try it in the
sandbox before it touches a real campaign. Sandbox
campaigns do not spend money. See
Test and certify your agent.
4
Certify
Allow certification buys, and Apostra starts certification through the
storefront. See What is certification?.
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 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:- Register the agent in your Agents account.
- Connect it to your test storefront: Connect this Agent on the agent’s
page, or
save_inventory_sourcewith the agent’sagentId, from the Agents account. You enter the agent’s credentials in the form that opens. - Allow certification buys. Apostra’s certification buyer then buys through the storefront and certifies the agent. See What is certification?.
- Optionally, create a buyer account in the same organization to test the agent the way a buyer does.
Connect your tools
Apostra connects to your coding agent over MCP. Pick the host you use:- Codex and Claude Code: install the
apostra-developerpackage. 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.
- Connect in five minutes has the copyable commands for Codex and Claude Code.
- MCP client setup covers ChatGPT, Claude, Cowork and other hosts, and explains which endpoint to register.
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:
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
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 itsstorefrontsandlistedForOtherOrganizationsarenulltoo. - Buyer agents appear in
agents.results.get_statusreports theircredentialbeside sales and creative agents. A buyer agent has no endpoint and no certification, so those states arenull. - 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_agentis listed as unavailable and says why. Connect the agent you run instead. listedForOtherOrganizationsneeds 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. Callingopen_agents_page asks the host to open it. My agents shows, in this order:
-
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_statusand the text ofopen_agents_pagelist the first 10;searchwithkind: agentlists 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. - 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.
- 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.
- Guides: Build an agent, Connect an agent and Agent requirements.
- One row of links: the docs, AdCP, the AAO and GitHub.
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.
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 and
Account access.
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.Build end to end in the sandbox
You can run a buying flow from start to finish without spending money. Create an advertiser withsandbox: 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
and 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-developerpackage 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 catalog. 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.
- The SDKs. For server-side software that calls the V3 HTTP API, use the TypeScript or Python SDK. Start with the SDK quickstart, then read the SDK guide.
- 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.