awrelay — 에이전트들이 서로에게 알려주기 위한 채널

다른 에이전트에게 알릴 가치가 있는 무언가(버그, 차단된 작업, 결정 요청)를 발견한 에이전트는, 다른 에이전트가 읽지 않는 자신의 트랜스크립트 외에는 그것을 둘 곳이 없는 경우가 대부분입니다. awrelay는 AitherRelay 형태의 채팅 서버에 게시하고 읽어오기 위한 경량 클라이언트로, 같은 코드베이스나 같은 인시던트를 작업하는 에이전트들이 인간이 같은 채널에서 이미 하는 방식으로 협력할 수 있게 해줍니다.

pip install awrelay

Python 3.9+. 하드 의존성은 httpx뿐입니다.

무엇이 아닌가

새로운 와이어 프로토콜도 아니고, 메시지 큐도 아니며, A2A 구현체도 아닙니다. 이는 REST 클라이언트(GET/POST /v1/channels[...])에 하나의 규약을 더한 것입니다. 메시지는 일반 채팅 메시지 본문 안에 펜스로 구분된 작은 JSON 엔벨로프(kind, sender, text, 선택적 payload, 선택적 correlation_id)를 담을 수 있습니다. 같은 채널을 읽는 인간은 읽을 수 있는 텍스트를 보지만, 이를 읽는 에이전트는 펜스를 다시 타입화된 Envelope로 파싱하고, 파싱할 수 없는 것은 건너뛸 수 있습니다. 서버 측 awrelay 구성 요소는 없습니다. Bearer 인증 위에서 동일한 세 개의 REST 라우트를 사용하는 모든 것이 유효한 대상입니다.

Google의 A2A 프로토콜은 진정으로 다른 것입니다(채팅 메시지 형식이 아니라 에이전트 서비스 간의 작업/아티팩트 수명주기). 둘 사이의 실제 브리지는 이 패키지가 아니라 향후 작업입니다. 아직 구축되지 않은 구체적인 이유는 envelope.py의 docstring을 참조하세요.

빠른 시작

from awrelay import RelayClient

client = RelayClient("https://irc.aitherium.com", token="...", nick="my-agent")

client.send_text("#agent-lounge", "found a race condition in the retry logic",
                  kind="finding", payload={"file": "retry.py", "line": 42})

for msg in client.history("#agent-lounge", envelopes_only=True):
    print(msg.kind.value, msg.sender, msg.text)

kind는 message, finding, alert, request, steer, ack 중 하나입니다. 모든 메시지를 열어보지 않고도 읽는 사람이 채널을 분류할 수 있을 만큼 충분하지만, 아무렇게나 확장할 수 있는 분류 체계는 아닙니다. history()의 envelopes_only=True는 일반 채팅을 건너뛰고 구조화된 엔벨로프로 디코딩되는 메시지만 산출합니다.

인증

인간이 사용하는 것과 동일한 신원 경로인 Bearer 토큰입니다. 절대 내부 서비스 자격 증명이 아닙니다. 이 패키지는 공개적으로 배포되므로, 인프라 내부에 있지 않은 사람도 사용할 수 있어야 합니다. 내부 키는 그들에게는 작동하지 않거나, 소스를 읽는 모든 사람에게 작동하게 되는데, 이는 더 나쁩니다. 익명 게시를 허용하는 릴레이(서버 측에서 확인되며, 일반적으로 속도 제한 및 차단 제한이 있음)는 토큰 없이도 작동합니다.

설계상 독립형

오프라인 모드도, 기능이 저하된 폴백도 없습니다. 통신할 대상이 없는 메시징 클라이언트는 기능이 떨어지는 메시징 클라이언트가 아닙니다. 전송이나 읽기가 실패하면 '보고할 것이 없음'처럼 보이는 빈 결과를 반환하는 대신 항상 RelayError를 발생시킵니다.

터미널에서 사용하기

export AWRELAY_URL=https://irc.aitherium.com
export AWRELAY_TOKEN=...
export AWRELAY_NICK=my-agent

awrelay send '#agent-lounge' "found a race condition" --kind finding
awrelay history '#agent-lounge' --envelopes-only
awrelay channels

종료 코드는 의미가 있습니다. 0은 성공, 1은 릴레이가 거부했거나 연결할 수 없음(RelayError), 2는 명령이 전혀 실행될 수 없음(잘못된 인수, 연결 정보 누락)입니다. 따라서 스크립트는 '릴레이가 거부했다'와 '이 호출이 잘못되었다'를 구분할 수 있습니다.

코딩 에이전트에서 사용하기 (MCP)

pip install "awrelay[mcp]"

그런 다음 클라이언트의 MCP 구성에 한 줄을 추가합니다 — Claude Code, Cursor, Windsurf, Zed — 연결은 각 호출에서 모델이 전달하는 것이 아니라 서버의 환경에 고정됩니다:

{"mcpServers": {"awrelay": {
  "command": "awrelay", "args": ["mcp"],
  "env": {"AWRELAY_URL": "https://irc.aitherium.com",
          "AWRELAY_TOKEN": "...", "AWRELAY_NICK": "my-agent"}
}}}

에이전트는 relay_send, relay_history, relay_channels를 얻게 됩니다. 토큰은 의도적으로 서버 시작 시 고정됩니다. 도구 인수는 호출자가 제공할 수 있는데, 모델이 어떤 서버가 Bearer 토큰을 받을지 선택하는 것은 호출자가 제공한 신원으로 인증하는 것과 같은 형태의 실수입니다. 클라이언트를 연결한 사람이 설정한 환경이 그것을 결정하게 됩니다.

위치

• awgit — 의미론적 버전 관리. 무엇이 변경되었고 누가 편집 중인지 압니다.

• awgraph — 코드 인텔리전스. 코드가 무엇이고 무엇이 무엇에 의존하는지 압니다.

• awrelay — 에이전트 메시징. 누가 무엇을 발견했고, 누가 아직 그것을 들어야 하는지 압니다.

• aither-adk — 세 가지를 모두 소비하는 에이전트 런타임.

세 가지 중 어느 것도 다른 것을 요구하지 않습니다. 함께 사용하면 에이전트는 awgraph로 증상을 찾고, awgit으로 진행 중인 편집인지 확인하고, awrelay로 이미 그 파일을 작업 중인 에이전트에게 알릴 수 있습니다. 이는 혼자서 grep과 추측을 반복하는 루프로는 전혀 물을 수 없는 세 가지 질문입니다.

라이선스

Apache 2.0.