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:

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

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.

What's next