에이전트 Fleet을 효과적으로 관리하려면 워크로드가 발전함에 따라 서비스 세부정보를 보고 업데이트하고, 메타데이터를 재정의하거나, 더 이상 사용되지 않는 에이전트를 삭제하여 레지스트리를 정확하게 유지해야 합니다.
이 문서에서는 등록된 에이전트의 세부정보와 구성을 보고 수정하는 방법을 자세히 설명합니다.
시작하기 전에
에이전트를 관리하기 전에 에이전트가 에이전트 레지스트리에 등록되어 있는지 확인하세요. 이러한 작업을 수행하려면 프로젝트 ID 도 필요합니다.
이 문서에서 gcloud CLI 명령어를 사용하려면 Google Cloud CLI 환경을 설정해야 합니다.
필요한 역할
에이전트 레지스트리에서 등록된 에이전트를 관리하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트의 에이전트 레지스트리 API 편집자 (roles/agentregistry.editor) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
사용 가능한 에이전트 알아보기
에이전트를 등록한 후 환경에서 에이전트를 검색하고 엔드포인트, 기술, 연결된 메타데이터와 같은 세부 구성을 볼 수 있습니다.
에이전트 나열 및 보기
환경에 등록된 모든 에이전트를 나열하고 엔드포인트, 기술, 연결된 메타데이터와 같은 세부 구성을 볼 수 있습니다.
콘솔
콘솔에서 에이전트 레지스트리로 이동합니다. Google Cloud
프로젝트 선택 도구에서 에이전트 레지스트리를 Google Cloud 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
페이지에 등록된 모든 에이전트 목록이 표시됩니다. 목록에는 에이전트의 이름, 식별자, 유형, 설명, 버전, 런타임, 위치가 포함됩니다.
에이전트의 전체 세부정보를 보려면 에이전트 이름을 클릭합니다.
gcloud
특정 위치의 모든 에이전트를 나열하려면 agents list 명령어를 사용합니다.
gcloud alpha agent-registry agents list \
--project=PROJECT_ID \
--location=REGION
다음을 바꿉니다.
PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.
등록된 에이전트 필터링
에이전트가 여러 개 있거나 특정 에이전트의 등록을 확인하려면 에이전트의 메타데이터를 기준으로 목록을 필터링하면 됩니다.
콘솔
콘솔에서 에이전트 레지스트리로 이동합니다. Google Cloud
프로젝트 선택 도구에서 에이전트 레지스트리를 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
프로젝트 선택 도구에서 에이전트 레지스트리를 Google Cloud 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
페이지에 등록된 모든 에이전트 목록이 표시됩니다. 목록에는 에이전트의 이름, 식별자, 유형, 설명, 버전, 런타임, 위치가 포함됩니다.
보려는 에이전트의 이름을 클릭합니다.
세부정보 페이지에는 에이전트 세부정보를 위한 탭이 포함되어 있습니다.
해당 탭을 클릭하여 특정 에이전트 세부정보를 봅니다.
사용할 수 있는 기능은 런타임에 따라 다릅니다. **세션** , **플레이그라운드** , **메모리** , **평가** 와 같은 탭은 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: 레지스트리 리전입니다.
다음 단계
- 토폴로지 그래프를 사용하여 에이전트 관계를 보는 방법을 알아봅니다.
- 자연어 쿼리를 사용하여 에이전트와 도구를 검색하는 방법 을 알아봅니다.