Tutoriels Agent Framework

Premiers pas dans un notebook

Commencez à utiliser Agent Framework avec un agent "Hello World" dans un notebook.

Exemples d'agents

Pour consulter des exemples de code pour des agents, téléchargez le fichier ZIP à partir de ce dossier Google Drive dans votre environnement de développement local.

Le répertoire des exemples contient des agents de démonstration. Installez les dépendances dans le fichier requirements.txt pour un agent de démonstration spécifique:

pip install  -r samples/anthropic_demo/requirements.txt

Exécutez les commandes suivantes :

af web samples

af run samples/hello_world

Tutoriels

Cette page fournit des tutoriels détaillés sur les tâches courantes à effectuer avec le framework d'agent. Choisissez un tutoriel pour commencer.

Tutoriel: Intégrer vos propres données à un agent

Ce tutoriel présente différentes méthodes pour fournir vos propres données, connaissances ou documents à votre agent. La meilleure approche dépend de la taille et du type de vos données, ainsi que de l'équilibre souhaité entre latence et précision.

Fournir vos propres données

Il existe plusieurs façons de fournir vos propres données / connaissances / documents à l'agent, en fonction de la taille et du type des données, ainsi que des compromis de latence/précision souhaités.

Type Petit montant Grande quantité
Texte brut Intégrer dans les instructions ou le RAG RAG
Documents Intégrer dans les instructions ou le RAG RAG
Autres contenus multimédias 
(images, fichiers audio, vidéos, etc.)		 WIP WIP

Vous trouverez plus d'informations sur chaque approche dans les tutoriels suivants.

Intégrer des données dans les instructions

Pour fournir facilement une petite quantité de documents à l'agent, vous pouvez les intégrer aux instructions.

Les fichiers PDF ou autres fichiers textuels peuvent être convertis en texte brut et intégrés aux instructions.

Remarques

  • Le contenu des fichiers sera envoyé au modèle. Plus le fichier est volumineux, plus la latence et les coûts sont élevés.

  • Le contenu sera envoyé au modèle pour toutes les requêtes, que la requête de l'utilisateur n'ait rien à voir avec le contenu.

  • Vous pouvez utiliser du texte brut ou tout autre format de texte lisible, par exemple Markdown, pour votre fichier.

Risques de sécurité

  • L'intégration de contenu de cette manière présente certains risques de sécurité, car le serveur peut traiter le contenu des documents intégrés comme ses propres instructions.

  • Ce risque de sécurité peut être atténué dans une certaine mesure en marquant clairement le début et la fin du contenu intégré, comme illustré dans l'exemple ci-dessous.

  • En raison de ce risque, n'intégrez pas de contenu dont vous ne pouvez pas vous fier, par exemple du contenu généré par les utilisateurs.

Exemple

Pour rendre les instructions lisibles, une approche courante consiste à charger le fichier et à l'insérer dans les instructions à l'aide de la syntaxe de chaîne f de Python.

Notez qu'il utilise des balises XML pour séparer le contenu du fichier du reste des instructions. Vous pouvez également utiliser d'autres méthodes de séparation, à condition qu'elles soient claires pour le modèle. Par exemple, des tags tels que BEGIN_USER_GUIDE / END_USER_GUIDE.

def read_file(filename):
  file_path = os.path.join(os.path.dirname(__file__), filename)
  with open(file_path, 'r') as f:
    return f.read()

agent_framework_bot = Agent(
    # ...
    instruction=f"""You are an agent that answers user's questions about the Agent Framework.

You answer users' questions based on the user guide below:
<user_guide>
{read_file('user_guide.md')}
</user_guide>
"""
)

Utiliser le RAG

La génération augmentée par récupération est un modèle courant pour enrichir les réponses du modèle avec vos propres données. Elle est particulièrement utile pour les grandes quantités de données, car elle fonctionne en les indexant et ne récupère qu'une petite partie des données pertinentes pour la requête.

Le framework Agent propose plusieurs méthodes d'intégration à différents systèmes de classification RAG.

Scénarios Recommandations
Démos / Prototypes FilesRetrieval
Faible quantité de données
(une poignée de documents)		 FilesRetrieval
Solution RAG entièrement gérée VertexRagRetrieval
Solutions DIY ou autres solutions RAG LlamaIndexRetrieval

FilesRetrieval

FilesRetrieval crée un magasin de vecteurs en mémoire lorsque votre agent démarre. Il ajoute de la latence et est limité à la mémoire et aux performances de l'environnement d'hébergement de l'API. Par conséquent, cette option n'est adaptée qu'aux démonstrations / prototypes, ou à la production avec une très petite quantité de documents.

FilesRetrieval est basé sur LlamaIndex. Vous devez le configurer en suivant la documentation de LlamaIndex.

Une fois la configuration terminée, vous pouvez placer vos documents dans un dossier et créer un outil de récupération comme suit:

company_policies_retrieval = FilesRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    input_dir=os.path.join(os.path.dirname(__file__), 'company_policies'),
)

root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

VertexRagRetrieval

Le moteur RAG Vertex est un service entièrement géré qui gère l'ingestion, la transformation, l'intégration, l'indexation et la récupération des données.

Pour l'utiliser, suivez le guide de démarrage rapide pour configurer votre corpus et ingérer des documents. Ajoutez ensuite l'outil à votre agent.

company_policies_retrieval = VertexRagRetrieval(
    name='company_policies',
    description='Company policies about flight cancelation and rebooking.',
    rag_corpus_name='projects/.../locations/.../ragCorpora/...',
)
root_agent = Agent(
  # ...
  tools=[company_policies_retrieval],
)

Grâce à la recherche Google, votre agent pourra accéder à des informations concrètes en temps réel et utiliser la recherche Google pour répondre à vos questions.

Remarques

  • L'Ancrage dans la recherche Google peut entraîner des frais supplémentaires.
  • Pour Gemini 1.5 :
    • Lorsque vous ajoutez l'outil de recherche Google à un agent, vous ne pouvez pas utiliser d'autres outils pour cet agent.
    • L'outil de recherche Google est toujours exécuté, que la requête nécessite la recherche Google ou non.
  • Pour Gemini 2.0 et versions ultérieures :
    • Vous pouvez utiliser d'autres outils lorsque vous utilisez l'outil de recherche Google.
    • L'outil de recherche Google n'est exécuté que lorsque le modèle le juge nécessaire.
  • Les modèles tiers ne sont pas compatibles avec les outils de recherche Google.
  • Pour utiliser l'outil de recherche Google, vous devez respecter les consignes de la page Utiliser les suggestions de recherche Google, y compris en affichant toujours une bannière pour afficher les requêtes de recherche Google associées. Notre interface utilisateur pour les développeurs respecte également ces règles.

Exemple

Activer l'outil de recherche Google est très simple. Il vous suffit d'ajouter google_search à votre liste d'outils.

from agents.tools import google_search

root_agent = Agent(
    # ...
    tools=[google_search],
)

Tutoriel: Évaluer les performances de votre agent

Évaluer votre agent est essentiel pour vous assurer qu'il fonctionne comme prévu et qu'il respecte vos normes de qualité. Le framework d'agent propose plusieurs méthodes pour évaluer les performances de l'agent à l'aide de fichiers de test et de critères d'évaluation.

Fonctionnement de l'évaluation

Chaque fichier de test contient une liste de requêtes, de trajectoires d'outils attendues et de réponses de référence. Les fichiers de test peuvent être organisés dans des dossiers. Un dossier peut éventuellement inclure un fichier test_config.json qui spécifie les critères d'évaluation.

Exemple de fichier de test

Un fichier de test contient une session avec des requêtes, l'utilisation prévue de l'outil et des réponses de référence. Voici un exemple :

[
  {
    "query": "hi",
    "expected_tool_use": [],
    "reference": "Hello! What can I do for you?\n"
  },
  {
    "query": "roll a die for me",
    "expected_tool_use": [
      {
        "tool_name": "roll_die",
        "tool_input": {
          "sides": 6
        }
      }
    ]
  },
  {
    "query": "what's the time now?",
    "expected_tool_use": [],
    "reference": "I'm sorry, I cannot access real-time information, including the current time. My capabilities are limited to rolling dice and checking prime numbers.\n"
  }
]

Critères d'évaluation

Les critères d'évaluation dans test_config.json définissent la manière dont les performances de l'agent seront mesurées:

  • tool_trajectory_avg_score: évaluez les trajectoires des outils.
  • response_match_score: évaluez les réponses.

Si aucun critère d'évaluation n'est fourni, une configuration par défaut sera appliquée.

Exemples de critères d'évaluation (test_config.json)

Voici un exemple de fichier test_config.json spécifiant des critères d'évaluation personnalisés:

{
  "criteria": {
    "tool_trajectory_avg_score": 1.0,
    "response_match_score": 0.8
  }
}
  • tool_trajectory_avg_score: défini sur 1,0, ce qui signifie que l'utilisation d'une trajectoire d'outil parfaite est attendue.
  • response_match_score: défini sur 0,8, ce qui permet d'accepter une petite marge d'erreur dans les réponses de l'agent.

Méthodes d'exécution de l'évaluation

1. af web : exécuter des évaluations via l'interface utilisateur Web

Vous pouvez évaluer les agents de manière interactive à l'aide de notre interface utilisateur Web.

Étapes :
  1. Démarrez le serveur Web en exécutant: bash af web
  2. Dans l'interface Web :
    • Sélectionnez un agent.
    • Cliquez sur "Enregistrer la session en tant que fichier de test" pour enregistrer une session en tant que fichier de test.
    • Cliquez sur "Exécuter le fichier de test" pour afficher un pop-up contenant les fichiers de test dans le dossier de l'agent.
Fichiers de test:

Les fichiers de test sont stockés dans le même dossier que l'agent. Vous pouvez mettre à jour ou ajouter manuellement des fichiers de test si nécessaire.

2. af test : exécuter des tests via la ligne de commande

Vous pouvez exécuter tous les fichiers de test d'un dossier spécifié à l'aide de la commande af test. Le dossier doit contenir la définition de l'agent et les fichiers de test.

Exemple :
af test samples/agent_folder

Cette commande recherche et exécute tous les fichiers de test (*.test.json) dans le dossier spécifié.

3. pytest : exécuter des tests par programmation

Vous pouvez également utiliser pytest pour exécuter des fichiers de test dans le cadre de vos tests d'intégration.

Exemple de commande:
pytest tests/integrations/
Exemple de code de test:

Voici un exemple de cas de test pytest qui exécute un seul fichier de test:

def test_with_single_test_file():
    """Test the agent's basic ability via a session file."""
    AgentEvaluator.evaluate(
        "tests.integration.fixture.home_automation_agent",
        "tests/integration/fixture/home_automation_agent/simple_test.test.json",
    )

Cette approche vous permet d'intégrer les évaluations des agents à vos pipelines CI/CD ou à des suites de test plus importantes.