Integrações e observabilidade

Depois de definir a estrutura do fluxo de trabalho, decida quais interfaces externas integrar ao ciclo de execução do agente e como verificar o que aconteceu durante a execução.

Escolha o que integrar ao SDK

Para entender o que cada ferramenta pode fazer e como ela funciona, consulte Uso de ferramentas. Esta página explica como conectar o MCP ao SDK e acompanhar as execuções.

MCP

Use ferramentas MCP hospedadas quando o modelo precisar acessar o servidor remoto pela própria interface do modelo.

1
2
3
4
5
6
7
8
9
10
11
12import { 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",
    }),
  ],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16from 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",
            }
        )
    ],
)

Use transportes locais quando o aplicativo precisar se conectar diretamente ao servidor MCP.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22import { 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();
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29import 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())

Escolha de acordo com quem deve controlar a conexão.

• Use MCP hospedado para servidores remotos públicos compatíveis com o modelo de confiança da plataforma.
• Use MCP local ou privado quando o seu ambiente de execução precisar controlar a conectividade, a filtragem ou as aprovações.

Para entender como o MCP funciona na plataforma, qual é o modelo de confiança e quais produtos oferecem suporte, consulte a referência principal sobre servidores MCP.

Rastreamento

O SDK de Agentes inclui rastreamento e o habilita por padrão no modo usual de execução no servidor. Cada execução pode gerar um registro estruturado das chamadas ao modelo e às ferramentas, das transferências de controle entre agentes, das salvaguardas e dos segmentos de rastreamento personalizados. Você pode examinar esse registro no painel de rastreamento.

O rastro padrão geralmente inclui os seguintes elementos:

• uma visão geral da execução ou do fluxo de trabalho
• cada chamada ao modelo
• as chamadas às ferramentas e seus resultados
• as transferências de controle entre agentes e as salvaguardas
• os segmentos de rastreamento personalizados que você definir para abranger o fluxo de trabalho

Se precisar de menos rastreamento, use os controles disponíveis no SDK ou em cada execução para preservar a observabilidade do fluxo de trabalho.

1
2
3
4
5
6
7
8
9
10
11
12
13import { 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);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import 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())

Use os rastros para duas tarefas:

• Depurar uma execução do fluxo de trabalho e entender o que aconteceu.
• Usar os exemplos mais informativos na avaliação de fluxos de trabalho de agentes quando você estiver pronto para pontuar o comportamento de forma sistemática.

Próximas etapas

Depois de conectar as interfaces externas, escolha o guia de acordo com a próxima tarefa: projetar recursos, definir quais ações exigem revisão ou avaliar o fluxo de trabalho.