HumanSecurity/human-verified-ai-agent

HTTP Message Signatures와 Google A2A 프로토콜을 사용하여 암호학적으로 안전한 에이전트-서비스 통신을 보여주는 다중 에이전트 AI 시스템입니다.

이 레포지토리는 외부 서비스에 대한 에이전트 요청의 인증을 위해 HTTP Message Signatures를 구현하는 다중 에이전트 AI 시스템의 오픈 소스 쇼케이스입니다. 이는 포괄적인 여행 계획 서비스를 제공하기 위해 세 가지 전문화된 에이전트가 함께 작동하는 Google A2A (Agent-to-Agent) 아키텍처를 시연합니다.

이 레포지토리에 대한 더 깊은 deepwiki 사양은 다음 링크를 따르세요 (https://deepwiki.com/HumanSecurity/human-verified-ai-agent)

HTTP Message Signatures (RFC 9421)는 HTTP 요청의 진위성과 무결성을 검증하기 위한 암호학적 방법을 제공합니다. API 키나 토큰에 의존하는 기존 인증 방식과 달리, HTTP Message Signatures는 공개키 암호화(public-key cryptography)를 사용하여 민감한 자격 증명을 노출하지 않으면서 요청이 특정 에이전트에서 왔음을 증명합니다.

이 시스템은 이 RFC 표준을 기반으로 하며, Web Bot Authentication Architecture 초안의 추가적인 아키텍처 고려 사항을 포함합니다.

전반적인 목표는 AI 에이전트가 외부 웹 서비스에 자신을 식별할 수 있는 강력하고 검증 가능한 방법을 제공하는 것이며, IP 기반 또는 User-Agent 기반 식별 방식에서 벗어나는 것입니다.

이 프로젝트를 탐색함으로써 다음 내용을 이해할 수 있습니다:

• AI 에이전트 인증을 위한 HTTP Message Signatures 구현 방법
• Google A2A 프로토콜을 사용한 다중 에이전트 아키텍처 패턴
• 개별 에이전트를 위한 암호학적 키 관리(Cryptographic key management)
• 안전한 에이전트-외부 서비스 통신 패턴
• RFC 9421 표준의 실제 적용 사례

개별 에이전트 키를 갖춘 다중 에이전트 아키텍처

이 쇼케이스는 세 가지 전문화된 에이전트를 가진 Google A2A (Agent-to-Agent) 프로토콜 구현을 시연합니다:

LLM 에이전트 (Orchestrator): AI를 사용하여 여행 계획 프로세스를 조정합니다. Weather 에이전트: 도시의 현재 날씨 정보를 제공합니다. Attractions 에이전트: 도시의 관심 지점 및 명소를 검색합니다. 주요 기능: 개별 에이전트 키: 각 에이전트는 JWK 형식으로 자체 고유한 Ed25519 키 쌍을 가집니다. 암호화 인증: 에이전트는 외부 서비스와 통신할 때 HTTP 메시지 서명을 사용합니다. 보안 요청 게이트웨이: 이 게이트웨이 서비스는 서명을 검증하고 요청을 외부 API로 라우팅합니다. 에이전트 오케스트레이션: LLM 에이전트는 날씨 및 명소 데이터를 결합하여 종합적인 여행 일정을 생성합니다. ANS (Agent Name Service): 각 에이전트는 구조화된 에이전트 식별을 위해 OWASP ANS v1.0 표준을 따르는 보안 이름 지정 기능을 구현합니다. 이 에이전트들은 forecast.weather.v1.human-security.com 및 planner.trip.v1.human-security.com과 같은 계층적 이름을 사용하여 안전한 에이전트 검색 및 인증을 가능하게 합니다. 이 명명 시스템은 분산 시스템 전반에 걸쳐 확장 가능한 AI 에이전트 신원 관리의 DNS에서 영감을 받은 프레임워크를 제공합니다. 데모 키 관리: 이 쇼케이스는 데모 키 쌍을 사용하여 즉시 작동하도록 설계되었습니다. 각 에이전트는 showcases/examples/keys/ 디렉터리에 자체 개인 키를 가지고 있으며, 해당 공개 키는 HUMAN의 레지스트리에 미리 구성되어 있습니다. 이 접근 방식은 사용자가 자체 인증 기관이나 키 관리 인프라를 설정할 필요 없이 다중 에이전트 HTTP 메시지 서명 프로토콜을 즉시 경험할 수 있도록 합니다. 경고: 예제 키만 사용 가능합니다. 운영 환경에서 사용하지 마십시오. 이 키들은 공개적으로 커밋되고 공유되었으므로, 실제 배포 시에는 반드시 자체 키를 생성하고 안전하게 보관하십시오. 이 접근 방식이 데모에 필요한 이유:

• 이 프로토콜에 대한 에이전트 레지스트리나 인증 기관(Certificate Authority)이 현재 운영 환경에는 존재하지 않습니다.
• 검증자 서비스는 알려진 공개 키를 사용하여 서명을 신뢰하고 유효성 검사해야 합니다.
• 이 데모 설정은 키 관리의 복잡성보다는 다중 에이전트 서명 프로토콜을 이해하는 데 집중할 수 있도록 합니다.

운영 환경(production environment)에서는 각 에이전트가 적절한 인증 기관을 통해 발급받은 고유한 키 쌍을 갖게 될 것입니다. 하지만 학습 및 시연 목적을 위해, 이 데모 키 쌍들은 아키텍처를 이해하는 가장 간단한 경로를 제공합니다.

⚠️ 중요 공지: 이것은 학습 및 평가 목적으로 설계된 데모 프로젝트입니다. 암호화 구현 자체는 운영 환경에 적합하지만(production-ready), 키 관리 및 에이전트 레지스트리 구성 요소는 교육적 사용을 위해 단순화되었습니다. showcases/examples/keys/ 아래의 키들은 예시용일 뿐이며, 절대 운영 환경에서 사용해서는 안 됩니다. 만약 귀하가 상업적인 AI 에이전트 회사이고, 귀하의 AI 에이전트 메시지가 HUMAN에 의해 암호학적으로 검증되기를 원한다면, 이 이메일([email protected])을 통해 검증 요청을 제출해 주십시오.

• Python 3.8 이상 버전
• Google API 키 (LLM 에이전트 오케스트레이터 기능에 필요)

python3 -m venv .venv
source .venv/bin/activate

pip3 install -r requirements.txt

프로젝트 루트 디렉토리에 .env 파일을 생성하십시오. .env.example 파일을 템플릿으로 사용할 수 있습니다.

환경 파일 설정 방법:

cp .env.example .env

다음 내용들로 .env 파일을 채워야 합니다:

GOOGLE_API_KEY
: 기본 언어 모델을 사용하기 위한 유효한 Google API 키입니다 (LLM 에이전트 오케스트레이터에 필요).
AGENT_VERIFIER_ADDRESS
: 검증자 구성 요소의 네트워크 주소(URL)입니다. 이 값은 HUMAN의 기존 서비스를 사용하여 자동으로 채워집니다.
AGENT_HOSTED_DOMAIN
: 검증자가 공개 키를 가져올 도메인입니다. 이는 Signature-Agent에서 사용됩니다.

헤더를 통해 검증자가 에이전트의 공개 키를 찾을 수 있는 위치를 나타냅니다.

메인 쇼케이스는 세 가지 전문화된 에이전트가 협력하여 지능적이고 날씨에 민감한 여행 일정을 생성하는 완전한 다중 에이전트 시스템을 시연합니다.

위 다이어그램은 LLM 에이전트(오케스트레이터), Weather Agent, Attractions Agent 및 외부 서비스를 통한 암호화 서명 요청 간의 전체 상호 작용 흐름을 보여줍니다.

python -m showcases.a2a_showcase

사용자 입력: 목적지 도시를 프롬프트합니다.
여행 조정: LLM 에이전트(오케스트레이터)가 전체 여행 계획 프로세스를 조정합니다.
날씨 데이터 수집: Weather Agent가 서명된 API 요청을 통해 현재 날씨 조건을 가져옵니다.
관광지 발견: Attractions Agent가 서명된 API 요청을 통해 관심 지점을 검색합니다.
지능적 통합: LLM 에이전트가 AI를 사용하여 날씨 및 관광지 데이터를 결합합니다.
보안 통신: 모든 외부 서비스 통신은 개별 에이전트 키를 사용한 HTTP 메시지 서명을 사용합니다.
최종 출력: 포괄적이고 날씨에 민감한 여행 일정을 제시합니다.

• AI 기능을 위해 Google API 키가 필요합니다.

적절한 에이전트 식별자를 사용하여 서명 검증 흐름을 테스트하여 HTTP 메시지 서명이 어떻게 작동하는지 이해하십시오.

python -m showcases.simple_success_showcase

• 검증자의 /verify 엔드포인트로 암호화 서명된 POST 요청을 전송합니다.

• 서명에 적절한 에이전트 도메인 식별자를 포함합니다.

• 성공적인 서명 검증 프로세스를 시연합니다.

• 외부 서비스가 에이전트의 진위 여부를 어떻게 확인할 수 있는지 보여줍니다.

• Google API 키는 필요하지 않습니다.

에이전트 식별자가 누락되었을 때 어떤 일이 발생하는지 테스트하여 적절한 에이전트 인증의 중요성을 이해하십시오.

python -m showcases.simple_failure_showcase

• 적절한 에이전트 도메인 식별 없이 서명된 POST 요청을 전송하는 방식 - 검증자가 공개 키를 찾을 수 없을 때 인증이 실패하는 방법을 시연합니다.

• 누락되거나 잘못된 에이전트 식별의 보안적 영향을 보여줍니다.

• 검증 프로세스의 오류 처리를 예시합니다.

• Google API 키가 필요하지 않습니다.

이 구현은 세 가지 전문화된 에이전트를 사용하는 Google A2A (Agent-to-Agent) 프로토콜을 시연합니다:

LLM Agent(showcases/agents/llm_agent.py):
다른 에이전트들을 호출하여 여행 계획을 조정하는 오케스트레이터입니다.
Weather Agent(showcases/agents/weather_agent.py):
외부 API에서 데이터를 가져와 날씨 정보를 제공합니다.
Attractions Agent(showcases/agents/trip_agent.py):
외부 API에서 데이터를 가져와 명소(attractions) 정보를 제공합니다.

통신 아키텍처:

에이전트-대-에이전트 (Agent-to-Agent): LLM Agent는 표준 Google A2A 프로토콜(HTTP/JSON)을 사용하여 Weather Agent 및 Attractions Agent와 통신합니다.
에이전트-대-외부 서비스 (Agent-to-External-Service): Weather Agent와 Attractions Agent는 인증을 위해 HTTP 메시지 서명(HTTP Message Signatures)을 사용하는 검증자 서비스를 통해 외부 API와 통신합니다.

통신 흐름:

LLM Agent → Weather Agent(A2A 프로토콜, 서명 없음)
Weather Agent → 검증자 서비스 (Verifier Service) → 외부 날씨 API (External Weather API)(HTTP 메시지 서명)
LLM Agent → Attractions Agent(A2A 프로토콜, 서명 없음)
Attractions Agent → 검증자 서비스 (Verifier Service) → 외부 명소 API (External Attractions API)(HTTP 메시지 서명)

human-verified-ai-agent/
├── agent_key_manager.py # 핵심 키 관리 인프라
├── request_signer.py # 핵심 HTTP 메시지 서명 인프라
...

핵심 인프라 구성 요소:

Agent Key Manager(agent_key_manager.py):
개별 Ed25519 키 쌍을 JWK 형식으로 생성하고 관리합니다.
Request Signer(request_signer.py):
모든 에이전트 통신에 대한 HTTP 메시지 서명을 처리합니다.
Request Orchestrator(request_orchestrator.py)

):

• A2A Showcase(showcases/a2a_showcase.py
  ): 전체 다중 에이전트 시스템을 시연하는 메인 진입점

쇼케이스 구성 요소:

개별 에이전트(showcases/agents/
): 자체 키와 책임 영역을 가진 세 가지 전문 에이전트
요청 게이트웨이(showcases/utils/request_gateway.py
): 에이전트 간에 서명된 요청을 라우팅하고 검증
에이전트 유틸리티(showcases/utils/
): 에이전트 운영 및 표시를 위한 지원 유틸리티

주요 기능:

• 각 에이전트는 JWK 형식으로 저장된 고유한 Ed25519 키 쌍을 가집니다.
• 외부 서비스 통신은 인증을 위해 HTTP 메시지 서명을 사용합니다.
• 요청 게이트웨이는 서명을 검증하고 요청을 외부 API로 라우팅합니다.
• 에이전트 간 통신을 위한 Google A2A 프로토콜 호환성을 제공합니다.
• 핵심 인프라와 쇼케이스 구현 사이에 깔끔한 분리가 이루어져 있습니다.

시스템은 핵심 agent_key_manager.py를 사용하여 각 에이전트에 대한 개별 키를 생성합니다.

인프라:

LLM 에이전트:showcases/examples/keys/9i2hRtJ6sUUO2fK1ZJyXdUGJK1kwI1wVRoe9VDhX4yY (JWK 형식)
날씨 에이전트:showcases/examples/keys/aAVQ596pKliWDfyo89RNTromrwqQMyD45YI36ldcCeo (JWK 형식)
명소 에이전트:showcases/examples/keys/DTNGykza-ch_trY8qfZwXRojdNa4R06CtC_ixX0VwuE (JWK 형식)

각 키 파일에는 JWK 형식의 개인 키가 포함되어 있으며, 파일명은 해당 키의 ID(JWK 썸프린트)입니다. 대응하는 공개 키는 동일한 key_id를 사용하여 식별하기 위해 HUMAN의 검증 서비스에 등록됩니다.

키 관리 기능:

• 각 에이전트를 위한 개별 Ed25519 키 쌍
• 웹 호환성을 위한 JWK 형식 지원
• 효율적인 조회를 위한 key_id 기반의 공개 키 파일명
• agent_key_manager.py를 통한 중앙 집중식 키 관리
• 자동 키 생성 및 변환 유틸리티

현재 구현에 대한 참고 사항: 현재 구현은 간소화되었으며, 에이전트 레지스트리(agent registry), 인증서 관리, 또는 도메인 검증 기능은 포함하고 있지 않습니다. 완전한 레지스트리 시스템은 일반적으로 등록, 인증서 갱신, 그리고 폐기(revocation) 프로세스를 포함하여 전체 에이전트 수명 주기(lifecycle)를 처리합니다. 이러한 향상된 보안 기능들은 추후 통합될 예정입니다.

이 다중 에이전트 구현은 외부 서비스로의 요청에 암호학적으로 서명하기 위해 RFC 9421: HTTP 메시지 서명(HTTP Message Signatures)을 사용합니다. 각 에이전트는 JWK 형식으로 자체 고유한 Ed25519 키 쌍을 가지며, 외부 API와의 통신은 검증자 서비스(verifier service)를 통해 서명되고 검증됩니다. 이 서명은 특정 HTTP 구성 요소를 포함하며, 보안 요구 사항에 따라 어떤 구성 요소가 포함될지 설정할 수 있습니다.

이 라이브러리는 세 가지 미리 정의된 구성 요소 세트를 제공합니다:

:MINIMAL_COMPONENTS

`[