Skip to main content
An Agent is a connected software actor. The way an Agent appears depends on which workspace you are using.

​
Agents in a buyer organization

In a buyer workspace, Agents are first-class organization resources alongside Advertisers. A buyer agent is software installed into the organization; it is not a person, the account is not classified as agent-driven, and a human user is not tied to an agent. Six related concepts remain intentionally separate:
  • The Agent is the named software actor and its purpose.
  • Its installation is the Agent’s presence in one buyer organization.
  • Its principal is the durable internal identity used for routing and audit.
  • A credential lets the software prove that identity without sharing a human login.
  • A connection lets the Agent exchange supported data or use an organization-owned resource, such as a reporting database, bucket, or file drop. The resource and its credential belong to the organization, not the Agent.
  • A grant is explicit permission for an advertiser or account. Connections, credentials, and principals never imply a grant.
Organization administrators add and manage these Agents from Agents in the buyer navigation. Until a supported grant workflow gives an Agent access, its Access page says No advertiser access. Spend, payment, and Terms authority remain separate and are never inferred. One buyer organization can eventually manage external connected installations and Apostra-hosted installations in this same area. Operation mode changes the operational readback, not the organization or account type. The current supported Add agent flows connect external software; hosted creation waits for the production installation and provisioning contract. Machine-event subscriptions into an Agent belong under Notifications. Organization-owned output destinations that an Agent may be allowed to use, such as an approved Slack connection, remain separate connection resources. Future Slack, email, or inbox notifications for people are a third, human-facing concept and are not represented as machine subscriptions. See Manage buyer agents for the console, credential, connection, and security workflows.

​
Agents that power seller inventory

In a seller workspace, an Agent is an organization-owned software capability. It has its own identity, role, production implementation, certification, and implementation health. An Agent is not necessarily a Sales Agent. For Sales Agents, a Source is the storefront-specific connection to that Agent. The Source owns its credentials, reachability, mappings, and transaction health. The Agent owns the shared implementation and certification facts. Request eligibility and health are separate at both levels. A Source can have a permissions or credential problem while its shared Agent is healthy, and an Agent problem can affect several Sources. Apostra continues sending requests to degraded or erroring Sources while they remain explicitly eligible; only an explicit Source- or Agent-level ineligibility decision stops routing. The Agents preview is currently available to enrolled organizations and organizations with active Partner program access.

​
Create an Agent

A directly authenticated organization administrator can choose Create Agent from the Agents collection. The Task creates a private organization-owned Agent and requires its role. A Sales Agent also requires an explicit product mode: Wholesale, Composing, or Both. The Task either selects a claimed operator the organization already owns or creates a separately named operator at the same time. The operator is the secondary company/provider identity; the Agent remains its own capability. Creation establishes only the reusable Agent identity. It does not make the Agent public or a Partner listing, and it does not request credentials, select an authentication method or Source lane, create a Source, or establish a production implementation. Those are separate connection, Source, and certification workflows. When Apostra refreshes a connected Sales Agent’s capabilities, it reads the Agent’s declared AdCP buying modes to keep its product mode current. A wholesale declaration means Wholesale, brief means Composing, and declaring both means Both. Apostra records that this value came from the Agent. An absent declaration leaves the mode unresolved; Apostra does not guess from an endpoint or catalog response. An organization administrator can confirm or override an owned Sales Agent’s mode with V3 save_agent, recording an owner-confirmed value and a reason. A Seller administrator can correct the value only for that Seller’s own Source binding while the Agent is unclaimed. This binding correction never changes the Agent for other Sellers. Once the Agent is claimed, its owner controls the Agent-wide declaration and the Seller must contact that owner. A Seller may set Both for its own binding; the binding retains its normal product-path selection. This endpoint requires that same directly authenticated account-admin session; service tokens, delegated sessions, impersonation, and staff-assisted contexts cannot create Agents. Reuse an idempotency UUID only to retry the same request.

​
Review your organization’s Agents

Organization administrators can open Agents from the account switcher in the top bar to see the Agents their organization operates. The collection identifies each Agent, its role and operator, certification state, implementation health, and the one next action selected by the service. Agents remains the primary destination in the Agent workspace. Organizations with client-management access also see Clients nested beneath it; other organizations keep the same Agents navigation without a Clients destination. Use these endpoints while authenticated as an organization administrator:
An agent working in one of the organization’s Buyer or Seller accounts can use the account-resolved V3 MCP reads instead:
This V3 noun means software Agents the active organization owns. It is not an alias for a Storefront or another buyer counterparty. The compact response includes customer-safe certification and implementation-health facts, plus certificationRequested, the owner’s saved answer to whether Apostra may send certification buys to the Agent (details). It omits operator identifiers, claim state, private certification evidence, relationship identities, credentials, and owner-only action URLs. The certification include expands the public policy, requirement, expiry, and recurring-canary summary. validationRuns adds at most five recent, server-verified run summaries with outcome, cleanup status, accountable failure layer, safe error code, and an exact-read directive. The webhookDeliveries include adds the Agent’s recent inbound webhook outcomes, each refusal with its reason (details). The diagnostics include adds the observed implementation health and current production-revision label. A Sales Agent detail also returns the immutable versioned validationSkill entry to run through ordinary V3 calls. To inspect one returned run without putting every retained request and response in model context, repeat the Agent read with its exact server-issued run ID:
The exact graph contains ordered Activity and request identifiers, the workflow step and V3 operation, platform dispatch outcomes, outbound Agent-call method and status, and the last completed and failed stages. It never returns endpoint URLs, request or response payloads, credentials, private prompts, raw creatives, or customer object identifiers. Caller-supplied workflow annotations group the graph but cannot bind it to an Agent: Apostra returns a run here only after durable server evidence binds that run to the exact Agent revision. Exact private evidence remains on the governed certification surface. Inside Apostra, Agents is its own workspace, and the Agent page is a Developer account surface. Only a Developer account has the Agent page. A storefront, buyer or organization account never does, and the seller navigation has no Agents row. A seller reaches its Agents through the organization’s Developer account: switch to that account, and the Agents page opens the collection in the main canvas. If your organization has no Developer account yet, choose Create on the Developer account row of the organization’s account list. An organization with both a storefront and a Developer account has the Agent page on the Developer account only. Select an Agent. Use the left navigation to move between its sections, grouped beneath the selected Agent’s name. API calls is a separate workspace-level item: it opens the existing Activity widget for the account, not a selected Agent. API keys remain in Settings; selecting an Agent does not scope keys or API calls to it. On a narrow screen, All agents returns to the collection, and a section selector appears above the selected Agent’s Page. Direct links and external MCP hosts show the equivalent section tabs inside the portable Page. Sellers using older navigation, or a failed-checklist fallback without the Agents workspace, keep the existing Activity shortcut. The Agent Page has four bounded sections:
  • Overview identifies the Agent, its operator, role, shared implementation, trust states, and the one next action selected by the service.
  • Endpoint & protocol holds the shared, non-secret connection contract and production revision. Credentials, credential expiry, reachability, mappings, and request failures stay with each exact Inventory Source.
  • Test & certify shows live certification for a Sales Agent by tested use case. Apostra judges each applicable use case with a small sandbox test buy, its tracker, and the seller’s reports; registering a production revision is for change detection, not a certification prerequisite. The card shows each use case’s latest outcome, evaluation time, and any recorded reason; when no run has completed, it says No live certification run yet. A Developer account’s administrator allows certification buys for a Sales Agent with Allow certification buys. See How certification works. For other Agent roles, this section is labeled Test and does not invent Sales certification requirements.
  • Inventory sources lists the Sales Agent deployments the viewer is authorized to identify and links each one to its Inventory Source details. An Inventory Source owns credentials, authentication, reachability, mappings, failures, and transaction evidence. When Partner operations are active, Invite a client Storefront opens client onboarding with this exact Agent selected and shows this Agent’s pending invitations. An invitation starts a relationship request; it does not yet create an Inventory Source or grant account access. The equivalent future relationship section for a non-Sales Agent stays hidden until that role has a supported connection contract.
Use ?section=overview, ?section=endpoint, ?section=test, or ?section=connections to deep-link to a section. The stable path remains /{organizationId}/agents/{agentId}. The API uses CONNECTIONS as the stable section identifier even when the Sales label is Inventory sources. Navigation links returned to an MCP app are absolute URLs on the applicable Apostra or admin origin, so the same action works from any supported host. The detail response never returns Source credentials, private certification evidence, or another organization’s Source identities. An Agent owner can see an aggregate relationship count while client-specific relationships outside their authority remain hidden.

​
Required capability declarations

For a Sales Agent, Test & certify also shows the stored declarations that decide the Agent-wide baseline: AdCP major version 3, billing that supports an Agent or operator, acceptance of the connected credential for every buyer (no account.require_operator_auth), both sync_accounts and list_accounts so the Agent takes buyer account requests itself, and a stored product with a creative kind Apostra supplies (display_tag, video_vast, or audio_daast). If product evidence has not been stored yet, the Page says Not yet observed rather than guessing. The Page reads only data Apostra already stored; opening it does not call the Agent. When the current production revision has an immutable observed manifest, that is the declaration record shown. Otherwise, the Page uses each connected Inventory Source’s cached manifest. If Sources differ, the Page identifies the Source-specific results rather than implying a shared declaration. Property lists are shown separately as a per-buy feature, not as an Agent-wide baseline gate. For AdCP 3.1, the Agent declares media_buy.features.property_list_filtering and a selected product declares property_targeting_allowed. For an Agent negotiating AdCP 3.2, the Agent also declares media_buy.execution.targeting.property_list and property_list_exclude, and the selected product declares overlay_support.property_list. An Agent that does not make these declarations can still receive buys that do not carry a property list. Async task handling is verified from observed behavior, not from this declaration list.

​
Test a Sales Agent

A claimed owner can open Test & certify and choose a validation profile. The Page enables brief-only for an Agent with a connected Source and endpoint-brief for one without. The remaining profiles stay visible with their current availability:
  • brief-only temporarily enables the exact Seller for a synthetic sandbox Advertiser, discovers products, then restores DEFAULT and cleans up the temporary Campaign and Advertiser.
  • endpoint-brief calls the Agent’s attested production endpoint with a fixed no-spend discovery brief. It is offered only when the Agent has no current Source.
  • transaction is offered only to Apostra’s own internal canary sessions. A customer account is not offered it, and a request for it is refused with transaction_test_internal_only. Certification is judged on live traffic, not by this profile.
  • complete-floor remains unavailable until every required profile has an executable fixture and confirmation path.
  • rerun-failed remains visibly unavailable until an ordinary V3 read can reconstruct the exact failed run and its inputs.
  • creative remains visibly unavailable until the public skill has an approved executable creative fixture.
Choose Run validation skill. The Page runner remains pinned to the immutable, currently-published test-sales-agent bundle and resolves the current Agent revision. It uses only ordinary /mcp/v3 tools against the authenticated Media Company’s own isolated, no-spend sandbox. When an owner has selected an eligible Source, the run remains bound to that exact Agent and Source. The Page never receives a Source credential. A profile result is diagnostic evidence, not a certificate. Certification is judged on live traffic, use case by use case; see How certification works. Saving a Source as No auth completes the credential step; it does not need a placeholder secret before validation can run. To test one deployment’s read path first, open that Source’s diagnostics and choose Test product discovery. It calls get_products directly, creates no media buy, and works before the Storefront is ready for transactions. Choose Run validation skill there only when you want the complete readiness workflow. That launch is bound to the exact Agent and Source IDs, and products that cannot prove that Source attribution are rejected. Powered-by and admin Agent views may open the public instructions but cannot run the owner’s full validation control. An external MCP host follows the same path from scratch:
  1. Call get with kind: "agent" and the exact Agent ID.
  2. Fetch the returned validationSkill.skillUrl and manifest version. Do not replace it with a legacy test endpoint.
  3. Execute the selected scenario through the ordinary V3 tools and keep the skill, scenario, workflow, run, and step metadata specified by the skill.
  4. Preserve ordinary confirmations and reverse-order cleanup.
  5. Read the Agent again with include: ["certification", "diagnostics"] and, when a Source is present, read that exact inventory source with include: ["diagnostics"]. Correlate those server reads with the exact run and Activity identifiers returned by the ordinary calls to obtain the customer-safe graph and accountable Agent, Source, caller, or platform stage.
The final report distinguishes observed, failed, unavailable, and unexercised assertions and cleanup status. A validation run never claims certification; Apostra evaluates trusted evidence separately.

​
Availability and access

All Agent reads require authentication. V2 organization-management reads require a directly authenticated organization administrator. V3 compact reads also accept an account-bound machine credential working in that exact Buyer or Seller account; a user-bound credential still requires organization-admin authority. Delegated, simulated, impersonated, and staff-scoped contexts cannot use the owner projection. V3 search and get, including Murph, list the agent kind only to callers these rules admit; anyone else does not see it, rather than seeing it and being refused. Source reads require access to the relevant storefront. The V2 Page endpoints are available when your organization is enrolled in the Agents preview or has a granted Partner workspace; otherwise, they are unavailable. The internal governed-administration view is not part of the customer API.