---
title: "Create agent"
method: POST
path: "/agents"
tags: ["Agents"]
---

# Create agent

`POST /agents`

Create an agent for your party.

## Headers

- `Idempotency-Key` string, required
- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Request body

- object
  - `data` object, required — Resource object
    - `attributes` object, required — Agent creation attributes
      - `name` string, required — Agent display name
      - `description` string — Agent description
      - `limits` object — Optional spend caps (per-transaction/daily/monthly) for the agent. AGENT actors may create sibling agents but must not set the limits that gate them: supplying `limits` as an AGENT actor fails with 403.
        - `perTransaction` integer, nullable — Positive per-transaction limit in cents. null means no per-transaction limit.
        - `perDay` integer, nullable — Positive daily (UTC) spend cap in cents. null means no daily limit.
        - `perMonth` integer, nullable — Positive calendar-month (UTC) spend cap in cents. null means no monthly limit.
      - `walletId` string — Wallet the agent is granted access to. When omitted, launch behavior currently uses the party default wallet.

## Response `201`

Successful Response

- object
  - `data` object, required
    - `type` 'agent', required — Resource type
    - `id` string, required — Resource ID
    - `attributes` object, required — Resource attributes
      - `name` string, required — Agent display name
      - `description` string, nullable, required — Agent description
      - `handle` string, nullable, required — Agent handle composed from the owning party's handle and the agent slug (e.g. "@acme-bot"), or null when either part is unclaimed
      - `status` 'ACTIVE' | 'REVOKED', required — Agent status
      - `limits` object, nullable, required — Spend caps for actions this agent initiates on its owner's party. null = no limits. Stored as Policies(scope=Agent(id)) in the policy service.
        - `perTransaction` integer, nullable — Positive per-transaction limit in cents. null means no per-transaction limit.
        - `perDay` integer, nullable — Positive daily (UTC) spend cap in cents. null means no daily limit.
        - `perMonth` integer, nullable — Positive calendar-month (UTC) spend cap in cents. null means no monthly limit.
      - `createdAt` string, date-time, nullable, required — When this agent was created
      - `createdBy` string, nullable, required — User who created this agent (usr_*)
      - `lastActiveAt` string, date-time, nullable, required — Timestamp of the agent's most recent authenticated request, or null if it has never made one. Updated at most about once per minute, so it reflects recent activity at minute granularity rather than exactly.
    - `relationships` object, required — Resource relationships
      - `party` object, required — Party that owns the agent
        - `data` object, required — Related resource identifier
          - `type` 'party', required — Resource type
          - `id` string, required

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found — returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/natural/natural-api/revisions/8cc2aed45847/schema)