Antisèche Kit SDK Agents OpenAI
Le Kit SDK Agents OpenAI est un petit framework Python opinioné pour construire des applications agentiques. Il expose quatre primitives essentielles — Agents (un LLM plus des instructions et des outils), Tools (fonctions Python ou outils hébergés), Handoffs (déléguer une exécution à un autre agent), et Guardrails (valider les entrées et sorties) — avec Sessions pour la mémoire et Tracing intégrés. Il est flexible en termes de fournisseur mais fonctionne prêt à l’emploi avec les modèles OpenAI.
Installation
| Étape | Commande |
|---|
| Installer | pip install openai-agents |
| Avec uv | uv add openai-agents |
| Définir la clé | export OPENAI_API_KEY="sk-..." |
| Extras vocaux | pip install "openai-agents[voice]" |
| Vérifier | python -c "import agents; print(agents.__version__)" |
Agent Minimal
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="You are a concise, helpful assistant.",
)
result = Runner.run_sync(agent, "Summarize the Unix philosophy in one line.")
print(result.final_output)
| Appel | Description |
|---|
Runner.run_sync(agent, input) | Exécuter de façon synchrone |
await Runner.run(agent, input) | Exécuter de façon asynchrone |
Runner.run_streamed(agent, input) | Diffuser les événements au fur et à mesure |
result.final_output | La réponse finale de l’agent |
result.new_items | Éléments structurés d’exécution (messages, appels d’outils, handoffs) |
Outils
from agents import Agent, function_tool
@function_tool
def get_weather(city: str) -> str:
"""Return the weather for a city."""
return f"Sunny in {city}"
agent = Agent(name="Weather", tools=[get_weather])
| Concept | Description |
|---|
@function_tool | Transformer une fonction Python typée en outil (schéma auto-généré à partir de la signature/docstring) |
| Outils hébergés | Éléments intégrés comme la recherche web et la recherche de fichiers |
tool_use_behavior | Contrôler si la sortie de l’outil termine le tour |
| Agents comme outils | agent.as_tool(...) expose un agent comme outil appelable d’un autre |
Handoffs
from agents import Agent, handoff
billing = Agent(name="Billing", instructions="Handle billing questions.")
triage = Agent(
name="Triage",
instructions="Route the user to the right specialist.",
handoffs=[billing], # or handoff(billing, ...)
)
Les handoffs transfèrent la conversation complète à l’agent destinataire dans une seule exécution ; les guardrails d’entrée s’appliquent au premier agent et les guardrails de sortie à l’agent qui produit la sortie finale.
Guardrails
from agents import Agent, input_guardrail, GuardrailFunctionOutput
@input_guardrail
async def no_secrets(ctx, agent, user_input):
tripped = "password" in user_input.lower()
return GuardrailFunctionOutput(output_info={}, tripwire_triggered=tripped)
agent = Agent(name="Safe", input_guardrails=[no_secrets])
| Type | S’exécute | Objectif |
|---|
@input_guardrail | Avant l’agent | Valider/examiner l’entrée utilisateur |
@output_guardrail | Après la sortie finale | Valider la réponse de l’agent |
| Guardrails d’outil | Autour de chaque appel d’outil | Vérifier les entrées/sorties des outils individuels |
| Tripwire | Au déclenchement | Lever une exception pour arrêter l’exécution |
Sessions (Mémoire)
from agents import Agent, Runner, SQLiteSession
session = SQLiteSession("user-123", "conversations.db")
Runner.run_sync(agent, "My name is Nick.", session=session)
Runner.run_sync(agent, "What's my name?", session=session) # remembers
| Session | Utilisation |
|---|
SQLiteSession | Mémoire de conversation locale/persistante |
| Session en mémoire | Contexte éphémère au sein d’un processus |
| Session personnalisée | Implémenter le protocole de session pour votre propre magasin |
Traçage
| Fonctionnalité | Description |
|---|
| Traces automatiques | Chaque Runner.run enregistre les appels de modèle, appels d’outils, handoffs, résultats de guardrails, et la synchronisation |
| Tableau de bord | Les traces s’affichent sous votre projet sur la plateforme OpenAI |
trace(...) | Grouper plusieurs exécutions en une trace de flux de travail |
| Processeurs externes | Exporter les spans vers des outils d’observabilité tiers |
Flux de Travail Courants
# Streaming de tokens vers une interface utilisateur
import asyncio
from agents import Agent, Runner
async def main():
agent = Agent(name="Writer", instructions="Write vividly.")
streamed = Runner.run_streamed(agent, "Describe a thunderstorm.")
async for event in streamed.stream_events():
print(event)
asyncio.run(main())
Ressources
