activities
latest
false
UiPath logo, featuring letters U and I in white

Integration Service Activities

Last updated Oct 29, 2025

Execute Google Vertex Agent

Description

Vertex AI Agents are autonomous software systems on Google Cloud's Vertex AI platform that use generative AI to understand, reason, plan, and complete tasks with users or other agents.

A core part of these agents is the Vertex AI Agent Engine, which provides a managed runtime for developing, deploying, and scaling agents in production.

This activity enables the use of agents deployed to the Agent Engine as participants in an automated process orchestrated by Maestro.

Creating the Vertex Agent

The ways in which you can deploy agents based on the Vertex AI Agent Engine are constantly evolving. Currently, this is a code-first configuration in Vertex AI. All frameworks supported by Agent Engine are supported by the Google Vertex connector. (e.g. google-adk). When a Vertex AI agent is successfully deployed, it is organized under a Google Cloud Project under Vertex AI > Agent Builder > Agent Engine. An agent that is ready for integration with UiPath must be visible with a resource name assigned under a URL such as this: 

projects/771273109380/locations/us-central1/reasoningEngines/7522902537708503040projects/771273109380/locations/us-central1/reasoningEngines/7522902537708503040
In this example, the project ID is 771273109380.

In most Maestro scenarios, you prompt the agent to generate output in the form of a JSON structure. e.g. {"sku1": "9735A45", "sku2": "1735A50"}.

How to use the activity

To use this activity in a Maestro agentic process, follow these steps:

  1. Add a service task element to the canvas and open the task's Properties panel.
  2. Name the service task Vertex Hello World.
  3. In the Implementation section, from the Action dropdown list, select Start and wait for external agent.
  4. Select the Google Vertex connector.
  5. Select an existing connection or create a new one. For more information, see Google Vertex authentication.

  6. From Activity, select Execute Google Vertex Agent.

  7. From Agent Name, select an agent that you previously created in Vertex AI (e.g. ORDERS_AGENT). Please note that using the wrong service account key will result in you getting a dropdown that includes unexpected agents or no agents at all.

  8. in the Message field, enter "What can you do?". Make sure to include the quotes in the prompt.
  9. In the User id field, enter user.

  10. Connect the start event to the service task, and the service task to an end event node on the canvas.

  11. Select Debug to run this process. After a successful run, review the Global variables and look for the {:} response from the source Vertex. Take note of the structure of the reply. For example, this is the agent's response to the prompt "What can you do?": 

    {
  "usage_metadata": {
    "candidates_token_count": 404,
    "thoughts_token_count": 46,
    "total_token_count": 1229,
    "prompt_tokens_details": [
      {
        "token_count": 779,
        "modality": "TEXT"
      }
    ],
    "traffic_type": "ON_DEMAND",
    "candidates_tokens_details": [
      {
        "token_count": 404,
        "modality": "TEXT"
      }
    ],
    "prompt_token_count": 779
  },
  "author": "loan_eligibility_agent",
  "invocation_id": "e-a496b1b8-fb54-4120-9aa2-7fac34e1d04d",
  "session_id": "3080378032481894400",
  "id": "26G1y9He",
  "content": {
    "parts": [
      {
        "text": "I am a loan eligibility evaluation agent. My primary function is to assess whether a loan applicant is eligible for approval based on a predefined set of criteria.\n\nHere's what I can do:\n\n1.  **Receive Loan Application Details:** I expect loan application details in a JSON format. If I don't receive it, I will prompt you to provide it.\n2.  **Evaluate Against Criteria:** I will evaluate each field in the provided JSON against specific eligibility criteria, which include:\n    *   Age (21-60)\n    *   Employment status and duration (employed, min 12 months)\n    *   Monthly net income (min $2,500 USD)\n    *   Credit Score (min 650)\n    *   Debt-to-Income Ratio (monthly obligations <= 40% of income)\n    *   Residency Status (legal resident/citizen)\n    *   Loan Purpose (specific allowed purposes, no disallowed ones)\n3.  **Determine Eligibility:** Based on the evaluation, I will determine one of three outcomes:\n    *   `eligible`: If all standard criteria are met.\n    *   `not eligible`: If one or more core criteria are failed, and no compelling justification is provided.\n    *   `manual review: other_criteria`: If one or more core criteria are failed, but an \"other_criteria\" explanation is provided that might justify an exception (e.g., medical hardship, protected populations, employment transition).\n4.  **Provide Justification:** For every determination, I will provide a detailed explanation outlining how the decision was reached, referencing the specific parameters from the eligibility criteria and the applicant's data.\n5.  **Output in JSON:** My final output will always be a JSON object containing the `determination` and `justification`.\n\nEssentially, I automate the initial screening process for personal loan applications according to established rules."
      }
    ],
    "role": "model"
  },
  "timestamp": 1758552780.125623
}{
  "usage_metadata": {
    "candidates_token_count": 404,
    "thoughts_token_count": 46,
    "total_token_count": 1229,
    "prompt_tokens_details": [
      {
        "token_count": 779,
        "modality": "TEXT"
      }
    ],
    "traffic_type": "ON_DEMAND",
    "candidates_tokens_details": [
      {
        "token_count": 404,
        "modality": "TEXT"
      }
    ],
    "prompt_token_count": 779
  },
  "author": "loan_eligibility_agent",
  "invocation_id": "e-a496b1b8-fb54-4120-9aa2-7fac34e1d04d",
  "session_id": "3080378032481894400",
  "id": "26G1y9He",
  "content": {
    "parts": [
      {
        "text": "I am a loan eligibility evaluation agent. My primary function is to assess whether a loan applicant is eligible for approval based on a predefined set of criteria.\n\nHere's what I can do:\n\n1.  **Receive Loan Application Details:** I expect loan application details in a JSON format. If I don't receive it, I will prompt you to provide it.\n2.  **Evaluate Against Criteria:** I will evaluate each field in the provided JSON against specific eligibility criteria, which include:\n    *   Age (21-60)\n    *   Employment status and duration (employed, min 12 months)\n    *   Monthly net income (min $2,500 USD)\n    *   Credit Score (min 650)\n    *   Debt-to-Income Ratio (monthly obligations <= 40% of income)\n    *   Residency Status (legal resident/citizen)\n    *   Loan Purpose (specific allowed purposes, no disallowed ones)\n3.  **Determine Eligibility:** Based on the evaluation, I will determine one of three outcomes:\n    *   `eligible`: If all standard criteria are met.\n    *   `not eligible`: If one or more core criteria are failed, and no compelling justification is provided.\n    *   `manual review: other_criteria`: If one or more core criteria are failed, but an \"other_criteria\" explanation is provided that might justify an exception (e.g., medical hardship, protected populations, employment transition).\n4.  **Provide Justification:** For every determination, I will provide a detailed explanation outlining how the decision was reached, referencing the specific parameters from the eligibility criteria and the applicant's data.\n5.  **Output in JSON:** My final output will always be a JSON object containing the `determination` and `justification`.\n\nEssentially, I automate the initial screening process for personal loan applications according to established rules."
      }
    ],
    "role": "model"
  },
  "timestamp": 1758552780.125623
}

The agent’s output must be assigned to a process variable so it can influence the progress of the Maestro process, for example to make a decision based on a boolean evaluation, or to use the answer from a classification task.

  1. In Design mode, select the agent from the design canvas.

  2. Select Properties.

  3. Under Output, select Add new and add a variable of type String named agent_reponse.

  4. For Value, select Vertex Hello World > response (object) > Content (object) > Content text (string).

Tip: In practice, specify the structured output of your choice from the agent, and then evaluate the output within Maestro using the Expression editor to extract the specific part of the output you need in the type necessary for your process flow.

Troubleshooting and Tuning

Beyond establishing connectivity, you should test prompts both in the Vertex workspace as well as from Maestro. This ensures you achieve the desired output that can best be consumed by Maestro, assigned to variables, and passed on to other actors in the process.

We recommend that detailed prompts remain within the system prompts of the agent within Vertex. The user prompt which is provided by Maestro to the agent at runtime should be brief and to the point. Its role is primarily to indicate the relevant variables needed by the agent to perform a specific tasks and generate an expected consistent output.

Output that is aimed at humans, for example the reasons for an escalation, can be easily passed as natural text for the human. Output that is expected for an API/robot action must be strictly composed. Here is an example user prompt that yields a specific output from an agent. Use the C# Expression editor within Studio to add variables as needed.
"What is the quantity on inventory of Order ID " + vars.orderId_1 + "respond only with a JSON object with the quantity in the key Order_Quantity. No explanations, only JSON""What is the quantity on inventory of Order ID " + vars.orderId_1 + "respond only with a JSON object with the quantity in the key Order_Quantity. No explanations, only JSON"

The agent will reply with:

{"Order_Quantity":"100"}{"Order_Quantity":"100"}
Pay special attention to types in your request to the agent and in the actual response. Even if the response looks like type JSON, it may actually be of type string.
  • Description
  • Creating the Vertex Agent
  • How to use the activity
  • Troubleshooting and Tuning

Was this page helpful?

Support and Services
Get The Help You Need
UiPath Academy
Learning RPA - Automation Courses
UiPath Forum
UiPath Community Forum
Uipath Logo
Trust and Security
Terms of Use
Privacy Policy
Cookies Policy
© 2005-2025 UiPath. All rights reserved.