命令参考：智能体、运行和规范

概述

这些命令用于管理智能体及其运行。它们需要浏览器登录、API 地址，以及支持智能体功能的服务器；否则会停止并提示“This server does not support the requested CLI feature: agents”（退出码 6）。在工作区中列出或创建内容的命令接受 --org <workspace-id>，或使用 profile 中的 orgId。

控制台

figena console bootstrap

把工作区绑定到智能体控制台。需要 --org 或 profile 中的 orgId。

figena console status

显示服务器版本，以及它向 CLI 报告的功能。

智能体

figena agents list

列出工作区中的智能体。选项：--org <workspace-id>。

figena agents get <agentId>

查看一个智能体。

figena agents create

创建智能体。选项：--name <name>（必填）、--description <text> 和 --org <workspace-id>。

figena agents version create <agentId>

根据工作流规范创建版本。用 --spec <file> 传入文件，或用 --spec-json '<json>' 直接传入。加上 --allow-unknown 可以接受服务器无法识别的字段。

figena agents version get <versionId>

查看一个智能体版本。

figena agents publish <versionId>

发布一个版本，使其可以运行。

figena agents deploy <agentId>

在一次请求中根据规范创建版本，并按选项决定是否发布、运行冒烟测试和设为默认版本。用 <agentId> 或 --agent <agentId> 指定智能体，并用 --spec 或 --spec-json 传入规范（必填）。

• --publish：发布新版本。
• --promote-default：把新版本设为智能体的默认版本。
• --run-smoke：运行冒烟测试。提供 --smoke-input <file> 或 --smoke-input-json '<json>' 时会自动开启冒烟测试。
• --wait：等待部署完成，最长 --timeout（默认 10m）。
• --allow-unknown：接受服务器无法识别的规范字段。
• --rollback-on-fail：CLI 接受这个选项并随请求发送，但当前服务器不会据此执行任何操作。部署失败时不会自动回滚，请先检查结果再把版本设为默认。

figena agents deploy <agentId> \  --spec ./workflow.json \  --publish --promote-default \  --smoke-input ./smoke-input.json \  --wait --timeout 5m

请求成功后，CLI 输出“Agent deploy completed”和服务器返回的结果。

运行

figena run <versionId>

运行一个已发布的版本。用 --input <file> 或 --input-json '<json>' 传入输入；--trigger-type 默认为 manual。默认情况下，CLI 会一直等到运行状态变为 succeeded、failed、needs_approval 或 canceled，最长 --timeout（默认 10m）。加上 --detach 可以在运行开始后立即返回。

figena runs list

列出工作区中的运行。选项：--org、--agent <agentId>、--status <status> 和 --page-size <n>（或 --limit <n>）。

figena runs get <runId>

查看一次运行。

figena runs steps <runId>

列出一次运行的各个步骤。

figena runs trace <runId>

查看运行的追踪摘要。如果要追踪一次已发布调用，请传入 --session-id <id>，并可选传入 --run-id <id>。

figena runs wait <runId>

等待运行进入最终状态：succeeded、failed、needs_approval 或 canceled。CLI 会在 1 秒、2 秒后检查，之后每 4 秒检查一次。如果在 --timeout（默认 10m）内仍未结束，命令会以退出码 7 停止。

工作流规范

figena spec validate <file>

把 JSON 规范文件发送到服务器校验，并输出“Workflow spec is valid”或“Workflow spec is invalid”及详细信息。加上 --allow-unknown 可以接受服务器无法识别的字段。规范无效时会返回 ok: false，但退出码为 0，脚本应检查 ok。

figena spec inspect <file>

在接受未知字段的前提下校验规范，并同时返回校验结果和规范中的 metadata 部分。

典型的发布流程

figena spec validate ./workflow.jsonfigena agents version create <agentId> --spec ./workflow.jsonfigena agents publish <versionId>figena run <versionId> --input-json '{"question":"What changed this week?"}'