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

# Register Agent

> Explicitly register an agent identity in the project

Creates a new agent row and returns its id. Registration is optional: tracing under a bare
`name` auto-registers a single stable agent per distinct name. Register explicitly when you
want a real id up front, or when you deliberately need **two agents sharing one display name**
(the only way that can happen) - from then on, disambiguate them by passing the returned `_id`
as `agentId` on [Submit Trace](/api-reference/tracing/submit-trace).

<Note>
  This endpoint always creates a **new** row, even if an agent with this name already exists.
  The implicit path (tracing under a name with no explicit `agentId`) keeps resolving to the
  oldest agent registered under that name, so existing callers never change behavior.
</Note>

## Authentication

<ParamField header="x-api-key" type="string" required>
  Project API key.
</ParamField>

## Body

<ParamField body="name" type="string" required>
  Agent display name. Leading/trailing whitespace is trimmed.
</ParamField>

## Response

Returns `201 Created`.

<ResponseField name="agent" type="object">
  The created agent: `{ "_id": string, "name": string, "createdAt": string }`.
</ResponseField>

## Errors

| Status | Body                              | Meaning                                |
| ------ | --------------------------------- | -------------------------------------- |
| `400`  | `{ "error": "name is required" }` | `name` missing, not a string, or blank |

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST http://localhost:4700/api/v1/agents \
    -H "x-api-key: agtx_local_0f3c9a17d2b84e6a5c01b9f4e7d8a2c6431b5f97a0e2d4c8" \
    -H "Content-Type: application/json" \
    -d '{ "name": "customer-support-agent" }'
  ```

  ```python Python SDK theme={null}
  agent = client.monitor.create_agent("customer-support-agent")
  print(agent["_id"])
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "agent": {
      "_id": "aG5kR8sLp3WvX1nC7qZtB",
      "name": "customer-support-agent",
      "createdAt": "2026-08-27T10:30:00.000Z"
    }
  }
  ```

  ```json 400 Missing name theme={null}
  {
    "error": "name is required"
  }
  ```
</ResponseExample>