指令參考：智慧代理、執行和規格

概述

這些指令用於管理智慧代理及其執行。它們需要瀏覽器登入、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?"}'