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

# Agent Create (`proofable_agent_create`)

> Create or import an agent on your profile, with an optional dedicated spend account.

The agent links to your Proofable profile and defaults to your signed-in account. Add a separate spend account and limits only when you need them.

| Step | Action |
| - | - |
| 1 | **`proofable_agent_link`** with **`agentId`** and **`agentWallet`** (use the signed-in account from **`proofable_context`** unless you already have a dedicated account) |
| 2 | **`proofable_agent_create`** with the same stable identifiers |
| 3 | Follow the returned **`next_action`** exactly |
| 4 | **`proofable_agent_link`** until **`linked: true`** |

Leave out **`controllerWallet`** when the signed-in account from **`proofable_context`** should own the agent.

Ask:

> Create or import an agent on my Proofable profile. Give it a separate spend account if it needs one. Set spend and action limits. Then confirm it is ready.

[Agent concepts](../agents/concepts)

Inspect a package, repo, or card with the [agent import](/agents/import) HTTP routes, then call **`proofable_agent_create`** with the mapped fields. There is no separate import tool.

## Account options

### Signed-in profile (default)

Omit **`agentWallet`**. The agent lives on your signed-in account. Identity is enough. Several agents on one account need **`agentId`** on every link and mount call.

### Dedicated account

Proofable does not generate or hold private keys. Create the account in your wallet or secure runtime, then pass only its public address as **`agentWallet`**.

```json theme={"system"}
{
  "agentId": "data-analyst",
  "agentWallet": "0xAgent...",
  "delegationAllowedActions": ["read_context", "read_proofs"],
  "delegationDeniedActions": ["send_message"],
  "delegationRuntimePolicy": { "requiresHumanApproval": true },
  "maxSpend": "15000000"
}
```

Use a dedicated account when you want independent spend, revocation, or offboarding without touching your profile account.

### Bring an existing account

Pass an existing **`agentWallet`**. The agent account signs identity. The approving profile signs spend and action limits.

When the signed-in account does not control that key:

1. Sign and submit the returned identity step with the agent key.
2. Repeat **`proofable_agent_create`** unchanged.
3. The approving account completes permissions in-session or through the returned hosted URL.

A controller session cannot self-attest for a different agent account, so identity always comes first.

## What each result means

Every non-validation result includes **`path`** and **`next_action`**.

| `path` | Meaning | `next_action` |
| - | - | - |
| `already_linked` | Identity and the permissions this account needs already exist | `ready` |
| `session_auto_complete` | Signed-in session completed the missing step(s) | `call_proofable_agent_link` |
| `signatures_required` | A signature is still required | `submit_remaining_signatures` |
| `hosted_required` | Browser handoff is required | `open_hosted_verify` |
| `payment_required` | The account paying for the current step needs more credits | `complete_billing_then_retry` |

**`sessionProgress.identityComplete`**, **`delegationRequired`**, and **`delegationComplete`** show which step is required and already saved. On **`payment_required`**, add credits and retry the same request. This is an account billing requirement, not a signature failure.

## Hosted callback

Use the SDK helper instead of assembling query strings:

```javascript theme={"system"}
import { getHostedAgentCreateUrl } from '@proofable/sdk';

const url = getHostedAgentCreateUrl({
  agentId: 'data-analyst',
  agentWallet,
  controllerWallet,
  identityQHash, // required here because the accounts differ
  allowedActions: ['read_context', 'read_proofs'],
  deniedActions: ['send_message'],
  runtimePolicy: { requiresHumanApproval: true },
  returnUrl: 'https://app.example.com/agents/callback',
});
```

With **`identityQHash`**, Hosted Verify requests only permissions. The callback receives the new permission **`qHash`**, **`agentId`**, and **`agentWallet`**. Keep the identity **`qHash`** from step 1.

Do not combine agent creation with **`gateId`** or **`intent=login`** on one URL:

* Login: **`intent=login&returnUrl=...`**
* Gate checkout: **`gateId=...&returnUrl=...`**
* Agent setup: **`getHostedAgentCreateUrl(...)`**

## Billing

Billing follows the signer for each proof unless a validated sponsor or pay-per-call proof overrides it:

* Agent identity: the **agent account** pays.
* Permissions (separate spend account only): the **approving profile** pays.
* Hosted completion: the signed-in account pays for the step it signs.
* Sponsor grant or pay-per-call: the validated sponsor/caller pays.

Hosted sign-in itself is free. See [Pricing](../pricing).

Optional fields include **`instructions`**, **`skills`**, **`services`**, scope, expiry, spend cap, runtime policy, approval policy, and allowed/denied actions. See [Agent identity](../agents/agent-identity) and [Agent delegation](../agents/agent-delegation).

## Related

[Auth](./auth), [Agent link](./agent-link), [Overview](./overview), [Verify an agent](../agents/named-agent-card)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.