AG2Agent no Agent Platform SDK, é possível criar agentes que realizam tarefas complexas e se integram a ferramentas externas.
Este documento explica como desenvolver um agente AG2, incluindo a definição do modelo, a adição de ferramentas e a personalização do fluxo de orquestração.
Para mais informações sobre como gerenciar os agentes implantados, consulte Gerenciar agentes implantados.
Para criar um agente AG2:
- Definir e configurar um executável
- Definir e usar uma ferramenta
- Opcional: Personalizar a orquestração
Antes de começar
Verifique se o ambiente está configurado seguindo as etapas em Configurar o ambiente.
Etapa 1. Definir e configurar um executável
Especifique o modelo que você quer usar:
model = "gemini-3.5-flash"
Defina o nome do executável a ser usado:
runnable_name = "Get Exchange Rate Agent"
Opcional: configure o modelo:
from google.cloud.aiplatform.aiplatform import initializer
llm_config = {
"config_list": [{
"project_id": initializer.global_config.project,
"location": initializer.global_config.location,
"model": "gemini-3.5-flash",
"api_type": "google",
}]
}
Para saber mais sobre como configurar o modelo no AG2, consulte Configuração do modelo Análise detalhada.
Opcional: defina as configurações de segurança do modelo. Confira a seguir um exemplo de como definir as configurações de segurança:
from vertexai.generative_models import HarmBlockThreshold, HarmCategory
safety_settings = {
HarmCategory.HARM_CATEGORY_HARASSMENT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
HarmCategory.HARM_CATEGORY_HATE_SPEECH: HarmBlockThreshold.BLOCK_ONLY_HIGH,
HarmCategory.HARM_CATEGORY_SEXUALLY_EXPLICIT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT: HarmBlockThreshold.BLOCK_ONLY_HIGH,
}
for config_item in llm_config["config_list"]:
config_item["safety_settings"] = safety_settings
Para saber mais sobre as opções disponíveis para configurações de segurança no Gemini, consulte Configurar atributos de segurança.
Crie um
AG2Agent
usando as configurações do modelo:
from vertexai import agent_engines
agent = agent_engines.AG2Agent(
model=model, # Required.
runnable_name=runnable_name, # Required.
llm_config=llm_config, # Optional.
)
Se você estiver executando em um ambiente interativo (como um terminal ou notebook do Colab), poderá executar uma consulta como uma etapa de teste intermediária:
response = agent.query(input="What is the exchange rate from US dollars to SEK today?", max_turns=1)
print(response)
A resposta é um dicionário Python semelhante ao exemplo a seguir:
{'chat_id': None,
'chat_history': [{'content': 'What is the exchange rate from US dollars to Swedish currency?',
'role': 'assistant',
'name': 'user'},
{'content': 'I do not have access to real-time information, including currency exchange rates. To get the most up-to-date exchange rate from US dollars to Swedish Krona (SEK), I recommend using a reliable online currency converter or checking with your bank. \n',
'role': 'user',
'name': 'Exchange Rate Agent'}],
'summary': 'I do not have access to real-time information, including currency exchange rates. To get the most up-to-date exchange rate from US dollars to Swedish Krona (SEK), I recommend using a reliable online currency converter or checking with your bank. \n',
'cost': {'usage_including_cached_inference': {'total_cost': 5.2875e-06,
'gemini-3.5-flash': {'cost': 5.2875e-06,
'prompt_tokens': 34,
'completion_tokens': 62,
'total_tokens': 96}},
'usage_excluding_cached_inference': {'total_cost': 5.2875e-06,
'gemini-3.5-flash': {'cost': 5.2875e-06,
'prompt_tokens': 34,
'completion_tokens': 62,
'total_tokens': 96}}},
'human_input': []}
Opcional: personalização avançada
O
AG2Agent
modelo usa api_type=="google" por padrão, porque fornece acesso a todos os
modelos básicos disponíveis em Google Cloud. Para usar um modelo não
disponibilizado por api_type=="google", personalize o llm_config
parâmetro.
Para conferir uma lista dos modelos compatíveis com o AG2 e os respectivos recursos, consulte
Provedores de modelos.
O conjunto de valores aceitos para llm_config= é específico para cada modelo de chat. Por isso, consulte a documentação correspondente para ver detalhes.
Gemini
Instalado por padrão.
Ele é usado no AG2Agent quando você omite o llm_config
argumento, por exemplo
from vertexai import agent_engines
agent = agent_engines.AG2Agent(
model=model, # Required.
runnable_name=runnable_name # Required.
)
Anthropic
Primeiro, siga a respectiva documentação para configurar uma conta e instalar o pacote.
Em seguida, defina um llm_config:
llm_config = {
"config_list": [{
"model": "claude-3-5-sonnet-20240620", # Required.
"api_key": "ANTHROPIC_API_KEY", # Required.
"api_type": "anthropic", # Required.
}]
}
Por fim, use-o no AG2Agent com o seguinte código:
from vertexai import agent_engines
agent = agent_engines.AG2Agent(
model="claude-3-5-sonnet-20240620", # Required.
runnable_name=runnable_name, # Required.
llm_config=llm_config, # Optional.
)
OpenAI
É possível usar OpenAI com a API ChatCompletions
do Gemini.
Primeiro, defina um llm_config:
import google.auth
from google.cloud.aiplatform.aiplatform import initializer
project = initializer.global_config.project
location = initializer.global_config.location
base_url = f"https://{location}-aiplatform.googleapis.com/v1beta1/projects/{project}/locations/{location}/endpoints/openapi"
# Note: the credential lives for 1 hour by default.
# After expiration, it must be refreshed.
creds, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
auth_req = google.auth.transport.requests.Request()
creds.refresh(auth_req)
llm_config = {
"config_list": [{
"model": "google/gemini-3.5-flash", # Required.
"api_type": "openai", # Required.
"base_url": base_url, # Required.
"api_key": creds.token, # Required.
}]
}
Por fim, use-o no AG2Agent com o seguinte código:
from vertexai import agent_engines
agent = agent_engines.AG2Agent(
model="google/gemini-3.5-flash", # Or "meta/llama3-405b-instruct-maas".
runnable_name=runnable_name, # Required.
llm_config=llm_config, # Optional.
)
Etapa 2. Definir e usar uma ferramenta
Depois de definir o modelo, a próxima etapa é definir as ferramentas que o modelo usa para raciocínio. Ela pode ser uma ferramenta AG2 ou uma função Python.
Ao definir a função, é importante incluir comentários que descrevam completa e claramente os parâmetros da função, o que ela faz e o que ela retorna. Essas informações são usadas pelo modelo para determinar qual função usar. Você também precisa testar a função localmente para confirmar se ela funciona.
Use o código a seguir para definir uma função que retorna 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 usá-la no agente, execute o seguinte:
get_exchange_rate(currency_from="USD", currency_to="SEK")
A resposta será semelhante a esta:
{'amount': 1.0, 'base': 'USD', 'date': '2024-02-22', 'rates': {'SEK': 10.3043}}
Para usar a ferramenta dentro do AG2Agent, adicione-a à lista de ferramentas no argumento tools=:
from vertexai import agent_engines
agent = agent_engines.AG2Agent(
model=model, # Required.
runnable_name=runnable_name, # Required.
tools=[get_exchange_rate], # Optional.
)
Você pode testar o agente localmente executando consultas de teste nele. Execute o comando a seguir para testar o agente localmente usando dólares americanos e coroas suecas:
response = agent.query(input="What is the exchange rate from US dollars to Swedish currency?", max_turns=2)
A resposta é um dicionário semelhante a este:
{'chat_id': None,
'chat_history': [{'content': 'What is the exchange rate from US dollars to Swedish currency?',
'role': 'assistant',
'name': 'user'},
{'content': '',
'tool_calls': [{'id': '2285',
'function': {'arguments': '{"currency_from": "USD", "currency_to": "SEK"}',
'name': 'get_exchange_rate'},
'type': 'function'}],
'role': 'assistant'},
{'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}",
'tool_responses': [{'tool_call_id': '2285',
'role': 'tool',
'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}"}],
'role': 'tool',
'name': 'user'},
{'content': 'The current exchange rate is 1 USD to 10.6509 SEK. \n',
'role': 'user',
'name': 'Get Exchange Rate Agent'},
{'content': 'What is the exchange rate from US dollars to Swedish currency?',
'role': 'assistant',
'name': 'user'},
{'content': '',
'tool_calls': [{'id': '4270',
'function': {'arguments': '{"currency_from": "USD", "currency_to": "SEK"}',
'name': 'get_exchange_rate'},
'type': 'function'}],
'role': 'assistant'},
{'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}",
'tool_responses': [{'tool_call_id': '4270',
'role': 'tool',
'content': "{'amount': 1.0, 'base': 'USD', 'date': '2025-02-27', 'rates': {'SEK': 10.6509}}"}],
'role': 'tool',
'name': 'user'},
{'content': 'The current exchange rate is 1 USD to 10.6509 SEK. \n',
'role': 'user',
'name': 'Get Exchange Rate Agent'}],
'summary': 'The current exchange rate is 1 USD to 10.6509 SEK. \n',
'cost': {'usage_including_cached_inference': {'total_cost': 0.0002790625,
'gemini-3.5-flash': {'cost': 0.0002790625,
'prompt_tokens': 757,
'completion_tokens': 34,
'total_tokens': 791}},
'usage_excluding_cached_inference': {'total_cost': 0.0002790625,
'gemini-3.5-flash': {'cost': 0.0002790625,
'prompt_tokens': 757,
'completion_tokens': 34,
'total_tokens': 791}}},
'human_input': []}
Etapa 3. Personalizar a orquestração
Todos os agentes AG2 implementam a interface ConversableAgent,
que fornece esquemas de entrada e saída para orquestração. O
AG2Agent
modelo precisa que um executável seja criado para responder a consultas. Por
padrão,
AG2Agent
cria um executável vinculando o modelo a
ferramentas.
Convém personalizar a orquestração se você pretende (i) implementar um
agente assistente
que resolve uma tarefa com o modelo, (ii) implementar um agente proxy do usuário
que pode executar código e fornecer feedback aos outros agentes ou (iii)
implementar um agente de raciocínio que
resolve uma tarefa com o modelo e o raciocínio da árvore de pensamento. Para fazer isso, você tem que
substituir o executável padrão ao criar
AG2Agent
especificando o argumento runnable_builder= com uma função Python da
seguinte assinatura:
def runnable_builder(
**runnable_kwargs,
):
Isso oferece diferentes opções para personalizar a lógica de orquestração.
Agente assistente
No caso mais simples, para criar um agente assistente sem orquestração,
é possível substituir o runnable_builder por AG2Agent.
from vertexai import agent_engines
def runnable_builder(**kwargs):
from autogen import agentchat
return agentchat.AssistantAgent(**kwargs)
agent = agent_engines.AG2Agent(
model=model,
runnable_name=runnable_name,
runnable_builder=runnable_builder,
)
Agente proxy do usuário
No caso mais simples, para criar um agente proxy do usuário sem orquestração,
é possível substituir o runnable_builder por AG2Agent.
from vertexai import agent_engines
def runnable_builder(**kwargs):
from autogen import agentchat
return agentchat.UserProxyAgent(**kwargs)
agent = agent_engines.AG2Agent(
model=model,
runnable_name=runnable_name,
runnable_builder=runnable_builder,
)
Agente de raciocínio
No caso mais simples, para criar um agente de raciocínio sem orquestração,
é possível substituir o runnable_builder por AG2Agent.
from vertexai import agent_engines
def runnable_builder(**kwargs):
from autogen import agentchat
return agentchat.ReasoningAgent(**kwargs)
agent = agent_engines.AG2Agent(
model=model,
runnable_name=runnable_name,
runnable_builder=runnable_builder,
)
A seguir
Implantar agentes
Aprenda as cinco maneiras de implantar um agente no Agent Platform Runtime com base nas suas necessidades de desenvolvimento.
Avaliar seus agentes
Crie e implante um agente básico e use o serviço de avaliação de IA generativa para avaliar o agente.
Resolver problemas de criação de agentes
Aprenda a resolver erros comuns ao criar agentes personalizados.