Agent Runtime에서 호스팅되는 ADK 에이전트 등록 및 관리

이 페이지에서는 관리자가 Gemini Enterprise 웹 앱에서 사용할 수 있도록 Agent Runtime에서 ADK 에이전트를 등록하는 방법을 설명합니다.

Agent Runtime에 배포된 ADK 에이전트의 경우 Agent Platform의 Agents CLI 명령 하나를 사용하여 에이전트를 Gemini Enterprise에 등록할 수 있습니다.

Agent Runtime에서 호스팅되는 ADK 에이전트를 Gemini Enterprise 앱에 등록하고 Gemini Enterprise 웹 앱의 최종 사용자가 이러한 에이전트를 사용할 수 있도록 하면 다음이 적용됩니다.

  • Agent Runtime 서비스는 에이전트 쿼리를 처리합니다.

  • Agent Runtime ML 처리 약관이 적용됩니다. 자세한 내용은 에이전트 런타임 제한사항을 참고하세요.

다음 표에서는 안전하고 제어된 배포와 사용을 보장하기 위해 ADK 에이전트가 관리되는 방법을 설명합니다.

상담사 거버넌스 설명
보안 통신 에이전트 런타임과 Gemini Enterprise 간의 연결은 VPC 서비스 제어 (VPC-SC)를 준수하여 안전한 데이터 교환을 보장합니다.
교차 프로젝트 상담사 지원 다른 Google Cloud에서 호스팅되는 ADK 에이전트를 연결할 수 있습니다. Gemini Enterprise는 이러한 프로젝트 간 연결에 Google Cloud의 보안 비공개 네트워킹을 사용합니다. 자세한 내용은 교차 프로젝트 ADK 에이전트 액세스 구성을 참고하세요.
맞춤형 상호작용 ADK 에이전트는 Gemini Enterprise로부터 사용자의 이메일 주소를 수신합니다. 이를 통해 상담사는 개별 사용자를 인식하고 ID 및 권한을 기반으로 맞춤 응답을 제공할 수 있습니다.

시작하기 전에

다음 항목이 있는지 확인합니다.

  • Gemini Enterprise 관리자 역할

  • Discovery Engine API 사용 설정 Google Cloud프로젝트에 Discovery Engine API를 사용 설정하려면 Google Cloud 콘솔에서 Discovery Engine API 페이지로 이동합니다.

    Discovery Engine API로 이동

  • 기존 Gemini Enterprise 앱. 앱을 만들려면 앱 만들기를 참조하세요.

  • Agent Runtime에서 호스팅되는 ADK 에이전트. 자세한 내용은 에이전트 개발 키트 개요를 참조하세요.

    • 에이전트가 없는 경우 adk-samples GitHub 저장소의 단계에 따라 fun_facts 에이전트를 에이전트 런타임에 배포합니다. 그런 다음 Gemini Enterprise에 에이전트를 등록할 수 있습니다.

  • ADK 에이전트가 Gemini Enterprise 앱과 다른 Google Cloud 프로젝트에 호스팅된 경우 필요한 권한을 부여해야 합니다. 자세한 내용은 프로젝트 간 ADK 에이전트 액세스 권한 부여를 참고하세요.

승인 세부정보 구성 (선택사항)

다음 단계에 따라 승인 세부정보를 가져오세요.

  1. Google Cloud 콘솔의 API 및 서비스 페이지에서 사용자 인증 정보 페이지로 이동합니다.

    사용자 인증 정보로 이동

  2. 에이전트가 액세스할 데이터 소스가 있는 Google Cloud 프로젝트를 선택합니다. 예를 들어 에이전트가 쿼리할 BigQuery 데이터 세트가 포함된 프로젝트를 선택합니다.

  3. 사용자 인증 정보 만들기를 클릭하고 OAuth 클라이언트 ID를 선택합니다.

  4. 애플리케이션 유형에서 웹 애플리케이션을 선택합니다.

  5. 승인된 리디렉션 URI 섹션에 다음 URI를 추가합니다.

    • https://vertexaisearch.cloud.google.com/oauth-redirect
    • https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

  6. 만들기를 클릭합니다.

  7. OAuth 클라이언트 생성됨 패널에서 JSON 다운로드를 클릭합니다. 다운로드한 JSON에는 선택한Google Cloud 프로젝트의 Client ID, Authorization URI, Token URI, Client secret이 포함됩니다. 승인 리소스를 만들려면 이러한 세부정보가 필요합니다.

ADK 에이전트를 Gemini Enterprise에 등록

Google Cloud 콘솔 또는 REST API를 사용하여 ADK 에이전트를 Gemini Enterprise에 등록할 수 있습니다. 이렇게 하면 Gemini Enterprise 앱 내에서 사용자가 에이전트를 사용할 수 있습니다.

콘솔

Google Cloud 콘솔을 사용하여 ADK 에이전트를 등록하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

    Gemini Enterprise

  2. 에이전트를 등록할 앱의 이름을 클릭합니다.

  3. 에이전트를 클릭합니다. 에이전트 페이지가 표시됩니다.

  4. 에이전트 추가를 클릭합니다. 상담사 추가 패널이 표시됩니다.

  5. Agent Runtime을 통한 커스텀 에이전트의 추가를 클릭합니다. 승인 페이지가 표시됩니다.

  6. 에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스하도록 하려면 각 리소스에 승인이 필요합니다. 단일 리소스에 대한 승인을 설정하려면 다음 단계를 따르세요.

    1. 승인 추가를 클릭합니다.

    2. 승인 이름에 고유한 값을 입력합니다. ID는 이름을 기반으로 생성되며 나중에 변경할 수 없습니다.

    3. 인증 세부정보 구성 (선택사항)에서 생성한 값을 다음 필드에 입력합니다.

      1. 클라이언트 ID 필드에 값을 입력합니다.

      2. 클라이언트 보안 비밀 필드에 값을 입력합니다.

      3. 토큰 URI 필드에 값을 입력합니다.

      4. 인증 URI 필드에 값을 입력합니다. OAuth 사용자 인증 정보 JSON 파일의 세부정보를 사용하여 승인 URI를 구성합니다. 다음 템플릿을 복사하고 자리표시자를 특정 값으로 바꿉니다.

        https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

      5. 완료를 클릭합니다.

  7. 다음을 클릭합니다.

  8. 에이전트를 구성하려면 다음 단계를 따르세요.

    1. 에이전트 이름 필드에 이름을 입력합니다. 이 값은 Gemini Enterprise 웹 앱에 에이전트의 표시 이름으로 표시됩니다.

    2. 에이전트 설명 필드에 설명을 입력합니다. 이 값은 사용자 쿼리에 대한 응답으로 사용자의 에이전트를 호출할지 여부를 결정하기 위해 LLM에서 사용됩니다.

    3. Agent Runtime 리소스 경로를 입력합니다. 리소스 경로의 형식은 다음과 같습니다.

       projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

      Agent Runtime에서 호스팅되는 에이전트를 나열하고 리소스 경로를 가져오는 방법에 대한 자세한 내용은 배포된 에이전트 나열을 참고하세요.

    4. 만들기를 클릭합니다.

REST

REST API를 사용하여 ADK 에이전트를 등록하려면 다음 단계를 따르세요.

Gemini Enterprise에 승인 리소스 추가 (선택사항)

에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스해야 하는 경우 다음 명령어를 실행하여 승인 세부정보 구성 (선택사항) 섹션에서 만든 승인 리소스를 Gemini Enterprise에 등록합니다.

curl -X POST \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_NUMBER/locations/LOCATION/authorizations?authorizationId=AUTH_ID" \
   -d '{
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/authorizations/AUTH_ID",
      "serverSideOauth2": {
         "clientId": "OAUTH_CLIENT_ID",
         "clientSecret": "OAUTH_CLIENT_SECRET",
         "authorizationUri": "OAUTH_AUTH_URI",
         "tokenUri": "OAUTH_TOKEN_URI"
      }
   }'

다음을 바꿉니다.

  • PROJECT_ID: 프로젝트의 ID입니다.
  • PROJECT_NUMBER: Google Cloud 프로젝트 수
  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • LOCATION: 데이터 스토어의 멀티 리전입니다(global, us 또는 eu).
  • AUTH_ID: 승인 리소스의 ID입니다. 이는 사용자가 정의하는 임의의 영숫자 ID입니다. OAuth 지원이 필요한 에이전트를 등록할 때 이 ID를 나중에 참조해야 합니다.
  • OAUTH_CLIENT_ID: OAuth 사용자 인증 정보를 만들 때 획득한 OAuth 2.0 클라이언트 식별자입니다.
  • OAUTH_CLIENT_SECRET: OAuth 사용자 인증 정보를 만들 때 획득한 OAuth 2.0 클라이언트 보안 비밀번호입니다.

  • OAUTH_AUTH_URI: 승인 URI입니다. 앱을 승인하려면 OAuth 사용자 인증 정보 JSON 파일의 세부정보를 사용하여 특정 승인 URI를 구성합니다. 다음 템플릿을 복사하고 자리표시자를 특정 값으로 바꿉니다.

    https://accounts.google.com/o/oauth2/v2/auth?client_id=OAUTH_CLIENT_ID&redirect_uri=https%3A%2F%2Fvertexaisearch.cloud.google.com%2Fstatic%2Foauth%2Foauth.html&scope=YOUR_CUSTOM_SCOPES&include_granted_scopes=true&response_type=code&access_type=offline&prompt=consent

    • YOUR_CUSTOM_SCOPES: 필요한 범위를 추가할 수 있습니다. 예를 들어 다음 OAuth 범위 문자열은 Google Drive 및 Google Docs에 대한 읽기 전용 액세스를 요청합니다.

      scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdocuments.readonly

  • OAUTH_TOKEN_URI: OAuth 사용자 인증 정보를 만들 때 획득한 토큰 URI입니다.

승인 URI 매개변수에 관한 자세한 정보입니다.

URI가 올바르게 작동하는지 확인하려면 다음 필드를 확인하세요.

매개변수 값 또는 작업
client_id 다운로드한 JSON에 있는 client_id로 바꿉니다.
redirect_uri 변경하지 마세요. https://vertexaisearch.cloud.google.com/static/oauth/oauth.html이어야 합니다.
scope

앱이 사용자를 대신하여 액세스해야 하는 Google API 범위를 나열합니다. 예를 들어 BigQuery에 대한 액세스 권한을 부여하려면 https://www.googleapis.com/auth/bigquery 범위를 사용하고 Google Docs에 대한 읽기 전용 액세스 권한을 부여하려면 https://www.googleapis.com/auth/documents.readonly을 사용합니다.

여러 범위를 사용하는 경우 공백으로 구분합니다. 공백은 URL에서 %20이 됩니다.
include_granted_scopes true이어야 합니다.
response_type 승인 코드를 받으려면 code여야 합니다.
access_type 갱신 토큰을 수신할 수 있도록 offline로 설정합니다.
prompt 사용자에게 항상 동의 화면이 표시되도록 하려면 consent로 설정합니다.

ADK 에이전트 등록

이 코드 샘플은 ADK 에이전트를 등록하는 방법을 보여줍니다.

   curl -X POST \
      -H "Authorization: Bearer $(gcloud auth print-access-token)" \
      -H "Content-Type: application/json" \
      -H "X-Goog-User-Project: PROJECT_ID" \
      "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents" \
      -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "icon": {
            "uri": "ICON_URI"
         },
         "adkAgentDefinition": {
            "provisionedReasoningEngine": {
               "reasoningEngine": "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngines/RESOURCE_ID"
            }
         },
         "authorizationConfig": {
            "toolAuthorizations": [
               "projects/PROJECT_NUMBER/locations/global/authorizations/AUTH_ID"
            ]
         }
      }'

변수를 다음 값으로 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.

    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.

  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

  • PROJECT_NUMBER: Google Cloud 프로젝트 수

  • APP_ID: Gemini Enterprise 앱의 고유 식별자입니다.

  • DESCRIPTION: Gemini Enterprise에 표시되는 에이전트의 설명입니다.

  • ICON_URI: 에이전트 이름 근처에 표시할 아이콘의 공개 URI입니다. 또는 Base64로 인코딩된 이미지 파일 콘텐츠를 전달할 수 있으며, 이 경우 icon.content를 사용합니다.

    • RESOURCE_ID: ADK 에이전트가 배포된 Agent Runtime 엔드포인트의 ID입니다. Agent Runtime에서 호스팅되는 에이전트를 나열하고 리소스 ID를 가져오는 방법에 대한 자세한 내용은 배포된 에이전트 나열을 참고하세요.

    • RESOURCE_LOCATION: Agent Runtime 엔드포인트의 클라우드 위치입니다. 자세한 내용은 Agent Runtime 위치를 참고하세요.

    • authorization_config: 승인 세부정보를 획득했고 에이전트가 사용자를 대신하여 Google Cloud 리소스에 액세스하도록 하려면 JSON 리소스에 authorization_config 필드를 추가합니다.

사용자와 에이전트 공유

사용자가 Gemini Enterprise 웹 앱을 사용하여 에이전트에 액세스하도록 허용하려면 에이전트 공유하기를 참고하세요.

앱에 연결된 에이전트 나열

다음 코드 샘플은 앱에 연결된 모든 에이전트의 세부정보를 가져오는 방법을 보여줍니다.

REST 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents"

변수를 다음 값으로 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
  • LOCATION: 앱의 멀티 리전입니다(global, us 또는 eu).
  • APP_ID: Gemini Enterprise 앱의 ID입니다.

에이전트가 Google에서 사전 빌드되지 않은 경우 응답의 처음 몇 줄에 name 필드가 포함됩니다. 이 필드의 값에는 경로 끝에 있는 에이전트 ID가 포함됩니다. 예를 들어 다음 응답에서 에이전트 ID는 12345678901234567890입니다.

{
"name": "projects/123456/locations/global/collections/default_collection/engines/my-app/assistants/default_assistant/agents/12345678901234567890",
...
}

ADK 에이전트 세부정보 보기

다음 코드 샘플은 Gemini Enterprise에 등록된 에이전트의 세부정보를 가져오는 방법을 보여줍니다.

REST 

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

변수를 다음 값으로 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
  • LOCATION: 앱의 멀티 리전입니다(global, us 또는 eu).
  • APP_ID: Gemini Enterprise 앱의 ID입니다.
  • AGENT_ID: 에이전트의 ID입니다. 앱에 연결된 에이전트를 나열하여 에이전트 ID를 확인할 수 있습니다.

ADK 에이전트 업데이트

Google Cloud 콘솔 또는 REST API를 사용하여 Gemini Enterprise에 등록된 기존 에이전트의 세부정보를 수정할 수 있습니다.

콘솔

Google Cloud 콘솔을 사용하여 에이전트를 업데이트하려면 다음 단계를 따르세요.

  1. Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.

    Gemini Enterprise

  2. 업데이트할 에이전트가 포함된 앱의 이름을 클릭합니다.

  3. 에이전트를 클릭합니다.

  4. 업데이트할 Agent Runtime 에이전트의 이름을 클릭한 다음 수정을 클릭합니다.

  5. 표시 이름, 설명 또는 Agent Runtime 추론 엔진을 업데이트합니다.

    리소스 경로의 형식은 다음과 같습니다.

    projects/PROJECT_ID/locations/LOCATION/reasoningEngines/RESOURCE_ID

    Agent Runtime에서 호스팅되는 에이전트를 나열하고 리소스 경로를 가져오는 방법에 대한 자세한 내용은 배포된 에이전트 나열을 참고하세요.

  6. 저장을 클릭합니다.

REST

에이전트 등록 중에 모든 필드를 업데이트할 수 있습니다. 하지만 다음 필드는 반드시 업데이트해야 합니다.

  • displayName
  • description

  • reasoningEngine

    이 코드 샘플은 기존 ADK 에이전트의 등록을 업데이트하는 방법을 보여줍니다.

    curl -X PATCH \
   -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   -H "Content-Type: application/json" \
   -H "X-Goog-User-Project: PROJECT_ID" \
   "https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/AGENT_RESOURCE_NAME" \
   -d '{
         "displayName": "DISPLAY_NAME",
         "description": "DESCRIPTION",
         "adkAgentDefinition": {
         "provisionedReasoningEngine": {
            "reasoningEngine":
            "projects/PROJECT_ID/locations/RESOURCE_LOCATION/reasoningEngine
            s/RESOURCE_ID"
         },
      }
   }'

    변수를 다음 값으로 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.

    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.

  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.

  • AGENT_RESOURCE_NAME: 업데이트할 에이전트 등록의 리소스 이름입니다.

  • DISPLAY_NAME: 필수 항목입니다. Gemini Enterprise에 표시되는 에이전트의 사용자 친화적인 이름입니다.

  • DESCRIPTION: 필수 항목입니다. Gemini Enterprise의 사용자에게 표시되는 에이전트의 기능을 간략하게 설명합니다.

  • RESOURCE_LOCATION: Agent Runtime 엔드포인트의 클라우드 위치입니다. 자세한 내용은 Agent Runtime 위치를 참고하세요.

  • RESOURCE_ID: ADK 에이전트가 배포된 Agent Runtime 엔드포인트의 ID입니다. Agent Runtime에서 호스팅되는 에이전트를 나열하고 리소스 ID를 가져오는 방법에 대한 자세한 내용은 배포된 에이전트 나열을 참고하세요.

ADK 에이전트 삭제

다음 코드 샘플은 앱에 연결된 에이전트를 삭제하는 방법을 보여줍니다.

REST 

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1alpha/projects/PROJECT_ID/locations/LOCATION/collections/default_collection/engines/APP_ID/assistants/default_assistant/agents/AGENT_ID"

변수를 다음 값으로 바꿉니다.

  • ENDPOINT_LOCATION: API 요청의 멀티 리전입니다. 다음 값 중 하나를 지정합니다.
    • 미국 멀티 리전의 경우 us
    • EU 멀티 리전의 경우 eu
    • 전역 위치의 경우 global
    자세한 내용은 데이터 스토어의 멀티 리전 지정을 참조하세요.
  • PROJECT_ID: Google Cloud 프로젝트의 ID입니다.
  • LOCATION: 앱의 멀티 리전입니다(global, us 또는 eu).
  • APP_ID: Gemini Enterprise 앱의 ID입니다.
  • AGENT_ID: 에이전트의 ID입니다. 앱에 연결된 에이전트를 나열하여 에이전트 ID를 확인할 수 있습니다.

Agent Runtime 위치

에이전트를 등록하거나 업데이트할 때 Agent Runtime 위치가 Gemini Enterprise 앱의 위치와 호환되어야 합니다. 위치가 일치하지 않으면 오류가 발생합니다.

호환성 요구사항은 다음 표를 참고하세요.

Gemini Enterprise 앱 위치 허용된 Agent Runtime 위치
global 지원되는 모든 Google Cloud 리전
us us-로 시작하는 모든 지역(예: us-central1 또는 us-east4)
eu europe-로 시작하는 모든 지역(예: europe-west1 또는 europe-west3)