당신은 두 개의 에이전트를 작성했습니다. 단위 테스트 (Unit tests)는 통과했고, 도구 호출 모의 객체 (tool-call mocks)는 완벽하며, 첫 번째 통합 테스트 — 하나의 프로세스 내에서 두 에이전트를 실행하는 것 — 도 잘 작동합니다. 하지만 배포를 하면, 에이전트 A가 에이전트 B에 도달하지 못합니다. 이는 로직 버그가 아닙니다. 연결성 (connectivity) 버그입니다. 핸드셰이크 (handshake)가 타임아웃되거나, 주소가 해석되지 않거나, 메시지가 상대방이 승인하지 않은 채널로 전달되는 문제입니다.

해결책은 지루하지만 효과적입니다. 배포하기 전에 로컬에서 에이전트 간 연결성을 테스트하는 것입니다. 하나의 호스트에서 두 개의 데몬 (daemon) 프로세스를 실행하고, 각각에 실제 식별자 (identity)를 부여한 뒤, 실제 환경에서 마주하게 될 것과 동일한 실패 모드(failure modes) — 재시작, 주소 변경, 신뢰 결정 (trust decisions), 손실이 발생하는 링크 (lossy links) — 를 테스트하십시오. 이 루프를 통과한다면, 배포는 형식적인 절차에 불과할 것입니다.

제가 사용하는 개발 루프와 정확한 명령어를 소개합니다.

"에이전트 간 연결성"의 실제 의미

무엇인가를 테스트하기 전에, 계층 (layers)의 이름을 정의해야 합니다. 에이전트 A가 에이전트 B와 통신하기 위해서는 다음 네 가지가 충족되어야 합니다:

1. 주소 지정 (Addressing) — A가 B의 이름을 지정할 수 있어야 합니다. 프로세스와 함께 사라지는 소켓 (socket)이 아니라, 재시작과 IP 변경에도 유지되는 이름이어야 합니다.
2. 전송 (Transport) — A의 바이트 (bytes)가 실제로 B에 도달해야 합니다. NAT, 방화벽을 통과해야 하며, 양측 모두에 고정 IP (static IP)가 없어도 가능해야 합니다.
3. 신뢰 (Trust) — B가 A로부터 오는 메시지를 수락해야 합니다. "VPN 상의 모든 것은 신뢰한다"가 아니라, 명시적이고 피어(peer)별이며 상호적인(mutual) 신뢰여야 합니다.
4. 탐색 (Discovery) — A가 B가 존재한다는 사실 자체를 찾아낼 수 있어야 합니다.

단위 테스트는 이 네 가지를 모두 모의 (mock) 합니다. 통합 테스트는 보통 하나의 프로세스 내부에서 두 에이전트를 모두 실행하는데, 이는 localhost가 항상 응답하기 때문에 테스트를 실패하게 만드는 것이 불가능합니다. 두 방법 모두 운영 환경 (production)에 대해서는 아무것도 알려주지 않습니다.

두 프로세스 개발 루프

핵심적인 움직임은 이것입니다: 에이전트를 테스트하는 것을 멈추고, 에이전트 사이의 네트워크를 테스트하기 시작하십시오. 하나의 호스트에서 각각 고유한 식별자와 주소를 가진 두 개의 데몬 프로세스를 실행하고, 운영 환경에서 사용할 것과 동일한 전송 계층 (transport)을 통해 통신하게 합니다.

Pilot Protocol은 정확히 이러한 형태를 위해 구축된 오픈 소스 오버레이 네트워크 (overlay network)이며, 그 데몬이 곧 식별 계층 (identity layer)이므로 테스트 환경 구축은 2분이면 충분합니다. 별도의 식별 파일 (identity files)을 사용하여 노드 1과 노드 2를 시작하십시오:

# node one
pilotctl daemon start --identity ~/.pilot/identity-a.json --hostname agent-a

...

각 데몬 (daemon)은 재시작이나 IP 변경 후에도 유지되는 영구적인 가상 주소를 등록합니다. 그것이 바로 여러분이 테스트하려는 속성입니다.

원격 환경에서 발생할 수 있는 문제 시뮬레이션하기

로컬호스트 (localhost)는 모든 것을 숨깁니다. 하지만 실제 식별 파일 (identity files)을 가진 두 개의 데몬은 그렇지 않습니다. 다음의 실패 모드 (failure modes)를 순서대로 따라가며 테스트하십시오:

1. 데몬 하나를 재시작하십시오. 노드 B를 종료한 후 다시 시작합니다. 해당 주소가 유지됩니까? 만약 데몬이 부팅할 때마다 새로운 주소로 재등록한다면, 피어 (peer)들이 이를 찾을 수 없게 되어 배포 시

구체적인 테스트 스크립트

다음은 매 배포 전에 실행할 수 있는 전체 루프(loop)를 스크립트로 구성한 것입니다:

#!/usr/bin/env bash
set -e

...

스크립트를 실행하고, 문제가 발생하는 부분을 수정하고, 다시 실행하세요. 그것이 바로 루프입니다.

배포 전 로컬에서 에이전트 간 연결성 테스트하기 — 체크리스트

이 포스트에서 다른 것은 다 잊더라도, 다음 리스트만큼은 반드시 활용하세요:

• 데몬 재시작 후에도 주소가 유지되는가.
• 터널(tunnel)을 통해 메시지가 양방향으로 왕복(round-trip)하는가.
• 승인되지 않은 피어 (peer)는 메시지를 전달할 수 없는가.
• 코드 변경 없이 승인(approval)만으로 전달 기능이 활성화되는가.
• 새로운 ID (identity)가 피어 (peer)에 의해 거부되는가.
• 디스커버리 (discovery)가 작동하는가: A가 하드코딩된 IP가 아닌 이름으로 B를 찾을 수 있는가.
• 경로에 실제 NAT가 있는 환경에서도 동일한 명령어가 통과하는가.

각 항목은 운영 환경(production)에서 장애를 일으키고 디버깅에 한 시간을 허비하게 만드는 요소들입니다. 또한 모든 항목은 단 한 대의 머신에서 테스트 가능합니다.

데몬 형태가 중요한 이유

모의 객체 (mock) 대신 한 호스트에서 두 개의 데몬을 실행하는 것이 올바른 테스트 환경 (harness)인 이유는, 여러분이 실제로 배포하게 될 실제 아티팩트 (artifacts), 즉 프로세스, 그 정체성 (identity), 신뢰 결정 (trust decisions), 그리고 전송 (transport)을 테스트하기 때문입니다. 재시작과 NAT 홉 (hop)을 포함하여 한 쌍의 데몬이 로컬에서 정상 작동한다면, 여러분과 운영 환경 사이의 남은 리스크는 아키텍처 (architecture)가 아닌 설정 (configuration)의 문제입니다.

Pilot Protocol은 이 루프를 위한 매우 적합한 옵션 중 하나입니다. 이는 오픈 소스 (AGPL-3.0, Go, 외부 의존성 없음)이며, 모든 에이전트 (agent)에게 영구적인 가상 주소를 부여하고, X25519 키 교환 (key exchange)과 AES-GCM으로 터널을 암호화하며, 신뢰 (trust)를 피어 (peer)별 명시적 핸드셰이크 (handshake)로 만듭니다. Pilot Protocol 문서에는 주소 지정 (addressing), 전송 (transport), 그리고 신뢰 모델 (trust model)에 대한 상세한 내용이 담겨 있습니다. 또한 노드 간 통신이 시작되면 단 한 번의 명령어로 설치할 수 있는 에이전트 네이티브 도구 앱 스토어도 갖추고 있습니다. 하지만 이는 다음 포스트에서 다루겠습니다.

직접 시작하여 루프를 실행해 보세요:

curl -fsSL https://pilotprotocol.network/install.sh | sh

두 개의 데몬, 한 대의 호스트, 단 몇 분이면 충분합니다. 첫 번째 운영 장애를 겪는 것보다 훨씬 저렴합니다.