Esta página foi traduzida pela API Cloud Translation.

Desenvolva um agente AG2

O AG2, uma ramificação orientada pela comunidade do AutoGen original, é uma framework de código aberto para criar agentes com tecnologia de IA. Esta página mostra como desenvolver um agente usando o modelo AG2 específico da framework (a classe AG2Agent no SDK Vertex AI para Python). O agente devolve a taxa de câmbio entre duas moedas numa data especificada. Siga estes passos:

Defina e configure um ficheiro executável
Defina e use uma ferramenta
(Opcional) Personalize a orquestração

Antes de começar

Certifique-se de que o seu ambiente está configurado seguindo os passos em Configure o seu ambiente.

Passo 1. Defina e configure um executável

Defina a versão do modelo a usar.

model = "gemini-2.0-flash"

Defina o nome executável a usar.

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-2.0-flash",
        "api_type":         "google",
    }]
}

Para saber mais sobre a configuração do modelo no AG2, consulte o artigo Análise detalhada da configuração do modelo.

(Opcional) Configure as definições de segurança do modelo. Segue-se um exemplo de como pode configurar as definiçõ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 as definições de segurança no Gemini, consulte o artigo Configure atributos de segurança.

Crie um AG2Agent com 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 estiver a executar num ambiente interativo (por exemplo, um terminal ou um bloco de notas do Colab), pode executar uma consulta como um passo de teste intermédio:

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 seguinte exemplo:

{'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-2.0-flash': {'cost': 5.2875e-06,
    'prompt_tokens': 34,
    'completion_tokens': 62,
    'total_tokens': 96}},
  'usage_excluding_cached_inference': {'total_cost': 5.2875e-06,
   'gemini-2.0-flash': {'cost': 5.2875e-06,
    'prompt_tokens': 34,
    'completion_tokens': 62,
    'total_tokens': 96}}},
 'human_input': []}

(Opcional) Personalização avançada

O modelo AG2Agent usa o api_type=="google" por predefinição, porque oferece acesso a todos os modelos fundamentais disponíveis no Google Cloud. Para usar um modelo que não esteja disponível através de api_type=="google", pode personalizar o parâmetro llm_config.

Para ver uma lista dos modelos suportados na AG2 e as respetivas capacidades, consulte o artigo Fornecedores de modelos. O conjunto de valores suportados para llm_config= é específico de cada modelo de chat, pelo que deve consultar a respetiva documentação para obter detalhes.

Gemini

Instalada por predefinição.

É usado em AG2Agent quando omite o argumento llm_config, por exemplo

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model=model,                # Required.
    runnable_name=runnable_name # Required.
)

Anthropic

Primeiro, siga a 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 em 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

Pode usar OpenAI em conjunto 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-2.0-flash",  # Required.
        "api_type": "openai",                    # Required.
        "base_url": base_url,                    # Required.
        "api_key": creds.token,                  # Required.
    }]
}

Por fim, use-o em AG2Agent com o seguinte código:

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model="google/gemini-2.0-flash",  # Or "meta/llama3-405b-instruct-maas".
    runnable_name=runnable_name,          # Required.
    llm_config=llm_config,                # Optional.
)

Passo 2. Defina e use uma ferramenta

Depois de definir o modelo, o passo seguinte é definir as ferramentas que o modelo usa para o raciocínio. Uma ferramenta pode ser uma ferramenta AG2 ou uma função Python.

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': '2024-02-22', 'rates': {'SEK': 10.3043}}

Para usar a ferramenta no 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.
)

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:

response = agent.query(input="What is the exchange rate from US dollars to Swedish currency?", max_turns=2)

A resposta é um dicionário semelhante ao seguinte:

{'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-2.0-flash': {'cost': 0.0002790625,
    'prompt_tokens': 757,
    'completion_tokens': 34,
    'total_tokens': 791}},
  'usage_excluding_cached_inference': {'total_cost': 0.0002790625,
   'gemini-2.0-flash': {'cost': 0.0002790625,
    'prompt_tokens': 757,
    'completion_tokens': 34,
    'total_tokens': 791}}},
 'human_input': []}

Passo 3. Personalize a orquestração

Todos os agentes AG2 implementam a interface ConversableAgent, que fornece esquemas de entrada e saída para a orquestração. O modelo AG2Agent requer a criação de um executável para responder a consultas. Por predefinição, o AG2Agent cria um ficheiro executável deste tipo associando o modelo a ferramentas.

Pode querer personalizar a orquestração se pretender: (i) Implementar um agente do Assistente que resolva uma tarefa com um modelo, ou (ii) implementar um agente proxy do utilizador que possa executar código e fornecer feedback aos outros agentes, ou (iii) implementar um agente de raciocínio que resolva uma tarefa com um modelo e um raciocínio de árvore de pensamento. Para tal, tem de substituir o executável predefinido ao criar AG2Agent especificando o argumento runnable_builder= com uma função Python da seguinte assinatura:


def runnable_builder(
    **runnable_kwargs,
):

Isto oferece diferentes opções para personalizar a lógica de orquestração.

Agente do Assistente

No caso mais simples, para criar um agente do assistente sem orquestração, pode 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 utilizador

No caso mais simples, para criar um agente proxy do utilizador sem orquestração, pode 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, pode 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,
)