AG2Agent in Agent Platform SDK, puoi creare agenti che eseguono attività complesse e si integrano con strumenti esterni.
Questo documento spiega come sviluppare un agente AG2, inclusa la definizione del modello, l'aggiunta di strumenti e la personalizzazione del flusso di orchestrazione.
Per ulteriori informazioni sulla gestione degli agenti di cui hai eseguito il deployment, vedi Gestire gli agenti di cui hai eseguito il deployment.
Per creare un agente AG2:
- Definisci e configura un eseguibile
- Definisci e utilizza 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
Specifica il modello che vuoi 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, vedi Configurazione del modello Analisi approfondita.
(Facoltativo) Configura le impostazioni di sicurezza del modello. Di seguito è riportato un esempio di come configurare le impostazioni di 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'applicazione in un ambiente interattivo (ad esempio un terminale o un notebook di 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 llm_config
parametro.
Per un elenco dei modelli supportati in AG2 e delle relative funzionalità, vedi
Fornitori di modelli.
L'insieme di valori supportati per llm_config= è specifico per ogni modello di chat, pertanto per i dettagli devi consultare la documentazione corrispondente.
Gemini
Installato per impostazione predefinita.
Viene utilizzato in AG2Agent quando ometti l'llm_config
argomento, ad esempio
from vertexai import agent_engines
agent = agent_engines.AG2Agent(
model=model, # Required.
runnable_name=runnable_name # Required.
)
Anthropic
Innanzitutto, segui la loro 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 utilizzati dal modello 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 seguente comando:
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, devi aggiungerlo 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: Personalizza l'orchestrazione
Tutti gli agenti AG2 implementano l'interfaccia ConversableAgent,
che fornisce schemi di input e output per l'orchestrazione. Il
AG2Agent
modello richiede la creazione di un eseguibile per rispondere alle query. Per
impostazione
AG2Agent
creerà un eseguibile di questo tipo associando il modello agli
strumenti.
Potresti voler personalizzare l'orchestrazione se intendi (i) implementare un
Assistente
Agente
che risolve un'attività con il modello, o (ii) implementare un Proxy Utente
Agente
che può eseguire codice e fornire feedback agli altri agenti, o (iii)
implementare un Ragionamento
Agente che
risolve un'attività con il modello e il ragionamento ad albero di pensiero. Per farlo, devi
sostituire l'eseguibile predefinito quando crei
AG2Agent
specificando l'argomento runnable_builder= con una funzione Python con la
seguente firma:
def runnable_builder(
**runnable_kwargs,
):
In questo modo hai a disposizione diverse opzioni per personalizzare la logica di orchestrazione.
Agente assistente
Nel caso più semplice, per creare un agente assistente senza orchestrazione,
puoi sostituire 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,
)
Agente proxy utente
Nel caso più semplice, per creare un agente proxy utente senza orchestrazione,
puoi sostituire 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,
puoi sostituire il 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,
)
Passaggi successivi
Eseguire il deployment degli agenti
Scopri i cinque modi per eseguire il deployment di un agente su Agent Platform Runtime in base alle tue esigenze di sviluppo.
Valutare gli agenti
Crea ed esegui il deployment di un agente di base e utilizza Gen AI evaluation service per valutare l'agente
Risolvere i problemi relativi alla creazione di agenti
Scopri come risolvere gli errori comuni durante la creazione di agenti personalizzati.