워크플로우의 구조를 정했다면 에이전트 루프에 어떤 외부 기능을 연결할지, 실행 중 실제로 어떤 일이 일어났는지 어떻게 확인할지 결정하세요.
SDK에서 사용할 기능 선택
| 목적 | 먼저 사용할 기능 | 이유 |
|---|---|---|
| 에이전트가 원격으로 호스팅되는 공개 MCP 도구를 사용하도록 설정 | SDK의 호스팅형 MCP 도구 | 모델이 플랫폼의 호스팅형 도구를 통해 원격 MCP 서버를 호출할 수 있습니다. |
| 런타임에서 로컬 또는 비공개 MCP 서버에 연결 | stdio 또는 스트리밍 가능한 HTTP로 연결하는 SDK 관리형 MCP 서버 | 런타임에서 연결, 승인, 네트워크 경계를 관리합니다. |
| 프롬프트, 도구, 핸드오프 또는 승인 디버깅 | 기본 제공 트레이싱 | 정식 평가 절차를 마련하기 전에도 트레이스에서 실행 전 과정을 확인할 수 있습니다. |
각 도구가 제공하는 기능과 동작 방식은 도구 사용을 참고하세요. 이 페이지에서는 Agents SDK에서 MCP를 연결하고 실행 과정을 관찰하는 방법을 다룹니다.
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 개념과 신뢰 모델, 제품별 지원 범위는 공식 참고 문서인 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);
});트레이스는 다음 두 가지 용도로 활용하세요.
- 워크플로우의 개별 실행을 디버깅하고 실제로 어떤 일이 일어났는지 파악하세요.
- 에이전트의 동작을 체계적으로 채점할 준비가 되면 동작의 특성이 잘 드러나는 사례를 골라 에이전트 워크플로우 평가에 활용하세요.
다음 단계
외부 기능을 연결했다면 기능 설계, 검토가 필요한 지점 설정, 워크플로우 평가 중 다음에 다룰 주제에 맞는 가이드를 선택하세요.