에이전트의 Fleet을 효과적으로 관리하려면 워크로드가 진화함에 따라 에이전트 세부정보를 보고 업데이트하고, 메타데이터를 재정의하거나, 더 이상 사용하지 않는 에이전트를 삭제하여 레지스트리를 정확하게 유지해야 합니다.
이 문서에서는 등록된 에이전트의 세부정보와 구성을 보고 수정하는 방법을 자세히 설명합니다.
시작하기 전에
에이전트를 관리하기 전에 에이전트가 에이전트 레지스트리에 등록되어 있는지 확인하세요. 이러한 작업을 수행하려면 프로젝트 ID도 필요합니다.
이 문서에서 gcloud CLI 명령어를 사용하려면 Google Cloud CLI 환경을 설정해야 합니다.
필요한 역할
에이전트 레지스트리에서 등록된 에이전트를 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 에이전트 레지스트리 API 편집자 (roles/agentregistry.editor) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
사용 가능한 에이전트 살펴보기
에이전트를 등록한 후 환경에서 에이전트를 검색하고 엔드포인트, 기술, 연결된 메타데이터와 같은 세부 구성을 볼 수 있습니다.
에이전트 나열 및 보기
환경에 등록된 모든 에이전트를 나열하고 엔드포인트, 기술, 연결된 메타데이터와 같은 세부 구성 정보를 볼 수 있습니다.
콘솔
Google Cloud 콘솔에서 Agent Registry로 이동합니다.
프로젝트 선택 도구에서 Google Cloud 에이전트 레지스트리를 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
페이지에 등록된 모든 에이전트 목록이 표시됩니다. 목록에는 에이전트의 이름, 식별자, 유형, 설명, 버전, 런타임, 위치가 포함됩니다.
에이전트의 전체 세부정보를 보려면 에이전트 이름을 클릭합니다.
gcloud
특정 위치의 모든 에이전트를 나열하려면 agents list 명령어를 사용합니다.
gcloud alpha agent-registry agents list \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
등록된 에이전트 필터링
에이전트가 여러 명인 경우 또는 특정 에이전트의 등록을 확인하려면 에이전트의 메타데이터로 목록을 필터링하면 됩니다.
콘솔
Google Cloud 콘솔에서 Agent Registry로 이동합니다.
프로젝트 선택 도구에서 Google Cloud 에이전트 레지스트리를 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
페이지에 등록된 모든 에이전트 목록이 표시됩니다. 목록에는 에이전트의 이름, 식별자, 유형, 설명, 버전, 런타임, 위치가 포함됩니다.
에이전트의 위치 또는 런타임 리소스로 목록을 필터링합니다.
- 위치를 기준으로 필터링하려면 위치 메뉴를 클릭하고 필터링할 위치를 선택한 다음 적용을 클릭합니다.
- 런타임별로 필터링하려면 런타임 메뉴를 클릭하고 필터링할 런타임을 선택한 다음 적용을 클릭합니다.
페이지에 선택한 조건에 따라 필터링된 등록된 상담사 목록이 표시됩니다.
gcloud
--filter 플래그를 사용하여 특정 메타데이터와 일치하는 리소스만 반환하도록 에이전트 목록을 필터링합니다.
gcloud alpha agent-registry agents list \
--project=PROJECT_ID \
--location=REGION \
--filter="FILTER_EXPRESSION"
FILTER_EXPRESSION을 필터링하려는 상담사의 필터 표현식으로 바꿉니다. 예를 들어 다음 필터를 사용할 수 있습니다.
- 표시 이름으로 필터링하려면
displayName='DISPLAY_NAME'를 사용하세요. - 전역 고유 식별자 (URN)로 검색하려면
agentId='urn:agent:AGENT_URN'를 사용하세요.
에이전트의 세부정보 보기
프로토콜, 기술, ID를 비롯한 특정 에이전트의 세부정보를 확인합니다.
콘솔
Google Cloud 콘솔에서 Agent Registry로 이동합니다.
프로젝트 선택 도구에서 Google Cloud 에이전트 레지스트리를 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
페이지에 등록된 모든 에이전트 목록이 표시됩니다. 목록에는 에이전트의 이름, 식별자, 유형, 설명, 버전, 런타임, 위치가 포함됩니다.
보려는 상담사의 이름을 클릭합니다.
세부정보 페이지에는 에이전트 세부정보 탭이 포함되어 있습니다.
해당 탭을 클릭하여 특정 상담사 세부정보를 확인합니다.
기능 사용 가능 여부는 런타임에 따라 다릅니다. 세션, Playground, 메모리, 평가와 같은 탭은 Vertex AI Agent Engine과 같은 관리형 런타임에서 빌드된 에이전트에 표시되는 특정 기능입니다.
- 개요: 에이전트의 이름, 식별자, 위치, 설명, 런타임을 비롯한 에이전트의 핵심 세부정보입니다. 개요에는 토폴로지 그래프에서 쿼리를 빌드하는 데 필요한 기술과 리소스 URI도 표시됩니다.
- 관측 가능성: 지연 시간, 트래픽, 오류, 토큰 사용량과 같은 애플리케이션 중심의 인사이트입니다. 이 탭은 Google Cloud Observability 도구와 통합되어 실시간 성능 측정항목과 시스템 수준 사용률을 표시하므로 비용과 사용자 환경을 관리하는 데 도움이 됩니다. 자세한 내용은 관측 가능성 개요를 참고하세요.
- 트레이스: 복잡한 멀티 에이전트 추론 루프 또는 도구 호출 오류를 실시간으로 디버그하기 위해 입력 및 어시스턴트 메시지의 세부 형식 지정을 포함하여 대화의 정확한 경로를 단계별로 보여줍니다. 자세한 내용은 에이전트 trace 보기를 참고하세요.
- 보안: 콘텐츠 정책 위반, 데이터 유출 위험, 규정 준수 평가를 비롯한 Model Armor 및 Security Command Center의 발견 항목 보안에 대한 자세한 내용은 보안 결과 보기를 참고하세요.
- 토폴로지: 에이전트, 할당된 에이전트 게이트웨이, 상호작용하는 MCP 서버 간의 관계 및 트래픽 흐름을 시각적으로 보여주는 지도입니다. 에이전트 게이트웨이에 대한 자세한 내용은 에이전트 게이트웨이 개요를 참고하세요. 토폴로지에 대한 자세한 내용은 등록된 에이전트의 그래프 보기를 참고하세요.
- ID: 정책 시행에 사용되는 에이전트 주 구성원입니다. 이 ID는 예를 들어 도구 및 리소스에 대한 인증을 위해 인증 제공업체 바인딩을 구성하는 데 사용됩니다.
- 세션: 지속적인 대화 기록 및 에이전트와의 활성 상호작용 추적
- 플레이그라운드: 에이전트의 동작을 테스트하는 직접 채팅 인터페이스입니다.
- 메모리: 에이전트와의 이전 대화에서 세부정보를 생성하거나 불러와 상호작용 전반에서 컨텍스트를 유지하는 장기 맞춤설정 기능입니다.
- 평가: 모든 에이전트 평가 작업의 세부정보입니다. 이 탭에서는 새 평가 작업을 만들고, 측정항목을 업로드하고, 실시간 트래픽 또는 합성 시뮬레이션에 대해 에이전트의 인지 성능과 모델 신뢰성을 평가할 수 있습니다.
gcloud
특정 에이전트의 자세한 메타데이터를 보려면 agents describe 명령어를 사용합니다.
gcloud alpha agent-registry agents describe AGENT_NAME \
--project=PROJECT_ID \
--location=REGION
AGENT_NAME을 에이전트 이름으로 바꿉니다(예: my-custom-agent).
에이전트 메타데이터 및 엔드포인트 업데이트
에이전트의 런타임 URL이 변경되거나 표시 이름, 설명 또는 사양을 재정의하려면 에이전트 메타데이터를 업데이트하면 됩니다.
Agent Registry API의 경우 Agent 리소스가 검색에 사용됩니다. 따라서 등록된 Service 리소스를 직접 업데이트해야 합니다.
특정 플래그와 함께 Google Cloud CLI를 사용하여 에이전트의 매개변수를 수정합니다.
표시 이름 및 설명 업데이트:
--display-name및--description플래그를 사용합니다. 예를 들면 다음과 같습니다.gcloud alpha agent-registry services update AGENT_NAME \ --project=PROJECT_ID \ --location=REGION \ --display-name="New display name" \ --description="Updated description of the agent's purpose."다음을 바꿉니다.
AGENT_NAME: 에이전트의 이름입니다(예:my-support-agent).PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
엔드포인트 URL 업데이트:
--interfaces플래그를 사용하여 새 엔드포인트를 지정합니다(예:gcloud alpha agent-registry services update AGENT_NAME \ --project=PROJECT_ID \ --location=REGION \ --interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL다음을 바꿉니다.
ENDPOINT_URL: 새 에이전트 엔드포인트 URL입니다(예:https://new-api.example.com/agent).PROTOCOL: 엔드포인트의 프로토콜 바인딩입니다. 유효한 값은HTTP_JSON,GRPC또는JSONRPC입니다.
에이전트 사양 업데이트: 새 에이전트 카드가 있는 경우와 같이
--agent-spec-content플래그를 사용합니다.gcloud alpha agent-registry services update AGENT_NAME \ --project=PROJECT_ID \ --location=REGION \ --agent-spec-content=@AGENT_SPECAGENT_SPEC을 새 에이전트 사양의 이름으로 바꿉니다(예:new-agent-card.json).
에이전트 삭제
에이전트 레지스트리에 자동으로 등록된 에이전트를 삭제하려면 특정 Google Cloud 런타임에서 기본 에이전트를 삭제해야 합니다. 그러면 에이전트가 레지스트리에서 자동으로 삭제됩니다.
레지스트리에서 수동으로 등록된 에이전트를 삭제하려면 기본 Service 리소스를 삭제해야 합니다. 이 작업은 검색 결과에서 에이전트를 삭제하고 다른 도구에서 에이전트를 검색할 수 없도록 합니다.
gcloud alpha agent-registry services delete AGENT_NAME \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
AGENT_NAME: 삭제하려는 에이전트의 이름입니다(예:my-support-agent).PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
다음 단계
- 토폴로지 그래프를 사용하여 에이전트 관계를 확인하는 방법을 알아봅니다.
- 자연어 쿼리를 사용하여 에이전트와 도구를 검색하는 방법을 알아보세요.