> ## Documentation Index > Fetch the complete documentation index at: https://docs.apostra.com/llms.txt > Use this file to discover all available pages before exploring further. # Agents > Understand connected buyer agents and the software Agents that power seller inventory 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](/v2/setup/buyer-agent-credentials) 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 versioned-certification workflows. 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. ```http theme={null} POST https://api.apostra.com/api/v2/agents { "displayName": "Example Agent", "role": "SALES", "salesMode": "WHOLESALE", "operator": { "kind": "NEW", "displayName": "Example Operator" }, "idempotencyKey": "a UUID" } ``` ## Review your organization’s Agents Organization administrators can open **Agents** from the account navigation 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: ```http theme={null} GET https://api.apostra.com/api/v2/agents GET https://api.apostra.com/api/v2/agents/{agentId} ``` An agent working in one of the organization's Buyer or Seller accounts can use the account-resolved V3 MCP reads instead: ```json theme={null} { "kind": "agent", "query": "sales", "limit": 25 } ``` ```json theme={null} { "kind": "agent", "id": "AGENT_ID", "include": ["certification", "validationRuns", "diagnostics"] } ``` 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, but 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 `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: ```json theme={null} { "kind": "agent", "id": "AGENT_ID", "validationRunId": "VALIDATION_RUN_ID", "include": ["diagnostics"] } ``` 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 Murph, Agents is a full workspace alongside Inventory and Advertisers. Choose **Agents** in the left navigation to open the collection in the main canvas, then 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 the public certification decision, policy version, revision, expiry, and requirement results for a Sales Agent. Governed review actions and private evidence remain in the certification queue. 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. ## Test a Sales Agent A claimed owner can open **Test & certify** and choose a validation profile. The Page currently enables **brief-only** and **transaction**. 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. * **transaction** runs the no-spend own-supply MediaBuy scenario. It pauses before the guarded transaction step and continues only when the same directly authenticated owner supplies the returned confirmation for the exact run, generation, and pending step. Apostra re-resolves authority before it resumes and reverses the sandbox changes during cleanup. * **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. When no Source is selected, the service can use only that owner's registered temporary certification fixture; it never borrows another publisher's Source or creates a client relationship. The Page never receives a fixture token or Source credential. A profile result is diagnostic evidence, not a production certificate. Complete Sales Agent certification requires the current revision to have all required, server-owned certification assertions. A transaction result cannot by itself certify the Agent. 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. ## See which Agent powers a Source Storefront users can see the trust summary for the Agent powering one of their own inventory Sources: ```http theme={null} GET https://api.apostra.com/api/v2/storefront/inventory-sources/{sourceId}/powered-by-agent ``` `sourceId` is the identifier from your storefront’s inventory-source response. The result is one of these states: * `ACTIVE` — returns the connected Agent’s safe identity, certification, and implementation-health summary. * `UNMAPPED` — the Source has no active Agent connection. * `REVOKED` — the previous Agent connection is no longer authorized. This endpoint is scoped to the authenticated storefront and Source. It does not reveal the Agent’s other Sources, credentials, evidence, or operator-only controls. The **Powered by** projection exposes public certification detail for the connected Agent and exactly the caller’s Source. Open that Source for connection and mapping diagnostics; certification and Source health intentionally remain separate trust signals. An `ACTIVE` result carries the connected Agent’s `authority`, and the Source Diagnostics **Powered by** card reads its heading from it: * `OWNER` — the Agent belongs to your own organization. The card reads **Your Agent** rather than naming an operator, and links to your full Agent Page. * `POWERED_BY` (or `ADMIN`) — the Agent belongs to another organization. The card reads **Powered by *Agent name***, names the operator, and links to the client-safe **Powered by** projection of that Agent’s Page. `UNMAPPED` reads **This source isn't linked to an agent yet.** and `REVOKED` reads **Agent link revoked** — Apostra never falls back to URL matching to guess a binding. ## Connect your own Agent to a Source A directly authenticated organization administrator can connect an Agent their organization owns to an Inventory Source their organization owns without platform assistance: ```http theme={null} POST https://api.apostra.com/api/v2/storefront/inventory-sources/{sourceId}/agent-binding { "agentId": "20000000-0000-4000-8000-000000000001", "agentProductMode": "BOTH" } ``` For an Agent that declares both product paths, `agentProductMode` is required and selects `WHOLESALE`, `COMPOSING`, or `BOTH` for this Source. Omit it for a single-mode or undeclared Agent. This is **first-party only, and direct only**: the platform resolves the Agent's actual owning organization itself and rejects the request before writing anything if the Agent does not belong directly to your organization — including an Agent owned by a parent or sibling organization. Hierarchy-wide first-party binding is deferred to future org entity-model work. Cross-organization (Partner) connections are set up by Apostra for now. If the Agent's operator was mapped by Apostra but never explicitly claimed, binding your own Source to it also claims the operator for your organization in the same request — you do not need a separate claim step first. Only `AGENT`-execution Inventory Sources are eligible; ESA and other platform-managed Sources are not. See [Bind your Agent to a Source](/v2/storefront/agents/tasks/bind-agent-to-source) for the full request and error contract. ## 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. 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.