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

# Create Agent

> Create a new agent to establish a dedicated Moorcheh namespace for storing and retrieving memories.

## Overview

Create a new agent namespace for storing and retrieving memories. Each agent receives a unique `agent_id` which acts as an isolated context container in Moorcheh (`memanto_agent_{agent_id}`).

## Authentication

Memanto validates Moorcheh credentials **on the server** using `MOORCHEH_API_KEY` (environment / server configuration).

<ParamField header="Authorization" type="string">
  `Bearer <key>` — required unless the request originates from a loopback client. See [Management Endpoint Authentication](/api-reference/authentication#management-endpoint-authentication-agent-lifecycle).
</ParamField>

<ParamField header="X-Api-Key" type="string">
  Alternative to `Authorization: Bearer` — same credential.
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

## Body

<ParamField body="agent_id" type="string" required>
  Unique agent identifier (alphanumeric, hyphens, underscores only).
</ParamField>

<ParamField body="pattern" type="string">
  Agent pattern for memory organization. One of: `support`, `project`, `tool`. Defaults to `support`.
</ParamField>

<ParamField body="description" type="string">
  Optional human-readable description of the agent.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8000/api/v2/agents" \
    -H "Content-Type: application/json" \
    -d '{
      "agent_id": "customer-support",
      "pattern": "support",
      "description": "Handles customer inquiries"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 - Created theme={null}
  {
    "agent_id": "customer-support",
    "namespace": "memanto_agent_customer-support",
    "pattern": "support",
    "description": "Handles customer inquiries",
    "created_at": "2026-05-04T10:30:00.000000",
    "last_session": null,
    "memory_count": 0,
    "session_count": 0,
    "status": "ready"
  }
  ```

  ```json 401 - Unauthorized (Management Auth Required) theme={null}
  {
    "detail": "Unauthorized. Agent management endpoints require either a loopback client or a valid management credential (Authorization: Bearer <key> or X-Api-Key)."
  }
  ```

  ```json 409 - Conflict theme={null}
  {
    "detail": {
      "error": "AgentAlreadyExists",
      "message": "Agent 'customer-support' already exists",
      "details": {}
    }
  }
  ```

  ```json 422 - Validation Error theme={null}
  {
    "detail": [
      {
        "type": "missing",
        "loc": [
          "body",
          "agent_id"
        ],
        "msg": "Field required",
        "input": {}
      }
    ]
  }
  ```

  ```json 500 - Server Error theme={null}
  {
    "detail": {
      "error": "InternalServerError",
      "message": "An unexpected error occurred",
      "details": {
        "original_error": "..."
      }
    }
  }
  ```
</ResponseExample>

Common causes of `500` include the server missing `MOORCHEH_API_KEY`, an invalid key (Memanto may fail at startup), or failure to create the namespace in Moorcheh.

## Next Steps

After creating a new agent, you can:

* [Activate Agent](/api-reference/sessions/activate-agent) to start a session and obtain an operational token
* [List Agents](/api-reference/agents/list-agents) to verify it was created
* [Get Agent](/api-reference/agents/get-agent) to retrieve its configuration details