pydantic/building-pydantic-ai-agents

Que fait building-pydantic-ai-agents ?

Construisez des agents IA avec Pydantic AI — outils, capacités (y compris chargement à la demande), sorties structurées, streaming, tests et motifs multi-agents. Utilisez cette compétence lorsque l'utilisateur mentionne Pydantic AI, importe pydantic_ai, ou demande de construire un agent IA, ajouter des outils/capacités, différer le chargement des capacités, diffuser la sortie, définir des agents depuis un fichier YAML, ou tester le comportement d'un agent.

Installation

pip install pydantic-ai

Création de base d'un agent

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-4o',
    system_prompt="Sois un agent utile.",
)

Ajout d'outils

Les outils sont des fonctions Python que l'agent peut appeler.

@agent.tool
def get_weather(location: str) -> str:
    return f"Il fait soleil à {location}."

Pour les outils asynchrones :

@agent.tool
def get_weather_async(location: str) -> str:
    return f"Il fait nuageux à {location}."

Capacités (chargement statique et à la demande)

Les capacités sont des sous-systèmes auto-contenus qui peuvent être attachés à un agent.

Chargement statique

class WeatherCapability:
    """Capacité météo : fournit des outils liés à la météo."""

    @agent.tool
    def get_temperature(self, location: str) -> str:
        return f"25°C à {location}."

    @agent.tool
    def get_humidity(self, location: str) -> str:
        return f"60% d'humidité à {location}."

# Attacher la capacité à l'agent
weather_cap = WeatherCapability()
# Les outils sont enregistrés via le décorateur @agent.tool
# Aucune étape supplémentaire n'est requise

Chargement à la demande (On-demand)

Utilisez le chargement à la demande pour différer l'initialisation des outils jusqu'à ce qu'ils soient nécessaires. Ceci est utile pour les systèmes modulaires avec des coûts de démarrage importants (par exemple, connexions à une base de données, modèles de ML).

import json
from pydantic_ai import ToolDefinition

class OnDemandWeatherCapability:
    async def __init__(self):
        self.weather_data = await fetch_weather_data()

    async def get_temperature(self, location: str, ctx) -> str:
        return f"Température actuelle à {location} : 25°C"

    async def prepare_temperature_tool_def(self, ctx) -> ToolDefinition:
        return ToolDefinition(
            name="get_temperature",
            description="Obtenir la température actuelle pour un lieu.",
            parameters_json_schema={
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "Nom de la ville"}
                },
                "required": ["location"],
            },
        )

# Enregistrer la capacité à la demande
weather_cap = OnDemandWeatherCapability()
agent.register_capability(weather_cap)

Sortie structurée

Utilisez un modèle Pydantic pour une sortie structurée.

from pydantic import BaseModel

class WeatherResponse(BaseModel):
    temperature: float
    humidity: float
    conditions: str

agent = Agent(
    'openai:gpt-4o',
    result_type=WeatherResponse,
    system_prompt="Fournis des informations météo précises.",
)

result = await agent.run("Quel temps fait-il à Paris ?")
print(result.data.temperature)  # Accès aux champs structurés

Streaming

async with agent.run_stream("Raconte une blague") as result:
    async for text in result.stream():
        print(text, end='', flush=True)

Validation des résultats

Utilisez result_validator pour une validation personnalisée.

@agent.result_validator
def validate_result(ctx, result: str) -> str:
    if "erreur" in result.lower():
        raise ValueError("La réponse contient une erreur.")
    return result

Tests

pip install pytest pytest-asyncio

# test_agent.py
import pytest
from pydantic_ai import Agent

@pytest.mark.asyncio
async def test_agent_response():
    agent = Agent('openai:gpt-4o', system_prompt="Réponds toujours 'Bonjour'.")
    result = await agent.run("Salut")
    assert "Bonjour" in result.data

Motifs multi-agents

Pour les systèmes complexes, orchestrez plusieurs agents.

from pydantic_ai import Agent, RunContext

class Orchester:
    def __init__(self):
        self.agent_meteo = Agent('openai:gpt-4o', system_prompt="Fournis des prévisions météo.")
        self.agent_actualites = Agent('openai:gpt-4o', system_prompt="Donne les dernières actualités.")

    async def gerer_demande(self, requete: str) -> str:
        if "météo" in requete.lower():
            return await self.agent_meteo.run(requete)
        elif "actualités" in requete.lower():
            return await self.agent_actualites.run(requete)
        else:
            return "Demande non reconnue."

orchester = Orchester()
reponse = await orchester.gerer_demande("Quel temps fait-il ?")

Définition d'agents depuis YAML

# agent.yaml
name: MonAgent
model: openai:gpt-4o
system_prompt: "Sois utile et concis."
outils:
  - nom: obtenir_meteo
    description: Obtenir la météo pour un lieu.
    parametres:
      type: object
      proprietes:
        lieu:
          type: string
      requis:
        - lieu

import yaml

with open("agent.yaml") as f:
    config = yaml.safe_load(f)

agent = Agent(
    config['model'],
    system_prompt=config['system_prompt'],
)

# Enregistrer les outils de manière dynamique selon la configuration
for outil_config in config.get('outils', []):
    # Créer et enregistrer l'outil selon la configuration
    pass

Bonnes pratiques

• Utilisez des dépendances explicites dans les fonctions d'outils.
• Pour le chargement à la demande, gérez la durée de vie des capacités avec le manager de contexte de l'agent.
• Testez toujours les agents avec pytest et pytest-asyncio.
• Utilisez des variables d'environnement pour les clés API.
• Validez les sorties avec result_validator et des modèles Pydantic.