確定工作流程的架構後,接下來要決定將哪些外部介面納入智慧體的執行迴圈,以及如何檢視執行時實際發生的事。
決定哪些功能交由 SDK 處理
| 需求 | 建議做法 | 原因 |
|---|---|---|
| 讓智慧體存取託管於遠端的公開 MCP 工具 | 使用 SDK 中的託管式 MCP 工具 | 模型可透過託管介面呼叫遠端 MCP 伺服器 |
| 從執行環境連線至本機或私有 MCP 伺服器 | 使用由 SDK 管理、透過 stdio 或可串流 HTTP 連線的 MCP 伺服器 | 連線、核准與網路邊界皆由你的執行環境掌控 |
| 針對提示詞、工具、任務交接或核准流程進行除錯 | 使用內建追蹤功能 | 在建立正式評估流程前,即可透過追蹤查看完整的執行紀錄 |
各項工具功能的運作方式請參閱使用工具。本頁著重說明如何在 SDK 中接入 MCP,以及如何觀察工作流程的執行情形。
MCP
如果要讓模型透過平台介面呼叫遠端伺服器,請使用託管式 MCP 工具。
接入託管式 MCP 伺服器
TypeScript
import { Agent, hostedMcpTool } from "@openai/agents";
const agent = new Agent({
name: "MCP assistant",
instructions: "Use the MCP tools to answer questions.",
tools: [
hostedMcpTool({
serverLabel: "gitmcp",
serverUrl: "https://gitmcp.io/openai/codex",
}),
],
});如果應用程式需要直接連線至 MCP 伺服器,請使用本機傳輸機制。
連線至本機 MCP 伺服器
TypeScript
import { Agent, MCPServerStdio, run } from "@openai/agents";
const server = new MCPServerStdio({
name: "Filesystem MCP Server",
fullCommand:
"npx -y @modelcontextprotocol/server-filesystem fixtures/sample_files",
});
await server.connect();
try {
const agent = new Agent({
name: "Filesystem assistant",
instructions: "Read files with the MCP tools before answering.",
mcpServers: [server],
});
const result = await run(agent, "Read the files and list them.");
console.log(result.finalOutput);
} finally {
await server.close();
}實務上,可依下列條件選擇:
- 若公開的遠端伺服器符合平台的信任模型,請使用託管式 MCP。
- 若連線、篩選或核准應由你的執行環境掌控,請使用本機或私有 MCP。
如需瞭解 MCP 在整個平台上的運作概念、信任模型,以及各產品的支援情形,請以 MCP 伺服器為準。
追蹤
Agents SDK 內建追蹤功能,在伺服器端以一般方式使用 SDK 時,預設會啟用追蹤。每次執行都能產生結構化紀錄,涵蓋模型呼叫、工具呼叫、任務交接、防護機制及自訂追蹤區段。你可以在追蹤儀表板中檢視這些紀錄。
預設的追蹤紀錄通常包含:
- 單次執行或整個工作流程的概況
- 每一次模型呼叫
- 工具呼叫及其輸出
- 任務交接與防護機制
- 你為工作流程設定的任何自訂追蹤區段
若要減少追蹤紀錄,可調整 SDK 層級或單次執行的追蹤設定,讓工作流程仍保有可觀測性。
在同一筆追蹤紀錄中涵蓋多次執行
TypeScript
import { Agent, run, withTrace } from "@openai/agents";
const agent = new Agent({
name: "Joke generator",
instructions: "Tell funny jokes.",
});
await withTrace("Joke workflow", async () => {
const first = await run(agent, "Tell me a joke");
const second = await run(agent, `Rate this joke: ${first.finalOutput}`);
console.log(first.finalOutput);
console.log(second.finalOutput);
});追蹤紀錄有兩種用途:
- 針對工作流程的單次執行進行除錯,瞭解執行過程中發生的事。
- 準備好系統性地為智慧體的行為評分時,可從追蹤紀錄中挑選更能反映實際行為的範例,用於智慧體工作流程評估。
後續步驟
接入外部介面後,可依需求繼續閱讀下列指南,瞭解如何設計功能、設定審查範圍或評估工作流程。