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

# Manage your agents

> List and edit your agents

See every agent you have created, inspect one, rename it, or revoke it when it is done.

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

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

## List your agents

List every agent on your account with [`GET /agents`](/api-reference/agents/list-agents).

<CodeGroup>
  ```python Python theme={null}
  from naturalpay import Natural

  client = Natural()
  agents = client.agents.list()
  ```

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

  const client = new Natural();
  const agents = await client.agents.list();
  ```

  ```bash CLI theme={null}
  natural agents list
  ```

  ```text MCP theme={null}
  List my agents.
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/agents \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

## Inspect one agent

Inspect one agent by ID with [`GET /agents/{agentId}`](/api-reference/agents/get-agent).

<CodeGroup>
  ```python Python theme={null}
  agent = client.agents.get("agt_019cd1798d637a4da75dce386343931d")
  ```

  ```typescript TypeScript theme={null}
  const agent = await client.agents.get({
    agentId: "agt_019cd1798d637a4da75dce386343931d",
  });
  ```

  ```bash CLI theme={null}
  natural agents get --agent-id agt_019cd1798d637a4da75dce386343931d
  ```

  ```text MCP theme={null}
  Show me my Procurement Agent.
  ```

  ```bash cURL theme={null}
  curl https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
    -H "Authorization: Bearer $NATURAL_API_KEY"
  ```
</CodeGroup>

## Rename an agent

Rename an agent, change its description, or adjust its [limits](/guides/controls/limits), with [`PATCH /agents/{agentId}`](/api-reference/agents/update-agent).

<CodeGroup>
  ```python Python theme={null}
  import uuid

  agent = client.agents.update(
      "agt_019cd1798d637a4da75dce386343931d",
      idempotency_key=str(uuid.uuid4()),
      name="Procurement Agent v2.1",
      description="Autonomous agent that pays contractors",
  )
  ```

  ```typescript TypeScript theme={null}
  const agent = await client.agents.update({
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    idempotencyKey: crypto.randomUUID(),
    name: "Procurement Agent v2.1",
    description: "Autonomous agent that pays contractors",
  });
  ```

  ```bash CLI theme={null}
  natural agents update --agent-id agt_019cd1798d637a4da75dce386343931d \
    --name "Procurement Agent v2.1" \
    --description "Autonomous agent that pays contractors" \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X PATCH https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{
      "data": {
        "attributes": {
          "name": "Procurement Agent v2.1",
          "description": "Autonomous agent that pays contractors"
        }
      }
    }'
  ```
</CodeGroup>

## Revoke an agent

Revoke an agent with [`DELETE /agents/{agentId}`](/api-reference/agents/delete-agent). Its status becomes `REVOKED` and it stops moving money at once, but the record stays readable so its history survives.

<CodeGroup>
  ```python Python theme={null}
  import uuid

  client.agents.remove(
      "agt_019cd1798d637a4da75dce386343931d",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  await client.agents.remove({
    agentId: "agt_019cd1798d637a4da75dce386343931d",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agents remove --agent-id agt_019cd1798d637a4da75dce386343931d \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.natural.com/agents/agt_019cd1798d637a4da75dce386343931d \
    -H "Authorization: Bearer $NATURAL_API_KEY" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>

## Agent keys

An agent key (`ak_ntl_*`) is a credential bound to one agent. Your dashboard lists keys on the agent detail page; over the API, use the agent-keys endpoints below. Issue a new key when you [create an agent](/guides/agents/create-agent#issue-a-key).

### List keys

There is no get-by-id endpoint. List keys with [`GET /agent-keys`](/api-reference/agent-keys/list-agent-keys), optionally filtered by agent.

<CodeGroup>
  ```python Python theme={null}
  keys = client.agent_keys.list(agent_id="agt_019cd1798d637a4da75dce386343931d")
  ```

  ```typescript TypeScript theme={null}
  const keys = await client.agentKeys.list({ agentId: "agt_019cd1798d637a4da75dce386343931d" });
  ```

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

  ```bash cURL theme={null}
  curl "https://api.natural.com/agent-keys?agentId=agt_019cd1798d637a4da75dce386343931d" \
    -H "Authorization: Bearer $NATURAL_USER_TOKEN"
  ```
</CodeGroup>

### Rotate a key

Rotate with [`POST /agent-keys/{keyId}/rotate`](/api-reference/agent-keys/rotate-agent-key) to mint a fresh secret on the same agent. Set a grace period so running workloads can pick up the new key before the old one stops working. The new secret is again shown once.

<CodeGroup>
  ```python Python theme={null}
  import uuid

  rotated = client.agent_keys.rotate(
      key_id="agk_550e8400e29b41d4a716446655440000",
      data={"attributes": {"expiresInSeconds": 86400}},
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  const rotated = await client.agentKeys.rotate({
    keyId: "agk_550e8400e29b41d4a716446655440000",
    data: { attributes: { expiresInSeconds: 86400 } },
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agent-keys rotate \
    --key-id agk_550e8400e29b41d4a716446655440000 \
    --expires-in-seconds 86400 \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.natural.com/agent-keys/agk_550e8400e29b41d4a716446655440000/rotate \
    -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)" \
    -H "Content-Type: application/json" \
    -d '{ "data": { "attributes": { "expiresInSeconds": 86400 } } }'
  ```
</CodeGroup>

### Revoke a key

Revoke with [`DELETE /agent-keys/{keyId}`](/api-reference/agent-keys/revoke-agent-key) to invalidate a key immediately. This cannot be undone, and other keys on the same agent keep working. Reach for it when a secret leaks or you are retiring one credential without archiving the agent.

<CodeGroup>
  ```python Python theme={null}
  import uuid

  client.agent_keys.revoke(
      key_id="agk_550e8400e29b41d4a716446655440000",
      idempotency_key=str(uuid.uuid4()),
  )
  ```

  ```typescript TypeScript theme={null}
  await client.agentKeys.revoke({
    keyId: "agk_550e8400e29b41d4a716446655440000",
    idempotencyKey: crypto.randomUUID(),
  });
  ```

  ```bash CLI theme={null}
  natural agent-keys revoke \
    --key-id agk_550e8400e29b41d4a716446655440000 \
    --idempotency-key "$(uuidgen)"
  ```

  ```bash cURL theme={null}
  curl -X DELETE https://api.natural.com/agent-keys/agk_550e8400e29b41d4a716446655440000 \
    -H "Authorization: Bearer $NATURAL_USER_TOKEN" \
    -H "Idempotency-Key: $(uuidgen)"
  ```
</CodeGroup>