Xerrameca

독립적인 에이전트 간 오케스트레이션 서비스.

Xerrameca는 자율 에이전트 간의 구조화된 대화를 조정합니다: 턴, 임대, 라운드, 지연, 완료 합의, 감독 및 수동 모니터링. REST 및 MCP 인터페이스를 노출하며, 신원, 권한 및 선택적 장기 Brain 요약을 위해 공개 HTTP 어댑터를 통해 Pluribus와 통합됩니다.

설계 규칙

Xerrameca는 독립적인 서비스입니다. Pluribus 내부를 가져오거나, Pluribus SQLite 데이터베이스를 열거나, Brain 테이블에 직접 쓰지 않습니다.

Agents / MCP / REST
        |
        v
+------------------------+
|       Xerrameca        |
| conversations / turns  |
| leases / rounds        |
| passive monitor        |
| own SQLite database    |
+-----------+------------+
            |
      ports / HTTP adapters
            |
            v
+------------------------+
|        Pluribus        |
| identity / permissions |
| optional Brain memory  |
+------------------------+

Xerrameca가 중지되거나 고장 나더라도 Pluribus는 정상 상태를 유지해야 합니다.

Related MCP server: MachineHearts

현재 기능

• 독립적인 SQLite 영속성

• 2-에이전트 교대 대화 프로토콜

• 클레임/임대 보호 및 타임아웃 검사

• 라운드 및 구성 가능한 지연

• 완료 제안 + 두 번째 에이전트 확인

• 감독자 모드

• 개시자/관리자 취소

• REST 명령/수신함/클레임/응답 표면

• 정확히 7개의 독립형 MCP 도구

• 공개 /v1/identity/* API를 사용하는 Pluribus 신원 어댑터

• 공개 /v1/memory/write를 사용하는 선택적 Brain 요약 어댑터

• 종료된 대화를 롤백할 수 없는 재시도 가능한 요약 아웃박스

• 관리자 전용 수동 모니터

• 루트가 아닌 Docker 이미지 및 강화된 systemd 기준

• 실제 2-에이전트 X3 인증 스모크 스크립트

레거시 Pluribus 웹훅 푸시 Runner는 의도적으로 필수 코어에 포함되지 않습니다. 선택적 푸시 전달은 별도로 추적되며 Pluribus 내부가 아닌 향후 전달 포트를 사용해야 합니다.

로컬 실행

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[test]'
cp .env.example .env
uvicorn xerrameca.app:app --host 127.0.0.1 --port 8791

그런 다음:

GET  http://127.0.0.1:8791/health
POST http://127.0.0.1:8791/mcp/

Pluribus 기반 신원을 사용하려면 XERRAMECA_IDENTITY_PROVIDER=pluribus와 연결 가능한 PLURIBUS_BASE_URL을 구성하세요.

에이전트 호환성 계약

REST:

• POST /v1/xerrameca/command

• GET /v1/xerrameca/inbox

• POST /v1/xerrameca/turns/{turn_id}/claim

• POST /v1/xerrameca/turns/{turn_id}/reply

• 대화 목록/조회/메시지 엔드포인트

MCP:

• xerrameca_command

• xerrameca_inbox

• xerrameca_claim

• xerrameca_reply

• xerrameca_list

• xerrameca_get

• xerrameca_messages

에이전트 지향 호출은 X-API-Key를 사용합니다. X-Agent-ID는 선택 사항이며 자격 증명으로 확인된 신원을 재정의할 수 없습니다.

전체 클라이언트 계약은 docs/AGENT_INTEGRATION.md를 참조하세요.

로드맵

• ✅ X0 — 부트스트랩 및 추출 계약

• ✅ X1 — 독립적인 풀 모드 코어, REST/MCP 및 수동 모니터

• ◐ X2 — Pluribus HTTP 어댑터: 구현 병합됨; 실제 제공자 인증 대기 중

• ◐ X3 — 독립 배포: 패키징/런북 병합됨; 실제 배포/E2E 인증 대기 중

• ⏳ X4 — Pluribus 정리: X3 인증 후에만

선택적 푸시/웹훅 전달은 별도로 추적되며 풀 모드 독립 서비스를 차단하지 않습니다.

문서

• docs/ARCHITECTURE.md

• docs/PLURIBUS_INTEGRATION.md

• docs/AGENT_INTEGRATION.md

• docs/DEPLOYMENT.md

라이선스

Apache-2.0.