build-agent

构建 Agenta Agent

将一条普通语言请求转化为 Agenta 上可用且经过测试的 Agent。你只需编写一个 JSON 配置，并运行几个打包好的脚本。尽量减少调用次数和耗时。 最简单的 Agent 只需两步：编写配置，运行 build.sh。简单的需求无需过度思考。

Agenta 是一个用于构建、测试和部署大模型应用及 Agent 的开源平台。本技能通过 Agenta HTTP API 构建 Agenta Agent。

请先使用本技能。 你需要的一切都在此文件夹中：下方的操作指南和 scripts/ 中的脚本。这些信息已通过实时 Agenta 部署确认。默认情况下不要浏览网页或代码库。只有在确实遇到阻碍时，才可将开源仓库（https://github.com/Agenta-AI/agenta）和文档（https://docs.agenta.ai）作为后备参考；优先采用此处的说明。

首次运行：凭据和先决条件

每次构建前，只需完成以下两项一次。

1. 凭据。 脚本需要 AGENTA_API_KEY；仅当用户自行托管时才需要 AGENTA_HOST（默认使用 Agenta 云端 https://cloud.agenta.ai）。

• 向用户索要 API 密钥，并告知他们在哪里获取：Agenta 项目设置中的 API 密钥页面（云端地址为 https://cloud.agenta.ai）。仅当用户自行托管时，才询问主机 URL；这种情况下，主机 URL 是他们自己的 Agenta 域名。
• 然后询问用户希望如何设置，并主动代为处理：
  • 代为写入： 在工作目录中创建 .env 文件，写入 AGENTA_API_KEY=...（自行托管时还要写入 AGENTA_HOST=...）。lib.sh 会自动读取本地 .env。
  • 提供可粘贴的内容： 提供 export 命令，或可供用户自行创建的 .env 文件内容。
• 切勿打印或提交密钥。如果该目录是代码仓库，请将 .env 添加到 .gitignore。

2. 先决条件。 运行 bash scripts/check-prereqs.sh。该脚本会检查是否已安装 bash、curl 和 jq。如果缺少某项，它会显示适用于用户平台的准确安装命令；将命令展示给用户，请他们安装相应工具，然后继续。

每个 Agent 的结构

Agent 是一个 JSON 对象，即 parameters.agent。你只需决定其中四项：instructions.agents_md（它的身份和职责）、tools（它可以调用的集成操作）、skills（可复用的专业知识），以及是否需要触发器（计划或事件）。其余内容都是固定模板——请原样复制：

{
  "instructions": { "agents_md": "<what the agent is and does>" },
  "llm": { "model": "sonnet", "provider": "anthropic", "connection": { "mode": "self_managed" } },
  "tools": [],
  "mcps": [],
  "skills": [],
  "harness": { "kind": "claude" },
  "runner": { "kind": "sidecar", "interactions": { "headless": "auto" } },
  "sandbox": { "kind": "local" }
}

除非另有指示，否则请保持 llm / harness / runner / sandbox 与上方完全一致。model 是别名（sonnet、opus、haiku、default），不能使用原始模型 ID。要逐字段了解完整配置，包括工具条目、技能条目，以及放错位置会导致 500 错误的字段，请阅读 references/config-schema.md。

循环（按顺序执行，跳过请求不需要的步骤）

1. 阅读请求，判断需要什么，使用下方的决策表。大多数请求只需要指令。不要发现请求未要求的工具或触发器。
2. 如果需要集成操作，则发现相应集成，运行 bash scripts/discover-tools.sh "<capability>"。此命令会输出确切的 tools 条目以及每个连接的状态。详情请参阅： references/tools-and-connections.md。
3. 如果所需连接的状态不是 ready，则停止并请用户连接。 不要猜测，不要捏造结果。说明需要连接哪个集成以及原因，然后停止。这是正确且完整的结果，并非失败。
4. 将配置写入 configs/ 下的文件。 集成操作放入 tools，可复用的知识放入 skills，行为放入 instructions.agents_md。对于多工具或定时 Agent，将 instructions.agents_md 写成明确的编号步骤，按顺序列出确切的工具，并以终止操作结尾——否则运行过程会偏离方向或提前停止。详细说明请参阅 references/writing-instructions.md。
5. 一次性创建并测试： bash scripts/build.sh <config> <slug> "<test message>"。 阅读 OUTPUT 和 RESOLVED 行。RESOLVED 必须显示 harness=claude model=sonnet connection=self_managed。
6. 如果需要触发器，使用 variant id 和 revision id（两者均由 create-agent.sh / build.sh 输出）创建触发器——定时任务使用 bash scripts/create-schedule.sh，事件订阅使用 bash scripts/create-subscription.sh（仅在运行 discover-triggers.sh 且连接状态为 ready 后）。必须传入 revision id：如果没有传入，触发器就没有绑定的运行版本，Agenta UI 会将其视为错误。如果手头只有 variant id，可用字面值 latest 替代 revision id。运行 bash scripts/triggers.sh schedules（或 subscriptions）进行确认。
7. 报告：用简短的项目符号列表说明构建的内容、工件 ID、测试内容、结果，以及需要用户处理的事项。

决策表

请求……	需要	添加内容
转换用户粘贴的文本（总结、改写、分类）	无需额外内容	仅需 instructions
应用一套知识（写作风格、审查标准）	一个技能	一个 skills 条目
在外部工具中读写（GitHub、Slack 等）	网关工具	discover-tools.sh，然后添加 tools 条目
按时运行（例如每天两次）	一个定时任务	构建 Agent，然后运行 create-schedule.sh
对外部事件作出反应（新 issue、新消息）	一个订阅	discover-triggers.sh，然后运行 create-subscription.sh（需要就绪的连接）
修改已有 Agent	一个新版本	针对 variant id 运行 update-agent.sh，然后重新测试

脚本（你与 API 交互的唯一接口）

在此技能目录中运行 bash scripts/<name>。这些脚本封装了真实的 Agenta 端点，并会自行加载凭据——你无需处理 API 密钥。

• check-prereqs.sh — 开始前检查是否已安装 bash/curl/jq。
• build.sh <config.json> <slug> "<msg>" [name] — 创建 Agent 并测试。最快捷的方式。
• create-agent.sh <config.json> <slug> [name] — 仅创建；输出 application_id / variant_id / revision_id。需要在安排任务前获取 variant id 时使用。
• test-agent.sh <application_id> <config.json> "<msg>" — 批量调用并验证。单次非流式调用会返回完整的真实对话轮次，因此会输出 OUTPUT（最后一条助手消息）、TOOLS: 行（按顺序列出调用的所有工具及调用／结果数量）、运行暂停在审批关卡时显示的 APPROVAL: 行、RESOLVED（运行实际使用的配置）以及 TRACE id。
• discover-tools.sh "<capability>" ... — 根据自然语言操作查找网关工具；显示每个连接的状态以及可直接接入的工具对象。
• discover-triggers.sh "<event>" ... — 查找事件触发器（仅用于订阅）。
• update-agent.sh <variant_id> <config.json> [message] — 将新配置提交到现有 Agent。优先使用此脚本，而不是归档后重新创建：slug、各个 id 及任何触发器都会保留。
• create-schedule.sh <variant_id> <revision_id> "<cron UTC>" <event_key> [name] [inputs_json] — 定时触发器。revision id（来自 create-agent.sh / build.sh）用于固定运行的已提交版本；省略它会导致定时任务未绑定任何 revision。传入 latest 而非真实 id，脚本便会为你查找该 variant 当前的 HEAD revision。
• create-subscription.sh <variant_id> <revision_id> <event_key> <connection> [name] [trigger_config_json] [inputs_json] — 事件触发器。revision id 要求（以及 latest 快捷方式）与 create-schedule.sh 相同。连接（id 或 slug）必须先处于 ready 状态；使用 triggers.sh deliveries 验证实际触发情况。
• triggers.sh schedules|subscriptions|deliveries|rm-schedule <id>|rm-subscription <id>。
• check-tools.sh <trace_id> [terminal_tool] — 可选的备用方案。test-agent.sh 已会列出运行中调用的工具（其 TOOLS: 行）。仅在需要确认受审批关卡约束的 WRITE 是否确实返回 ok:true 时使用此脚本——传入终端工具，以便根据 trace spans 得出 PASS/INCOMPLETE 判定。
• archive-agent.sh <application_id> — 软删除应用；用于清理或释放 slug。

还有两个辅助脚本位于 scripts/extras/ 中，不属于常规流程：list-connections.sh（discover 已会输出 CONNECTIONS 区块；参见 references/tools-and-connections.md）以及 annotate-trace.sh（实验者演示；参见 references/annotate-trace.md）。

深入主题（按需阅读）

简单 Agent 请遵循上述流程。仅在任务需要时阅读以下内容之一。

要执行的操作	阅读
逐项了解完整的 Agent 配置字段	references/config-schema.md
发现工具、接入连接、添加事件触发器	references/tools-and-connections.md
为多工具或定时 Agent 编写指令	references/writing-instructions.md
设置定时任务或订阅传递给运行的输入	references/trigger-inputs.md
针对 trace 记录反思	references/annotate-trace.md

硬性规则（避免常见故障）

• 创建触发器需要修订 ID，而不只是变体 ID。 create-schedule.sh 和 create-subscription.sh 都接受 <variant_id> <revision_id> ...——请传入两者（由 create-agent.sh / build.sh 打印），或者如果手头只有变体 ID，就用 latest 代替修订 ID。 省略修订 ID 会创建一个未绑定版本的触发器，Agenta UI 会将其视为错误（必填项“运行哪个版本？”未设置）。
• 尽量减少调用次数。 不使用工具的 Agent 只需两个操作：写入配置，然后运行 build.sh。 不要重新列出，不要重新核实此处已提供的信息，也不要重新读取架构。
• 声明完成前先测试。 如果没有运行 build.sh / test-agent.sh，就不能声称已完成。检查 OUTPUT 是否正确，以及 RESOLVED 是否显示预期配置。
• 将角色描述写成明确的祈使句。 Agent 底层使用 Claude Code；遇到模糊输入时，它会退回到通用编码助手角色，而不是执行具体任务。请将 instructions.agents_md 写成明确的祈使句——说明 Agent 是谁、要做什么，并以命令形式表达，而不是写成模糊的话题。（同样，一次性测试也要用动词来表述： "Summarize the following text:\n\n<text>"，而不是只写 <text>，以免测试被理解为聊天开场白。）
• Cron 使用 UTC，包含五个字段，最小间隔为一分钟。 请自行换算用户的本地时间。
• needs_auth 意味着停止。 如果所需连接的状态不是 ready，就停止并请用户连接。这就是该步骤的全部工作。
• 发现是搜索，不是预言。 discover-tools.sh / discover-triggers.sh 会在实时目录中返回高召回率的最佳猜测。匹配到的连接状态可信；匹配到的集成和操作则不一定正确。搜索会匹配词语：“save notes to Notion”可能会将 Slack 的 SEARCH_MESSAGES 匹配为主要工具，并仍然打印 READY: true——而你需要的 Notion 操作却被埋在 alternatives 中，且其连接状态为 needs_auth。因此，请确认匹配工具的 integration 正是你指定的集成，并将各集成的 CONNECTIONS: 区块（而非标题中的 READY 行）视为准确信息。如果匹配不符，请改写搜索片段，或从备选项中选择——搜索 "new telegram message" 也可能以同样的方式返回 Slack 事件。具体来说，对于 discover-triggers.sh，集成正确还不够——关键词匹配可能会落到该集成中的错误事件上（例如，“new github issue opened”可能仅因共享了“created”一词而匹配到 GITHUB_ARTIFACT_CREATED_TRIGGER 事件，同时连接仍显示为 ready）。在将任何内容接入 create-subscription.sh 之前，务必阅读脚本为匹配事件打印的 fires_on 行和 ALTERNATIVES 区块；event_key 看起来合理、集成正确且连接为 ready，并不能证明它会在你指定的事件发生时触发。如果 MATCHED 或 ALTERNATIVES 中没有任何内容与所请求的事件相符，请停止并告知用户该集成目前不支持此触发器——不要接入仅关键词最接近的匹配项。
• 通过提交更改来更新现有 Agent，而不是重新创建。 update-agent.sh <variant_id> <config.json> 会向同一应用提交新修订；slug、ID 以及任何计划或订阅都会继续有效。归档后重新创建会丢失这些内容。更新后请使用 test-agent.sh 重新测试。
• 构建失败仍会创建应用。 如果 build.sh 创建了应用，但调用失败，应用（及其 slug）仍已存在。请修复配置，并使用现有 application_id 通过 test-agent.sh 重新测试——不要使用相同 slug 再次运行 build.sh（会发生冲突）。如需全新重试，请先运行 archive-agent.sh <application_id>。
• 调用会内联携带配置（这是实验套件的产物，并非缺陷）。 build.sh 和 test-agent.sh 每次调用底层 agent-service 端点时都会内联完整配置，该端点不会加载已提交的引用。此行为与端点 / 身份验证 / 请求体格式约定本身无关；该约定已确定——请参阅 agenta 仓库中的 docs/designs/invoke-negotiations/specs.md。产品 API 的调用路径会在服务端加载已提交的引用，因此仅使用引用的调用是实际产品功能；本工具包仍未使用该路径，也无需重写脚本来通过裸引用调用。
• 简短汇报。 写几个要点。先说明结果和产物 ID。

验证（不要只看 200）

test-agent.sh 会发送非流式调用（Accept: application/json）。响应中的 data.outputs 包含本次运行完整的实际轮次，而不只是最终字符串：messages（按顺序包含 助手文本，以及每次工具调用和结果对应的 role: "tool" 条目）、stop_reason，以及仅在运行 暂停于审批关卡时才会出现的 pending_interaction。脚本会直接读取这些内容，因此下面的 OUTPUT / TOOLS / APPROVAL 都直接来自调用响应，无需追踪记录。（端点、身份验证、请求体格式和 此响应约定均已确定，详见 agenta 仓库中的 docs/designs/invoke-negotiations/specs.md。脚本 不会发送额外的标头，因此会使用默认设置：完整对话记录、已解析的工作流嵌入内容。）

test-agent.sh 还会打印运行追踪记录中的 RESOLVED。它必须与你的预期一致。如果显示的是不同的 harness/model，则运行已悄然回退——请修正配置并重新测试。追踪记录会延迟一两秒写入；脚本已 内置重试。

多工具 Agent——请查看 TOOLS: 行，不要只看 OUTPUT。 调用多个工具的运行可能会在工具调用 轮次结束，因此 OUTPUT（最后一条助手消息）确实可能为空——这不是失败，也不是解析遗漏，而是 表示运行的最后一轮是工具调用，而非回复。test-agent.sh 的 TOOLS: 行会按顺序列出运行调用 过的每个工具，以及每个结果的 ok/ERROR（例如 github__LIST_COMMITS -> ok -> slack__SEND_MESSAGE -> ok (2 calls, 2 results)）。这是可靠判断“是否到达最终工具，以及该工具是否返回 ok”的信号。如果最终工具在 列表中且结果为 ok，则运行已到达该工具并完成；如果缺少该工具，则运行提前停止了（完成前面的 读取后就偏离了方向，始终未到达最终操作）。如果运行提前停止，请使用更直白、带编号的指令重新 测试——配置通常没有问题，只是运行偏离了方向。请参阅 references/writing-instructions.md。

当 stop_reason == "paused" 时，test-agent.sh 会打印一行 APPROVAL:——某个写入操作（如 SEND_MESSAGE）触发了人工审批关卡。运行在此处停止：该工具调用会出现在 TOOLS 中，但尚无对应 结果，因为运行在执行该操作前就暂停了。该写入操作可能根本不会在本次调用中完成（审批可能一直 未获处理）。

check-tools.sh 是针对本次调用尚无法显示的信息的备用方案：它会读取追踪跨度——工具跨度一经 调用便会出现，但只有在工具实际返回后才会包含结果。因此，bash scripts/check-tools.sh <trace_id> SEND_MESSAGE 只有在该工具已运行且返回结果时才会打印 VERDICT: PASS；如果工具 已调度但其跨度中没有结果（这是审批停滞的典型特征），则会打印 UNCONFIRMED；如果工具从未运行， 则会打印 INCOMPLETE。已执行列表中出现工具名称，并不能证明该工具已完成——受审批关卡限制的 写入操作可能出现在列表中，却没有结果。对于外部写入操作，即使已返回结果，也只有读取回其副作用 （例如获取频道历史记录）才能真正确认。读取回查是唯一确定的检查方式。