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:
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. 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
and Inviting members.
Start building
Building a sales agent? What a great sales agent does puts everything it has to do in order, step by step, and the sales agent checklist 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/v3connection, 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_taskon the organization MCP surface. From an Agents account’s/mcp/v3connection, callopen_agents_page, then choose Connect an agent. To connect an agent without the task, callsave_agentwith the agent’s URL: see Connect an agent from its URL. To register a sales or creative agent that has no URL yet, callsave_agentwith noagentId, and sendkind,displayNameand anidempotencyKey. For a sales agent you can also sendsalesMode. A buyer agent is created withsave_buyer_agent. - REST.
POST /api/v2/agents. See Create an Agent 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 thesave_agent
response, so an assistant calling save_agent sees the same answers.
-
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.
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.
- 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.
- 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.
- 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.
- 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.
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’sget_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, and connect it later.
Preview what Apostra reads
Callsave_agent with the agent’s URL and dryRun: true. A preview needs no
idempotencyKey, saves nothing and creates no agent.
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 callsget_adcp_capabilities. The preview returns what the
agent declared, under reading:
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.
What Apostra infers
What Apostra infers comes only from fields the agent declares. No product, price, traffic or hostname decides anything. The result is underinferred.
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 withoutdryRun, with an idempotencyKey (a UUID
you generate) and the confirmations you chose.
needsis not empty. The error names the missing field (kindorsalesMode) and carries the reasonneeds_confirmation. Send the field and save again.- the
kindyou 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.
kind and a different
idempotencyKey. Each role is its own agent.
What saving creates
A successful save writes everything together, or nothing:
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
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: oneget_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:
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), 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, the
agent:
- cannot be given Partner standing or listed in the marketplace.
- cannot be used by another organization.
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 itsagentId 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:
urlis 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 asreading.agentUrl, andstuckOnrepeats it.typeissalesfor a sales agent andcreativefor a creative agent. A proposal agent is listed assales, because AdCP’sbrand.jsonhas no proposal agent type.- The file is a valid AdCP
brand.json, which also gives each entry anidof lowercase letters, digits and underscores.
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).
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
verifiedagent 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
unverifiedat once inget,get_statusandstuckOn, 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 asverifiedagain. If you connect the agent again while the approval is missing, Apostra records it asunverified, and it becomesverifiedagain when you connect it again after the domain is approved. - Until the agent is verified,
get_statusandgetshowendpointControl: unverified, and theendpoint_control.unverifiedfinding tells you what to publish and where: the file URL, the entry with itsurlandtype, and the domain rule. For a creative agent, which has no certification stage,stuckOnnames the same step once the agent has passed its conformance test. An agent that was not connected from a URL carries noendpointControlat all.
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 sendkind: "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:
- In the Seller account, call
save_inventory_sourcewith theaccountIdand the agent’sagentId. The address is the one you registered. - Store the agent’s credentials on the source in the secure credential form. Credentials stay on the source.
- Apostra reads the agent with those credentials and records what it read on
the agent: its capabilities, name and AdCP release.
notReadYetbecomesnull, and the agent’s stage and test results follow from what was read.
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:
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 anidempotencyKey. 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 itsagentId
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.
- 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
displayNameorsalesModewith anagentIdis refused. Rename an agent withdisplayNameand noagentUrl.
Which URLs Apostra accepts
- An
httpsaddress, up to 2048 characters, with no username, password, query string or fragment, on the default port (443). A bare host such asagent.example.comis read ashttps://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.
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’shttps 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 closeddetails.reason, the
AdCP recovery (correctable, transient or terminal) and, where it applies,
retry_after in seconds.
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). 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.
- 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.
- Inventory sources: the sources connected to the agent.
- Webhooks: the recent inbound webhook outcomes, each refusal with its reason.
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 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_capabilitiesandget_products. Each has a View call action.
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.
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
describes.
Kinds of agent
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.
Sales modes
A sales agent declares how it sells. The mode follows the AdCP buying modes the agent supports.
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.
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.
- Register the agent. In your Agents account, create a sales agent as described in Start building. See Sales modes for the choice it asks you to make.
- 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_sourcewith only the agent’sagentId. 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_sourcetakesagentIdand 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) and callsave_inventory_sourcewith the agent’sagentIdthere. If you would rather certify through a storefront your organization sells through, connect the agent there instead: in that Seller account, callsave_inventory_sourcewith the agent’sagentId. You need to be an Operator or Admin of that account. To create a Seller account, an organization administrator callssave_accountwithaccountType: "seller"and approves the request on the website; the organization’s plan must allow the type of account you choose. See 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.
- Allow certification buys. You do not need to
prove control of the agent’s URL
first: an agent behind your own storefront is reached only through Apostra.
Turn on Allow certification buys, or send
certificationRequested: truewithsave_agent. See 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 toACTIVEyourself is refused until then. See When Apostra starts a run, Test buy size and What is certification?. - Optional: test as a buyer. To see your agent the way a buyer does, create
a buyer account in the same organization with
save_accountandaccountType: "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 withsellerAccountIdswhen the buyer callsrequest_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 and Storefronts. This test is not a certification run, and it does not replace step 3. - 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_capabilitiesandget_productsand 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’svalidationSkilllists theendpoint-briefprofile asUNAVAILABLE, and itsreasonsays 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.
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.
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
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.
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). 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
trueon a Creative agent is refused. Savingfalseis 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.
- With a rename.
displayNameandcertificationRequestedcan 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 namesdisplayName, and neither is saved. SendcertificationRequestedon 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 and The certification deadline. Only Apostra staff set, extend or clear an exemption. You cannot set it, andsave_agent
does not accept it.
get for kind: "agent" returns certificationExemption beside
certificationRequested:
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 insearch 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:
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_agentwith the sameagentIdandisArchived: 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 optionalsignupUrl, 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
signupUrlto 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
httpsURL 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
Callget_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.
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 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:
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.
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 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 thebuying
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:
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
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 withget (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).
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:
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:
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.
The behaviour and declaration codes are explained in
Agent requirements: declarations and behaviour,
certification in How certification works.
Who has to act on each code
A failed certification use case’s
howToFix names the change for the check that
failed, as What each check judges
describes it.
When Apostra cannot reach your agent
Theimplementation.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).
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.
When your agent returns an error
Theimplementation.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.
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
Thesource.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
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 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.whatWeSawquotes 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_MISSINGorAUTH_REQUIRED).whatWeSawgives 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.
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 callopen_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 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. - 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.
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 callopen_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 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 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. Theclaim.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 acreative_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.