如何在你的產品裡打造 Agentic 功能：從聊天框到可控的任務迴圈

使用者在產品裡輸入：「幫我看部署說明，整理今天要做的事，確認後建立待辦。」如果後端只把文字送給模型，再把回答放回聊天框，最多得到一份看起來像清單的文字。它還沒有讀取產品資料，也沒有建立任何待辦。

這個系列綜合了過去一兩年，我們打造 cosGlint、Termdock 等產品，以及企業輔導過程中的經驗。主題是如何在自己的產品裡打造 Agentic 功能：讓模型參與任務決策，同時把資料權限、工具操作、記憶與執行狀態留在可檢查的產品流程裡。

文章把這些經驗整理成可以套用到不同產品的設計方法，再搭配現行 SDK 說明實作選擇。範例用來說明設計取捨，不是任何單一產品的架構介紹，也不表示這些產品已採用文中的 SDK。

先決定你的產品需要哪一種自主性

在這個系列裡，Agentic 指的是：模型能依任務和已取得的結果提出下一步，執行環境檢查後呼叫工具，再把結果交回模型，直到完成、需要澄清、等待核准，或到達停止條件。OpenAI Agents SDK 的執行器處理的就是這種模型、工具與最終回答之間的迴圈。OpenAI：Running agents

但不是每個功能都需要這個迴圈。摘要一份已知文件，可以先用一次模型呼叫；固定的「查訂單、查配送、組合結果」流程，也可以由程式依序完成。當下一步真的取決於使用者需求或工具結果，例如缺資料要改查另一份文件，才有理由讓模型參與決策。

可以先寫一份任務契約：允許完成什麼、可以讀哪些資料、哪些動作會改變產品狀態，以及什麼結果才算完成。「協助管理專案」太大；「讀取自己專案的部署文件，提出待辦，核准後建立」就能檢查。

一次回答，和一個可接續的任務有什麼差別

先選「查詢資料」，比較單次模型呼叫與工具迴圈。單次呼叫只能提出查詢需求，沒有工具結果就不該宣稱查到了資料。迴圈模式則先提出工具呼叫，取得資料後再整理回答。

接著改成「更新紀錄」。保持尚未核准，觀察產品停在等待核准，而不是顯示成功或失敗。核准後才會出現一次寫入；拒絕則不執行。最後把模型呼叫上限縮成一次，看這個範例如何在工具執行前停止，避免先寫入才發現沒有預算整理結果。

圖中的資料只用來說明流程，不會呼叫模型或執行工具。這個範例用模型呼叫次數表示預算，不等於所有 SDK 的 maxTurns 都採相同計數方式；實作時要依所選 SDK 核對停止語意。

把 Agent 接進現有產品

產品後端、SDK 與工具各自負責什麼

把現有產品改成 Agentic 功能時，可以保留原本的 API 與資料服務，把 SDK 放在任務執行的位置。不要讓模型直接拿到一份不受限制的資料庫帳號。

部分	責任
產品入口	驗證登入身分、租戶、請求格式與功能範圍，建立可查詢的任務
任務執行器	呼叫 SDK，管理截止時間、模型與工具上限、取消及接續
SDK 執行環境	處理模型與工具往返、執行事件，以及各 SDK 支援的狀態與核准機制
工具服務	驗證參數、檢查資源權限、執行原本的產品 API，回傳可檢查的結果
資料與記憶	保存產品狀態、對話對應、長期偏好、檢索資料與必要的操作紀錄
使用者介面	區分進行中、等待核准、完成、取消與失敗，呈現實際操作結果

OpenAI Agents SDK 的官方定位是由應用程式管理部署、工具、儲存與核准決策，SDK 執行 Agent 迴圈。Claude Agent SDK 則把 Claude Code 的執行環境、工具與狀態管理帶進自己管理的程序。兩者都不會自動接上你的產品帳號與租戶權限。OpenAI Agents SDK、Claude Agent SDK

MCP 可以讓工具有共同的連接方式，但不會替代工具背後的授權。產品認證資料由後端提供，模型提出的參數只代表它想做的事，不代表它已取得操作權限。OpenAI：MCP 整合、Claude：Custom tools

從一個只讀工具開始，先驗證完整往返

下面用 OpenAI Agents SDK 示範一次「提出查詢、取得工具資料、整理答案」。工具回傳固定的示範文件；真正接進產品時，將執行函式換成有權限檢查的資料服務。SDK 的 Agent、tool() 與 run() 介面可見官方 Agent 定義說明。

import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const lookupGuide = tool({
  name: "lookup_deployment_guide",
  description: "查詢部署文件，回傳來源與步驟。",
  parameters: z.object({ topic: z.string() }),
  async execute({ topic }) {
    return {
      topic,
      source: "示範部署文件",
      steps: ["確認環境變數", "執行本機檢查", "檢查部署紀錄"],
    };
  },
});

const agent = new Agent({
  name: "product-helper",
  instructions: "使用臺灣繁體中文。查詢部署說明時先用工具，保留來源，不宣稱已完成部署。",
  tools: [lookupGuide],
});

const result = await run(agent, "請查部署前要確認哪些事情。");
console.log(result.finalOutput);

這段需要在後端使用 @openai/agents、zod 與有效憑證，實際模型呼叫會產生費用。先確認工具確實被呼叫、回答保留來源，以及它沒有宣稱自己做了部署。上線前再補執行上限、資料隔離與失敗處理；不要把範例的固定資料當成產品的真實查詢結果。

若產品需要程式碼修改或 CI 工作，Codex SDK 的 @openai/codex-sdk 能控制本機 Codex thread，包含開始、接續與恢復程式開發任務。它和泛用的 @openai/agents 是不同套件、不同執行環境，不應把兩者合稱為同一個「Codex Agent SDK」。Codex SDK

加入寫入能力之前，先把暫停與接續做好

「建立待辦」和「列出待辦建議」是兩個不同能力。前者會改變產品資料，應讓使用者看到目標、欄位與操作內容，核准後才呼叫原本的寫入 API。

OpenAI Agents SDK 的工具可以設定 needsApproval，讓結果帶回 interruptions 與可接續的 state。產品收到核准後接續原任務，不是把使用者原句重新送一次。Claude Agent SDK 的權限回呼與 hooks 也能介入工具決策，但已自動核准的工具不一定會進入 canUseTool；逐次政策檢查應放在適當的工具邊界。OpenAI：人工核准、Claude：Permissions

如果任務要跨 HTTP 請求等待，就把產品工作 ID、SDK 狀態、已完成動作與核准紀錄保存起來。工作執行器重新啟動時，先查已完成哪些寫入，再決定接續，不要把「恢復任務」寫成整段重跑。佇列、冪等鍵與可靠交接仍是產品後端的責任。

停止條件至少包括：已完成、無法取得必要資料、等待使用者、核准被拒絕、時間或成本預算不足，以及工具結果不符合契約。把這些狀態回傳給介面，比只提供「模型正在思考」更有用。

這個系列怎麼讀

先把一個只讀任務做通，再沿著同一條請求路徑補上控制：

1. 安全與授權邊界：模型有工具後，如何限制資料與動作。
2. 對話狀態與長期記憶：SDK 接續與產品記憶如何分工。
3. 模型層與 SDK 選擇：重試、備援與狀態相容。
4. 工具契約與執行計畫：把既有產品 API 交給 Agent。
5. 資料整理與語意分群：讓 Agent 使用有證據的群組，而不是猜分類。
6. 效能與執行預算：區分工具等待、首段文字與任務完成時間。
7. 產品 API 與任務狀態：讓介面知道任務是否真的完成。
8. 可觀測性與故障定位：查回模型與工具實際做了什麼。
9. 語氣與臺灣用語：保留產品口吻，也保留事實與限制。

每篇都有可以調整的互動圖解。讀到下一個主題時，帶著同一個問題：模型提案之後，產品如何判斷、執行、記錄並交付結果？

延伸閱讀

SDK 文件核對日期：2026-10-07。SDK 範例依官方介面整理，未在本篇連接真實產品或執行模型測試。

• OpenAI Agents SDK：部署與執行責任
• OpenAI Agents SDK：模型與工具迴圈
• Claude Agent SDK：執行環境與一般 API SDK 的差別
• Codex SDK：程式開發任務