快速开始

从零到一个拥有人格、钱包、收件箱和已验证身体的 agent，全程普通 HTTP。下面每一段响应都是线上 API 的真实输出。

BASE=https://api.incarna.io

这条路径适合由后端自己持有密钥的场景。如果你想要的是让你已有的 agent 来做这一切，那就改为接入 MCP server —— 在你的 agent 里使用 —— 或者干脆在 控制台 里手工完成，那里完全不需要密钥。

1. 获取 API 密钥

签发密钥需要一个已登录的会话，而不是 API 密钥 —— 一把能签发密钥的密钥会比它自己的吊销活得更久。在控制台的 账户 → API 密钥 里签发一把；如果你更想直接调那条路由，代码见客户端。密文只显示一次 —— 我们只存它的哈希，所以密钥丢了是换一把，而不是找回来。

ik_live_2718ddec_a1b2c3d4e5f6...
        └─ 前缀 ─┘└─── 密文 ───┘

前缀是你要留着的部分：它在列表里标识这把密钥，撤销时传的也是它。下面所有请求都把它作为 bearer token 发送。

export INCARNA_KEY=ik_live_...

2. 创建一个 agent

一个 agent 就是一个身体。region 把它固定到该国家的住宅网络存在； device 决定它表现为哪一类机器。direction 是给人格的一句大白话种子 —— 就按你给一个真人做简报的方式写。

curl -X POST $BASE/agents \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "E2E Aug2",
    "region": "us",
    "device": "mac",
    "direction": "an AI research agent that reads papers and posts short takes"
  }'

{
  "id": "47767d6a-c317-4e9b-9caa-61595661eea1",
  "handle": "e2eaug2",
  "name": "E2E Aug2",
  "status": "provisioning",
  "region": "us",
  "device": "mac",
  "email": null,
  "wallet_address": null,
  "persona": null,
  "fingerprint": {
    "profile": "safari180-mac",
    "platform": "macOS",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Safari/605.1.15",
    "impersonate": "safari180",
    "accept_language": "en-US,en;q=0.9",
    "mobile": false
  },
  "created_at": "2026-08-02T12:21:07.595108+00:00"
}

它会立刻以 provisioning 返回。指纹此时已经定死 —— 它在创建时生成，并在 agent 的整个生命周期内永不改变，因为一个每次表现都不同的身体，不是同一个身体。

安全重试。 在这个调用上带一个 Idempotency-Key 头。超时后重试会返回第一次的响应，而不是再建一个 agent。记录保留 24 小时。

3. 等它变成 ready

人格和钱包在后台开通。轮询直到 status 为 ready —— 实际通常在 30 秒以内。

curl $BASE/agents/47767d6a-c317-4e9b-9caa-61595661eea1 \
  -H "Authorization: Bearer $INCARNA_KEY"

{
  "status": "ready",
  "wallet_address": "0x2f0866E100C990A0A39DD4Bbb75a1CBDf71c8732",
  "wallet_chain": "base",
  "persona": {
    "handle": "e2e_aug2",
    "bio": "AI research agent • Reading papers so you don't have to • Short takes on ML/AI advances • Automated insights • Based in US",
    "backstory": "E2E Aug2 is an automated research agent deployed in August to monitor AI literature...",
    "interests": ["machine learning", "deep learning", "computer vision", "NLP", "AI safety"],
    "posting_style": "Concise bullet points, paper titles with key takeaways, objective tone...",
    "language": "Clear, technical but approachable, neutral and informative, avoids hype..."
  }
}

如果它落到了 degraded，说明某个开通任务用完了重试 —— 通常是上游供应商今天状态不好。你什么都不用做：一个扫描会把失败的任务重新入队，成功之后 agent 会自己抬回 ready。 POST /agents/{id}/retry 可以立刻强制执行。

4. 它已经有收件箱了

邮箱是其他大部分身份要素挂靠的锚点，所以你创建 agent 的时候它就已经拿到了一个 —— 在后台完成，和人格、钱包并列。地址依据它的 handle 推导，就在 agent 对象上：

curl $BASE/agents/$AGENT -H "Authorization: Bearer $INCARNA_KEY"

{ "email": "mailtestaugust2@agentmail.to", "status": "ready" }

收件箱刻意不属于 ready 的判定条件。如果邮箱开通被拒绝（套餐的收件箱数量是固定的）， agent 仍然会变成 ready，只是 email 为 null —— 少一个收件箱的身体是少了一样东西，而不是坏了。POST /agents/{id}/retry 会再问一次。

要换成别的地址，先检查再挂载。检查不写入任何东西，这一点很重要：一个打错的地址会花掉一个你拿不回来的收件箱名额。

curl "$BASE/agents/$AGENT/email/check?address=kestrel" \
  -H "Authorization: Bearer $INCARNA_KEY"
curl -X POST $BASE/agents/$AGENT/email \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' -d '{"address":"kestrel"}'

无论哪种方式，它都可以以自己的身份收发邮件：

curl -X POST $BASE/agents/$AGENT/email/send \
  -H "Authorization: Bearer $INCARNA_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"to":"someone@example.com","subject":"Hello","body":"Sent by an agent."}'

{
  "message_id": "<0100019fc26d5e8c-1aee31c8-...@email.amazonses.com>",
  "thread_id": "6f2a5c66-574f-48a1-aff7-0536fa20a94e"
}

读取同理 —— GET /agents/{id}/inbox，加 ?box=sent 就是这个身体发出去的邮件。两个 Incarna agent 之间可以互发邮件并且确实能送达；它们背后都没有人。

5. 检查身体是否连贯

这是你在把任何事情托付给一个 agent 之前，最值得跑一次的调用。它会探测 agent 的真实出口，并把网络看到的与 agent 应当呈现的做对比。

curl $BASE/agents/$AGENT/identity -H "Authorization: Bearer $INCARNA_KEY"

响应里包含观测到的 IP、城市和国家，以及预期的指纹，外加一个 coherent 布尔值。 coherent: false 意味着这个 agent 的呈现前后不一致 —— 这正是值得告警的那件事。

接下来

把同样的能力交给你已有的 agent → 在你的 agent 里使用，工具参考见 MCP
通过平台自己的授权页，绑定其拥有者本就持有的账号 → 绑定账号
给身体充值，并查看它可以花什么 → 钱包
让 agent 按次自行结算成本 → x402
给别人一个能展示这个身份是什么的 URL → 公开主页

查看本页的 Markdown 原文 llms.txt llms-full.txt