Skip to main content
A partner can offer one sales agent to many publishers. To sell through that agent, a publisher connects their Seller Account to it. V3 does this through one form, the partner connection form, so the partner’s own setup questions and your credentials never pass through a chat.

The agents a Seller Account can add

search({ "kind": "agent" }) in a Seller Account lists the sales agents you can add, and each row says which kind it is in relationship. An Operator or Admin of the account, signed in as themselves, gets the list. An Operator can connect their own organization’s agents; connecting a partner’s agent needs an Admin.
  • own: a sales agent your organization owns, for example one registered in your organization’s Agents account. The row carries agentId and displayName. Your own agents need no certification to connect. Their certification, validation runs and diagnostics stay in the account that owns the agent.
  • partner: a partner’s shared sales agent you can connect through, as described on this page. The row also carries partnerName, urlMode and, when the partner offers one, signupUrl, and agentCertification, which says whether the agent is certified, exempt from certification, or in its partner’s beta and not yet certified. See Certified, exempt and beta partner agents.
open_page({ "page": "connect_sales_agent" }) opens the Connect sales agent task, which shows this list and lets a person choose one to connect. It is the same task Seller Setup’s Sales agent choice opens. The same page says where you register a sales agent of your own:
  • developerAccounts: your organization’s Agents accounts, each as accountId and name. An organization holds one Agents account (see Manage organization accounts), so the list has one entry, or none until it is created. Name it with accountId to register an agent there; it then appears in this list as own.
  • developerAccountsUrl: the account settings screen that creates a Agents account: your organization’s Accounts screen, or, for an account that is not part of an organization, its own Accounts screen. Creating an Agents account there turns that account into an organization, with your seller account as one of its accounts. Creating one needs an administrator.
get({ "kind": "agent", "id": "AGENT_ID" }) reads any listed id. An agent your Seller Account itself owns keeps its full read. save_inventory_source with only the agentId connects either kind. For your own agent it opens the connection task where you enter that source’s name, protocol and credentials, bound to the agent; the agent connects at the address registered for it. For a partner’s agent it opens the partner connection form below.

Open the form

Call save_inventory_source with only the agent’s agentId.
The call creates nothing. It returns the form for that agent, and you complete the connection there. Only a Seller Account can open it. A partner’s form can be read or completed only by an Admin of the account or its organization, signed in as themselves; anyone else is refused with a message that says connecting a partner’s agent needs an Admin. A Buyer Account is refused with a wrong-account error. agentId stands alone. Sending it with any other save_inventory_source field, such as endpointUrl, authenticationType or name, is refused with VALIDATION_FAILED and names the extra field. The form owns those values for a partner’s agent, and a credential is never a model-visible input. An agentId the account cannot connect to is refused before the form opens.

Connect your own sales agent

You do not type a sales agent’s address to connect it. The address belongs in your organization’s Agents account, where the agent is registered, and connecting is choosing that agent.
  1. Register the agent in your organization’s Agents account. Call save_agent with the agent’s agentUrl and the Agents account’s accountId. See Connect an agent.
  2. Find its agentId. search({ "kind": "agent" }) in your Seller Account lists it as an own row, with its agentId and displayName.
  3. Connect it. Call save_inventory_source with only that agentId, as described above, or choose the agent in the Connect sales agent task. The connection is bound to that agent and uses the address registered for it in the Agents account. An agent with no registered address is refused, and the message says to register one first.
An Operator or Admin of the Seller Account, signed in as themselves, can connect one of your organization’s own agents. A machine credential cannot.

An agent that needs credentials for every call

Some agents refuse every call without a credential, including the call that describes them, so Apostra cannot read them when you register their URL. Register such an agent as the Agents account’s save_agent step describes, by sending its kind (see Register an agent that needs credentials). Its address is recorded and the agent is marked not read yet. Connect it here as any other own agent: call save_inventory_source with its agentId, then store its credentials in the secure credential form. Apostra reads the agent with those credentials and records what it read on the agent, which ends not read yet. If the read with credentials fails, the source reports the failure and the agent stays not read yet. Credentials stay on the source; they are never collected on the Agents account or in chat.

A sales agent from an endpoint alone is refused

A Seller Account adds a sales agent only as one of the agents above: its organization’s own, or a certified partner’s. save_inventory_source without agentId that would create a SALES source from an endpointUrl is refused with VALIDATION_ERROR on the endpointUrl field, and nothing is created. The message names the way forward for your account:
  • When your organization owns sales agents, it lists up to five of them, each with its name, agentId and registered address, and says how many more there are. When the address you sent is the registered address of one of them, it says so and names that agent’s agentId. It then tells you to resend with the agent’s agentId. The REST connection call carries it as attachToAgentId; on V3, send agentId alone to save_inventory_source.
  • When your organization owns none, it says to register the agent in your organization’s Agents account first (see Connect your own sales agent).
  • Either way, it points to connecting a certified partner’s agent instead.
Only an Operator or Admin of the account, signed in as themselves, gets the list. A machine credential gets the general instruction without it, because it cannot connect an agent. The same holds when you send no address at all: save_inventory_source that would create a SALES source without agentId is refused with VALIDATION_FAILED on agentId, which says to send only the agentId of an agent from search({ "kind": "agent" }). It never asks for an address. On the REST connection call, attachToAgentId selects the agent and endpointUrl can be left out; the source connects at the agent’s registered address. If you send an endpointUrl as well, it must be that registered address. A different address is refused with VALIDATION_ERROR on the endpointUrl field, naming the registered address and saying to send only the agent’s id. To change an agent’s address, change it in the Agents account. A source you already connected keeps the address it was connected at, so change the source’s address too: save_inventory_source with the source’s id and the new endpointUrl. Until you do, Apostra does not record the source’s reads on the agent, and the agent’s next step names both addresses. The refusal covers creating a sales agent only:
  • Sources you already have keep working, and save_inventory_source with their id still changes them.
  • Signal, creative and outcome agents are still created from their endpointUrl.
The form opens as an MCP app, so it needs a host that renders them. See MCP Apps host.

Choose a sales agent in the Connect sales agent task

In Seller Setup, Sales agent (or Choose sales agent) opens the Connect sales agent task; Source diagnostics opens it too. You pick the agent from a list and don’t need to know its agentId. The list is the one search({ "kind": "agent" }) returns in a Seller Account, in two groups:
  • Your organization’s agents. The own rows: sales agents your organization owns, such as those registered in its Agents account. Choosing Connect opens the form in the same task, bound to that agent, where you enter this source’s name, protocol and credentials. The form has no address field: the agent connects at the address registered for it, and the row shows that address’s host so two agents are easy to tell apart. An agent with no registered address says it has no address yet and cannot be chosen until you add its URL in your Agents account; the row links there when Apostra gives the screen. The task shows this from Apostra’s own read of the agent; search({ "kind": "agent" }) returns the row without the host or the state.
  • Partner agents. The partner rows: certified partners’ shared sales agents. Each row shows the agent’s name, the partner that shares it, and whether the agent is certified, exempt from certification, or in its partner’s beta and not yet certified (see Certified, exempt and beta partner agents). A partner’s agent is listed once the partner may operate agents for other organizations’ clients through the Partner Program (see Certification) and has published how publishers connect to it. Until then it is not listed, get does not return it, and its agentId does not open the form. Choosing Connect opens the partner connection form for that agent, the same form save_inventory_source with its agentId opens.
  • Register in an Agents account. A Seller Account has no form for an endpoint that is not one of these agents, and the API refuses to create one (see A sales agent from an endpoint alone is refused). The task says where your own agents are registered: it names your Agents accounts you can name with accountId, or, when your organization has none, links to Create an Agents account in your account settings. It does not choose an account for you. A new agent then appears in the list.
  • Sign up. When a partner publishes a sign-up address for its agent, the row also shows a Sign up for link with the partner’s name. It opens the partner’s own sign-up page outside the chat, for a publisher who does not yet have credentials from the partner. Connecting still needs the credentials the partner gives you.
  • Approval and visibility. The partner does not approve each publisher who connects. The agent’s single certification covers every publisher connected to it. Buyers never see which partner a seller connects through.
  • When a connection is refused. The form says why in plain words and what to do next, rather than a general failure. An agent with no registered address, or whose operator has not been claimed yet, is sent to the Agents account to fix it, with a link. An agent that supports more than one way of working needs one chosen before it connects. An agent whose address is not registered with the AAO registry has to be registered at agenticadvertising.org first. Any other refusal of what you entered shows Apostra’s own message, and a refusal with no message shows a general line. On the REST connection call, these four refusals are a VALIDATION_ERROR whose details.reason is agent_has_no_address, agent_not_claimed, agent_product_mode_required or agent_not_in_aao_registry.
  • Paging and errors. A list longer than one page has a Show more button. If the list cannot be loaded, the task says so; try again. The list does not appear when the task is already attaching one agent, or when it was opened for one named provider’s connection; those show their form.

What the form asks for

The partner publishes how a publisher connects. The form shows what the partner published and nothing else:
  • Connection type. Shown only when the partner publishes more than one.
  • Endpoint. An address field appears only when the partner’s setup asks the publisher for one, for example a tenant URL. When the partner serves every publisher from one address, the form asks for none. Apostra validates the address you enter.
  • Partner fields. Any further fields the partner’s setup defines, such as a source name.
  • How to authenticate. Shown only when the partner offers more than one method. Credentials are entered in password fields. They are used to connect and are not shown again.
Apostra decides what is required and what is refused. When a value is not accepted, the form shows the message Apostra returns and keeps what you typed so you can correct it.

What happens when you connect

  1. Apostra creates your source attached to the partner’s shared agent.
  2. Apostra completes the connection. The connection is accepted and validation starts.
  3. The source goes live once validation passes and the agent is certified. The agent’s single certification covers every publisher connected to it.
If the source is created but completing the connection fails, the form keeps the source and offers only the step still to do. Connecting again does not create a second source. When your account is already connected to the agent, the form says so and asks for nothing.

Partner invites

A publisher who accepts a partner’s invite connects through the same form. The existing invite page keeps serving accepted invites until it moves to the form.