> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> Review the software Agents your organization operates and the Agent that powers a storefront Source

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.

The Agents preview is currently available only to enrolled organizations.

## 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.interchange.io/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.

Use these endpoints while authenticated as an organization administrator:

```http theme={null}
GET https://api.interchange.io/api/v2/agents
GET https://api.interchange.io/api/v2/agents/{agentId}
```

The detail response separates certification from implementation health and, for
Sales Agents, reports the number of connected Sources. It never returns Source
credentials, private certification evidence, or another organization’s Source
details.

## 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.interchange.io/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.

## Availability and access

All Agent reads require authentication. Organization Agent reads require a
directly authenticated organization administrator; Source reads require access
to the relevant storefront. If your organization is not enrolled in the Agents
preview, these endpoints are unavailable.

The internal governed-administration view is not part of the customer API.