REST Resource: projects.locations.collections.engines.agents

리소스: 에이전트

미리 정의된 특정 작업을 실행합니다.

JSON 표현 
{
  "name": string,
  "displayName": string,
  "description": string,
  "icon": {
    object (Image)
  },
  "createTime": string,
  "updateTime": string,
  "authorizations": [
    string
  ],
  "authorizationConfig": {
    object (AuthorizationConfig)
  },
  "dataStoreSpecs": {
    object (DataStoreSpecs)
  },
  "state": enum (State),
  "toolSettings": {
    object (AgentToolSettings)
  },
  "languageCode": string,
  "starterPrompts": [
    {
      object (StarterPrompt)
    }
  ],
  "customPlaceholderText": string,

  // Union field definition can be only one of the following:
  "adkAgentDefinition": {
    object (AdkAgentDefinition)
  },
  "managedAgentDefinition": {
    object (ManagedAgentDefinition)
  },
  "a2aAgentDefinition": {
    object (A2AAgentDefinition)
  },
  "dialogflowAgentDefinition": {
    object (DialogflowAgentDefinition)
  }
  // End of list of possible types for union field definition.

  // Union field agent_state_reason can be only one of the following:
  "suspensionReason": string,
  "rejectionReason": string,
  "deploymentFailureReason": string
  // End of list of possible types for union field agent_state_reason.
}
필드
name

string

식별자. 에이전트의 리소스 이름입니다. 형식: projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}/agents/{agent} 또는 projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/agents/{agent}
displayName

string

필수 항목입니다. 에이전트의 표시 이름입니다. 이는 LLM이 사용자 쿼리에 응답할 에이전트를 자동으로 선택하는 데 사용될 수 있습니다.
description

string

필수 항목입니다. 인간이 읽을 수 있는 에이전트 설명입니다. 이는 LLM이 사용자 쿼리에 응답할 에이전트를 자동으로 선택하는 데 사용될 수 있습니다.
icon

object (Image)

(선택사항) UI에서 에이전트를 나타내는 아이콘입니다.
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"입니다.
authorizations[]
(deprecated)

string

(선택사항) 지원 중단됨: 대신 Agent.authorization_config을 사용하세요. 이 에이전트에 필요한 승인 목록입니다.
authorizationConfig

object (AuthorizationConfig)

(선택사항) 에이전트에 필요한 승인입니다.
dataStoreSpecs

object (DataStoreSpecs)

(선택사항) 에이전트와 연결된 DataStoreSpecs입니다. 이 필드를 설정하지 않으면 엔진의 모든 데이터 스토어가 사용됩니다.
state

enum (State)

출력 전용입니다. 에이전트의 수명 주기 상태입니다.
toolSettings
(deprecated)

object (AgentToolSettings)

(선택사항) 지원 중단됨: AgentCard 정의로의 마이그레이션이 계획되어 있습니다.
languageCode

string

(선택사항) description, displayName, starterPrompts 필드의 텍스트 언어 코드입니다.
starterPrompts[]

object (StarterPrompt)

(선택사항) 에이전트의 방문 페이지에 사용자에게 표시할 스타터 프롬프트 제안입니다.
customPlaceholderText

string

(선택사항) 사용자가 텍스트를 입력하기 전에 텍스트 상자에 표시되는 맞춤 자리표시자 텍스트입니다.
통합 필드 definition. 에이전트의 정의입니다. LINT.IfChange(definition) definition은 다음 중 하나여야 합니다.
adkAgentDefinition

object (AdkAgentDefinition)

(선택사항) 에이전트의 동작이 ADK 에이전트로 정의됩니다.
managedAgentDefinition

object (ManagedAgentDefinition)

(선택사항) Google 관리 에이전트의 동작입니다.
a2aAgentDefinition

object (A2AAgentDefinition)

(선택사항) 에이전트의 동작은 A2A 에이전트로 정의됩니다.
dialogflowAgentDefinition

object (DialogflowAgentDefinition)

(선택사항) 에이전트의 동작은 Dialogflow 에이전트로 정의됩니다.
통합 필드 agent_state_reason. 상담사가 현재 상태인 이유입니다. agent_state_reason은 다음 중 하나여야 합니다.
suspensionReason

string

출력 전용입니다. 상담사가 정지된 이유입니다. 상태가 SUSPENDED인 경우에만 설정됩니다.
rejectionReason

string

출력 전용입니다. 에이전트가 거부된 이유입니다. 상태가 비공개이고 거부를 통해 도달한 경우에만 설정됩니다.
deploymentFailureReason

string

출력 전용입니다. 에이전트 배포가 실패한 이유입니다. 상태가 DEPLOYMENT_FAILED인 경우에만 설정됩니다.

AdkAgentDefinition

ADK를 사용하고 Agent Engine (이전 명칭: Reasoning Engine)에 배포되는 에이전트의 정의를 저장합니다.

JSON 표현 
{
  "toolSettings": {
    object (AgentToolSettings)
  },
  "provisionedReasoningEngine": {
    object (ProvisionedReasoningEngine)
  },
  "authorizations": [
    string
  ]
}
필드
toolSettings

object (AgentToolSettings)

(선택사항) 에이전트가 플래너 LLM에 표시되는 방식을 정의하는 파라미터입니다.
provisionedReasoningEngine

object (ProvisionedReasoningEngine)

(선택사항) 에이전트가 연결된 추론 엔진입니다.
authorizations[]
(deprecated)

string

(선택사항) 지원 중단됨: 대신 Agent.authorizations을 사용하세요. 필요한 승인의 리소스 이름입니다. 사용자가 승인되지 않은 경우 서비스는 사용자가 브라우저에서 열고 승인해야 하는 여러 승인 URI를 반환합니다. 모든 승인이 부여되면 사용자가 쿼리를 다시 시도할 수 있으며 승인이 에이전트에게 전달됩니다.

형식: projects/{project}/locations/{location}/authorizations/{authorization}

AgentToolSettings

Agentspace 플래너 LLM에 에이전트를 나타내는 도구의 설정입니다.

JSON 표현 
{
  "toolDescription": string,
  "inputParameterName": string,
  "inputParameterDescription": string
}
필드
toolDescription

string

필수 항목입니다. 이는 LLM이 에이전트를 사용해야 하는 시기를 설명하는 데 사용할 수 있습니다.
inputParameterName

string

(선택사항) 함수 호출의 파라미터 이름입니다. 이 파라미터 이름은 파라미터에 포함될 것으로 예상되는 콘텐츠 유형(예: '질문', '명령어', 'searchQuery' 등)에 대한 힌트를 LLM에 제공합니다.
inputParameterDescription

string

(선택사항) 함수 호출의 파라미터 설명입니다. 이 설명은 파라미터에 대한 추가 정보(예: 전달될 것으로 예상되는 콘텐츠의 종류, 콘텐츠에 대해 수행해야 하는 작업)를 LLM에 제공합니다.

ProvisionedReasoningEngine

에이전트가 연결된 추론 엔진을 추적합니다. 이 메시지는 에이전트의 수명 주기를 추적하기 위한 것이 아닙니다. 대신 이미 추론 엔진에 배포된 에이전트에 연결하는 매개변수를 정의하는 데만 사용됩니다.

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

string

필수 항목입니다. 에이전트가 연결된 추론 엔진입니다. 형식: projects/{project}/locations/{location}/reasoningEngines/{reasoningEngine}

ManagedAgentDefinition

Google 관리 에이전트의 정의를 저장합니다.

JSON 표현 
{
  "toolSettings": {
    object (AgentToolSettings)
  },
  "authorizations": [
    string
  ],
  "deploymentInfo": {
    object (DeploymentInfo)
  },

  // Union field agent_config can be only one of the following:
  "dataScienceAgentConfig": {
    object (DataScienceAgentConfig)
  }
  // End of list of possible types for union field agent_config.
}
필드
toolSettings

object (AgentToolSettings)

(선택사항) 에이전트가 플래너 LLM에 표시되는 방식을 정의하는 파라미터입니다.
authorizations[]
(deprecated)

string

(선택사항) 지원 중단됨: 대신 Agent.authorizations을 사용하세요. 필요한 승인의 리소스 이름입니다. 사용자가 승인되지 않은 경우 서비스는 사용자가 브라우저에서 열고 승인해야 하는 여러 승인 URI를 반환합니다. 모든 승인이 부여되면 사용자가 쿼리를 다시 시도할 수 있으며 승인이 에이전트에게 전달됩니다.

형식: projects/{project}/locations/{location}/authorizations/{authorization}
deploymentInfo

object (DeploymentInfo)

출력 전용입니다. 에이전트의 자동 배포 정보입니다.
통합 필드 agent_config. 에이전트 유형별 구성입니다. agent_config은 다음 중 하나여야 합니다.
dataScienceAgentConfig

object (DataScienceAgentConfig)

(선택사항) Google 사전 제작 데이터 과학 에이전트에만 적용되는 구성입니다. 이 데이터 구조는 에이전트의 배포 및 요청 시간 구성을 저장하기 위한 것입니다.

DataScienceAgentConfig

Google 사전 제작 데이터 과학 에이전트에만 적용되는 구성입니다. 이 데이터 구조는 에이전트의 배포 및 요청 시간 구성을 저장하기 위한 것입니다.

JSON 표현 
{
  "bqProjectId": string,
  "bqDatasetId": string,
  "blocklistTables": [
    string
  ],
  "allowlistTables": [
    string
  ],
  "nlQueryConfig": {
    object (NlQueryConfig)
  }
}
필드
bqProjectId

string

필수 항목입니다. 데이터 세트가 있는 BigQuery 프로젝트 ID입니다.
bqDatasetId

string

필수 항목입니다. 에이전트에 사용할 BigQuery 데이터 세트 ID입니다. 데이터 세트는 bqProjectId로 지정된 프로젝트에 있어야 합니다.
blocklistTables[]

string

(선택사항) 에이전트가 사용하지 못하도록 차단할 BigQuery 테이블입니다.
allowlistTables[]

string

(선택사항) 에이전트가 사용할 수 있도록 허용할 BigQuery 테이블입니다.
nlQueryConfig

object (NlQueryConfig)

(선택사항) 고객이 제공한 구성입니다.

NlQueryConfig

자연어 번역을 SQL/Python 코드로 변환하는 데 필요한 고객 제공 구성을 정의합니다.

JSON 표현 
{
  "nl2sqlPrompt": string,
  "nl2pyPrompt": string,
  "nl2sqlExamples": [
    {
      object (Nl2SqlExample)
    }
  ],
  "schemaDescription": string,
  "bqSqlGenUseCustomPrompt": boolean
}
필드
nl2sqlPrompt

string

(선택사항) 고객이 제공한 NL2SQL 안내
nl2pyPrompt

string

(선택사항) 고객이 LLM에 데이터 분석을 위한 Python 코드를 작성하도록 지시했습니다.
nl2sqlExamples[]

object (Nl2SqlExample)

(선택사항) 고객이 입력과 예상 SQL을 모두 포함한 NL2SQL 예시를 제공했습니다.
schemaDescription

string

(선택사항) BigQuery 데이터 세트의 스키마에 대한 자연어 설명입니다.
bqSqlGenUseCustomPrompt

boolean

(선택사항) BigQuery SQL 생성 서비스에 맞춤 프롬프트를 사용할지 여부입니다.

Nl2SqlExample

단일 NL2SQL 예시

JSON 표현 
{
  "query": string,
  "expectedSql": string,
  "expectedResponse": string
}
필드
query

string

(선택사항) 답변할 자연어 질문입니다.
expectedSql

string

(선택사항) 예상되는 SQL 출력입니다.
expectedResponse

string

(선택사항) 질문에 대한 예상 응답입니다.

DeploymentInfo

에이전트의 자동 배포 정보입니다.

JSON 표현 
{
  "operation": string,
  "finishTime": string
}
필드
operation

string

출력 전용입니다. 배포의 장기 실행 작업 리소스입니다. 배포 상태를 폴링하는 데 사용할 수 있습니다. 배포가 완료되면 이 필드는 비어 있습니다. 배포가 실패하면 필드에 실패한 LRO의 리소스 이름이 포함되지만 작업 리소스 자체는 일정 시간이 지나면 자동으로 삭제됩니다.
finishTime

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"입니다.

A2AAgentDefinition

A2A를 사용하는 에이전트의 저장된 정의입니다.

JSON 표현 
{

  // Union field agent_card can be only one of the following:
  "jsonAgentCard": string,
  "remoteAgentCard": {
    object (RemoteAgentcard)
  }
  // End of list of possible types for union field agent_card.
}
필드
통합 필드 agent_card. 에이전트의 이름, 기능, 인증 정보 등을 저장합니다. agent_card은 다음 중 하나여야 합니다.
jsonAgentCard

string

(선택사항) 에이전트 카드는 JSON 문자열입니다.
remoteAgentCard

object (RemoteAgentcard)

(선택사항) 원격 에이전트 카드입니다.

RemoteAgentcard

원격으로 호스팅되는 에이전트 카드의 정의입니다.

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

string

필수 항목입니다. 상담사 카드의 URI입니다.

DialogflowAgentDefinition

Dialogflow 에이전트를 사용하는 에이전트의 저장된 정의입니다.

JSON 표현 
{
  "toolSettings": {
    object (AgentToolSettings)
  },
  "dialogflowAgent": string
}
필드
toolSettings

object (AgentToolSettings)

(선택사항) 에이전트가 플래너 LLM에 표시되는 방식을 정의하는 파라미터입니다.
dialogflowAgent

string

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

이미지

이미지를 나타냅니다.

JSON 표현 
{

  // Union field storage_method can be only one of the following:
  "uri": string,
  "content": string
  // End of list of possible types for union field storage_method.
}
필드
통합 필드 storage_method. URI 또는 base64 문자열로 인코딩된 콘텐츠일 수 있습니다. storage_method은 다음 중 하나여야 합니다.
uri

string

이미지 URI입니다.
content

string

Base64로 인코딩된 이미지 파일 콘텐츠입니다.

AuthorizationConfig

필요한 승인을 설명합니다.

JSON 표현 
{
  "toolAuthorizations": [
    string
  ],
  "agentAuthorization": string
}
필드
toolAuthorizations[]

string

(선택사항) 에이전트가 다른 리소스에 액세스하는 데 필요한 승인 목록입니다. 인증 토큰은 요청 본문의 일부로 에이전트에 전달됩니다.
agentAuthorization

string

(선택사항) 에이전트를 호출하는 데 필요한 승인입니다. 인증 토큰은 요청 인증 헤더의 일부로 에이전트에게 전달됩니다.

DataStoreSpecs

데이터 스토어 사양 세트를 나타냅니다.

JSON 표현 
{
  "specs": [
    {
      object (DataStoreSpec)
    }
  ]
}
필드
specs[]

object (DataStoreSpec)

(선택사항) 검색 호출에서 필터링할 DataStore와 해당 데이터 저장소의 구성을 정의하는 사양입니다. 데이터 스토어가 여러 개인 Engine에만 적용됩니다.

주

에이전트의 수명 주기 상태에 가능한 값입니다.

열거형
STATE_UNSPECIFIED 상태가 지정되지 않았습니다.
CONFIGURED 에이전트가 구성되었지만 아직 배포가 트리거되지 않았습니다.
DEPLOYING 에이전트가 배포되고 있습니다.
DISABLED 에이전트는 관리자만 사용할 수 있습니다.
DEPLOYMENT_FAILED 에이전트 배포에 실패했습니다.
PRIVATE 에이전트는 생성자만 사용할 수 있습니다.
ENABLED 액세스 권한이 있는 사용자가 에이전트를 사용할 수 있습니다.
SUSPENDED 액세스 권한이 있는 사용자에게는 표시되지만 에이전트를 일시적으로 사용할 수 없습니다.

StarterPrompt

에이전트의 방문 페이지에 사용자에게 표시할 시작 프롬프트 제안입니다.

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

string

필수 항목입니다. 시작 프롬프트의 텍스트입니다.

메서드

create

 Agent를 만듭니다.

delete

 Agent를 삭제합니다.

deploy

 Agent을 배포합니다.

get

 Agent을 가져옵니다.

getAgentView

 주어진 Agent에 대해 AgentView를 반환합니다. 여기에는 에이전트에 관한 추가 정보가 포함됩니다.

list

 호출자가 만든 Assistant의 모든 Agent를 나열합니다.

patch

 Agent 업데이트