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 carriesagentIdanddisplayName. 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 carriespartnerName,urlModeand, when the partner offers one,signupUrl, andagentCertification, 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 asaccountIdandname. An organization holds one Agents account (see Manage organization accounts), so the list has one entry, or none until it is created. Name it withaccountIdto register an agent there; it then appears in this list asown.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
Callsave_inventory_source with only the agent’s agentId.
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.- Register the agent in your organization’s Agents account. Call
save_agentwith the agent’sagentUrland the Agents account’saccountId. See Connect an agent. - Find its
agentId.search({ "kind": "agent" })in your Seller Account lists it as anownrow, with itsagentIdanddisplayName. - Connect it. Call
save_inventory_sourcewith only thatagentId, 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 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’ssave_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,
agentIdand 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’sagentId. It then tells you to resend with the agent’sagentId. The REST connection call carries it asattachToAgentId; on V3, sendagentIdalone tosave_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.
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_sourcewith theiridstill 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 itsagentId. The list is the one
search({ "kind": "agent" }) returns in a Seller Account, in two groups:
- Your organization’s agents. The
ownrows: 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
partnerrows: 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,getdoes not return it, and itsagentIddoes not open the form. Choosing Connect opens the partner connection form for that agent, the same formsave_inventory_sourcewith itsagentIdopens. - 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_ERRORwhosedetails.reasonisagent_has_no_address,agent_not_claimed,agent_product_mode_requiredoragent_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.
What happens when you connect
- Apostra creates your source attached to the partner’s shared agent.
- Apostra completes the connection. The connection is accepted and validation starts.
- The source goes live once validation passes and the agent is certified. The agent’s single certification covers every publisher connected to it.