Hoppa till huvudinnehåll
Svenska— Välj ett språk
Meny

Appel de fonctions avancé : schémas et validation

Lektion 7 av 25 Uppdaterad 29 juli 2026 Utvecklare
På denna sida
  1. Appel de fonctions avancé : schémas et validation
  2. Schémas JSON et mode strict
  3. Validation personnalisée avec Pydantic
  4. Gestion des erreurs dans les outils
  5. Sortie structurée pour les outils
  6. Motif : outils avec contexte partagé
  7. Viktiga punkter

Appel de fonctions avancé : schémas et validation

L’appel de fonctions est le mécanisme central qui permet à un agent de décider quand et comment invoquer tes outils. Déclarer un outil suffit pour un prototype, mais passer en production exige que tu contraignes les appels, valides les valeurs métier et gères les échecs sans faire planter l’agent. C’est exactement ce que couvre cette leçon.

Schémas JSON et mode strict

L’API Responses utilise des schémas JSON pour décrire les paramètres de chaque outil, et le mode strict garantit que le modèle respecte exactement le schéma. Plus précisément, l’utilisation d’un Enum ou d’un Literal ferme la porte aux valeurs inventées.

from agents import function_tool
from pydantic import BaseModel, Field
from typing import Literal
from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

class CreateTicket(BaseModel):
    title: str = Field(description="Short ticket title (max 100 characters)")
    description: str = Field(description="Detailed problem description")
    priority: Priority = Field(description="Ticket priority level")
    component: Literal["frontend", "backend", "infra", "data"] = Field(
        description="Affected technical component"
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Optional tags to categorize the ticket"
    )

@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
    """Creates a new technical support ticket."""
    # In production: call Jira, Linear, GitHub Issues, etc.
    return f"Ticket created: [{ticket.priority.value}] {ticket.title} ({ticket.component})"

Avec le mode strict activé par défaut, le modèle ne peut jamais envoyer une priorité invalide ou un composant hors de la liste autorisée. Tu n’auras pas besoin d’écrire du code backend défensif pour traduire « urgent » ou « P1 » en une valeur que ton système de billetterie reconnaît.

Validation personnalisée avec Pydantic

La vérification des types empêche les valeurs impossibles, pas les valeurs absurdes. Un IBAN de quinze caractères est une chaîne parfaitement valide ; ta logique métier le rejette. Pydantic te permet d’intégrer ces règles directement dans le schéma.

from pydantic import BaseModel, Field, field_validator

class MoneyTransfer(BaseModel):
    source_account: str = Field(description="Source account IBAN")
    destination_account: str = Field(description="Destination account IBAN")
    amount: float = Field(gt=0, le=50000, description="Amount in euros (max 50,000)")
    reason: str = Field(min_length=5, max_length=200, description="Reason for transfer")

    @field_validator("source_account", "destination_account")
    @classmethod
    def validate_iban(cls, v):
        if not v.startswith("FR"):
            raise ValueError("Only French IBANs are accepted")
        if len(v) != 27:
            raise ValueError("IBAN must contain 27 characters")
        return v

@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
    """Executes a bank transfer between two accounts."""
    return f"Transfer of €{transfer.amount} initiated from {transfer.source_account[:8]}... to {transfer.destination_account[:8]}..."

Les contraintes gt=0 et le=50000 sur le montant jouent un rôle similaire à un autre niveau : elles rendent structurellement impossible un transfert négatif ou dépassant la limite, quelle que soit la formulation de la demande par l’utilisateur.

Gestion des erreurs dans les outils

Que se passe-t-il lorsqu’un outil s’exécute mais échoue ? La tentation est de laisser l’exception remonter ; c’est une erreur, car cela interrompt la boucle de l’agent. À la place, renvoie un message d’erreur clair que le modèle peut lire et interpréter.

import json
from agents import function_tool

@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
    """Queries an external API with the specified parameters."""
    try:
        # In production: real HTTP call
        import httpx
        response = httpx.get(f"https://api.example.com/{endpoint}", params=parameters, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), ensure_ascii=False)
    except httpx.TimeoutException:
        return json.dumps({
            "error": True,
            "message": f"Timeout calling {endpoint}. Retry in a few moments."
        })
    except httpx.HTTPStatusError as e:
        return json.dumps({
            "error": True,
            "message": f"HTTP error {e.response.status_code} on {endpoint}.",
            "details": str(e)
        })
    except Exception as e:
        return json.dumps({
            "error": True,
            "message": f"Unexpected error: {str(e)}"
        })

Chaque branche formate le message dans un langage que le modèle comprend. En cas de délai d’attente, l’agent tentera un nouvel appel ; en cas d’erreur HTTP 404, il informera l’utilisateur ou changera d’approche plutôt que de persister aveuglément.

Sortie structurée pour les outils

Cette contrainte s’applique également à la sortie finale. Avec output_type, final_output n’est plus un texte à analyser mais un objet typé, directement utilisable par le code appelant.

from pydantic import BaseModel
from agents import Agent, Runner

class AnalysisResponse(BaseModel):
    summary: str
    key_points: list[str]
    recommendation: str
    confidence_score: float

agent = Agent(
    name="Analyst",
    instructions="Analyze the provided data and produce a structured report.",
    model="gpt-5.6-terra",
    output_type=AnalysisResponse,
)

result = Runner.run_sync(agent, "Analyze Q1 2026 sales trends.")
# result.final_output is of type AnalysisResponse
print(f"Summary: {result.final_output.summary}")
print(f"Score: {result.final_output.confidence_score}")

Motif : outils avec contexte partagé

Un dernier problème récurrent : tes outils ont souvent besoin d’un état partagé — session utilisateur, connexion base de données, clé API — qu’il serait absurde de faire passer par le modèle. Le contexte résout ce problème en le transmettant alongside la conversation.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class AppContext:
    user_id: str
    db_connection: object  # Your DB connection
    api_key: str

@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
    """Retrieves the current user's profile."""
    user_id = ctx.context.user_id
    # Use ctx.context.db_connection for the query
    return f"User profile {user_id}: Premium, active since 2024"

agent = Agent(
    name="Personalized Agent",
    instructions="You assist the logged-in user.",
    tools=[get_user_profile],
)

context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "What is my profile?", context=context)

L’outil n’a aucun paramètre métier : l’identité de l’utilisateur provient du contexte, pas du modèle. C’est aussi une mesure de sécurité, car l’agent ne peut pas consulter le profil de quelqu’un d’autre en modifiant un argument.

Viktiga punkter

  • Les schémas Pydantic avec énumérations et Literals garantissent la validité des appels
  • Les validateurs de champs ajoutent une validation métier par-dessus la vérification des types
  • Renvoie des messages d’erreur JSON au lieu de lever des exceptions dans les outils
  • output_type force l’agent à structurer sa réponse finale
  • Le contexte partagé (RunContextWrapper) permet aux outils d’accéder à l’état de l’application