Démarrage rapide

Ce guide vous permet de créer rapidement un agent fonctionnel avec le SDK. Les exemples suivent la même démarche en JavaScript et en Python : définissez un agent, exécutez-le, puis ajoutez des outils et des agents spécialisés à mesure que votre workflow évolue.

Installez le SDK

Créez un projet, installez le SDK et configurez votre clé API.

1234567# JavaScript
npm install @openai/agents zod

# Python
pip install openai-agents

export OPENAI_API_KEY=sk-...

Créez et exécutez votre premier agent

Commencez par un seul agent chargé d’une tâche précise et un seul tour de conversation. Le SDK appelle le modèle et renvoie un objet contenant la sortie finale et l’historique d’exécution.

1
2
3
4
5
6
7
8
9
10import { Agent, run } from "@openai/agents";

const agent = new Agent({
  name: "History tutor",
  instructions: "You answer history questions clearly and concisely.",
  model: "gpt-6-astra",
});

const result = await run(agent, "When did the Roman Empire fall?");
console.log(result.finalOutput);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18import asyncio

from agents import Agent, Runner

agent = Agent(
    name="History tutor",
    instructions="You answer history questions clearly and concisely.",
    model="gpt-6-astra",
)


async def main() -> None:
    result = await Runner.run(agent, "When did the Roman Empire fall?")
    print(result.final_output)


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

Une réponse concise devrait s’afficher dans le terminal. Une fois cette boucle en place, conservez la même structure et ajoutez progressivement des fonctionnalités, sans partir d’emblée sur une architecture complexe à plusieurs agents.

Transmettez l’état au tour suivant

Le résultat de la première exécution vous permet aussi de choisir l’état à utiliser au deuxième tour.

Après un transfert, réutilisez lastAgent au tour suivant si l’agent spécialisé doit continuer à mener la conversation.

Dotez l’agent d’un outil

Le premier outil que vous ajoutez est souvent une fonction exposée comme outil ou un outil hébergé par OpenAI, comme la recherche web ou la recherche dans les fichiers.

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

const historyFunFact = tool({
  name: "history_fun_fact",
  description: "Return a short history fact.",
  parameters: z.object({}),
  async execute() {
    return "Sharks are older than trees.";
  },
});

const agent = new Agent({
  name: "History tutor",
  instructions:
    "Answer history questions clearly. Use history_fun_fact when it helps.",
  tools: [historyFunFact],
});

const result = await run(
  agent,
  "Tell me something surprising about ancient life on Earth."
);

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
28import asyncio

from agents import Agent, Runner, function_tool


@function_tool
def history_fun_fact() -> str:
    """Return a short history fact."""
    return "Sharks are older than trees."


agent = Agent(
    name="History tutor",
    instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
    tools=[history_fun_fact],
)


async def main() -> None:
    result = await Runner.run(
        agent,
        "Tell me something surprising about ancient life on Earth.",
    )
    print(result.final_output)


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

Consultez le guide commun Utilisation des outils si vous souhaitez utiliser des outils hébergés, rechercher des outils ou utiliser des agents comme outils.

Ajoutez des agents spécialisés

L’étape suivante consiste souvent à répartir les tâches du workflow entre plusieurs agents spécialisés. Un routeur peut alors passer la main à l’agent compétent pour chaque tâche.

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

const historyTutor = new Agent({
  name: "History tutor",
  instructions: "Answer history questions clearly and concisely.",
});

const mathTutor = new Agent({
  name: "Math tutor",
  instructions: "Explain math step by step and include worked examples.",
});

const triageAgent = Agent.create({
  name: "Homework triage",
  instructions: "Route each homework question to the right specialist.",
  handoffs: [historyTutor, mathTutor],
});

const result = await run(
  triageAgent,
  "Who was the first president of the United States?"
);

console.log(result.finalOutput);
console.log(result.lastAgent?.name);

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
34import asyncio

from agents import Agent, Runner

history_tutor = Agent(
    name="History tutor",
    handoff_description="Specialist for history questions.",
    instructions="Answer history questions clearly and concisely.",
)

math_tutor = Agent(
    name="Math tutor",
    handoff_description="Specialist for math questions.",
    instructions="Explain math step by step and include worked examples.",
)

triage_agent = Agent(
    name="Homework triage",
    instructions="Route each homework question to the right specialist.",
    handoffs=[history_tutor, math_tutor],
)


async def main() -> None:
    result = await Runner.run(
        triage_agent,
        "Who was the first president of the United States?",
    )
    print(result.final_output)
    print(result.last_agent.name)


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

Examinez les traces dès la première exécution

Le SDK enregistre les traces lors d’une exécution standard côté serveur. Dès que la première exécution aboutit, ouvrez le tableau de bord des traces pour examiner les appels au modèle, les appels aux outils, les transferts entre agents et les garde-fous avant d’affiner vos prompts.

Étapes suivantes

Une fois la première exécution réussie, consultez le guide correspondant à la prochaine fonctionnalité que vous souhaitez ajouter.