Développer un agent Agent Development Kit

Agent Runtime vous permet de développer et de déployer des agents à l'aide du modèle Agent Development Kit (ADK). En utilisant la classe AdkApp dans le Agent Platform SDK pour Python, vous pouvez créer des agents qui renvoient des taux de change et gèrent les interactions avec état.

Ce document explique comment développer un agent ADK, y compris comment définir le modèle, ajouter des outils et gérer les sessions et les mémoires.

Pour en savoir plus sur la gestion de vos agents déployés, consultez Gérer les agents déployés.

Avant de commencer

Assurez-vous que votre environnement est configuré en suivant la procédure décrite dans Configurer votre environnement.

Définir et configurer un modèle

Spécifiez le modèle que vous souhaitez utiliser :

model = "gemini-2.0-flash"

Facultatif : configurez les paramètres de sécurité du modèle. Pour en savoir plus sur les options disponibles pour configurer les paramètres de sécurité dans Gemini, consultez Configurer les attributs de sécurité. Voici un exemple de configuration des paramètres de sécurité :

from google.genai import types

safety_settings = [
    types.SafetySetting(
        category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
        threshold=types.HarmBlockThreshold.OFF,
    ),
]

Facultatif : spécifiez les paramètres de génération de contenu :

from google.genai import types

generate_content_config = types.GenerateContentConfig(
   safety_settings=safety_settings,
   temperature=0.28,
   max_output_tokens=1000,
   top_p=0.95,
)

Créez un AdkApp à l'aide des configurations de modèle :

from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp

agent = Agent(
   model=model,                                      # Required.
   name='currency_exchange_agent',                   # Required.
   generate_content_config=generate_content_config,  # Optional.
)
app = AdkApp(agent=agent)

Si vous utilisez un environnement interactif, tel que le terminal ou un notebook Colab, vous pouvez exécuter une requête à l'aide de la AdkApp.async_stream_query méthode comme étape de test intermédiaire :

async for event in app.async_stream_query(
   user_id="USER_ID",  # Required
   message="What is the exchange rate from US dollars to Swedish currency?",
):
   print(event)

• USER_ID : choisissez votre propre ID utilisateur avec une limite de 128 caractères. Exemple : user-123.

La réponse est un dictionnaire Python semblable à l'exemple suivant :

{'actions': {'artifact_delta': {},
             'requested_auth_configs': {},
             'state_delta': {}},
 'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'To provide you with the most accurate '
                                'exchange rate, I need to know the specific '
                                'currencies you\'re asking about. "Swedish '
                                'currency" could refer to:\n'
                                '\n'
                                '*   **Swedish Krona (SEK):** This is the '
                                'official currency of Sweden.\n'
                                '\n'
                                "Please confirm if you're interested in the "
                                'exchange rate between USD and SEK. Once you '
                                'confirm, I can fetch the latest exchange rate '
                                'for you.\n'}],
             'role': 'model'},
 'id': 'LYg7wg8G',
 'invocation_id': 'e-113ca547-0f19-4d50-9dde-f76cbc001dce',
 'timestamp': 1744166956.925927}

Facultatif : définir et utiliser un outil

Une fois votre modèle défini, définissez les outils qu'il utilise pour le raisonnement.

Lorsque vous définissez votre fonction, il est important d'inclure des commentaires qui décrivent pleinement et clairement les paramètres de la fonction, ce qu'elle fait et ce qu'elle renvoie. Le modèle utilise ces informations pour déterminer quelle fonction utiliser. Vous devez également tester votre fonction en local pour vérifier qu'elle fonctionne.

Utilisez le code suivant pour définir une fonction qui renvoie un taux de change :

def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """Retrieves the exchange rate between two currencies on a specified date.

    Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
    exchange rate data.

    Args:
        currency_from: The base currency (3-letter currency code).
            Defaults to "USD" (US Dollar).
        currency_to: The target currency (3-letter currency code).
            Defaults to "EUR" (Euro).
        currency_date: The date for which to retrieve the exchange rate.
            Defaults to "latest" for the most recent exchange rate data.
            Can be specified in YYYY-MM-DD format for historical rates.

    Returns:
        dict: A dictionary containing the exchange rate information.
            Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
                "rates": {"EUR": 0.95534}}
    """
    import requests
    response = requests.get(
        f"https://api.frankfurter.app/{currency_date}",
        params={"from": currency_from, "to": currency_to},
    )
    return response.json()

Pour tester la fonction avant de l'utiliser dans votre agent, exécutez la commande suivante :

get_exchange_rate(currency_from="USD", currency_to="SEK")

La sortie devrait ressembler à ce qui suit :

{'amount': 1.0, 'base': 'USD', 'date': '2025-04-03', 'rates': {'SEK': 9.6607}}

Pour utiliser l'outil dans le AdkApp, ajoutez-le à la liste des outils sous l'argument tools= :

from google.adk.agents import Agent

agent = Agent(
    model=model,                     # Required.
    name='currency_exchange_agent',  # Required.
    tools=[get_exchange_rate],       # Optional.
)

Vous pouvez tester l'agent en local en exécutant des requêtes de test à l'aide de la AdkApp.async_stream_query méthode. Exécutez la commande suivante pour tester l'agent en local en utilisant le dollar américain et la couronne suédoise :

from vertexai.agent_engines import AdkApp

app = AdkApp(agent=agent)
async for event in app.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK on 2025-04-03?",
):
    print(event)

où USER_ID est l'ID utilisateur que vous avez défini. Exemple : user-123.

La réponse est une séquence de dictionnaires semblable à la suivante :

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-e39f3ba2-fa8c-4169-a63a-8e4c62b89818',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'zFyIaaif',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-e39f3ba2-fa8c-4169-a63a-8e4c62b89818',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': 'u2YR4Uom',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 9.6607.'}],
             'role': 'model'},
 'id': 'q3jWA3wl',
 # ...
}

Facultatif : gérer les sessions

AdkApp utilise des sessions en mémoire lors de l’exécution en local et utilise des sessions gérées dans le cloud après le déploiement de l’agent dans Agent Runtime. Cette section explique comment configurer votre agent ADK pour qu'il fonctionne avec des sessions gérées.

Facultatif : personnaliser votre base de données de sessions

Remarque : Si vous utilisez un service de session en mémoire personnalisé, les sessions peuvent ne pas rester synchronisées lorsque vous déployez l'agent dans Agent Runtime. Nous vous recommandons de personnaliser votre base de données uniquement si vous pouvez synchroniser l'état entre les sessions dans un environnement déployé.

Si vous souhaitez remplacer le service de session géré par défaut par votre propre base de données, vous pouvez définir une session_service_builder fonction comme suit :

def session_service_builder():
  from google.adk.sessions import InMemorySessionService

  return InMemorySessionService()

Transmettez votre base de données à AdkApp en tant que session_service_builder= :

from vertexai.agent_engines import AdkApp

app = AdkApp(
   agent=agent,                                      # Required.
   session_service_builder=session_service_builder,  # Optional.
)

Utiliser l'agent avec des sessions

Lorsque vous exécutez le AdkApp en local, les instructions suivantes utilisent des sessions en mémoire.

Pour créer une session pour votre agent, utilisez la AdkApp.async_create_session méthode :

session = await app.async_create_session(user_id="USER_ID")
print(session)

La session est créée en tant que représentation du dictionnaire d'un objet de session ADK.

Pour répertorier les sessions associées à votre agent, utilisez la AdkApp.async_list_sessions méthode :

await app.async_list_sessions(user_id="USER_ID")

Pour obtenir une session particulière, utilisez la AdkApp.async_get_session méthode :

session = await app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")

Où :

• USER_ID est l'ID utilisateur que vous avez défini. Exemple : user-123.

• SESSION_ID est l'ID de la session particulière que vous souhaitez récupérer.

Pour interroger l'agent de manière asynchrone, utilisez la AdkApp.async_stream_query méthode :

async for event in app.async_stream_query(
    user_id="USER_ID",
    session_id=SESSION_ID, # Optional. you can pass in the session_id when querying the agent
    message="What is the exchange rate from US dollars to Swedish currency on 2025-04-03?",
):
    print(event)

L'agent peut répondre par une demande d'informations semblable à la suivante :

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'I need to know the Swedish currency code to '
                                'provide you with the exchange rate.'}],
             'role': 'model'},
 'id': 'wIgZAtQ4',
 #...
}

Vous pouvez envoyer une réponse (par exemple, "SEK") au nom de USER_ID dans la session correspondant à session en spécifiant :

async for event in app.async_stream_query(
    user_id="USER_ID",
    session_id=session.id, # Optional. you can pass in the session_id when querying the agent
    message="SEK",
):
    print(event)

Vous devriez recevoir une continuation de la conversation semblable à la séquence de dictionnaires suivante :

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'bOPHtzji',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': '9AoDFmiL',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 1 USD to 9.6607 SEK.'}],
             'role': 'model'},
 'id': 'hmle7trT',
 # ...
}

Facultatif : gérer les mémoires

Par défaut, AdkApp utilise une implémentation en mémoire de la mémoire de l'agent lors de l'exécution en local et utilise Agent Platform Memory Bank après le déploiement de l'agent dans Agent Runtime.

Lorsque vous développez votre agent ADK, vous pouvez inclure un PreloadMemoryTool qui contrôle le moment où l'agent récupère les mémoires et la manière dont elles sont incluses dans le prompt. L'exemple d'agent suivant récupère toujours les mémoires au début de chaque tour et les inclut dans l'instruction système :

from google.adk.agents import Agent
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from vertexai.agent_engines import AdkApp

agent = Agent(
    model="gemini-2.0-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=[PreloadMemoryTool()],
)

app = AdkApp(agent=agent)

Facultatif : personnaliser votre service de mémoire

Remarque : Si vous utilisez un service de mémoire en mémoire personnalisé, les mémoires peuvent ne pas rester synchronisées lorsque vous déployez l'agent dans Agent Runtime. Nous vous recommandons de personnaliser le service de mémoire uniquement si vous pouvez synchroniser les mémoires entre les instances dans un paramètre distribué lorsque l'agent est déployé.

Si vous souhaitez remplacer le service de mémoire par défaut, vous pouvez définir une memory_service_builder fonction qui renvoie un BaseMemoryService comme suit :

def memory_service_builder():
  from google.adk.memory import InMemoryMemoryService

  return InMemoryMemoryService()

Transmettez votre base de données à AdkApp en tant que memory_service_builder= :

from vertexai.agent_engines import AdkApp

app = AdkApp(
   agent=agent,                                    # Required.
   memory_service_builder=memory_service_builder,  # Optional.
)

Utiliser l'agent avec des mémoires

Testez votre agent ADK avec des mémoires :

1. Créez une session et interagissez avec l'agent :

   initial_session = await app.async_create_session(user_id="USER_ID")
   
   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="Can you update the temperature to my preferred temperature?",
   ):
       print(event)
   

   Comme il n'y a pas de mémoires disponibles lors de la première session et que l'agent ne connaît aucune préférence de l'utilisateur, il peut répondre par une réponse telle que "Quelle est votre température préférée ?". Vous pouvez répondre avec la commande suivante :

   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="I like it at 71 degrees",
   ):
       print(event)
   

   L'agent peut répondre par une réponse telle que "Réglage de la température à 22 degrés Celsius. Température modifiée." La réponse de l'agent peut varier en fonction du modèle que vous avez utilisé.

2. Générez des mémoires à partir de la session. Pour stocker des informations de la session en vue d'une utilisation ultérieure, utilisez la async_add_session_to_memory méthode :

   await app.async_add_session_to_memory(session=initial_session)
   

3. Vérifiez que l'agent a conservé la mémoire de la session (à l'aide de PreloadMemoryTool) en créant une session et en invitant l'agent :

   new_session = await app.async_create_session(user_id="USER_ID")
   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="Fix the temperature!",
   ):
       print(event)
   

   L'agent peut renvoyer une réponse telle que "Réglage de la température à 22 degrés. Est-ce correct ?". La réponse de l'agent peut varier en fonction du modèle et du fournisseur de services de mémoire que vous avez utilisés.

4. Utilisez la méthode async_search_memory pour afficher les mémoires de l'agent :

   response = await app.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   print(response)
   

Étape suivante

Guide

Déployer des agents

Découvrez les cinq façons de déployer un agent sur Agent Platform Runtime en fonction de vos besoins de développement.

Présentation

Présentation des sessions

Découvrez comment utiliser des sessions pour maintenir l'état de la conversation avec vos agents.

Présentation

Présentation de Memory Bank

Découvrez comment utiliser Memory Bank pour stocker les préférences et les faits des utilisateurs à long terme.

Guide

Utiliser un agent Agent Development Kit

Utilisez un agent Agent Development Kit (ADK) avec Agent Platform Runtime.

Guide

Évaluer vos agents

Créez et déployez un agent de base, puis utilisez le service d'évaluation Gen AI pour l'évaluer.

Dépannage

Résoudre les problèmes liés à la création d'agents

Découvrez comment résoudre les erreurs courantes lors de la création d'agents personnalisés.

Ressource

Obtenir de l'aide

Trouvez des ressources et de l'aide pour Google Agent Platform.