sgr-agent-core：以 Schema 約束推理路徑的 Agent 框架
Schema-Guided Reasoning (SGR) has agentic system design created by neuraldeep community
秒懂
- 它是什麼？
- 這個專案把 agent 的推理步驟綁進 JSON Schema，讓模型只能沿著預先定義的欄位前進。它適合需要可預期輸出結構的研究型 agent，但對單純的工具呼叫場景反而多一層負擔。
- 適合誰用？
- 如果你的研究流程需要固定欄位的推理軌跡，而且願意接受多一輪 LLM 呼叫的成本，sgr-agent-core 的兩階段架構值得放進評估清單；若你只是要一個能呼叫函式的 chatbot，ToolCallingAgent 或直接用官方 SDK 會更省事。導入前先確認三件事：config.yaml 中 acp.agent 指向哪個 agent 定義、tools.web_search_tool 與 extract_page_content_tool 的 Tavily key 是否為必填、以及你的推論端點是否支援結構化輸出。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 20 天前。
- 用什麼語言寫的？
- 主要是 Python（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
它要解決的是推理軌跡不可控的問題
一般 function calling 的流程是：模型決定呼叫哪個工具，工具回傳結果，模型再決定下一步。問題在於中間的推理過程完全自由，模型可以跳過步驟、可以一次吐出多個結論、也可以把兩件事混在同一段文字裡。當你要把 agent 的輸出接進下游系統，這種自由度就變成解析負擔。
sgr-agent-core 的做法是先把推理本身變成一種結構化輸出。專案名稱裡的 Schema-Guided Reasoning 指的就是這件事：用 JSON Schema 描述推理應該有哪些欄位，模型填欄位，而不是自由書寫。README 把它描述為「combines structured reasoning with flexible tool selection」，結構化的是推理，工具選擇仍保留彈性。
目標使用者寫得很清楚：需要 research agent 的人。repo 的 topics 包含 deep-research 與 research，examples 目錄下的範例也叫 sgr_deep_research。如果你的場景是「給一個問題，產出一份有引用來源的報告」，這個框架的設計方向是對的。如果你要的是客服對話或表單填寫，這裡的機制會顯得繞路。
兩階段架構與三種 agent 型別的分工
README 提到核心是「a extendable BaseAgent interface implementing a two-phase architecture」。兩階段指的是先產生結構化推理，再根據推理結果決定行動，推理與行動被拆成兩次獨立的模型互動。這樣的拆分讓每次呼叫的輸出空間變小，Schema 的約束力才成立。
框架提供三種現成實作。SGRAgent 走完整的 Schema 引導路徑；ToolCallingAgent 是傳統的工具呼叫模式，不強制推理結構；SGRToolCallingAgent 則是兩者的混合，這也是 repo topics 裡出現 hybrid 相關字樣的原因。選哪一種取決於你要的是可解析性還是呼叫次數。
需要說清楚的是，README 只列出這三個名稱與一句定位，沒有給出各自的 Schema 內容或階段數量差異。實際每個 agent 在幾次 LLM 呼叫內完成一輪，必須看 examples 目錄下的 config.yaml 與原始碼才能確定。文件在這部分是薄的。
工具層由 search、reasoning、clarification 三類構成。clarification 的存在意味著 agent 可以反問使用者，這也是 CLI 端要處理 dialog 請求的原因。
從 Docker 到 sgrsh：三種啟動路徑
最快的路徑是 Docker。README 給的指令會掛載三個目錄：examples/sgr_deep_research 以唯讀方式掛進容器、logs 與 reports 可寫。啟動參數是 --config-file、--host、--port，映像檔來自 ghcr.io/vamplabai/sgr-agent-core:latest。服務起來後 API 在 8010 埠，Swagger UI 在 /docs。
作為函式庫安裝則是一行 pip install sgr-agent-core。要跑 API server 可以用 sgr 這個指令，短選項是 -c：
sgr --config-file examples/sgr_deep_research/config.yaml
等價的寫法是 python -m sgr_agent_core.server --config-file examples/sgr_deep_research/config.yaml。
互動式用途走 sgrsh。單次查詢直接帶字串，例如 sgrsh "Найди цену биткоина"；要指定 agent 用 --agent 或 -a，要換設定檔用 -c。不帶查詢參數就進入互動聊天模式。README 說明 sgrsh 會自動在當前目錄尋找 config.yaml。
設定檔的關鍵欄位有三個：llm.api_key、tools.web_search_tool.api_key、tools.extract_page_content_tool.tavily_api_key。README 把後兩者標為 optional，但搜尋與網頁抓取是研究 agent 的主要能力來源，不填等於放棄大部分功能。
ACP 讓編輯器直接掛上同一份 YAML
除了 HTTP 與 CLI，專案還提供 sgracp 這個 binary，走 Agent Client Protocol，透過 stdio 傳輸 newline-delimited JSON-RPC。啟動方式是 sgracp --config examples/sgr_deep_research/config.yaml。
這裡有個設計上的細節值得注意：HTTP server 與 ACP binary 共用同一份 YAML 設定。這表示你在本機用編輯器測出來的 agent 行為，跟部署成服務後的行為來自同一組參數，不需要維護兩套配置。
要選定暴露哪個 agent，config.yaml 裡加一個 acp 區塊：
acp: agent: sgr_agent
README 明確說若省略這個區塊，會採用 agents 清單中的第一個定義。這是一個容易被忽略的預設值。當你的 config.yaml 裡排了多個 agent，第一個未必是你想給編輯器用的那個，行為會跟預期不同。
協定實作依據官方 ACP 規範與 Python SDK，對應的套件是 agent-client-protocol。這部分依賴外部規範的演進，規範若有變動，升級成本會落在 sgracp 這一層。
SimpleQA 數字要看清楚它測的是什麼
README 放了一張 SimpleQA 比較圖，並列出在 gpt-4.1-mini 上的數字：準確率 86.08%，正確 3,724 題，錯誤 554 題，未嘗試 48 題。
這些數字是專案自己跑出來的，我沒有重現過。有兩點需要讀者自己判斷。第一，這是單一模型、單一資料集的結果，換模型或換題型未必成立。第二，SimpleQA 測的是短答案的正確性，而這個框架主打的是多步驟研究流程，兩者的貼合程度有限。用短答題的準確率去推論長篇研究報告的品質，中間有一段推論缺口。
比較圖裡的其他系統名稱與各自的設定，在提供的材料中沒有列出，無法在這裡展開對照。要看細節得連到 benchmark/simpleqa_benchmark_results.md。
把基準數字當成選型依據是常見做法，但對這個專案，更值得先確認的是：你的推論端點支不支援結構化輸出。若用的是本地模型而它對 JSON Schema 的遵循度不穩，再漂亮的基準數字也幫不上忙。
Schema 約束換來的是呼叫次數與脆弱性
這個框架最實質的限制來自它的核心機制。把推理步驟寫進 Schema，等於要求模型在每個欄位上都產出合規內容。模型只要有一次沒填對，整輪推理就得重來或走例外處理。
兩階段架構本身也意味著更多次 LLM 呼叫。相較於單次工具呼叫的 agent，同樣一個問題會多出至少一輪推理產生的成本與延遲。對需要即時回應的場景，這個代價不小。
另一個邊界是適用範圍。如果你的任務沒有固定的推理骨架，硬套 Schema 只會讓模型把內容塞進不合適的欄位。反過來說，當任務步驟本來就明確，例如先搜尋、再篩選、再彙整，Schema 才真的有約束價值。
還有一個操作層面的摩擦：README 的 Docker 步驟要求先建立 logs 與 reports 目錄並設成 777 權限。這是因為容器內的使用者與宿主機不同。在共用機器或多租戶環境，這個權限設定值得重新考慮，改用對應的 uid 掛載會更乾淨。
與直接使用 OpenAI SDK 的差別在哪
最直接的替代方案是 OpenAI 官方的 Python SDK 加上 function calling，或採用 LangGraph 這類以狀態圖描述流程的框架。差異在約束施加的位置。
官方 SDK 把結構化輸出的責任交給開發者：你自己寫 schema、自己驗證回傳、自己在程式碼裡決定下一步。彈性最大，但推理軌跡不會被記錄成結構化物件，除錯時只能看文字。
LangGraph 把流程寫成節點與邊，控制流由開發者定義。它的約束在圖的拓撲上，模型在單一節點內仍然自由生成。sgr-agent-core 的約束則落在模型的輸出格式上，由 Schema 決定這一步能講什麼。
兩種思路處理的是不同問題。LangGraph 回答「流程怎麼走」，SGR 回答「這一步的輸出長什麼樣」。若你的痛點是流程分支難以維護，換成 SGR 不會解決；若你的痛點是輸出無法穩定解析，Graph 類框架也幫不上。
對已經在用 OpenAI 相容端點的團隊，這個專案的吸引力在於它同時提供 REST API 與 ACP 兩種介面，而且設定檔共用。這省下的是接線工作，不是架構決策。
授權、維護節奏與升級時要看的東西
授權是 MIT，條款寬鬆，允許修改與再散布，商業使用沒有額外限制。要注意的是 repo 內各相依套件與範例設定所引用的外部服務（例如 Tavily）各有自己的條款，那些不在 MIT 的涵蓋範圍內。這裡不構成法律意見，實際條款請自行核對。
維護節奏可以從版本推斷。0.6.0 在 2026 年 1 月，0.7.0 在 3 月，0.7.1 在 7 月，最後一次推送在 8 月。半年內三個版本，屬於持續演進但不是高頻釋出的狀態。0.x 版號意味著 API 仍可能變動，把它當成穩定介面來依賴是有風險的。
升級成本主要落在兩處：config.yaml 的欄位結構，以及 BaseAgent 的子類別介面。前者因為 HTTP 與 ACP 共用同一份檔案，改動會同時影響兩個介面；後者是你自訂 agent 的地方，框架調整基底類別時需要跟著改。
要驗證的第一件事很具體：把 examples/sgr_deep_research/config.yaml.example 複製成 config.yaml，填入 llm.api_key，先不填 Tavily 的兩個 key，看 agent 在缺少搜尋工具時的行為是否符合預期。這一步能同時測出你的推論端點對結構化輸出的支援程度，以及框架在工具缺失時的降級方式。
編輯結論
如果你的研究流程需要固定欄位的推理軌跡，而且願意接受多一輪 LLM 呼叫的成本，sgr-agent-core 的兩階段架構值得放進評估清單；若你只是要一個能呼叫函式的 chatbot，ToolCallingAgent 或直接用官方 SDK 會更省事。導入前先確認三件事：config.yaml 中 acp.agent 指向哪個 agent 定義、tools.web_search_tool 與 extract_page_content_tool 的 Tavily key 是否為必填、以及你的推論端點是否支援結構化輸出。這三項決定了它能不能在你的環境跑起來，而不是取決於 README 上的任何宣稱。
社群筆記