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

# Agents

> Authorize autonomous agents to act for customers

Agents are created by developers using Natural to enable autonomous [Payments](/guides/concepts/payments) workflows. Developers can use agents to request payment authority from their customers, represented by another Party.
Developers can also use their own Party to send payments on behalf of themselves.

A developer can register multiple agents on Natural, each of which can execute on behalf of multiple parties on Natural.
Each agent-customer pair can have granular permissions and limits, managed through an agent-customer relationship requested by the developer and approved by the customer. Developers and their customers can subsequently update or revoke that relationship via the Dashboard or API.

<Tip>
  Not building the agent runtime yourself? Connect **Claude**, **Cursor**, or another MCP client to
  Natural via the [MCP connector](/guides/platform/mcp) with OAuth — the agent runs inside the host
  app and calls Natural's tools directly.
</Tip>

## Agent customer model

Alice (Developer) adds Bruce (Business) as a customer for one of her agents with specific permissions and limits. Bruce reviews and approves the agent-customer relationship:

```text theme={null}
1. Alice (Developer)
   └─ Creates Agent (Carrier Payment Agent)
   └─ Adds Bruce as a customer for the agent
       └─ Permissions: [payments.create, payments.read]
       └─ Limit: $1000 per transaction

2. Bruce (Business)
   └─ Approves the agent-customer relationship

3. Alice (Developer)
   └─ Uses Agent to pay Terri (Contractor) on behalf of Bruce
```

Agent-customer relationships can include the following permissions:

* `payments.create` - Create payments
* `payments.read` - Read payment status
* `wallets.read` - Check wallet balance
* `wallets.update` - Modify wallet settings
* `party.read` - View party information
* `party.update` - Modify party details

Agents operate within a configurable **per-transaction limit** — the maximum amount for any single payment.

When an agent attempts to exceed its limit, the transaction is blocked and an escalation is raised — the party's owners and admins are notified by dashboard and email to approve or deny it.
Developers do not need to store information around permissions, limits, and escalations.

## Agent authentication

Agents authenticate via our [SDKs](/guides/platform/sdks) using credentials the developer owns. There are two ways to establish agent identity:

* **Agent keys** (`ak_ntl_…`) — a credential bound to one agent. Requests resolve as that agent automatically. The same verified binding applies to agent-scoped [MCP OAuth](/guides/platform/mcp) grants.
* **API keys** (`sk_ntl_…`) — a party credential for user/party actions. Prefer agent keys or agent-scoped OAuth for new agent integrations.

See [Authentication](/api-reference/authentication) for the full credential model. Agent attribution is optional: dashboard users, user-scoped MCP grants, and plain API key calls move money as user/party actions without naming an agent.

### Instance ID required for agent money movement

Whenever a money-movement request is attributed to an agent — by agent key or agent-scoped OAuth grant — it must also carry an `instance_id` (`X-Instance-ID`) for transaction observability. Agent-attributed money-movement requests without `X-Instance-ID` are rejected with a 400 error (`missing_instance_id`). Reads do not require an instance ID.

## Agent instances

An `instance_id` is an identifier that groups related agent executions together. In other common frameworks like LangGraph or OpenAI Assistant API, this is represented by a `thread_id`. While Natural tracks every payment individually, an `instance_id` allows developers to correlate multiple actions belonging to the same logical workflow.

For example, if your agent processes a multi-step payment execution (outbound contractors → negotiate rates → send multiple payment), you can tag all actions with the same `instance_id` to view them as a single workflow in the audit trail.

Instances are developer-controlled. Developers should pass `instance_id` as an idempotent string to Natural that helps group their agent executions together.

## Audit trail

All agent actions are logged and auditable, with clear grouping by requests and instances. These will include intents such as tool calls as well as internal execution mechanics such as limits being hit or escalations having been triggered.

Developers can review agent activity to ensure compliance and detect anomalies.

## Related concepts

* [Parties](/guides/concepts/parties) - Party identities that agents operate on behalf of
* [Users](/guides/concepts/users) - Users who create and manage agents
* [Payments](/guides/concepts/payments) - Payment transactions executed by agents