Agent API 指南

第一个智能体

打开 @agentfather 并发送 /newagent。选择名称和以 _agent 结尾的唯一用户名（7–32 个字符）。
点击回复中的令牌按钮，确认签发并将令牌保存到服务器。令牌仅在独立对话框显示一次，不进入聊天记录。
在自己的服务器运行 Python 示例，然后向智能体发送消息。逻辑和 AI 运行在您的基础设施中；创建智能体账户并不会部署模型。

curl https://znosin.com/api/agent/v1/me \
  -H "Authorization: Bearer $ZNOSIN_AGENT_TOKEN"

下载 Python 示例 ↓

ZNOSIN_AGENT_TOKEN · Python 3.10+

v1 功能

通过 GET /updates?callbacks=true 获取点击事件。每个更新包含 message 或 callback。按钮数据来自服务器，点击用户为 callback.from。更改数据前请检查业务权限。通过 POST /callbacks/{id}/answer 提交 text 和 showAlert。客户端最多等待 10 秒，点击在 120 秒后过期。相同回复可安全重试。点击不会创建聊天消息。目前尚不支持 Webhook 和上传发送附件。

API 参考

使用 HTTPS 和 JSON，通过 Authorization: Bearer <token> 认证。成功响应包含 ok 和 result，错误包含 ok:false 和 error。消息时间为 Unix 毫秒。完整字段见 OpenAPI 文档。

https://znosin.com/api/agent/v1

GET /me资料

GET /updates?offset=0&timeout=25消息

POST /messages发送文本

PATCH /messages/{id}编辑文本

DELETE /messages/{id}删除消息

GET /commands?language=zh命令菜单

PUT /commands保存命令

GET /files/{id}下载附件

POST /api/agent/v1/messages

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Hello!",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee"
}

PUT /api/agent/v1/commands

{
  "language": "zh",
  "commands": [
    {
      "command": "help",
      "description": "Agent API 指南"
    }
  ]
}

OpenAPI 3.1 JSON →

命令与按钮

在 POST /messages 或 PATCH /messages/{id} 中添加 markup：inline 行可包含操作按钮（text、id、data）、HTTPS 链接（text、url）或迷你应用（text、appId）。reply 键盘发送回复代理的普通消息。oneTime 在使用后隐藏键盘，type remove 移除键盘。编辑时省略 markup 可保留按钮，传入 null 则删除按钮。

{
  "chatId": "CHAT_ID_FROM_UPDATE",
  "text": "Choose an action",
  "clientId": "d73d940c-9166-4a39-8e35-c3f7888995ee",
  "markup": {
    "type": "inline",
    "rows": [
      [
        {
          "text": "Confirm",
          "id": "confirm",
          "data": "confirm:123"
        },
        {
          "text": "Cancel",
          "id": "cancel",
          "data": "cancel:123"
        }
      ],
      [
        {
          "text": "Website",
          "url": "https://znosin.com"
        },
        {
          "text": "Calculator",
          "appId": "calculator"
        }
      ]
    ]
  }
}

在聊天中输入 / 查看可用命令。在群组中选择命令会通过 /command@nickname 指定一个代理。菜单支持全部七种界面语言。开发者可通过 PUT /commands 为每种语言注册最多 20 个命令。

/setcommands @nickname zh · @agentfather

{
  "type": "reply",
  "rows": [
    [
      "Yes",
      "No"
    ],
    [
      "Help"
    ]
  ],
  "oneTime": true
}

8 rows × 4 buttons · 64 characters/label · 256 UTF-8 bytes/data · HTTPS

按钮示例 ↓

用户语言

传入消息和按钮回调包含 from.language_code，可为 en、ru、uk、de、fr、pl 或 zh。它记录事件创建时发送者的界面语言，群组也适用。旧事件、未知语言偏好和智能体自己发送的消息返回 null，请在代码中设置备用语言。重启和重试会保留该值，后续消息、编辑或其他设备的设置不会改变它。转发记录的是转发者的语言，而非原作者的语言。这是客户端提供的偏好，不是文本语言识别，也不能作为授权依据。客户端发送 X-Znosin-Language；Accept-Language 中受支持的语言作为备用来源。回复与按钮的翻译由你的代码负责。AgentFather 已随界面语言调整；/language ru 固定语言，/language auto 恢复自动选择。

{
  "from": {
    "id": "USER_ID",
    "name": "Alex",
    "nickname": "alex",
    "language_code": "zh"
  }
}

访问与隐私

智能体不能主动发起私聊。用户先发送消息；/stop 阻止后续通信，/start 从新消息恢复。在群组中，只能读取加入后发送的 /help、/help@name_agent 等命令及对自身消息的回复，不提供引用历史、旧消息、所有者邮件、钱包或账户密钥。移出群组即撤销访问权限。

可靠消息传递

长轮询最多等待 25 秒，新消息到达即返回。每个智能体仅使用一个消费者，即使结果为空也应保存 nextOffset。重试发送时使用相同 clientId 和内容。队列最多保留 10,000 条输入，最长 24 小时；reset 表示过期或溢出。限制：每分钟 180 次请求、每个智能体每分钟 60 次发送、每个聊天每分钟 30 次发送。429 和 503 时遵循 Retry-After，网络故障时延迟重试。

管理智能体

在 @agentfather 中使用 /myagents、/token @用户名、/disable @用户名、/enable @用户名、/setname @用户名名称和 /setdescription @用户名描述。轮换立即撤销旧令牌，停用会撤销令牌并清空队列，重新启用后需签发新令牌。/language en|ru|uk|de|fr|pl|zh 选择语言；/language auto 跟随界面语言。每个所有者最多 20 个智能体。

连接 AI 模型

将示例中的回显替换为服务器端模型调用。向用户说明传给模型提供商的数据。将消息和文件视为不可信输入，限制工具权限，敏感操作需人工确认。不要将 Znosin 令牌或模型密钥放入提示词或客户端代码。

聊天中的智能体