如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題

整合與可觀測性

開始調校前,先接入 MCP 提供的功能,並檢視執行紀錄。

確定工作流程的架構後,接下來要決定將哪些外部介面納入智慧體的執行迴圈,以及如何檢視執行時實際發生的事。

決定哪些功能交由 SDK 處理

需求 建議做法 原因
讓智慧體存取託管於遠端的公開 MCP 工具 使用 SDK 中的託管式 MCP 工具 模型可透過託管介面呼叫遠端 MCP 伺服器
從執行環境連線至本機或私有 MCP 伺服器 使用由 SDK 管理、透過 stdio 或可串流 HTTP 連線的 MCP 伺服器 連線、核准與網路邊界皆由你的執行環境掌控
針對提示詞、工具、任務交接或核准流程進行除錯 使用內建追蹤功能 在建立正式評估流程前,即可透過追蹤查看完整的執行紀錄

各項工具功能的運作方式請參閱使用工具。本頁著重說明如何在 SDK 中接入 MCP,以及如何觀察工作流程的執行情形。

MCP

如果要讓模型透過平台介面呼叫遠端伺服器,請使用託管式 MCP 工具。

接入託管式 MCP 伺服器
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 伺服器
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 層級或單次執行的追蹤設定,讓工作流程仍保有可觀測性。

在同一筆追蹤紀錄中涵蓋多次執行
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);
});

追蹤紀錄有兩種用途:

  • 針對工作流程的單次執行進行除錯,瞭解執行過程中發生的事。
  • 準備好系統性地為智慧體的行為評分時,可從追蹤紀錄中挑選更能反映實際行為的範例,用於智慧體工作流程評估。

後續步驟

接入外部介面後,可依需求繼續閱讀下列指南,瞭解如何設計功能、設定審查範圍或評估工作流程。