REST Resource: projects.locations.apps.agents

Ressource: KI-Agent

Ein Agent ist der grundlegende Baustein, der dem Large Language Model (LLM) Anweisungen zur Ausführung bestimmter Aufgaben gibt.

JSON-Darstellung 
{
  "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.
}
Felder
name

string

ID. Die eindeutige Kennung des Agents. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

Erforderlich. Anzeigename des KI-Agenten.
description

string

Optional. Eine menschenlesbare Beschreibung des KI-Agenten.
modelSettings

object (ModelSettings)

Optional. Konfigurationen für das LLM-Modell.
instruction

string

Optional. Anweisungen für das LLM-Modell, um das Verhalten des KI-Agenten zu steuern.
tools[]

string

Optional. Liste der verfügbaren Tools für den Agenten. Format: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
childAgents[]

string

Optional. Liste der untergeordneten Agents in der Agent-Baumstruktur. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
beforeAgentCallbacks[]

object (Callback)

Optional. Die Callbacks, die vor dem Aufrufen des Agents ausgeführt werden sollen. Die bereitgestellten Callbacks werden sequenziell in der genauen Reihenfolge ausgeführt, in der sie in der Liste angegeben sind. Wenn ein Callback eine überschriebene Antwort zurückgibt, wird die Ausführung beendet und alle verbleibenden Callbacks werden übersprungen.
afterAgentCallbacks[]

object (Callback)

Optional. Die Callbacks, die nach dem Aufrufen des Agenten ausgeführt werden sollen. Die bereitgestellten Callbacks werden sequenziell in der genauen Reihenfolge ausgeführt, in der sie in der Liste angegeben sind. Wenn ein Callback eine überschriebene Antwort zurückgibt, wird die Ausführung beendet und alle verbleibenden Callbacks werden übersprungen.
beforeModelCallbacks[]

object (Callback)

Optional. Die Callbacks, die vor dem Aufrufen des Modells ausgeführt werden. Wenn das Modell mehrmals aufgerufen wird, wird der Callback mehrmals ausgeführt. Die bereitgestellten Callbacks werden sequenziell in der genauen Reihenfolge ausgeführt, in der sie in der Liste angegeben sind. Wenn ein Callback eine überschriebene Antwort zurückgibt, wird die Ausführung beendet und alle verbleibenden Callbacks werden übersprungen.
afterModelCallbacks[]

object (Callback)

Optional. Die Callbacks, die nach dem Aufrufen des Modells ausgeführt werden sollen. Wenn das Modell mehrmals aufgerufen wird, wird der Callback mehrmals ausgeführt. Die bereitgestellten Callbacks werden sequenziell in der genauen Reihenfolge ausgeführt, in der sie in der Liste angegeben sind. Wenn ein Callback eine überschriebene Antwort zurückgibt, wird die Ausführung beendet und alle verbleibenden Callbacks werden übersprungen.
beforeToolCallbacks[]

object (Callback)

Optional. Die Callbacks, die vor dem Aufrufen des Tools ausgeführt werden sollen. Wenn mehrere Toolaufrufe vorhanden sind, wird der Callback mehrmals ausgeführt. Die bereitgestellten Callbacks werden sequenziell in der genauen Reihenfolge ausgeführt, in der sie in der Liste angegeben sind. Wenn ein Callback eine überschriebene Antwort zurückgibt, wird die Ausführung beendet und alle verbleibenden Callbacks werden übersprungen.
afterToolCallbacks[]

object (Callback)

Optional. Die Callbacks, die nach dem Aufrufen des Tools ausgeführt werden sollen. Wenn mehrere Toolaufrufe vorhanden sind, wird der Callback mehrmals ausgeführt. Die bereitgestellten Callbacks werden sequenziell in der genauen Reihenfolge ausgeführt, in der sie in der Liste angegeben sind. Wenn ein Callback eine überschriebene Antwort zurückgibt, wird die Ausführung beendet und alle verbleibenden Callbacks werden übersprungen.
createTime

string (Timestamp format)

Nur Ausgabe. Zeitstempel für die Erstellung des Agents.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30"
updateTime

string (Timestamp format)

Nur Ausgabe. Zeitstempel der letzten Aktualisierung des Agents.

Verwendet RFC 3339, wobei die generierte Ausgabe immer Z-normalisiert ist und 0, 3, 6 oder 9 Nachkommastellen verwendet. Andere Offsets als „Z“ werden ebenfalls akzeptiert. Beispiele: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" oder "2014-10-02T15:01:23+05:30".
guardrails[]

string

Optional. Liste der Richtlinien für den Agenten. Format: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
etag

string

ETag, mit dem sichergestellt wird, dass sich das Objekt während eines Read-Modify-Write-Vorgangs nicht geändert hat. Wenn das ETag leer ist, werden durch das Update alle gleichzeitigen Änderungen überschrieben.
toolsets[]

object (Agent.AgentToolset)

Optional. Liste der Toolsets für den Agenten.
generatedSummary

string

Nur Ausgabe. Wenn der Agent vom LLM-Assistenten generiert wird, enthält dieses Feld eine beschreibende Zusammenfassung der Generierung.
transferRules[]

object (TransferRule)

Optional. Regeln für die Agentenübertragung. Wenn mehrere Regeln zutreffen, wird die erste Regel in der Liste verwendet.
validationErrors[]

string

Nur Ausgabe. Fehlkonfigurationen oder Fehler im Agent, die sich auf die Qualität des Agenten auswirken können.
Der Typ des KI-Agenten. Im Folgenden finden Sie eine Liste von sich gegenseitig ausschließenden Feldern. In einer Antwort wird höchstens eines der Felder festgelegt:
llmAgent

object (Agent.LlmAgent)

Optional. Der Standard-KI-Agent-Typ.
remoteDialogflowAgent

object (Agent.RemoteDialogflowAgent)

Optional. Der Remote-Dialogflow-Agent, der für die Ausführung des Agenten verwendet werden soll. Wenn dieses Feld festgelegt ist, werden alle anderen Eigenschaften auf Agentenebene ignoriert.

Hinweis: Wenn sich der Dialogflow-Agent in einem anderen Projekt als die App befindet, sollten Sie dem CES-Dienst-Agent service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com die Rolle roles/dialogflow.client zuweisen.
remoteA2aAgent

object (Agent.RemoteA2aAgent)

Optional. Der A2A-Remote-Agent, der für die Ausführung des Agenten verwendet werden soll.
Ende der sich gegenseitig ausschließenden Felder.

Agent.LlmAgent

Dieser Typ hat keine Felder.

Standard-Agent-Typ. Der Agent verwendet Anweisungen und Callbacks, die im Agent angegeben sind, um die Aufgabe mit einem Large Language Model auszuführen.

Agent.RemoteDialogflowAgent

Der Agent, der die Ausführung an einen Remote-Agenten in Dialogflow CX überträgt. Der Dialogflow-Agent verarbeitet nachfolgende Nutzeranfragen, bis die Sitzung oder der Ablauf endet und die Steuerung an den übergeordneten CES-Agent zurückgegeben wird.

JSON-Darstellung 
{
  "agent": string,
  "flowId": string,
  "environmentId": string,
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "respectResponseInterruptionSettings": boolean,
  "languageCodeVariable": string
}
Felder
agent

string

Erforderlich. Der Ressourcenname des Dialogflow-Agents. Format: projects/{project}/locations/{location}/agents/{agent}
flowId

string

Optional. Die Flow-ID des Flows im Dialogflow-Agenten.
environmentId

string

Optional. Die Umgebungs-ID des Dialogflow-KI-Agenten, der für die Ausführung des KI-Agenten verwendet werden soll. Wenn keine Angabe erfolgt, wird die Umgebung „draft“ verwendet.
inputVariableMapping

map (key: string, value: string)

Optional. Die Zuordnung der Namen der App-Variablen zu den Namen der Dialogflow-Sitzungsparameter, die als Eingabe an den Dialogflow-Agent gesendet werden sollen.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
outputVariableMapping

map (key: string, value: string)

Optional. Die Zuordnung der Namen der Dialogflow-Sitzungsparameter zu den Namen der App-Variablen, die nach Beendigung der Ausführung des Dialogflow-Agenten an den CES-Agenten zurückgesendet werden sollen.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
respectResponseInterruptionSettings

boolean

Optional. Gibt an, ob die auf Nachrichtenebene konfigurierten Unterbrechungseinstellungen im Dialogflow-Agent berücksichtigt werden sollen.

  • Falsch: Alle Antwortnachrichten des Dialogflow-Agents folgen den Einstellungen für das Unterbrechen auf App-Ebene.
  • Wenn „true“: Nur Antwortnachrichten, bei denen allow_playback_interruption auf „true“ gesetzt ist, können unterbrochen werden. Für alle anderen Nachrichten gelten die Einstellungen für das Unterbrechen auf App-Ebene.
languageCodeVariable

string

Optional. Der Name der Variablen, die den Sprachcode für die Dialogflow-Sitzung enthält. Wenn nicht angegeben, wird der Standardsprachcode des Dialogflow-Agents verwendet.

Agent.RemoteA2aAgent

Der Agent, der die Ausführung an einen Remote-A2A-Agenten überträgt.

JSON-Darstellung 
{
  "a2aConfig": {
    object (RemoteA2aConfig)
  }
}
Felder
a2aConfig

object (RemoteA2aConfig)

Erforderlich. Die A2A-Verbindungskonfiguration.

RemoteA2aConfig

Gemeinsame Konfiguration für die Verbindung zu einem A2A-Remote-Agent.

JSON-Darstellung 
{
  "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.
}
Felder
apiAuthentication

object (ApiAuthentication)

Optional. Authentifizierungskonfiguration für den Aufruf des Remote-Agents. Optional, wenn die Authentifizierung bereits über den Registry-Verweis erfolgt.
inputVariableMapping

map (key: string, value: string)

Optional. Zuordnung von Eingabevariablennamen des Remote-Agents zu GECX-Variablennamen.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
outputVariableMapping

map (key: string, value: string)

Optional. Zuordnung von Ausgabevariablennamen des Remote-Agents zu GECX-Variablennamen.

Ein Objekt, das eine Liste von "key": value-Paaren enthält. Beispiel: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
streamingEnabled

boolean

Optional. Gibt an, ob Streaming für den Remote-Agent aktiviert ist.
contextId

string

Optional. Wenn nicht leer, wird diese Kontext-ID für Interaktionen mit dem Remote-A2A-Agent verwendet. Das Feld „contextId“ kann auf eine Sitzungsvariable wie $context.variables.order_agent_session_id verweisen.
Spezifikation des Remote-Agents. Im Folgenden finden Sie eine Liste von sich gegenseitig ausschließenden Feldern. In einer Antwort wird höchstens eines der Felder festgelegt:
agentCard

object (AgentCard)

Optional. Die vollständige Agentenkarte, die inline definiert ist.
agentRegistry

string

Optional. Referenz auf den KI-Agenten in der Agent Registry. Format: projects/{project}/locations/{location}/agents/{agent}
Ende der sich gegenseitig ausschließenden Felder.

Agent.AgentToolset

Ein Toolset mit einer Auswahl seiner Tools.

JSON-Darstellung 
{
  "toolset": string,
  "toolIds": [
    string
  ]
}
Felder
toolset

string

Erforderlich. Der Ressourcenname des Toolsets. Format: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolIds[]

string

Optional. Die Tool-IDs zum Filtern des Toolsets.

TransferRule

Regel für die Weiterleitung an einen bestimmten Kundenservicemitarbeiter.

JSON-Darstellung 
{
  "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.
}
Felder
childAgent

string

Erforderlich. Der Ressourcenname des untergeordneten KI-Agenten, auf den sich die Regel bezieht. Format: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
direction

enum (TransferRule.Direction)

Erforderlich. Die Richtung der Übertragung.
Der Regeltyp. Im Folgenden finden Sie eine Liste von sich gegenseitig ausschließenden Feldern. In einer Antwort wird höchstens eines der Felder festgelegt:
deterministicTransfer

object (TransferRule.DeterministicTransfer)

Optional. Eine Regel, die sofort an den Ziel-Agent übertragen wird, wenn die Bedingung erfüllt ist.
disablePlannerTransfer

object (TransferRule.DisablePlannerTransfer)

Optional. Regel, die verhindert, dass der Planner an den Ziel-Agent übertragen wird.
Ende der sich gegenseitig ausschließenden Felder.

TransferRule.DeterministicTransfer

Deterministische Übertragungsregel. Wenn die Bedingung als „wahr“ ausgewertet wird, erfolgt die Übertragung.

JSON-Darstellung 
{

  // 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.
}
Felder
Die Bedingung, die ausgewertet werden soll. Im Folgenden finden Sie eine Liste von sich gegenseitig ausschließenden Feldern. In einer Antwort wird höchstens eines der Felder festgelegt:
expressionCondition

object (ExpressionCondition)

Optional. Eine Regel, die eine Bedingung für den Sitzungsstatus auswertet. Wenn die Bedingung als „wahr“ ausgewertet wird, erfolgt die Übertragung.
pythonCodeCondition

object (PythonCodeCondition)

Optional. Eine Regel, in der ein Python-Codeblock verwendet wird, um die Bedingungen auszuwerten. Wenn die Bedingung als „wahr“ ausgewertet wird, erfolgt die Übertragung.
Ende der sich gegenseitig ausschließenden Felder.

ExpressionCondition

Ausdrucksbedingung basierend auf dem Sitzungsstatus.

JSON-Darstellung 
{
  "expression": string
}
Felder
expression

string

Erforderlich. Die Stringdarstellung der Bedingung „cloud.api.Expression“.

PythonCodeCondition

Python-Codeblock zum Auswerten der Bedingung.

JSON-Darstellung 
{
  "pythonCode": string
}
Felder
pythonCode

string

Erforderlich. Der auszuführende Python-Code.

TransferRule.DisablePlannerTransfer

Eine Regel, die verhindert, dass der Planner an den Ziel-Agent übertragen wird.

JSON-Darstellung 
{
  "expressionCondition": {
    object (ExpressionCondition)
  }
}
Felder
expressionCondition

object (ExpressionCondition)

Erforderlich. Wenn die Bedingung „true“ ergibt, darf der Planer nicht zum Ziel-Kundenservicemitarbeiter weitergeleitet werden.

TransferRule.Direction

Die Richtung der Übertragung.

Enums
DIRECTION_UNSPECIFIED Nicht angegebene Richtung.
PARENT_TO_CHILD Übertragung vom übergeordneten Agenten an den untergeordneten Agenten.
CHILD_TO_PARENT Übertragung vom untergeordneten zum übergeordneten Agenten.

Methoden

create

 Erstellt einen neuen Agenten in der angegebenen App.

delete

 Löscht den angegebenen Agent.

get

 Ruft Details zum angegebenen Agent ab.

list

 Listet Agents in der angegebenen App auf.

patch

 Aktualisiert den angegebenen Agent.