ワークフローの構成が決まったら、どの外部機能をエージェントの実行ループに組み込むか、実行時に何が起きたかをどう確認するかを決めます。
用途に応じた SDK 機能の選択
| 用途 | 最初に使う機能 | 理由 |
|---|---|---|
| リモートでホストされている公開 MCP ツールをエージェントから利用する | SDK のホスト型 MCP ツール | モデルがプラットフォーム経由でリモートの MCP サーバーを呼び出せます。 |
| アプリケーションの実行環境からローカルまたは非公開の MCP サーバーに接続する | stdio または Streamable HTTP で接続する SDK 管理の MCP サーバー | 接続、承認、ネットワーク境界を実行環境側で管理します。 |
| プロンプト、ツール、ハンドオフ、承認をデバッグする | SDK 組み込みのトレーシング | 評価手順を整備する前でも、トレースで実行の一部始終を確認できます。 |
各ツールで何ができ、どう動作するかについては、ツールの使用を参照してください。このページでは、SDK での MCP の接続方法と、実行内容を継続的に確認する方法を説明します。
MCP
モデル側のインターフェースを介してリモートサーバーを呼び出す場合は、ホスト型 MCP ツールを使用します。
ホスト型 MCP サーバーの接続
JavaScript
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 サーバーへの接続
JavaScript
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 サーバーを参照してください。
トレーシング
Agents SDK にはトレーシングが組み込まれており、サーバー側で SDK を通常どおり使用する場合はデフォルトで有効です。実行ごとに、モデル呼び出し、ツール呼び出し、ハンドオフ、ガードレール、カスタムスパンの構造化された記録を出力できます。記録はトレースダッシュボードで確認できます。
デフォルトのトレースには、通常、次の内容が含まれます。
- 実行またはワークフローの全体像
- 個々のモデル呼び出し
- ツール呼び出しとその出力
- ハンドオフとガードレール
- ワークフローを囲むように設定したカスタムスパン
トレースの記録量を減らしたい場合は、ワークフローの実行状況を引き続き把握できるように、SDK 全体または実行単位の設定でトレーシングを調整してください。
複数の実行をまとめた単一のトレース
JavaScript
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);
});トレースは次の 2 つの用途に使えます。
- ワークフローの実行を 1 回分デバッグし、何が起きたかを把握します。
- 挙動を体系的に採点する準備が整ったら、トレースから評価に役立つ事例を選び、エージェントワークフローの評価に使用します。
次のステップ
外部機能を接続したら、機能の設計、レビューが必要な箇所の設定、評価のうち、目的に合うガイドに進んでください。