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:

  import 
  
  vertexai 
 
 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:

  from 
  
 google 
  
 import 
 auth 
 as 
 google_auth 
 from 
  
 google.auth.transport 
  
 import 
 requests 
 as 
 google_requests 
 import 
  
 requests 
 def 
  
 get_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 
 $( 
gcloud  
auth  
print-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):

  from 
  
 autogen 
  
 import 
 ConversableAgent 
 import 
  
 dataclasses 
 import 
  
 json 
 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.