REST Resource: projects.locations.apps.agents

Resource: Agent

An agent acts as the fundamental building block that provides instructions to the Large Language Model (LLM) for executing specific tasks.

JSON representation 
{
  "name": string,
  "displayName": string,
  "description": string,
  "modelSettings": {
    object (ModelSettings)
  },
  "instruction": string,
  "tools": [
    string
  ],
  "childAgents": [
    string
  ],
  "beforeAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterAgentCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterModelCallbacks": [
    {
      object (Callback)
    }
  ],
  "beforeToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "afterToolCallbacks": [
    {
      object (Callback)
    }
  ],
  "createTime": string,
  "updateTime": string,
  "guardrails": [
    string
  ],
  "etag": string,
  "toolsets": [
    {
      object (Agent.AgentToolset)
    }
  ],
  "generatedSummary": string,
  "transferRules": [
    {
      object (TransferRule)
    }
  ],

  // Union field agent_type can be only one of the following:
  "llmAgent": {
    object (Agent.LlmAgent)
  },
  "remoteDialogflowAgent": {
    object (Agent.RemoteDialogflowAgent)
  }
  // End of list of possible types for union field agent_type.
}
Fields
name

string

Identifier. The unique identifier of the agent. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

Required. Display name of the agent.
description

string

Optional. Human-readable description of the agent.
modelSettings

object (ModelSettings)

Optional. Configurations for the LLM model.
instruction

string

Optional. Instructions for the LLM model to guide the agent's behavior.
tools[]

string

Optional. List of available tools for the agent. Format: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
childAgents[]

string

Optional. List of child agents in the agent tree. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
beforeAgentCallbacks[]

object (Callback)

Optional. The callbacks to execute before the agent is called. The provided callbacks are executed sequentially in the exact order they are given in the list. If a callback returns an overridden response, execution stops and any remaining callbacks are skipped.
afterAgentCallbacks[]

object (Callback)

Optional. The callbacks to execute after the agent is called. The provided callbacks are executed sequentially in the exact order they are given in the list. If a callback returns an overridden response, execution stops and any remaining callbacks are skipped.
beforeModelCallbacks[]

object (Callback)

Optional. The callbacks to execute before the model is called. If there are multiple calls to the model, the callback will be executed multiple times. The provided callbacks are executed sequentially in the exact order they are given in the list. If a callback returns an overridden response, execution stops and any remaining callbacks are skipped.
afterModelCallbacks[]

object (Callback)

Optional. The callbacks to execute after the model is called. If there are multiple calls to the model, the callback will be executed multiple times. The provided callbacks are executed sequentially in the exact order they are given in the list. If a callback returns an overridden response, execution stops and any remaining callbacks are skipped.
beforeToolCallbacks[]

object (Callback)

Optional. The callbacks to execute before the tool is invoked. If there are multiple tool invocations, the callback will be executed multiple times. The provided callbacks are executed sequentially in the exact order they are given in the list. If a callback returns an overridden response, execution stops and any remaining callbacks are skipped.
afterToolCallbacks[]

object (Callback)

Optional. The callbacks to execute after the tool is invoked. If there are multiple tool invocations, the callback will be executed multiple times. The provided callbacks are executed sequentially in the exact order they are given in the list. If a callback returns an overridden response, execution stops and any remaining callbacks are skipped.
createTime

string (Timestamp format)

Output only. Timestamp when the agent was created.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Output only. Timestamp when the agent was last updated.

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
guardrails[]

string

Optional. List of guardrails for the agent. Format: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
etag

string

Etag used to ensure the object hasn't changed during a read-modify-write operation. If the etag is empty, the update will overwrite any concurrent changes.
toolsets[]

object (Agent.AgentToolset)

Optional. List of toolsets for the agent.
generatedSummary

string

Output only. If the agent is generated by the LLM assistant, this field contains a descriptive summary of the generation.
transferRules[]

object (TransferRule)

Optional. Agent transfer rules. If multiple rules match, the first one in the list will be used.
Union field agent_type. The type of agent. agent_type can be only one of the following:
llmAgent

object (Agent.LlmAgent)

Optional. The default agent type.
remoteDialogflowAgent

object (Agent.RemoteDialogflowAgent)

Optional. The remote Dialogflow agent to be used for the agent execution. If this field is set, all other agent level properties will be ignored.

Note: If the Dialogflow agent is in a different project from the app, you should grant roles/dialogflow.client to the CES service agent service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com.

Agent.LlmAgent

This type has no fields.

Default agent type. The agent uses instructions and callbacks specified in the agent to perform the task using a large language model.

Agent.RemoteDialogflowAgent

The agent which will transfer execution to a remote Dialogflow CX agent. The Dialogflow agent will process subsequent user queries until the session ends or flow ends, and the control is transferred back to the parent CES agent.

JSON representation 
{
  "agent": string,
  "flowId": string,
  "environmentId": string,
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "respectResponseInterruptionSettings": boolean
}
Fields
agent

string

Required. The Dialogflow agent resource name. Format: projects/{project}/locations/{location}/agents/{agent}
flowId

string

Optional. The flow ID of the flow in the Dialogflow agent.
environmentId

string

Optional. The environment ID of the Dialogflow agent to be used for the agent execution. If not specified, the draft environment will be used.
inputVariableMapping

map (key: string, value: string)

Optional. The mapping of the app variables names to the Dialogflow session parameters names to be sent to the Dialogflow agent as input.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
outputVariableMapping

map (key: string, value: string)

Optional. The mapping of the Dialogflow session parameters names to the app variables names to be sent back to the CES agent after the Dialogflow agent execution ends.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
respectResponseInterruptionSettings

boolean

Optional. Indicates whether to respect the message-level interruption settings configured in the Dialogflow agent.

  • If false: all response messages from the Dialogflow agent follow the app-level barge-in settings.
  • If true: only response messages with allow_playback_interruption set to true will be interruptable, all other messages follow the app-level barge-in settings.

Agent.AgentToolset

A toolset with a selection of its tools.

JSON representation 
{
  "toolset": string,
  "toolIds": [
    string
  ]
}
Fields
toolset

string

Required. The resource name of the toolset. Format: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolIds[]

string

Optional. The tools IDs to filter the toolset.

TransferRule

Rule for transferring to a specific agent.

JSON representation 
{
  "childAgent": string,
  "direction": enum (TransferRule.Direction),

  // Union field rule_type can be only one of the following:
  "deterministicTransfer": {
    object (TransferRule.DeterministicTransfer)
  },
  "disablePlannerTransfer": {
    object (TransferRule.DisablePlannerTransfer)
  }
  // End of list of possible types for union field rule_type.
}
Fields
childAgent

string

Required. The resource name of the child agent the rule applies to. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
direction

enum (TransferRule.Direction)

Required. The direction of the transfer.
Union field rule_type. The rule type. rule_type can be only one of the following:
deterministicTransfer

object (TransferRule.DeterministicTransfer)

Optional. A rule that immediately transfers to the target agent when the condition is met.
disablePlannerTransfer

object (TransferRule.DisablePlannerTransfer)

Optional. Rule that prevents the planner from transferring to the target agent.

TransferRule.DeterministicTransfer

Deterministic transfer rule. When the condition evaluates to true, the transfer occurs.

JSON representation 
{

  // Union field condition_type can be only one of the following:
  "expressionCondition": {
    object (ExpressionCondition)
  },
  "pythonCodeCondition": {
    object (PythonCodeCondition)
  }
  // End of list of possible types for union field condition_type.
}
Fields
Union field condition_type. The condition to evaluate. condition_type can be only one of the following:
expressionCondition

object (ExpressionCondition)

Optional. A rule that evaluates a session state condition. If the condition evaluates to true, the transfer occurs.
pythonCodeCondition

object (PythonCodeCondition)

Optional. A rule that uses Python code block to evaluate the conditions. If the condition evaluates to true, the transfer occurs.

ExpressionCondition

Expression condition based on session state.

JSON representation 
{
  "expression": string
}
Fields
expression

string

Required. The string representation of cloud.api.Expression condition.

PythonCodeCondition

Python code block to evaluate the condition.

JSON representation 
{
  "pythonCode": string
}
Fields
pythonCode

string

Required. The python code to execute.

TransferRule.DisablePlannerTransfer

A rule that prevents the planner from transferring to the target agent.

JSON representation 
{
  "expressionCondition": {
    object (ExpressionCondition)
  }
}
Fields
expressionCondition

object (ExpressionCondition)

Required. If the condition evaluates to true, planner will not be allowed to transfer to the target agent.

TransferRule.Direction

The direction of the transfer.

Enums
DIRECTION_UNSPECIFIED Unspecified direction.
PARENT_TO_CHILD Transfer from the parent agent to the child agent.
CHILD_TO_PARENT Transfer from the child agent to the parent agent.

Methods

create

 Creates a new agent in the given app.

delete

 Deletes the specified agent.

get

 Gets details of the specified agent.

list

 Lists agents in the given app.

patch

 Updates the specified agent.