Intégrations et observabilité

Une fois la structure du workflow définie, choisissez les interfaces externes à intégrer dans la boucle de l’agent et déterminez comment examiner ce qui se passe à l’exécution.

Choisissez les fonctionnalités du SDK à utiliser

Pour comprendre ce que chaque outil permet de faire, consultez Utilisation des outils. Cette page explique comment connecter des serveurs MCP avec le SDK et suivre l’exécution des workflows.

MCP

Utilisez les outils MCP hébergés lorsque le modèle doit accéder au serveur distant via sa propre interface.

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

Utilisez un transport local lorsque votre application doit se connecter directement au serveur 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())

Le choix dépend de votre configuration.

• Utilisez MCP en mode hébergé pour les serveurs distants publics compatibles avec le modèle de confiance de la plateforme.
• Utilisez MCP en environnement local ou privé lorsque votre environnement d’exécution doit gérer les connexions, le filtrage ou les approbations.

Le guide Serveurs MCP fait référence pour le fonctionnement de MCP à l’échelle de la plateforme, le modèle de confiance et la prise en charge de MCP selon les produits.

Traçage

L’Agents SDK intègre le traçage et l’active par défaut dans sa configuration habituelle côté serveur. Chaque exécution peut produire une trace structurée des appels au modèle, des appels d’outils, des transferts entre agents, des garde-fous et des segments de trace personnalisés. Vous pouvez la consulter dans le tableau de bord des traces.

La trace par défaut présente généralement les éléments suivants :

• une vue d’ensemble de l’exécution ou du workflow
• chaque appel au modèle
• les appels d’outils et leurs résultats
• les transferts entre agents et les garde-fous
• les segments de trace personnalisés que vous définissez autour du workflow

Pour limiter le traçage tout en conservant une visibilité sur le workflow, utilisez les réglages de traçage du SDK ou ceux propres à chaque exécution.

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

Les traces servent à deux fins :

• Déboguez une exécution du workflow pour comprendre ce qui s’est passé.
• Intégrez les exemples les plus révélateurs à l’évaluation des workflows d’agents lorsque vous souhaitez noter systématiquement le comportement de l’agent.

Étapes suivantes

Une fois les interfaces externes connectées, poursuivez avec le guide qui correspond à votre besoin : concevoir les fonctionnalités de l’agent, déterminer où une vérification est nécessaire ou évaluer le workflow.