Skip to main content
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. 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:
  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?.
  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.

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: 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: 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 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, Connect an agent and Agent requirements.
  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 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 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 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-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 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.

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 and the AdCP specification.

Where to go next