Manage deployed agents

This page describes how to manage agents that have been deploy to the Vertex AI Agent Engine managed runtime. Deployed agents are resources of type reasoningEngine in Vertex AI.

List deployed agents

List all deployed agents for a given project and location:

Console

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

1. In the Google Cloud console, go to the Vertex AI Agent Engine page.
   

   Go to Agent Engine

Deployed agents that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.

Vertex AI SDK for Python

Note: See the Agent Engine migration guide for instructions to migrate to the client-based Vertex AI SDK for Python if you are still on a version of google-cloud-aiplatform before 1.112.0.

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

for agent in client.agent_engines.list():
    print(agent)

To filter the list of by display_name:

for agent in client.agent_engines.list(
    config={
        "filter": 'display_name="DISPLAY_NAME"',
    },
):
    print(agent)

REST

Call the reasoningEngines.list method.

Before using any of the request data, make the following replacements:

• PROJECT_ID: your GCP project ID
• LOCATION: a supported region

HTTP method and URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.

Get a deployed agent

Each deployed agent has a unique RESOURCE_ID identifier. To learn more, see Deploy an agent.

Console

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

1. In the Google Cloud console, go to the Vertex AI Agent Engine page.
   

   Go to Agent Engine

   Deployed agents that are part of the selected project appear in the list. You can use the Filter field to filter the list by your specified column.

2. Click the name of the specified agent. The Metrics page for the agent opens.

3. (Optional) To view deployment details for the agent, click Deployment details. The Deployment details pane opens. To close the pane, click Done.

4. (Optional) To view the query and streamQuery URLs for the agent, click API URLs. The API URLs pane opens. To close the pane, click Done.

Vertex AI SDK for Python

Note: See the Agent Engine migration guide for instructions to migrate to the client-based Vertex AI SDK for Python if you are still on a version of google-cloud-aiplatform before 1.112.0.

The following code lets you get a specific deployed agent:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

remote_agent = client.agent_engines.get(
    name="projects/PROJECT_ID_OR_NUMBER/locations/LOCATION/reasoningEngines/RESOURCE_ID"
)

REST

Call the reasoningEngines.get method.

Before using any of the request data, make the following replacements:

• PROJECT_ID: your GCP project ID
• LOCATION: a supported region
• RESOURCE_ID: the resource ID of the deployed agent

HTTP method and URL:

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.

Update a deployed agent

You can update one or more fields of the deployed agent at the same time, but you have to specify at least one of the fields to be updated. The amount of time it takes to update the deployed agent depends on the update being performed, but it generally takes between a few seconds to a few minutes.

Console

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

1. In the Google Cloud console, go to the Vertex AI Agent Engine page.
   

   Go to Agent Engine

2. For your specified agent, click more actions menu ().

3. Click Edit. The Edit pane for the agent opens.

4. Edit the Display name or Description for the agent.

5. Click Save.

Vertex AI SDK for Python

Note: See the Agent Engine migration guide for instructions to migrate to the client-based Vertex AI SDK for Python if you are still on a version of google-cloud-aiplatform before 1.112.0.

To update a deployed agent (corresponding to RESOURCE_NAME) to an updated agent (corresponding to UPDATED_AGENT):

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

client.agent_engines.update(
    name=RESOURCE_NAME,                    # Required.
    agent=UPDATED_AGENT,                   # Optional.
    config={                                                # Optional.
        "requirements": REQUIREMENTS,      # Optional.
        "display_name": "DISPLAY_NAME",    # Optional.
        "description": "DESCRIPTION",      # Optional.
        "extra_packages": EXTRA_PACKAGES,  # Optional.
    },
)

The arguments are the same as when you are deploying an agent.

REST

Call the reasoningEngines.patch method and provide an update_mask to specify which fields to update.

Before using any of the request data, make the following replacements:

• PROJECT_ID: your GCP project ID
• LOCATION: a supported region
• RESOURCE_ID: the resource ID of the deployed agent
• update_mask: a list of comma-separated fields to update

HTTP method and URL:

PATCH https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"

Request JSON body:

{
"displayName": "DISPLAY_NAME",
"description": "DESCRIPTION"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description""

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID?update_mask="display_name,description"" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.

Delete a deployed agent

Delete a deployed agent from the Vertex AI Agent Engine managed runtime.

Console

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

1. In the Google Cloud console, go to the Vertex AI Agent Engine page.
   

   Go to Agent Engine

2. For your specified agent, click more actions menu ().

3. Click Delete.

4. Click Delete agent.

Vertex AI SDK for Python

Note: See the Agent Engine migration guide for instructions to migrate to the client-based Vertex AI SDK for Python if you are still on a version of google-cloud-aiplatform before 1.112.0.

If you already have an existing instance of the deployed agent (as remote_agent), you can run the following command:

remote_agent.delete(
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

Alternatively, you can call agent_engines.delete() to delete the deployed agent corresponding to RESOURCE_NAME in the following way:

import vertexai

client = vertexai.Client(  # For service interactions via client.agent_engines
    project="PROJECT_ID",
    location="LOCATION",
)

client.agent_engines.delete(
    name=RESOURCE_NAME,
    force=True, # Optional, if the agent has resources (e.g. sessions, memory)
)

REST

Call the reasoningEngines.delete method.

Before using any of the request data, make the following replacements:

• PROJECT_ID: your GCP project ID
• LOCATION: a supported region
• RESOURCE_ID: the resource ID of the deployed agent

HTTP method and URL:

DELETE https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID" | Select-Object -Expand Content

You should receive a successful status code (2xx) and an empty response.

What's next

• Use an agent.
• Troubleshoot managing deployed agents.