Use an AG2 agent

In addition to the general instructions for using an agent, this page describes features that are specific to AG2Agent.

Before you begin

This tutorial assumes that you have read and followed the instructions in:

Develop an AG2 agent: to develop agent as an instance of AG2Agent.
User authentication to authenticate as a user for querying the agent.
Import and initialize the SDK to initialize the client for getting a deployed instance (if needed).

Get an instance of an agent

To query a AG2Agent, you need to first create a new instance or get an existing instance.

To get the AG2Agent corresponding to a specific resource ID:

Vertex AI SDK for Python

Run the following code:

importvertexai
client = vertexai .Client( # For service interactions via client.agent_engines
 project="PROJECT_ID",
 location="LOCATION",
)
agent = client.agent_engines .get(name="projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID")
print(agent)

where

PROJECT_ID is the Google Cloud project ID under which you develop and deploy agents, and
LOCATION is one of the supported regions.
RESOURCE_ID is the ID of the deployed agent as a reasoningEngine resource.

Python requests library

Run the following code:

fromgoogleimport auth as google_auth
fromgoogle.auth.transportimport requests as google_requests
importrequests
defget_identity_token():
 credentials, _ = google_auth.default()
 auth_request = google_requests.Request()
 credentials.refresh(auth_request)
 return credentials.token
response = requests.get(
f"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID",
 headers={
 "Content-Type": "application/json; charset=utf-8",
 "Authorization": f"Bearer {get_identity_token()}",
 },
)

REST API

curl\
-H"Authorization: Bearer $(gcloudauthprint-access-token)"\
-H"Content-Type: application/json"\
https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

When using the Vertex AI SDK for Python, the agent object corresponds to an AgentEngine class that contains the following:

an agent.api_resource with information about the deployed agent. You can also call agent.operation_schemas() to return the list of operations that the agent supports. See Supported operations for details.
an agent.api_client that allows for synchronous service interactions
an agent.async_api_client that allows for asynchronous service interactions

The rest of this section assumes that you have an AgentEngine instance, named as agent.

Supported operations

The following operations are supported for AG2Agent:

query: for getting a response to a query synchronously.

The query method support the arguments:

input: the message to be sent to the agent.
max_turns: the maximum number of conversation turns allowed. When using tools, a minimum of max_turns=2 is required: one turn to generate tool arguments and a second to execute the tool.

Query the agent

The query() method provides a simplified way to interact with the agent. A typical call looks like this:

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

This method handles the underlying communication with the agent and returns the agent's final response as a dictionary. It is equivalent to the following (in full form):

fromautogenimport ConversableAgent
importdataclasses
importjson
input_message: str = "What is the exchange rate from US dollars to Swedish currency?"
max_turns: int = 2
with agent._runnable._create_or_get_executor(
 tools=agent._ag2_tool_objects, # Use the agent's existing tools
 agent_name="user", # Default
 agent_human_input_mode="NEVER", # query() enforces this
) as executor:
 chat_result = executor.initiate_chat(
 agent._runnable,
 message=input_message,
 max_turns=max_turns,
 clear_history=False, # Default
 summary_method="last_msg" # Default
 )
response = json.loads(
 json.dumps(dataclasses.asdict(chat_result)) # query() does this conversion
)

You can customize the agent's behavior beyond input and max_turns by passing additional keyword arguments to query().

response = agent.query(
 input="What is the exchange rate from US dollars to Swedish currency?",
 max_turns=2,
 msg_to="user" # Start the conversation with the "user" agent
)
print(response)

See the ConversableAgent.run documentation for a complete list of available parameters. However, keep in mind that user_input will always be overridden to False by the AG2Agent template.

Use an AG2 agent Stay organized with collections Save and categorize content based on your preferences.