통합과 관측성

통합과 관측성 (Integrations and observability)

워크플로우 형태가 명확해진 뒤에는 어떤 외부 표면이 에이전트 루프 안에 들어와야 하는지, 그리고 런타임에서 실제로 무엇이 일어났는지 어떻게 검사할지가 다음 질문이에요. SDK의 MCP 연결과 트레이싱을 다루는 가이드예요.

출처: 문서

본문

워크플로우 형태가 명확해진 뒤에는 어떤 외부 표면이 에이전트 루프 안에 들어와야 하는지와 런타임에서 실제로 일어난 일을 어떻게 검사할지가 다음 질문이에요.

SDK에 무엇을 넣을지 선택하기

도구 기능 의미론은 여전히 Using tools에 있어요. 이 페이지는 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",
    }),
  ],
});

from agents import Agent, HostedMCPTool

agent = Agent(
    name="MCP assistant",
    instructions="Use the MCP tools to answer questions.",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "gitmcp",
                "server_url": "https://gitmcp.io/openai/codex",
                "require_approval": "never",
            }
        )
    ],
)

여러분의 애플리케이션이 MCP 서버에 직접 연결해야 할 때는 로컬 전송(local transports)을 사용하세요.

로컬 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();
}

import asyncio

from agents import Agent, Runner
from agents.mcp import MCPServerStdio


async def main() -> None:
    async with MCPServerStdio(
        name="Filesystem MCP Server",
        params={
            "command": "npx",
            "args": [
                "-y",
                "@modelcontextprotocol/server-filesystem",
                "./sample_files",
            ],
        },
    ) as server:
        agent = Agent(
            name="Filesystem assistant",
            instructions="Read files with the MCP tools before answering.",
            mcp_servers=[server],
        )
        result = await Runner.run(agent, "Read the files and list them.")
        print(result.final_output)


if __name__ == "__main__":
    asyncio.run(main())

실질적인 구분은 다음과 같아요:

• 플랫폼 신뢰 모델에 맞는 공개 원격 서버에는 호스팅 MCP를 사용하세요.
• 여러분의 런타임이 연결, 필터링, 승인을 소유해야 할 때는 로컬 또는 프라이빗 MCP를 사용하세요.

플랫폼 전반의 개념, 신뢰 모델, 제품 지원 스토리는 MCP servers를 정식 참조로 유지하세요.

트레이싱 (Tracing)

트레이싱은 Agents SDK에 내장되어 있으며 일반적인 서버 측 SDK 경로에서 기본적으로 활성화돼요. 모든 실행은 모델 호출, 도구 호출, 핸드오프, 가드레일, 커스텀 스팬의 구조화된 기록을 만들 수 있으며, Traces dashboard에서 검사할 수 있어요.

기본 트레이스는 보통 다음을 제공해요:

• 전체 실행 또는 워크플로우
• 각 모델 호출
• 도구 호출과 그 출력
• 핸드오프와 가드레일
• 워크플로우 주변에 감싼 모든 커스텀 스팬

트레이싱을 덜 원한다면, 워크플로우에서 모든 관측성을 제거하는 대신 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);
});

import asyncio

from agents import Agent, Runner, trace

agent = Agent(
    name="Joke generator",
    instructions="Tell funny jokes.",
)


async def main() -> None:
    with trace("Joke workflow"):
        first = await Runner.run(agent, "Tell me a joke")
        second = await Runner.run(
            agent,
            f"Rate this joke: {first.final_output}",
        )
        print(first.final_output)
        print(second.final_output)


if __name__ == "__main__":
    asyncio.run(main())

트레이스를 두 가지 작업에 사용하세요:

• 하나의 워크플로우 실행을 디버그하고 무슨 일이 일어났는지 이해하기.
• 동작을 체계적으로 점수화할 준비가 되면 agent workflow evaluation에 더 신호가 강한 예시를 공급하기.

다음 단계

외부 표면이 연결되면, 능력 설계, 검토 경계, 또는 평가를 다루는 가이드로 계속 진행하세요.

[Using tools

    See how hosted tools, function tools, and agents-as-tools fit beside MCP.](https://developers.openai.com/api/docs/guides/tools#usage-in-the-agents-sdk)

[Guardrails and human review

    Add approval or validation boundaries around sensitive capabilities.](https://developers.openai.com/api/docs/guides/agents/guardrails-approvals)

[Agent workflow evaluation

    Move from one-off traces into repeatable grading once behavior stabilizes.](https://developers.openai.com/api/docs/guides/agent-evals)

더 알아보기 (Learn more)

관련 문서: 도구 사용하기와 에이전트 워크플로우 평가를 참고하세요.