Esta página mostra como desenvolver um agente usando o modelo do Agent Development Kit (a classe AdkApp no SDK Vertex AI para Python). O agente devolve a taxa de câmbio entre duas moedas numa data especificada.
Siga os passos seguintes:
- Defina e configure um modelo
- (Opcional) Defina e use uma ferramenta
- (Opcional) Faça a gestão de sessões
- (Opcional) Gerir memórias
Antes de começar
Certifique-se de que o seu ambiente está configurado seguindo os passos em Configure o seu ambiente.
Defina e configure um modelo
Defina a versão do modelo:
model = "gemini-2.0-flash"
(Opcional) Configure as definições de segurança do modelo. Para saber mais acerca das opções disponíveis para as definições de segurança no Gemini, consulte o artigo Configure atributos de segurança. Segue-se um exemplo de como pode configurar as definições de segurança:
from google.genai import types
safety_settings = [
types.SafetySetting(
category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
threshold=types.HarmBlockThreshold.OFF,
),
]
(Opcional) Especifique os parâmetros de geração de conteúdo:
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,
)
Crie um AdkApp com as configurações do modelo:
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)
Se estiver a executar num ambiente interativo, como o terminal ou um bloco de notas do Colab, pode executar uma consulta como um passo de teste intermédio:
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: escolha o seu próprio ID do utilizador com um limite de 128 carateres.
Por exemplo,
user-123.
A resposta é um dicionário Python semelhante ao seguinte exemplo:
{'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}
(Opcional) Defina e use uma ferramenta
Depois de definir o modelo, defina as ferramentas que o modelo usa para o raciocínio.
Quando define a sua função, é importante incluir comentários que descrevam de forma completa e clara os parâmetros da função, o que a função faz e o que a função devolve. Estas informações são usadas pelo modelo para determinar que função usar. Também tem de testar a função localmente para confirmar que funciona.
Use o seguinte código para definir uma função que devolve uma taxa de câmbio:
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()
Para testar a função antes de a usar no seu agente, execute o seguinte:
get_exchange_rate(currency_from="USD", currency_to="SEK")
A resposta deve ser semelhante à seguinte:
{'amount': 1.0, 'base': 'USD', 'date': '2025-04-03', 'rates': {'SEK': 9.6607}}
Para usar a ferramenta no AdkApp, adicione-a à lista de ferramentas no argumento tools=:
from google.adk.agents import Agent
agent = Agent(
model=model, # Required.
name='currency_exchange_agent', # Required.
tools=[get_exchange_rate], # Optional.
)
Pode testar o agente localmente executando consultas de teste em relação ao mesmo. Execute o comando seguinte para testar o agente localmente com dólares americanos e coroas suecas:
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)
em que USER_ID é o ID do utilizador que definiu. Por exemplo,
user-123.
A resposta é uma sequência de dicionários semelhante à seguinte:
{'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',
# ...
}
(Opcional) Faça a gestão de sessões
O AdkApp usa sessões na memória quando é executado localmente e usa sessões geridas baseadas na nuvem depois de implementar o agente no Vertex AI Agent Engine. Esta secção descreve como configurar o agente do ADK para funcionar com sessões geridas.
(Opcional) Personalize a base de dados de sessões
Se quiser substituir o serviço de sessão gerido predefinido pela sua própria base de dados, pode definir uma função session_service_builder da seguinte forma:
def session_service_builder():
from google.adk.sessions import InMemorySessionService
return InMemorySessionService()
Transmita a sua base de dados para AdkApp como session_service_builder=:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
session_service_builder=session_service_builder, # Optional.
)
Use o agente com sessões
Quando executa o comando AdkApp localmente, as seguintes instruções usam sessões na memória:
Crie uma sessão para o seu agente:
session = await app.async_create_session(user_id="USER_ID")
print(session)
A sessão é criada como a representação de dicionário de um objeto de sessão ADK.
Listar sessões associadas ao seu agente:
await app.async_list_sessions(user_id="USER_ID")
Obter uma sessão específica:
session = await app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")
onde
USER_ID é o ID do utilizador que definiu. Por exemplo,
user-123.SESSION_ID é o ID da sessão específica que quer obter.
Consulte o AdkApp através de sessões:
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)
O agente pode responder com um pedido de informações como as seguintes:
{'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',
#...
}
Pode enviar uma resposta (por exemplo, "SEK") em nome de
USER_ID na sessão correspondente a session
especificando:
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)
Deve receber uma continuação da conversa, como a seguinte sequência de dicionários:
{'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',
# ...
}
(Opcional) Faça a gestão das memórias
Por predefinição, a AdkApp usa uma implementação na memória da memória do agente quando é executada localmente e usa o Vertex AI Agent Engine Memory Bank depois de implementar o agente no Vertex AI Agent Engine.
Quando desenvolve o seu agente ADK, pode incluir um PreloadMemoryTool que controla quando o agente obtém memórias e como as memórias são incluídas no comando. O seguinte exemplo de agente obtém sempre memórias no início de cada interação
e inclui as memórias na instrução do sistema:
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)
(Opcional) Personalize o serviço de memória
Se quiser substituir o serviço de memória predefinido, pode definir uma função memory_service_builder que devolva um BaseMemoryService da seguinte forma:
def memory_service_builder():
from google.adk.memory import InMemoryMemoryService
return InMemoryMemoryService()
Transmita a sua base de dados para AdkApp como memory_service_builder=:
from vertexai.agent_engines import AdkApp
app = AdkApp(
agent=agent, # Required.
memory_service_builder=memory_service_builder, # Optional.
)
Use o agente com memórias
Teste o seu agente ADK com memórias:
Crie uma sessão e interaja com o agente:
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)Uma vez que não existem memórias disponíveis durante a primeira sessão e o agente não conhece as preferências do utilizador, o agente pode responder com uma resposta como "Qual é a sua temperatura preferida?" Pode responder com o seguinte comando:
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)O agente pode responder com algo como "A definir a temperatura para 22 graus Celsius. A temperatura foi alterada com êxito." A resposta do agente pode variar consoante o modelo que usou.
Gerar memórias a partir da sessão. Para armazenar informações da sessão para utilização em sessões futuras, use o método
async_add_session_to_memory:await app.async_add_session_to_memory(session=initial_session)Teste se o agente manteve a memória da sessão (usando
PreloadMemoryTool) criando uma nova sessão e pedindo ao agente: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)O agente pode devolver uma resposta como "a definir a temperatura para 22 graus. Está correto?" A resposta do agente pode variar consoante o modelo e o fornecedor de serviços de memória que usou.
Use o método
async_search_memorypara apresentar as memórias do agente:response = await app.async_search_memory( user_id="USER_ID", query="Fix the temperature!", ) print(response)
O que se segue?
- Vista geral das sessões
- Vista geral do banco de memórias
- Use um agente do Agent Development Kit.
- Avalie um agente.
- Implemente um agente.
- Resolva problemas de desenvolvimento de um agente.
- Receba apoio técnico.