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

# Create an agent

> Create an agent and get back its agent ID

An agent is an actor that moves money for you. Every payment, request, deposit, and withdrawal is attributed to its ID, so create one before you move any money.

<Snippet file="shared/prerequisites.mdx" />

<Snippet file="shared/mcp-callout.mdx" />

Create an agent with [`POST /agents`](/api-reference/agents/create-agent).

<CodeGroup>
  ```python Python theme={null}
  import uuid
  from naturalpay import Natural
  from naturalpay.agents import CreateAgentsRequestLimits

  client = Natural()
  agent = client.agents.create(
      name="Procurement Agent",
      slug="procurementagent",
      description="Buys supplies",
      limits=CreateAgentsRequestLimits(per_transaction=100_000),
      idempotency_key=str(uuid.uuid4()),
  )

  agent_id = agent.data.id
  ```

  ```typescript TypeScript theme={null}
  import Natural from "@naturalpay/sdk";

  const client = new Natural();
  const agent = await client.agents.create({
    name: "Procurement Agent",
    slug: "procurementagent",
    description: "Buys supplies",
    limits: { perTransaction: 100_000 },
    idempotencyKey: crypto.randomUUID(),
  });

  const agentId = agent.data.id;
  ```

  ```bash CLI theme={null}
  natural agents create --json '{
    "name": "Procurement Agent",
    "slug": "procurementagent",
    "description": "Buys supplies",
    "limits": { "perTransaction": 100000 }
  }' --idempotency-key "$(uuidgen)"
  ```

  ```text MCP theme={null}
  Create an agent called "Procurement Agent" with slug procurementagent for buying supplies, with a $1,000 per-transaction limit.
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/agents \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "name": "Procurement Agent",
          "slug": "procurementagent",
          "description": "Buys supplies",
          "limits": { "perTransaction": 100000 }
        }
      }
    }'
  ```
</CodeGroup>

Store the returned agent ID (`agt_*`) and pass it whenever this agent moves money, so Natural attributes the money movement to it.

## Issue a key

Creating an agent returns its ID, not a credential. Issue a key next so your runtime can authenticate as that agent with `ak_ntl_*`. The dashboard runs [`POST /agents`](/api-reference/agents/create-agent) and [`POST /agent-keys`](/api-reference/agent-keys/create-agent-key) back to back; over the API you do the same.

<CodeGroup>
  ```python Python theme={null}
  key = client.agent_keys.create(
      data={
          "attributes": {},
          "relationships": {
              "agent": {"data": {"type": "agent", "id": agent_id}},
          },
      },
  )
  print(key.data.attributes.agent_key)
  ```

  ```typescript TypeScript theme={null}
  const key = await client.agentKeys.create({
    data: {
      attributes: {},
      relationships: {
        agent: { data: { type: "agent", id: agentId } },
      },
    },
  });
  console.log(key.data.attributes.agentKey);
  ```

  ```bash CLI theme={null}
  natural agent-keys create --agent-id agt_019cd1798d637a4da75dce386343931d
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/agent-keys \
    -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {},
        "relationships": {
          "agent": {
            "data": { "type": "agent", "id": "agt_019cd1798d637a4da75dce386343931d" }
          }
        }
      }
    }'
  ```
</CodeGroup>

Issue keys from a user session only, not from a party API key. The full secret is returned once, so store it in your secrets manager immediately. Afterward you can see only its prefix.

To list, rotate, or revoke keys on an existing agent, see [Manage your agents](/guides/agents/manage-agents#agent-keys).