Skip to main content
Build the first version as a read-only client, then add one durable buying step at a time. Your application runs the agent and stores workflow progress. Apostra keeps the advertising objects, contacts eligible sellers, executes supported transactions, and returns delivery. Complete the connection quickstart first. This guide describes the application architecture; the buyer workflow reference contains the exact current request shapes for each buying step.

​
Start with seller discovery

  1. Connect an MCP client to /mcp/v3 and authenticate.
  2. Call get_status; verify the intended Buyer Account before using its data.
  3. Read tools/list and expose only the tools your prototype needs to its model.
  4. Call search with {"kind":"seller","limit":10}. Follow returned cursors if you need the complete list.
  5. Display the sellers and their returned readiness and connection information. Keep missing or blocked states visible.
This discovery read does not request proposals. request_proposals is a later step that sends a campaign brief to the eligible seller cohort. It should run only when the user has asked your application to start that buying workflow. Use the structured result for IDs and readiness. A model can explain the result but should not reconstruct qualified identifiers or extract them from prose.

​
Connect a seller when the workflow needs it

Read the selected seller’s connection and activation state before requesting offers. Use search or get for existing connection records and the current save_connection schema for the required selection, billing, authorization, provider-account choice, or advertiser mapping. An authorization action returns a browser URL; provider credentials do not belong in the tool arguments. After the person completes any required browser step, re-read the seller and connection. A listed seller is not necessarily ready for this advertiser to buy from. The buyer workflow explains these readiness checks before campaign authoring and proposal requests.

​
Give the loop a durable owner

For a production hybrid application, keep these records outside the model’s conversation: The loop is: Application code validates the model’s proposed tool and arguments against the current schema and your allowed actions. Stop a run when it needs a person, is waiting on asynchronous work, has reached its call budget, or has no valid next step. A scheduled worker or a supported notification can resume it later.

​
Add buying steps

The launch preview and confirmation use separate idempotency keys. If the campaign changes after approval, obtain a fresh preview and approval rather than confirming a different draft. Content approval, seller creative review, and launch approval are separate decisions.

​
Resume a proposal request

A fresh request_proposals call durably schedules seller discovery. It normally returns running. Persist the original campaign revision and idempotency key before making the call, then repeat that same request until its status is complete, partial, or failed. Once terminal, follow every page.nextCursor using the documented continuation arguments. One seller can span several result pages. A partial result is not permission to discard failed seller outcomes, and the first page is not the whole result. Only one proposal execution can run per buyer across campaigns. A new key starts a new round; it is not a polling mechanism. See Request proposals.

​
Recover from interrupted writes

A timeout or disconnected MCP session does not prove a write failed. Preserve the request, inspect any structured error and partialWrite evidence, and re-read the affected object before retrying. Reuse an idempotency key only for the same logical operation and unchanged arguments. Follow a tool’s specific contract where it supplies its own identity, such as the productQueryId used when staging returned products. Connections and individual tool calls have time limits and can be interrupted by deployments. A workflow that spans creative review or seller execution must survive reconnection. See Client setup and Capability limits.

​
Give independent software its own identity

An interactive assistant using a person’s OAuth connection requires no buyer-agent registration. For independently operated software, an organization administrator can register an external buyer agent, issue its credential, and grant exact advertiser access through buyer-agent management. These controls require the documented direct administrator session. Where the current catalog advertises save_buyer_agent, use it with the matching get/search reads. Use the documented console or REST path for controls the active v3 catalog does not expose. Do not assume a runtime credential can register itself or grant its own advertiser access. Registration gives software an identity; it does not make Apostra the hosted runtime for that software.

​
Test the boundaries

Use deterministic fixtures to prove that your application handles an empty seller list, a blocked account, a multi-page proposal result, an interrupted write, and a changed campaign revision. Test that a proposed launch cannot pass the application’s approval checkpoint without an approval for the exact draft. Then use the sandbox workflow for live transaction verification. A seller can follow the no-spend own-supply recipe and the published Test a Sales Agent skill. Sandbox access is scoped; it does not prove eligibility for live supply, funding, or production launch.