콘텐츠로 이동

원격 A2A 에이전트

Backend.AI GO는 Agent2Agent(A2A) 에이전트 카드로 외부에서 운영되는 에이전트를 등록할 수 있습니다. 원격 에이전트는 원격 (A2A)으로 구분되며 로컬 모델, 모델 프로바이더 또는 MCP 서버로 취급되지 않습니다.

에이전트 연결

  1. 에이전트 확장 페이지를 엽니다.
  2. 원격 에이전트 연결을 선택합니다.
  3. 에이전트 카드 URL을 입력합니다. 127.0.0.1과 같은 루프백 주소의 서비스가 아니면 HTTPS를 사용합니다.
  4. 카드가 비공개이면 Bearer 토큰을 추가합니다. 고급 인증에서 사용자 지정 헤더와 요청 제한 시간을 설정할 수 있습니다.
  5. 연결을 선택합니다.

Backend.AI GO는 카드를 가져와 A2A 버전과 동일 출처 RPC 엔드포인트를 확인하고 공개 식별 정보, 스킬 및 기능을 저장합니다. 자격 증명 값은 시스템 자격 증명 저장소에 보관됩니다. 프로필 조회에는 Bearer 토큰 설정 여부와 설정된 헤더 이름만 표시되며 값은 표시되지 않습니다.

원격 에이전트 사용

연결된 원격 에이전트는 로컬 에이전트 프로필과 같은 대상 선택기에 표시됩니다. 대화 대상으로 선택하거나 @로 멘션하고, 프로필에서 스쿼드에 추가하거나 delegate 대상으로 활성화할 수 있습니다. 원격 카드에는 대상 주소와 제공 스킬이 표시되므로 작업이 실행되는 위치를 확인할 수 있습니다.

원격 프로필에 보낸 메시지는 기기 밖의 원격 에이전트로 전송됩니다. 직접 채팅과 멘션에서는 현재 요청이 전송되고, 스쿼드 실행에서는 할당된 작업의 제목과 설명만 전송됩니다. 종속 작업 출력, 워크스페이스 파일, 로컬 대화 기록, 운영자 지시, 로컬 도구 자격 증명은 자동으로 전송되지 않습니다.

CLI 등록

셸 기록과 프로세스 인자에 비밀 값을 남기지 않도록 환경 변수에 저장합니다.

export AIGO_AGENT_TOKEN='...'
export AIGO_AGENT_API_KEY='...'
aigo agent-profile register-remote \
  https://agent.example/.well-known/agent-card.json \
  --bearer-token-env AIGO_AGENT_TOKEN \
  --header-env X-API-Key=AIGO_AGENT_API_KEY \
  --timeout 300

명령 출력에는 자격 증명 값이 포함되지 않습니다.

취소와 원격 작업 수명 주기

채팅, 위임 또는 스쿼드 작업을 중지하면 로컬 응답 대기를 즉시 중단하고 로컬 예약을 해제합니다. 원격 작업 ID를 알고 있으면 저장된 자격 증명으로 취소를 한 번 시도합니다. A2A 0.3에서는 tasks/cancel, A2A 1.0에서는 CancelTask를 사용합니다. SSE 연결이 열려 있는 동안에도 이벤트에서 작업 ID를 보관합니다. 시간 초과와 백그라운드 요청 중단도 같은 정리 경로를 사용합니다.

원격 정리 요청은 별도의 2초 제한 시간을 사용하며 로컬 중지 동작을 지연시키지 않습니다. 직접 채팅은 요청별 알림에 원격 취소 확인, 이미 종료된 작업, 취소 거부 또는 취소 미확인 상태를 표시합니다. 해당 원격 작업의 응답이 취소 상태일 때만 취소를 확인한 것으로 처리합니다. 지원하지 않는 메서드, 작업 ID 부재, 원격 작업 조회 실패, 통신 실패, 정리 제한 시간 초과는 원격 작업이 중지되었다는 증거가 아닙니다. 원격 자원을 계속 사용할 수 있으므로 원격 서비스의 제어 기능으로 확인하세요. 일반 원격 작업 목록 조회는 지원하지 않습니다.

취소 API는 localInterrupted와 remoteCancellation을 분리해 반환합니다. 원격 상태는 confirmed, alreadyTerminal, refused, notFound, unsupported, unknown 중 하나입니다. 로컬 요청을 중단했거나 로컬 요청이 없다는 이유만으로 원격 취소를 확인했다고 보고하지 않습니다. 중단된 메시지 전송 요청 자체는 HTTP 409와 remote_agent_cancelled 코드로 실패합니다. 이 응답은 원격 취소 시도가 끝나기 전에 반환되므로 원격 작업 상태를 알려 주지 않습니다. 원격 결과는 취소 API에서 확인하세요.

연결 오류

등록 과정에서는 누락된 자격 증명, 지원하지 않는 A2A 버전, 공개 HTTP URL, 카드와 출처가 다른 RPC URL, 안전하지 않은 대상, 잘못된 사용자 지정 헤더 및 크기 제한을 넘은 응답을 거부합니다. 오류에 표시된 필드 또는 원격 서비스 설정을 수정한 뒤 다시 연결하세요. 원격 프로필을 제거하면 저장된 자격 증명도 제거됩니다.

다른 GO 인스턴스에서 에이전트 게시

서비스할 인스턴스에서 저장된 로컬 프로필을 게시하고 연결 패널의 인증이 필요한 A2A 카드 URL을 복사하세요. 여기에서 해당 URL과 agent_invoke 권한이 있는 Management API 키로 등록합니다. 원격 등록에는 위에서 설명한 URL과 전송 방식 제한이 그대로 적용됩니다. 게시 방법과 호출자 승인 예제는 에이전트 엔드포인트를 참고하세요.