Définition des agents

L’agent est l’unité de base d’un workflow construit avec le SDK. Il réunit un modèle et des instructions. Vous pouvez aussi configurer son comportement à l’exécution avec des outils, des garde-fous, des serveurs MCP, des transferts entre agents et des sorties structurées.

Que configurer au niveau de l’agent ?

Configurez directement sur l’agent les éléments propres à sa spécialité.

Commencez par un agent spécialisé

Définissez l’agent le plus simple capable de prendre en charge une tâche précise. Ajoutez d’autres agents uniquement si vous devez répartir les responsabilités, donner des instructions distinctes, proposer des interfaces d’outils différentes ou appliquer des politiques d’approbation différentes.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { Agent, tool } from "@openai/agents";
import { z } from "zod";

const getWeather = tool({
  name: "get_weather",
  description: "Return the weather for a given city.",
  parameters: z.object({ city: z.string() }),
  async execute({ city }) {
    return `The weather in ${city} is sunny.`;
  },
});

const agent = new Agent({
  name: "Weather bot",
  instructions: "You are a helpful weather bot.",
  model: "gpt-6-astra",
  tools: [getWeather],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15from agents import Agent, function_tool


@function_tool
def get_weather(city: str) -> str:
    """Return the weather for a given city."""
    return f"The weather in {city} is sunny."


agent = Agent(
    name="Weather bot",
    instructions="You are a helpful weather bot.",
    model="gpt-6-astra",
    tools=[get_weather],
)

Configurez les instructions, les transferts et les sorties

Trois choix de configuration méritent une attention particulière.

• Commencez par définir des instructions statiques dans instructions. Si les consignes dépendent de l’utilisateur actuel, du locataire ou du contexte d’exécution, utilisez une fonction de rappel qui génère les instructions dynamiquement plutôt que de concaténer des chaînes de caractères au point d’appel.
• Rédigez une description courte et concrète dans handoffDescription pour que les agents chargés du routage sachent quand choisir ce spécialiste.
• Utilisez outputType si le code en aval a besoin de données typées plutôt que de texte libre.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import { Agent, run } from "@openai/agents";
import { z } from "zod";

const calendarEvent = z.object({
  name: z.string(),
  date: z.string(),
  participants: z.array(z.string()),
});

const agent = new Agent({
  name: "Calendar extractor",
  instructions: "Extract calendar events from text.",
  outputType: calendarEvent,
});

const result = await run(agent, "Dinner with Priya and Sam on Friday.");

console.log(result.finalOutput);

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
29
30import asyncio

from pydantic import BaseModel

from agents import Agent, Runner


class CalendarEvent(BaseModel):
    name: str
    date: str
    participants: list[str]


agent = Agent(
    name="Calendar extractor",
    instructions="Extract calendar events from text.",
    output_type=CalendarEvent,
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Dinner with Priya and Sam on Friday.",
    )
    print(result.final_output)


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

Utilisez prompt pour référencer une configuration de prompt enregistrée dans l’API Responses sans intégrer l’intégralité du prompt système au code.

Séparez le contexte local du contexte du modèle

Le SDK vous permet de transmettre l’état de l’application et ses dépendances à une exécution sans les envoyer au modèle. Utilisez le contexte local pour les informations sur l’utilisateur authentifié, les clients de base de données, les outils de journalisation et les fonctions utilitaires.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23import { Agent, run, tool } from "@openai/agents";
import { z } from "zod";

const fetchUserAge = tool({
  name: "fetch_user_age",
  description: "Return the age of the current user.",
  parameters: z.object({}),
  // TypeScript users can type this as RunContext<{ name: string; uid: number }>.
  async execute(_args, runContext) {
    return `User ${runContext?.context.name} is 47 years old`;
  },
});

const agent = new Agent({
  name: "Assistant",
  tools: [fetchUserAge],
});

const result = await run(agent, "What is the age of the user?", {
  context: { name: "John", uid: 123 },
});

console.log(result.finalOutput);

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
29
30
31
32
33
34
35import asyncio
from dataclasses import dataclass

from agents import Agent, RunContextWrapper, Runner, function_tool


@dataclass
class UserInfo:
    name: str
    uid: int


@function_tool
async def fetch_user_age(wrapper: RunContextWrapper[UserInfo]) -> str:
    """Fetch the age of the current user."""
    return f"The user {wrapper.context.name} is 47 years old."


agent = Agent[UserInfo](
    name="Assistant",
    tools=[fetch_user_age],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "What is the age of the user?",
        context=UserInfo(name="John", uid=123),
    )
    print(result.final_output)


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

La distinction tient à ce qui est visible de chaque côté.

• Le modèle a accès à l’historique de la conversation.
• Votre code a accès au contexte d’exécution.

Si le modèle a besoin d’une information, fournissez-la dans les instructions, dans les données d’entrée, via un mécanisme de recherche d’informations ou via un outil. Si seul votre environnement d’exécution en a besoin, conservez-la dans le contexte local.

Quand répartir le travail entre plusieurs agents ?

Scindez un agent en plusieurs lorsqu’un seul spécialiste ne devrait pas prendre en charge toute la réponse ou lorsque les fonctionnalités à mettre en œuvre diffèrent sensiblement. Voici quelques cas courants.

• Un spécialiste a besoin d’un outil différent ou d’une autre interface MCP.
• Un spécialiste a besoin d’une politique d’approbation différente ou d’un garde-fou différent.
• Une branche du workflow nécessite un autre modèle ou un autre style de sortie.
• Vous souhaitez que les décisions de routage apparaissent explicitement dans les traces plutôt que de les confier à un seul long prompt.

Étapes suivantes

Une fois votre premier agent spécialisé bien défini, consultez le guide qui répond à votre prochaine question de conception.