Integraciones y observabilidad

Una vez que tengas clara la estructura del flujo de trabajo, decide qué servicios externos integrar en el ciclo del agente y cómo revisarás lo que ocurrió durante la ejecución.

Decide qué integrar en el SDK

Para saber qué puede hacer cada herramienta y cómo funciona, consulta Uso de herramientas. Esta página se centra en cómo conectar MCP y observar las ejecuciones con el SDK.

MCP

Usa herramientas MCP alojadas cuando el modelo deba acceder al servidor remoto a través de su propia interfaz.

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",
            }
        )
    ],
)

Usa transportes locales cuando tu aplicación deba conectarse directamente al 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())

Elige según lo que necesites:

• Usa MCP alojado para servidores remotos públicos que se ajusten al modelo de confianza de la plataforma.
• Usa MCP local o privado cuando tu entorno de ejecución deba controlar la conectividad, el filtrado o las aprobaciones.

Consulta Servidores MCP como referencia principal para entender cómo funciona MCP en toda la plataforma, qué modelo de confianza utiliza y qué productos lo admiten.

Registro de trazas

El SDK de agentes incorpora el registro de trazas y lo habilita de forma predeterminada cuando usas el SDK del lado del servidor de la manera habitual. Cada ejecución puede generar un registro estructurado de las llamadas al modelo y a las herramientas, las transferencias entre agentes, los controles de seguridad y los segmentos personalizados. Puedes revisarlo en el panel de trazas.

La traza predeterminada suele mostrar:

• la ejecución o el flujo de trabajo en su conjunto
• cada llamada al modelo
• las llamadas a herramientas y sus resultados
• las transferencias entre agentes y los controles de seguridad
• los segmentos personalizados que definas para abarcar el flujo de trabajo

Si necesitas registrar menos trazas, ajusta los controles de trazas para todo el SDK o para cada ejecución en lugar de desactivar por completo la observabilidad del flujo de trabajo.

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())

Usa las trazas para dos tareas:

• Depurar una ejecución del flujo de trabajo y entender qué ocurrió.
• Incorporar los ejemplos más informativos a la evaluación de flujos de trabajo de agentes cuando quieras empezar a puntuar el comportamiento de forma sistemática.

Próximos pasos

Una vez que hayas conectado los servicios externos, continúa con la guía sobre el diseño de capacidades, los puntos de revisión o la evaluación, según lo que necesites.