Questa pagina è stata tradotta dall'API Cloud Translation.

Sviluppare un agente AG2

AG2, un fork basato sulla community dell'originale AutoGen, è un framework open source per la creazione di agenti basati sull'AI. Questa pagina mostra come sviluppare un agente utilizzando il modello AG2 specifico del framework (la classe AG2Agent nell'SDK Vertex AI per Python). L'agente restituisce il tasso di cambio tra due valute in una data specificata. Procedi nel seguente modo:

Definisci e configura un eseguibile
Definire e utilizzare uno strumento
(Facoltativo) Personalizza l'orchestrazione

Prima di iniziare

Assicurati che l'ambiente sia configurato seguendo i passaggi descritti in Configurare l'ambiente.

Passaggio 1: Definisci e configura un eseguibile

Definisci la versione del modello da utilizzare.

model = "gemini-2.0-flash"

Definisci il nome dell'eseguibile da utilizzare.

runnable_name = "Get Exchange Rate Agent"

(Facoltativo) Configura il modello.

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",
    }]
}

Per scoprire di più sulla configurazione del modello in AG2, consulta Analisi approfondita della configurazione del modello.

(Facoltativo) Configura le impostazioni di sicurezza del modello. Di seguito è riportato un esempio di come puoi configurare le impostazioni della sicurezza:

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

Per scoprire di più sulle opzioni disponibili per le impostazioni di sicurezza in Gemini, vedi Configurare gli attributi di sicurezza.

Crea un AG2Agent utilizzando le configurazioni del modello:

from vertexai import agent_engines

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

Se esegui l'operazione in un ambiente interattivo (ad es. un terminale o un notebook Colab), puoi eseguire una query come passaggio di test intermedio:

response = agent.query(input="What is the exchange rate from US dollars to SEK today?", max_turns=1)

print(response)

La risposta è un dizionario Python simile al seguente esempio:

{'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': []}

(Facoltativo) Personalizzazione avanzata

Il modello AG2Agent utilizza api_type=="google" per impostazione predefinita, perché fornisce l'accesso a tutti i modelli di base disponibili in Google Cloud. Per utilizzare un modello non disponibile tramite api_type=="google", puoi personalizzare il parametro llm_config.

Per un elenco dei modelli supportati in AG2 e delle relative funzionalità, consulta Provider di modelli. L'insieme di valori supportati per llm_config= è specifico per ogni modello di chat, quindi devi consultare la documentazione corrispondente per i dettagli.

Gemini

Installato per impostazione predefinita.

Viene utilizzato in AG2Agent quando ometti l'argomento llm_config, ad esempio

from vertexai import agent_engines

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

Anthropic

Innanzitutto, segui la documentazione per configurare un account e installare il pacchetto.

Poi, definisci un llm_config:

llm_config = {
    "config_list": [{
        "model": "claude-3-5-sonnet-20240620",            # Required.
        "api_key": "ANTHROPIC_API_KEY",  # Required.
        "api_type": "anthropic",                          # Required.
     }]
}

Infine, utilizzalo in AG2Agent con il seguente codice:

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

Puoi utilizzare OpenAI insieme all'API ChatCompletions di Gemini.

Innanzitutto, definisci un 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.
    }]
}

Infine, utilizzalo in AG2Agent con il seguente codice:

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.
)

Passaggio 2: Definisci e utilizza uno strumento

Dopo aver definito il modello, il passaggio successivo consiste nel definire gli strumenti che il modello utilizza per il ragionamento. Uno strumento può essere uno strumento AG2 o una funzione Python.

Quando definisci la funzione, è importante includere commenti che descrivano in modo completo e chiaro i parametri della funzione, cosa fa la funzione e cosa restituisce. Queste informazioni vengono utilizzate dal modello per determinare quale funzione utilizzare. Devi anche testare la funzione localmente per verificare che funzioni.

Utilizza il seguente codice per definire una funzione che restituisce un tasso di cambio:

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()

Per testare la funzione prima di utilizzarla nell'agente, esegui il comando seguente:

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

La risposta dovrebbe essere simile alla seguente:

{'amount': 1.0, 'base': 'USD', 'date': '2024-02-22', 'rates': {'SEK': 10.3043}}

Per utilizzare lo strumento all'interno di AG2Agent, aggiungilo all'elenco degli strumenti nell'argomento tools=:

from vertexai import agent_engines

agent = agent_engines.AG2Agent(
    model=model,                 # Required.
    runnable_name=runnable_name, # Required.
    tools=[get_exchange_rate],   # Optional.
)

Puoi testare l'agente localmente eseguendo query di test. Esegui il seguente comando per testare l'agente localmente utilizzando dollari statunitensi e corone svedesi:

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

La risposta è un dizionario simile al seguente:

{'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': []}

Passaggio 3: Personalizzare l'orchestrazione

Tutti gli agenti AG2 implementano l'interfaccia ConversableAgent, che fornisce schemi di input e output per l'orchestrazione. Il modello AG2Agent richiede la creazione di un eseguibile per rispondere alle query. Per impostazione predefinita, AG2Agent creerà un eseguibile di questo tipo associando il modello agli strumenti.

Potresti voler personalizzare l'orchestrazione se intendi (i) implementare un agente assistente che risolve un'attività con il modello, (ii) implementare un agente proxy utente che può eseguire codice e fornire feedback agli altri agenti, (iii) implementare un agente di ragionamento che risolve un'attività con il modello e il ragionamento ad albero del pensiero. Per farlo, devi eseguire l'override dell'eseguibile predefinito quando crei AG2Agent specificando l'argomento runnable_builder= con una funzione Python della seguente firma:


def runnable_builder(
    **runnable_kwargs,
):

In questo modo, hai diverse opzioni per personalizzare la logica di orchestrazione.

Agente assistente

Nel caso più semplice, per creare un agente assistente senza orchestrazione, puoi eseguire l'override di runnable_builder per 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,
)

User Proxy Agent

Nel caso più semplice, per creare un agente proxy utente senza orchestrazione, puoi eseguire l'override di runnable_builder per 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 di ragionamento

Nel caso più semplice, per creare un agente di ragionamento senza orchestrazione, <0A>puoi eseguire l'override di runnable_builder per 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,
)