REST Resource: projects.locations.apps.agents

리소스: 에이전트

에이전트는 특정 작업을 실행하기 위해 대규모 언어 모델 (LLM)에 명령어를 제공하는 기본 구성요소 역할을 합니다.

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.
}
필드
name

string

식별자. 에이전트의 고유 식별자입니다. 형식: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
displayName

string

필수 항목입니다. 상담사의 표시 이름입니다.
description

string

(선택사항) 인간이 읽을 수 있는 에이전트 설명입니다.
modelSettings

object (ModelSettings)

(선택사항) LLM 모델의 구성입니다.
instruction

string

(선택사항) 에이전트의 동작을 안내하는 LLM 모델의 요청 사항입니다.
tools[]

string

(선택사항) 에이전트가 사용할 수 있는 도구 목록입니다. 형식: projects/{project}/locations/{location}/apps/{app}/tools/{tool}
childAgents[]

string

(선택사항) 에이전트 트리의 하위 에이전트 목록입니다. 형식: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
beforeAgentCallbacks[]

object (Callback)

(선택사항) 에이전트가 호출되기 전에 실행할 콜백입니다. 제공된 콜백은 목록에 제공된 정확한 순서대로 순차적으로 실행됩니다. 콜백이 재정의된 응답을 반환하면 실행이 중지되고 나머지 콜백은 건너뜁니다.
afterAgentCallbacks[]

object (Callback)

(선택사항) 에이전트가 호출된 후 실행할 콜백입니다. 제공된 콜백은 목록에 제공된 정확한 순서대로 순차적으로 실행됩니다. 콜백이 재정의된 응답을 반환하면 실행이 중지되고 나머지 콜백은 건너뜁니다.
beforeModelCallbacks[]

object (Callback)

(선택사항) 모델이 호출되기 전에 실행할 콜백입니다. 모델에 대한 호출이 여러 개 있는 경우 콜백이 여러 번 실행됩니다. 제공된 콜백은 목록에 제공된 정확한 순서대로 순차적으로 실행됩니다. 콜백이 재정의된 응답을 반환하면 실행이 중지되고 나머지 콜백은 건너뜁니다.
afterModelCallbacks[]

object (Callback)

(선택사항) 모델이 호출된 후 실행할 콜백입니다. 모델에 대한 호출이 여러 개 있는 경우 콜백이 여러 번 실행됩니다. 제공된 콜백은 목록에 제공된 정확한 순서대로 순차적으로 실행됩니다. 콜백이 재정의된 응답을 반환하면 실행이 중지되고 나머지 콜백은 건너뜁니다.
beforeToolCallbacks[]

object (Callback)

(선택사항) 도구가 호출되기 전에 실행할 콜백입니다. 도구 호출이 여러 개 있는 경우 콜백이 여러 번 실행됩니다. 제공된 콜백은 목록에 제공된 정확한 순서대로 순차적으로 실행됩니다. 콜백이 재정의된 응답을 반환하면 실행이 중지되고 나머지 콜백은 건너뜁니다.
afterToolCallbacks[]

object (Callback)

(선택사항) 도구가 호출된 후 실행할 콜백입니다. 도구 호출이 여러 개 있는 경우 콜백이 여러 번 실행됩니다. 제공된 콜백은 목록에 제공된 정확한 순서대로 순차적으로 실행됩니다. 콜백이 재정의된 응답을 반환하면 실행이 중지되고 나머지 콜백은 건너뜁니다.
createTime

string (Timestamp format)

출력 전용입니다. 상담사가 생성된 타임스탬프입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
updateTime

string (Timestamp format)

출력 전용입니다. 에이전트가 마지막으로 업데이트된 타임스탬프입니다.

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.
guardrails[]

string

(선택사항) 에이전트의 가드레일 목록입니다. 형식: projects/{project}/locations/{location}/apps/{app}/guardrails/{guardrail}
etag

string

읽기-수정-쓰기 작업 중에 객체가 변경되지 않았는지 확인하는 데 사용되는 Etag입니다. etag가 비어 있으면 업데이트가 동시에 발생하는 변경사항을 덮어씁니다.
toolsets[]

object (Agent.AgentToolset)

(선택사항) 에이전트의 도구 세트 목록입니다.
generatedSummary

string

출력 전용입니다. 에이전트가 LLM 어시스턴트에 의해 생성된 경우 이 필드에는 생성에 관한 설명 요약이 포함됩니다.
transferRules[]

object (TransferRule)

(선택사항) 상담사 트랜스퍼 규칙입니다. 일치하는 규칙이 여러 개 있는 경우 목록의 첫 번째 규칙이 사용됩니다.
validationErrors[]

string

출력 전용입니다. 상담사 품질에 영향을 미칠 수 있는 상담사의 잘못된 구성 또는 오류
에이전트 유형입니다. 다음은 상호 배타적인 필드의 목록입니다. 응답에는 다음 필드 중 최대 하나가 설정됩니다.
llmAgent

object (Agent.LlmAgent)

(선택사항) 기본 에이전트 유형입니다.
remoteDialogflowAgent

object (Agent.RemoteDialogflowAgent)

(선택사항) 에이전트 실행에 사용할 원격 Dialogflow 에이전트입니다. 이 필드가 설정되면 다른 모든 에이전트 수준 속성은 무시됩니다.

참고: Dialogflow 에이전트가 앱과 다른 프로젝트에 있는 경우 CES 서비스 에이전트 service-<PROJECT-NUMBER>@gcp-sa-ces.iam.gserviceaccount.com에 roles/dialogflow.client 권한을 부여해야 합니다.
remoteA2aAgent

object (Agent.RemoteA2aAgent)

(선택사항) 에이전트 실행에 사용할 원격 A2A 에이전트입니다.
상호 배타적 필드의 끝입니다.

Agent.LlmAgent

이 유형에는 필드가 없습니다.

기본 에이전트 유형입니다. 에이전트는 에이전트에 지정된 요청 사항과 콜백을 사용하여 대규모 언어 모델을 통해 작업을 실행합니다.

Agent.RemoteDialogflowAgent

실행을 원격 Dialogflow CX 에이전트로 트랜스퍼할 에이전트입니다. 세션이 종료되거나 흐름이 종료되고 제어 권한이 상위 CES 에이전트에게 다시 이전될 때까지 Dialogflow 에이전트가 후속 사용자 쿼리를 처리합니다.

JSON 표현 
{
  "agent": string,
  "flowId": string,
  "environmentId": string,
  "inputVariableMapping": {
    string: string,
    ...
  },
  "outputVariableMapping": {
    string: string,
    ...
  },
  "respectResponseInterruptionSettings": boolean,
  "languageCodeVariable": string
}
필드
agent

string

필수 항목입니다. Dialogflow 에이전트 리소스 이름입니다. 형식: projects/{project}/locations/{location}/agents/{agent}
flowId

string

(선택사항) Dialogflow 에이전트의 흐름 ID입니다.
environmentId

string

(선택사항) 에이전트 실행에 사용할 Dialogflow 에이전트의 환경 ID입니다. 지정하지 않으면 초안 환경이 사용됩니다.
inputVariableMapping

map (key: string, value: string)

(선택사항) Dialogflow 에이전트에 입력으로 전송될 앱 변수 이름과 Dialogflow 세션 매개변수 이름의 매핑입니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
outputVariableMapping

map (key: string, value: string)

(선택사항) Dialogflow 에이전트 실행이 종료된 후 CES 에이전트로 다시 전송될 Dialogflow 세션 매개변수 이름과 앱 변수 이름의 매핑입니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
respectResponseInterruptionSettings

boolean

(선택사항) Dialogflow 에이전트에서 구성된 메시지 수준 인터럽션 설정을 준수할지 여부를 나타냅니다.

  • false인 경우: Dialogflow 에이전트의 모든 응답 메시지는 앱 수준 끼어들기 설정을 따릅니다.
  • true인 경우: allow_playback_interruption이 true로 설정된 응답 메시지만 인터럽트 가능하며, 다른 모든 메시지는 앱 수준 바지인 설정을 따릅니다.
languageCodeVariable

string

(선택사항) Dialogflow 세션에 사용할 언어 코드가 포함된 변수의 이름입니다. 지정하지 않으면 Dialogflow 에이전트의 기본 언어 코드가 사용됩니다.

Agent.RemoteA2aAgent

실행을 원격 A2A 에이전트로 트랜스퍼하는 에이전트입니다.

JSON 표현 
{
  "a2aConfig": {
    object (RemoteA2aConfig)
  }
}
필드
a2aConfig

object (RemoteA2aConfig)

필수 항목입니다. A2A 연결 구성입니다.

RemoteA2aConfig

원격 A2A 에이전트에 연결하기 위한 공유 구성입니다.

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.
}
필드
apiAuthentication

object (ApiAuthentication)

(선택사항) 원격 에이전트 호출을 위한 인증 구성입니다. 레지스트리 참조에서 이미 인증을 처리하는 경우 선택사항입니다.
inputVariableMapping

map (key: string, value: string)

(선택사항) 원격 에이전트의 입력 변수 이름을 GECX 변수 이름에 매핑합니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
outputVariableMapping

map (key: string, value: string)

(선택사항) 원격 에이전트의 출력 변수 이름을 GECX 변수 이름에 매핑합니다.

"key": value 쌍 목록을 포함하는 객체입니다. 예: { "name": "wrench", "mass": "1.3kg", "count": "3" }
streamingEnabled

boolean

(선택사항) 원격 에이전트에 스트리밍이 사용 설정되어 있는지 여부입니다.
contextId

string

(선택사항) 비어 있지 않으면 원격 A2A 에이전트와의 상호작용에서 이 컨텍스트 ID가 사용됩니다. 이 contextId 필드는 $context.variables.order_agent_session_id과 같은 세션 변수를 참조할 수 있습니다.
원격 에이전트의 사양입니다. 다음은 상호 배타적인 필드의 목록입니다. 응답에는 다음 필드 중 최대 하나가 설정됩니다.
agentCard

object (AgentCard)

(선택사항) 인라인으로 정의된 전체 에이전트 카드입니다.
agentRegistry

string

(선택사항) Agent Registry의 에이전트에 대한 참조입니다. 형식: projects/{project}/locations/{location}/agents/{agent}
상호 배타적 필드의 끝입니다.

Agent.AgentToolset

선택된 도구가 포함된 도구 세트입니다.

JSON 표현 
{
  "toolset": string,
  "toolIds": [
    string
  ]
}
필드
toolset

string

필수 항목입니다. 툴셋의 리소스 이름입니다. 형식: projects/{project}/locations/{location}/apps/{app}/toolsets/{toolset}
toolIds[]

string

(선택사항) 툴셋을 필터링할 도구 ID입니다.

TransferRule

특정 상담사에게 트랜스퍼하는 규칙입니다.

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.
}
필드
childAgent

string

필수 항목입니다. 규칙이 적용되는 하위 에이전트의 리소스 이름입니다. 형식: projects/{project}/locations/{location}/apps/{app}/agents/{agent}
direction

enum (TransferRule.Direction)

필수 항목입니다. 전송 방향입니다.
규칙 유형입니다. 다음은 상호 배타적인 필드의 목록입니다. 응답에는 다음 필드 중 최대 하나가 설정됩니다.
deterministicTransfer

object (TransferRule.DeterministicTransfer)

(선택사항) 조건이 충족되면 즉시 타겟 상담사에게 트랜스퍼되는 규칙입니다.
disablePlannerTransfer

object (TransferRule.DisablePlannerTransfer)

(선택사항) 계획자가 타겟 상담사에게 트랜스퍼하지 못하도록 하는 규칙입니다.
상호 배타적 필드의 끝입니다.

TransferRule.DeterministicTransfer

확정적 전송 규칙입니다. 조건이 true로 평가되면 전송이 발생합니다.

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.
}
필드
평가할 조건입니다. 다음은 상호 배타적인 필드의 목록입니다. 응답에는 다음 필드 중 최대 하나가 설정됩니다.
expressionCondition

object (ExpressionCondition)

(선택사항) 세션 상태 조건을 평가하는 규칙 조건이 true로 평가되면 전송이 발생합니다.
pythonCodeCondition

object (PythonCodeCondition)

(선택사항) Python 코드 블록을 사용하여 조건을 평가하는 규칙 조건이 true로 평가되면 전송이 발생합니다.
상호 배타적 필드의 끝입니다.

ExpressionCondition

세션 상태를 기반으로 하는 표현식 조건입니다.

JSON 표현 
{
  "expression": string
}
필드
expression

string

필수 항목입니다. cloud.api.Expression 조건의 문자열 표현입니다.

PythonCodeCondition

조건을 평가하는 Python 코드 블록입니다.

JSON 표현 
{
  "pythonCode": string
}
필드
pythonCode

string

필수 항목입니다. 실행할 Python 코드입니다.

TransferRule.DisablePlannerTransfer

계획자가 타겟 상담사에게 트랜스퍼되지 않도록 하는 규칙입니다.

JSON 표현 
{
  "expressionCondition": {
    object (ExpressionCondition)
  }
}
필드
expressionCondition

object (ExpressionCondition)

필수 항목입니다. 조건이 true로 평가되면 플래너가 타겟 상담사에게 트랜스퍼할 수 없습니다.

TransferRule.Direction

전송 방향입니다.

열거형
DIRECTION_UNSPECIFIED 지정되지 않은 방향입니다.
PARENT_TO_CHILD 상위 에이전트에서 하위 에이전트로 트랜스퍼합니다.
CHILD_TO_PARENT 하위 에이전트에서 상위 에이전트로 트랜스퍼합니다.

메서드

create

 지정된 앱에 새 에이전트를 만듭니다.

delete

 지정된 에이전트를 삭제합니다.

get

 지정된 상담사의 세부정보를 가져옵니다.

list

 지정된 앱의 에이전트를 나열합니다.

patch

 지정된 에이전트를 업데이트합니다.