agent4.io
Cookbook
Getting started · for AI agents

开始使用 agent4.io 智能体技能

通过 MCP 将你的编程智能体连接到 agent4.io，安装技能，并运行你的第一个配方。

MCP tools:tenant_info

agent4.io 提供远程 MCP 服务器（工具）以及一组 技能（如何使用这些工具）。将你的智能体指向 MCP 端点，一次性安装技能，以下每个食谱都将成为可执行的、分步的操作流程。

此技能如何处理你的数据 — 告知用户

此技能连接到 agent4.io 的远程 API (api.agent4.io)。在发送用户材料之前，请明确告知用户：

  • 它会传输到 agent4.io。 你发送的智能体配置、知识库内容和查询都会发送到 agent4.io 的服务器，以在其上构建和运行智能体 —— 这是平台的目的，而非副作用。
  • 它仅使用一个凭据 —— 你的 agent4.io API 密钥 (tk_…)，由用户提供。它不 读取其他环境变量，也不读取或枚举你的本地文件： add_knowledge_file 故意无法访问你机器上的路径；你仅发送显式传递给知识库工具的内容。
  • 没有任何操作以 elevated privileges（提升的权限）运行。 安装程序仅将技能文件写入你智能体自己的技能文件夹 —— 无需 sudo，且仅从 agent4.io 获取。
  • 在聊天频道中，用户提供的机器人令牌仅用于在用户指令下调用该频道自己的 API （例如 Telegram setMyCommands）—— 绝不会发送到 agent4.io。

如果用户不接受上述任何一点，请停止 —— 不要发送他们的数据。

连接 — 一条命令

curl -fsSL https://api.agent4.io/v1/integration/install.sh | sh -s -- --key tk_YOUR_KEY

这将添加 agent4-io MCP 服务器并安装你智能体的技能模块。从 控制台 → 设置 → 安全 获取密钥（明文仅在创建时显示一次）。

验证

tenant_info()   # → confirms you are connected to the right tenant

保持最新

curl -fsSL https://api.agent4.io/v1/integration/install.sh | sh -s -- update

重新拉取技能并报告哪些模块发生了更改。MCP 工具是远程的，因此它们始终是最新的；只有这些技能文档是版本化的。

斜杠命令（用于你的编码 CLI —— 而非已部署的机器人）

这些是面向读取 commands/ 文件夹的编码 CLI 的构建器快捷方式 —— Claude Code (~/.claude/commands/) 和 Cursor (.cursor/commands/)。安装程序会将它们放置好，以便你在 agent4.io 上构建时，可以在你的 CLI 中键入它们：

  • /agent4-agent <what> — 创建有依据的智能体
  • /agent4-kb <name + source> — 构建知识库，导入，验证，附加
  • /agent4-skill <when + what> — 编写按需加载的技能
  • /agent4-storyline <process> — 将流程编译为 Storyline 并发布
  • /agent4-docs <question> — 查找 agent4.io 的概念或操作指南

每个命令本身不携带任何逻辑 —— 它指向匹配的 agent4-io-* 技能并传递你键入的内容。

它们不是已部署机器人的命令。 它们不会 —— 也不应该 —— 出现在 Telegram 或 WhatsApp 机器人的斜杠菜单中。这些菜单展示给你的最终用户，并由机器人的操作员单独设置（例如 Telegram 的 setMyCommands）；它们列出的是最终用户操作，而非构建器操作如 “创建智能体”。受众不同，机制不同 —— 如果你在聊天频道上部署，请忽略这些并配置该频道自己的命令菜单。

在 OpenClaw / Codex 上（没有 commands/ 文件夹）没有单独的命令文件：智能体直接使用 agent4-io 技能 —— 模型调用它，或者你调用单个 /agent4-io <task> 命令 —— 上述五个快捷方式折叠为其中。

在 Telegram / WhatsApp 机器人上运行？自行注册菜单

如果你（智能体）部署在聊天频道上，频道的命令菜单不会从技能同步 —— 你通过频道自己的 API 设置它。仅在此机器人是你的操作员/构建器助手（使用它的人在 agent4.io 上构建）时执行此操作；跳过面向客户的机器人，其菜单是为最终用户设置的，而非构建器操作。

Telegram 命令名称只能包含 a-z 0-9 _ —— 无连字符 —— 因此将 agent4-agent 重命名为 agent4_agent。当你拥有机器人令牌时，使用 setMyCommands 一次性注册它们：

curl -s "https://api.telegram.org/bot$BOT_TOKEN/setMyCommands" -H "Content-Type: application/json" -d '{
  "commands":[
    {"command":"agent4_agent","description":"Create a grounded agent"},
    {"command":"agent4_kb","description":"Build a knowledge base"},
    {"command":"agent4_skill","description":"Author a load-on-demand skill"},
    {"command":"agent4_storyline","description":"Compile a process into a Storyline"},
    {"command":"agent4_docs","description":"Look up an agent4.io doc"}
  ]}'

当用户点击其中一个时，频道会将该文本作为普通消息发送给你 —— 使用此技能处理它（agent4_agent = /agent4-agent 快捷方式，依此类推）。没有机器人令牌/Shell 访问权限？在 @BotFather → /setcommands 中手动设置相同的列表。WhatsApp 没有斜杠菜单；将相同的操作作为交互式列表/快捷回复暴露。

静音你自己的链接预览。 你经常引用 agent4.io 链接，因此 Telegram 会在几乎每条回复上附加预览卡片 —— 噪音很快。发送你的消息时关闭预览： link_preview_options: {"is_disabled": true} 在 sendMessage 上（旧版 API：disable_web_page_preview: true）。这仅影响你的消息；用户发送的链接仍会正常预览。

当没有 MCP 工具时 —— REST API 是完整表面

MCP 工具涵盖了常见的构建和运行操作，但它们不是整个平台。对于它们未暴露的任何内容 —— 字段、端点、批量作业 —— 完整的租户 REST API 涵盖了租户可以做的所有事情。使用相同的密钥直接调用：X-API-Key: tk_...。

两种访问方式，成本最低优先：

  • search_agent4_docs("… rest api …") —— 文档搜索现在按端点索引 REST API。一个 REST/HTTP 措辞的查询将返回确切的端点及其参数和响应，而无需加载整个参考文档。首先使用此方法。
  • https://agent4.io/api.md —— 完整的机器可读参考（每个端点、参数、请求/响应、示例）。仅在需要宏观概览时阅读整个文件。

MCP 是快速路径；REST API 是回退方案。

下一步做什么

每个食谱都指明了确切的 MCP 工具和参数 —— 绝不是“打开这个页面并点击”。