> ## 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.

# Connect to a partner agent

> Connect a Seller Account to a partner's shared sales agent through one form: pick how to connect, enter the partner's fields and credentials, and start validation.

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](https://docs.apostra.com/v3/seller-partner-agent-certification.md).

`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](https://docs.apostra.com/v3/account-access.md#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`.

```json theme={null}
{ "agentId": "AGENT_ID" }
```

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](https://docs.apostra.com/v3/connect-an-agent.md).
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](https://docs.apostra.com/v3/connect-an-agent.md#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](https://docs.apostra.com/v3/seller-partner-connection-form.md#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`.

> [!NOTE]
>
> The form opens as an MCP app, so it needs a host that renders them. See
> [MCP Apps host](https://docs.apostra.com/v3/mcp-apps-host.md).

## 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](https://docs.apostra.com/v3/seller-partner-agent-certification.md)). A
  partner's agent is listed once the partner may operate agents for other
  organizations' clients through the Partner Program (see
  [Certification](https://docs.apostra.com/v3/certification.md#what-a-pass-unlocks)) 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](https://docs.apostra.com/v3/seller-partner-connection-form.md#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.