Développer un agent du kit de développement d'agents

Cette page vous explique comment développer un agent à l'aide du modèle Agent Development Kit (la classe AdkApp du SDK Vertex AI pour Python). L'agent renvoie le taux de change entre deux devises à une date précise.

Procédez comme suit :

1. Définir et configurer un modèle
2. (Facultatif) Définir et utiliser un outil
3. (Facultatif) Gérer les sessions
4. (Facultatif) Gérer les souvenirs

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

Définissez la version du modèle :

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 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 (128 caractères maximum). 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éterminez 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 localement 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 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 localement en exécutant des requêtes de test. 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 correspond à 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 lorsqu'il s'exécute en local et des sessions gérées basées sur le cloud une fois que vous avez déployé l'agent sur Vertex AI Agent Engine. Cette section explique comment configurer votre agent ADK pour qu'il fonctionne avec les 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é, il est possible que les sessions ne restent pas synchronisées lorsque vous déployez l'agent sur Vertex AI Agent Engine. 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 fonction session_service_builder 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 AdkApp en local, les instructions suivantes utilisent des sessions en mémoire :

Créez une session pour votre agent :

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

La session est créée sous la forme d'une représentation de dictionnaire d'un objet de session ADK.

Listez les sessions associées à votre agent :

await app.async_list_sessions(user_id="USER_ID")

Obtenir une session spécifique :

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 correspond à l'ID de la session spécifique que vous souhaitez récupérer.

Interrogez AdkApp à l'aide de sessions :

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 en vous demandant des informations comme celles-ci :

{'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 souvenirs

Par défaut, AdkApp utilise une implémentation en mémoire de la mémoire agentique lors de l'exécution en local et utilise la banque de mémoire Vertex AI Agent Engine après le déploiement de l'agent sur Vertex AI Agent Engine.

Lorsque vous développez votre agent ADK, vous pouvez inclure un PreloadMemoryTool qui contrôle le moment où l'agent récupère les souvenirs et la façon dont ils sont inclus dans l'invite. L'exemple d'agent suivant récupère toujours les souvenirs au début de chaque tour et les inclut dans l'instruction système :

from google import adk
from vertexai.agent_engines import AdkApp

agent = adk.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=[adk.tools.preload_memory_tool.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é, il est possible que les souvenirs ne restent pas synchronisés lorsque vous déployez l'agent sur Vertex AI Agent Engine. 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 fonction memory_service_builder 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 souvenirs

Testez votre agent ADK avec des souvenirs :

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 souvenirs 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 phrase telle que "Quelle est votre température préférée ?". Vous pouvez répondre à l'aide de 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 renvoyer une réponse telle que "Réglage de la température sur 22 degrés Celsius. La température a bien été modifiée." La réponse de l'agent peut varier en fonction du modèle que vous avez utilisé.

2. Générez des souvenirs à partir de la session. Pour stocker des informations de la session afin de les utiliser dans de futures sessions, utilisez la méthode async_add_session_to_memory :

   await app.async_add_session_to_memory(session=initial_session)
   

3. Testez que l'agent a conservé la mémoire de la session (à l'aide de PreloadMemoryTool) en créant une session et en demandant à 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égler la température sur 22 degrés. Est-ce exact ?" 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 souvenirs de l'agent :

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

Étapes suivantes

• Présentation des sessions
• Présentation de la Banque de mémoire
• Utilisez un agent Agent Development Kit.
• Évaluez un agent.
• Déployez un agent.
• Résolvez les problèmes liés au développement d'un agent.
• Accédez à l'assistance.