REST Resource: projects.locations.apps.agents

Recurso: agente

Um agente atua como o elemento básico que fornece instruções ao modelo de linguagem grande (LLM) para executar tarefas específicas.

Representação JSON 
{
  "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)
    }
  ],
  "validationErrors": [
    string
  ],

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "llmAgent": {
    object (Agent.LlmAgent)
  },
  "remoteDialogflowAgent": {
    object (Agent.RemoteDialogflowAgent)
  },
  "remoteA2aAgent": {
    object (Agent.RemoteA2aAgent)
  }
  // End of mutually exclusive fields.
}
Campos
name

string

Identificador. O identificador exclusivo do agente. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

Obrigatório. Nome de exibição do agente.
description

string

Opcional. Descrição do agente legível por humanos.
modelSettings

object (ModelSettings)

Opcional. Configurações do modelo de LLM.
instruction

string

Opcional. Instruções para o modelo de LLM orientar o comportamento do agente.
tools[]

string

Opcional. Lista de ferramentas disponíveis para o agente. Formato: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
childAgents[]

string

Opcional. Lista de agentes filhos na árvore de agentes. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
beforeAgentCallbacks[]

object (Callback)

Opcional. Os callbacks a serem executados antes da chamada do agente. Os callbacks fornecidos são executados em sequência na ordem exata em que aparecem na lista. Se um callback retornar uma resposta substituída, a execução será interrompida e os callbacks restantes serão ignorados.
afterAgentCallbacks[]

object (Callback)

Opcional. Os callbacks a serem executados depois que o agente for chamado. Os callbacks fornecidos são executados em sequência na ordem exata em que aparecem na lista. Se um callback retornar uma resposta substituída, a execução será interrompida e os callbacks restantes serão ignorados.
beforeModelCallbacks[]

object (Callback)

Opcional. Os callbacks a serem executados antes da chamada do modelo. Se houver várias chamadas para o modelo, o callback será executado várias vezes. Os callbacks fornecidos são executados em sequência na ordem exata em que aparecem na lista. Se um callback retornar uma resposta substituída, a execução será interrompida e os callbacks restantes serão ignorados.
afterModelCallbacks[]

object (Callback)

Opcional. Os callbacks a serem executados depois que o modelo é chamado. Se houver várias chamadas para o modelo, o callback será executado várias vezes. Os callbacks fornecidos são executados em sequência na ordem exata em que aparecem na lista. Se um callback retornar uma resposta substituída, a execução será interrompida e os callbacks restantes serão ignorados.
beforeToolCallbacks[]

object (Callback)

Opcional. Os callbacks a serem executados antes da invocação da ferramenta. Se houver várias invocações de ferramentas, o callback será executado várias vezes. Os callbacks fornecidos são executados em sequência na ordem exata em que aparecem na lista. Se um callback retornar uma resposta substituída, a execução será interrompida e os callbacks restantes serão ignorados.
afterToolCallbacks[]

object (Callback)

Opcional. Os callbacks a serem executados depois que a ferramenta é invocada. Se houver várias invocações de ferramentas, o callback será executado várias vezes. Os callbacks fornecidos são executados em sequência na ordem exata em que aparecem na lista. Se um callback retornar uma resposta substituída, a execução será interrompida e os callbacks restantes serão ignorados.
createTime

string (Timestamp format)

Apenas saída. Carimbo de data/hora em que o agente foi criado.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Apenas saída. Carimbo de data/hora da última atualização do agente.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
guardrails[]

string

Opcional. Lista de mecanismos de segurança para o agente. Formato: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
etag

string

Etag usada para garantir que o objeto não foi alterado durante uma operação de leitura-modificação-gravação. Se a ETag estiver vazia, a atualização vai substituir todas as mudanças simultâneas.
toolsets[]

object (Agent.AgentToolset)

Opcional. Lista de conjuntos de ferramentas para o agente.
generatedSummary

string

Apenas saída. Se o agente for gerado pelo assistente de LLM, esse campo vai conter um resumo descritivo da geração.
transferRules[]

object (TransferRule)

Opcional. Regras de transferência de agente. Se várias regras corresponderem, a primeira da lista será usada.
validationErrors[]

string

Apenas saída. Erros ou configurações incorretas no agente que podem afetar a qualidade dele.
O tipo de agente. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
llmAgent

object (Agent.LlmAgent)

Opcional. O tipo de agente padrão.
remoteDialogflowAgent

object (Agent.RemoteDialogflowAgent)

Opcional. O agente Dialogflow remoto a ser usado para a execução do agente. Se esse campo for definido, todas as outras propriedades no nível do agente serão ignoradas.

Observação: se o agente do Dialogflow estiver em um projeto diferente do app, conceda roles/dialogflow.client ao agente de serviço do CES service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com.
remoteA2aAgent

object (Agent.RemoteA2aAgent)

Opcional. O agente A2A remoto a ser usado para a execução do agente.
Fim dos campos mutuamente exclusivos.

Agent.LlmAgent

Esse tipo não tem campos.

Tipo de agente padrão. O agente usa instruções e callbacks especificados nele para realizar a tarefa usando um modelo de linguagem grande.

Agent.RemoteDialogflowAgent

O agente que vai transferir a execução para um agente Dialogflow CX remoto. O agente do Dialogflow vai processar as consultas subsequentes do usuário até que a sessão ou o fluxo termine, e o controle seja transferido de volta para o agente principal do CES.

Representação JSON 
{
  "agent": string,
  "flowId": string,
  "environmentId": string,
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "respectResponseInterruptionSettings": boolean,
  "languageCodeVariable": string
}
Campos
agent

string

Obrigatório. O nome do recurso do agente do Dialogflow. Formato: projects/{project}/locations/{location}/agents/{agent}
flowId

string

Opcional. O ID do fluxo no agente do Dialogflow.
environmentId

string

Opcional. O ID do ambiente do agente do Dialogflow a ser usado para a execução do agente. Se não for especificado, o ambiente de rascunho será usado.
inputVariableMapping

map (key: string, value: string)

Opcional. O mapeamento dos nomes das variáveis do app para os nomes dos parâmetros da sessão do Dialogflow a serem enviados ao agente do Dialogflow como entrada.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
outputVariableMapping

map (key: string, value: string)

Opcional. O mapeamento dos nomes dos parâmetros da sessão do Dialogflow para os nomes das variáveis do app que serão enviadas de volta ao agente do CES após o término da execução do agente do Dialogflow.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
respectResponseInterruptionSettings

boolean

Opcional. Indica se as configurações de interrupção no nível da mensagem configuradas no agente do Dialogflow devem ser respeitadas.

  • Se for "false", todas as mensagens de resposta do agente do Dialogflow vão seguir as configurações de interrupção no nível do app.
  • Se for "true": somente as mensagens de resposta com allow_playback_interruption definido como "true" poderão ser interrompidas. Todas as outras mensagens seguem as configurações de interrupção no nível do app.
languageCodeVariable

string

Opcional. O nome da variável que contém o código do idioma a ser usado na sessão do Dialogflow. Se não for especificado, o código de idioma padrão do agente do Dialogflow será usado.

Agent.RemoteA2aAgent

O agente que vai transferir a execução para um agente A2A remoto.

Representação JSON 
{
  "a2aConfig": {
    object (RemoteA2aConfig)
  }
}
Campos
a2aConfig

object (RemoteA2aConfig)

Obrigatório. A configuração da conexão A2A.

RemoteA2aConfig

Configuração compartilhada para se conectar a um agente A2A remoto.

Representação JSON 
{
  "apiAuthentication": {
    object (ApiAuthentication)
  },
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "streamingEnabled": boolean,
  "contextId": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "agentCard": {
    object (AgentCard)
  },
  "agentRegistry": string
  // End of mutually exclusive fields.
}
Campos
apiAuthentication

object (ApiAuthentication)

Opcional. Configuração de autenticação para chamar o agente remoto. Opcional se a referência do registro já processar a autenticação.
inputVariableMapping

map (key: string, value: string)

Opcional. Mapeamento de nomes de variáveis de entrada do agente remoto para nomes de variáveis do GECX.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
outputVariableMapping

map (key: string, value: string)

Opcional. Mapeamento de nomes de variáveis de saída do agente remoto para nomes de variáveis do GECX.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
streamingEnabled

boolean

Opcional. Se o streaming está ativado para o agente remoto.
contextId

string

Opcional. Se não estiver vazio, as interações com o agente A2A remoto vão usar esse ID de contexto. Esse campo contextId pode se referir a uma variável de sessão, como $context.variables.order_agent_session_id.
Especificação do agente remoto. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
agentCard

object (AgentCard)

Opcional. O card completo do agente definido inline.
agentRegistry

string

Opcional. Referência ao agente no Agent Registry. Formato: projects/{project}/locations/{location}/agents/{agent}
Fim dos campos mutuamente exclusivos.

Agent.AgentToolset

Um conjunto de ferramentas com uma seleção delas.

Representação JSON 
{
  "toolset": string,
  "toolIds": [
    string
  ]
}
Campos
toolset

string

Obrigatório. O nome do recurso do conjunto de ferramentas. Formato: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolIds[]

string

Opcional. Os IDs das ferramentas para filtrar o conjunto de ferramentas.

TransferRule

Regra para transferência para um agente específico.

Representação JSON 
{
  "childAgent": string,
  "direction": enum (TransferRule.Direction),

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "deterministicTransfer": {
    object (TransferRule.DeterministicTransfer)
  },
  "disablePlannerTransfer": {
    object (TransferRule.DisablePlannerTransfer)
  }
  // End of mutually exclusive fields.
}
Campos
childAgent

string

Obrigatório. O nome do recurso do agente secundário a que a regra se aplica. Formato: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
direction

enum (TransferRule.Direction)

Obrigatório. A direção da transferência.
O tipo de regra. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
deterministicTransfer

object (TransferRule.DeterministicTransfer)

Opcional. Uma regra que transfere imediatamente para o agente de destino quando a condição é atendida.
disablePlannerTransfer

object (TransferRule.DisablePlannerTransfer)

Opcional. Regra que impede a transferência do planejador para o agente de destino.
Fim dos campos mutuamente exclusivos.

TransferRule.DeterministicTransfer

Regra de transferência determinística. Quando a condição é avaliada como verdadeira, a transferência ocorre.

Representação JSON 
{

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "expressionCondition": {
    object (ExpressionCondition)
  },
  "pythonCodeCondition": {
    object (PythonCodeCondition)
  }
  // End of mutually exclusive fields.
}
Campos
A condição a ser avaliada. Confira a seguir uma lista de campos mutuamente exclusivos. No máximo um dos campos será definido em uma resposta:
expressionCondition

object (ExpressionCondition)

Opcional. Uma regra que avalia uma condição de estado da sessão. Se a condição for avaliada como verdadeira, a transferência vai ocorrer.
pythonCodeCondition

object (PythonCodeCondition)

Opcional. Uma regra que usa um bloco de código Python para avaliar as condições. Se a condição for avaliada como verdadeira, a transferência vai ocorrer.
Fim dos campos mutuamente exclusivos.

ExpressionCondition

Condição de expressão com base no estado da sessão.

Representação JSON 
{
  "expression": string
}
Campos
expression

string

Obrigatório. A representação de string da condição cloud.api.Expression.

PythonCodeCondition

Bloco de código Python para avaliar a condição.

Representação JSON 
{
  "pythonCode": string
}
Campos
pythonCode

string

Obrigatório. O código Python a ser executado.

TransferRule.DisablePlannerTransfer

Uma regra que impede a transferência do planejador para o agente de destino.

Representação JSON 
{
  "expressionCondition": {
    object (ExpressionCondition)
  }
}
Campos
expressionCondition

object (ExpressionCondition)

Obrigatório. Se a condição for avaliada como verdadeira, o planejador não poderá ser transferido para o agente de destino.

TransferRule.Direction

A direção da transferência.

Tipos enumerados
DIRECTION_UNSPECIFIED Direção não especificada.
PARENT_TO_CHILD Transferência do agente principal para o agente secundário.
CHILD_TO_PARENT Transferir do agente secundário para o agente pai.

Métodos

create

 Cria um novo agente no app especificado.

delete

 Exclui o agente especificado.

get

 Recebe detalhes do agente especificado.

list

 Lista os agentes no app especificado.

patch

 Atualiza o agente especificado.