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

# Create an Agent

> Register a private Agent for your organization

`POST /api/v2/agents` creates a private Agent for an enrolled organization
account admin. Supply a unique `idempotencyKey`; repeating the exact request
returns the original Agent with `created: false`.

Sales Agents require `salesMode` of `WHOLESALE`, `COMPOSING`, or `BOTH`.
Non-Sales Agents must set `salesMode` to `null`. Choose an existing claimed
operator, or provide a new operator name to create it atomically with the
Agent. Creation never publishes an Agent or connects a Source.

The organization MCP surface also provides `open_create_agent_task` to open
the bounded Create Agent Task, and `open_agent_page` to open a created Agent.

<Note>
  This is available only to directly authenticated account admins enrolled in
  Organization Agents. Service-token and delegated sessions cannot create Agents.
</Note>

## Request

```bash theme={null}
curl -X POST "https://api.interchange.io/api/v2/agents" \
  -H "Authorization: Bearer $INTERACTIVE_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Acme Signal Agent",
    "role": "SIGNAL",
    "salesMode": null,
    "operator": { "kind": "NEW", "displayName": "Acme" },
    "idempotencyKey": "20000000-0000-4000-8000-000000000003"
  }'
```

## Parameters

| Field                  | Type         | Required        | Notes                                                                           |
| ---------------------- | ------------ | --------------- | ------------------------------------------------------------------------------- |
| `displayName`          | string       | Yes             | Agent name, 1–255 characters after trimming.                                    |
| `role`                 | enum         | Yes             | `SALES`, `SIGNAL`, `CREATIVE`, or `OUTCOME`.                                    |
| `salesMode`            | enum or null | Yes             | `WHOLESALE`, `COMPOSING`, or `BOTH` for `SALES`; `null` for every other role.   |
| `operator.kind`        | enum         | Yes             | `EXISTING` or `NEW`.                                                            |
| `operator.operatorUid` | UUID         | When `EXISTING` | A claimed operator owned by your organization.                                  |
| `operator.displayName` | string       | When `NEW`      | New operator name, 1–255 characters after trimming.                             |
| `idempotencyKey`       | UUID         | Yes             | Reuse only for the same request to safely recover from an interrupted response. |

## Response

New creation returns `201`; an exact idempotent replay returns `200`.

```json theme={null}
{
  "agentId": "20000000-0000-4000-8000-000000000001",
  "href": "/42/agents/20000000-0000-4000-8000-000000000001",
  "created": true
}
```

`href` is a handoff target for the canonical Agent Page. It is not a public
Agent URL.

## Errors

* `400 VALIDATION_ERROR` — the request is malformed, a name is empty, the
  role and sales mode are incompatible, or the operator union is invalid.
* `403 ACCESS_DENIED` — the caller is not a directly authenticated organization
  account admin.
* `404 NOT_FOUND` — Organization Agents is unavailable to the caller's enrolled
  organization, or the requested existing operator is not owned and claimed.
* `409 CONFLICT` — the idempotency key was previously used with different input.
  A duplicate active `NEW` operator name in your organization also returns this
  conflict; select the existing claimed operator instead.

See [Errors](/v2/reference/errors) for the full error contract.

## MCP tools

`open_create_agent_task` opens the bounded Create Agent Task for an enrolled
organization admin. After creation, `open_agent_page` opens the private Agent
Page by `agentId`; it is also restricted to directly authenticated organization
account admins.