외부에서 호스팅되거나 지원되지 않는 런타임에서 실행되는 에이전트의 경우 에이전트 레지스트리에 수동으로 등록해야 합니다. Google Cloud 이 문서에서는 에이전트 레지스트리에 에이전트를 수동으로 등록하는 방법을 보여줍니다.
시작하기 전에
시작하기 전에 에이전트 레지스트리를 설정합니다. 이러한 작업을 수행하려면 프로젝트 ID 가 필요합니다.
이 문서에서 Google Cloud CLI 명령어를 사용하려면 gcloud CLI 환경을 설정해야 합니다.
필요한 역할
에이전트 레지스트리에 에이전트를 수동으로 등록하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 에이전트 레지스트리 API 편집기 (roles/agentregistry.editor) IAM 역할을 부여해 달라고 요청하세요.
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
A2A 호환 에이전트 등록
원격 에이전트가 Agent2Agent (A2A) 사양을 구현하는 경우,
에이전트 레지스트리를 에이전트의 agent-card.json 페이로드로 안내합니다. 레지스트리는
에이전트 카드를
자동으로 동기화하고
검색을 위해 에이전트의 사용 가능한 기술을 색인 생성합니다.
다음 단계에 따라 에이전트를 등록합니다.
콘솔
콘솔에서 에이전트 레지스트리로 이동합니다. Google Cloud
프로젝트 선택 도구에서 에이전트 레지스트리를 Google Cloud 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
에이전트 추가 를 클릭합니다.
에이전트 세부정보 패널에서 다음 세부정보를 입력합니다.
- 유형: A2A 를 선택합니다.
- 리전: 에이전트를 등록할 지리적 위치를 선택합니다.
다음 옵션 중 하나를 선택합니다.
- 리소스 URI를 사용하여 에이전트를 등록하려면 URI에서 탭을 선택하고 URI 필드에 유효한 URL을 입력합니다. 그런 다음 가져오기 를 클릭하여 URL에서 에이전트 카드를 가져옵니다.
- 에이전트 카드 콘텐츠를 복사하여 붙여넣으려면 JSON 붙여넣기 탭을 선택하고
agent-card.json파일의 전체 콘텐츠를 붙여넣습니다.
저장 을 클릭합니다.
gcloud
A2A 에이전트를 등록하려면 에이전트의 에이전트 카드를 로컬 JSON 파일(예: agent-card.json)로 저장하고 다음을 수행합니다.
gcloud alpha agent-registry services create AGENT_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=a2a-agent-card \
--agent-spec-content=agent-card.json
사양 파일의 최대 파일 크기는 10KB입니다.
다음을 바꿉니다.
AGENT_NAME: 에이전트에 지정할 이름입니다(예:my-support-agent).PROJECT_ID: 프로젝트 ID입니다.REGION: 에이전트를 등록할 리전 입니다. 특정 리전을 사용하지 않으려면global값을 사용합니다.DISPLAY_NAME: 에이전트에 지정할 사람이 읽을 수 있는 이름입니다(예:Support Agent).
표준 REST 에이전트 등록
표준 REST 에이전트는 이름과 설명으로 검색할 수 있지만 A2A 프로토콜을 채택하지 않는 한 검색 가능한 기술이 없습니다.
표준 REST 또는 SaaS API 엔드포인트와 같이 A2A 사양을 구현하지 않는 원격 에이전트를 등록하려는 경우 에이전트 레지스트리 API는 에이전트 프로토콜 사양 없이 Service 리소스를 만듭니다.
다음 단계에 따라 에이전트를 등록합니다.
콘솔
콘솔에서 에이전트 레지스트리로 이동합니다. Google Cloud
프로젝트 선택 도구에서 에이전트 레지스트리를 Google Cloud 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
에이전트 추가 를 클릭합니다.
에이전트 세부정보 패널에서 다음 세부정보를 입력합니다.
- 유형: 비 A2A를 선택합니다.
- 이름: 에이전트의 사람이 읽을 수 있는 표시 이름(예:
Travel Agent)을 입력합니다. - 설명: 에이전트 기능에 대한 설명(예:
A test agent that plans travel itineraries.)을 입력합니다. - 리전: 에이전트를 등록할 지리적 위치를 선택합니다.
- 엔드포인트: 에이전트가 호스팅되는 엔드포인트를 입력합니다.
저장 을 클릭합니다.
gcloud
선택적으로 정의된 HTTP/JSON 엔드포인트 인터페이스를 --interfaces 플래그와 함께 제공하여 레지스트리가 에이전트와 연결을 설정하도록 할 수 있습니다.
표준 REST 에이전트를 등록하려면 다음을 수행합니다.
gcloud alpha agent-registry services create AGENT_NAME \
--project=PROJECT_ID \
--location=REGION \
--display-name="DISPLAY_NAME" \
--agent-spec-type=no-spec \
--interfaces=url=ENDPOINT_URL,protocolBinding=PROTOCOL
다음을 바꿉니다.
AGENT_NAME: 에이전트에 지정할 이름입니다(예:my-remote-rest-agent).PROJECT_ID: 프로젝트 ID입니다.REGION: 레지스트리 리전입니다.DISPLAY_NAME: 에이전트에 지정할 사람이 읽을 수 있는 이름입니다(예:Remote REST Agent).ENDPOINT_URL: 에이전트의 API 엔드포인트 URL입니다(예:https://api.remote-service.com/v1/agents/1234).PROTOCOL: 엔드포인트의 프로토콜 바인딩입니다. 유효한 값은HTTP_JSON,GRPC또는JSONRPC입니다.
등록 확인
에이전트를 등록한 후 에이전트 레지스트리가 Service를 성공적으로 처리하고 해당 Agent 리소스를 만들었는지 확인합니다.
콘솔
콘솔에서 에이전트 레지스트리로 이동합니다. Google Cloud
프로젝트 선택 도구에서 에이전트 레지스트리를 Google Cloud 설정한 프로젝트를 선택합니다.
에이전트 탭을 선택합니다.
페이지에 등록된 모든 에이전트와 세부정보 목록이 표시되어야 합니다.
gcloud
gcloud alpha agent-registry agents list \
--project=PROJECT_ID \
--location=REGION
에이전트가 여러 개 있거나 단일 에이전트의 등록을 확인하려면 에이전트의 메타데이터로 목록을 필터링할 수 있습니다.
gcloud alpha agent-registry agents list \
--project=PROJECT_ID \
--location=REGION \
--filter="FILTER_EXPRESSION"
다음을 바꿉니다.
다음 단계
- 등록된 에이전트를 관리하는 방법을 알아봅니다.
- 관리형 런타임에 배포된 에이전트를 등록하는 데 권장되는 방법인 자동 등록에 대해 알아봅니다.