전체에 외부 에이전트로 거스를 추가한 방법

출처: Dev.to

나는 방금 PR을 열어 Goose를 Entire에 추가하는 지원을 만들었다. Goose는 Agentic AI Foundation이 만든 오픈 소스 코딩 에이전트이며, 최초의 MCP 클라이언트이자 Model Context Protocol의 레퍼런스 구현이다. 나는 이게 두 세계가 충돌하는 지점이라 매우 흥분된다. 나는 이전에 Goose를 구축하던 팀에서 일했었다. 팀을 떠나 Entire에 합류했지만, 여전히 Goose 문서를 관리하고 프로젝트에 반쯤 활발히 참여하고 있다.

이 글은 내가 통합을 어떻게 만들었는지 단계별로 설명한다. 또한 여러분이 좋아하는 에이전트를 Entire에 추가하는 가이드 역할도 한다.

Entire란?

전통적인 소프트웨어 개발 라이프사이클은 AI 에이전트를 위해 설계되지 않았다. 그래서 Entire는 AI 에이전트를 위한 라이프사이클을 만들고 있다. 우리는 인간과 에이전트가 협업하기 어렵게 만드는 주요 마찰 지점을 파악했다. 예를 들어, 에이전트는 종종 인간 개발자가 검토하고 싶어 하지 않는 거대한 PR을 만든다. 또한, AI가 생성한 코드는 병합된 후 며칠이 지나면 실제로 인간이 작성하지 않았기 때문에 그 이유를 완전히 잃어버리게 된다.

우리는 앞으로 더 많은 기능을 추가할 예정이지만, 먼저 에이전트 세션을 기록하는 CLI‑first 도구를 출시했다. 이 도구는 프롬프트, 에이전트 응답, 툴 호출 및 그 사이의 모든 것을 로그한다.

그래서 특정 기능이 왜 그렇게 구현됐는지 알고 싶을 때, 바로 트랜스크립트로 가서 읽을 수 있다. 개인적으로는 에이전트에게 직접 물어보거나 entire checkpoint explain 같은 명령을 실행해 해당 코드 라인 뒤에 있는 대화 내용을 요약해서 보는 편을 선호한다. 모든 세션은 git으로 버전 관리되며 동일한 레포지토리 안의 전용 메타데이터 브랜치에 저장된다.

왜 직접 에이전트를 추가해야 할까?

Entire는 Claude Code, Gemini CLI, Codex, Cursor, Copilot CLI와 같은 주요 코딩 에이전트에 대한 내장 지원을 제공한다. 하지만 에이전트 생태계는 매우 빠르게 변하고, 어느 한 팀이 모든 새로운 툴을 지원할 수는 없다.

그래서 우리는 external agent protocol을 만들었다. 이를 통해 여러분은 원하는 어떤 에이전트든 스스로 Entire에 추가할 수 있다. 사용 경험은 내장 에이전트를 사용하는 것과 동일하며, 동일한 명령어와 기능이 그대로 동작한다. Entire가 아직 여러분이 좋아하는 에이전트를 지원하지 않더라도 기다릴 필요가 없다. 직접 entireio/external-agents 레포지토리에서 통합을 구현하면 된다.

왜 Goose인가?

Goose의 유지보수자이자 전임 풀타임 개발자로서, 나는 Goose를 Entire에 연결할 완벽한 구실을 찾고 있었다. 가장 큰 기술적 장애물은 Goose가 훅을 지원하지 않았다는 점이었다. 훅은 세션 시작, 프롬프트 제출, 에이전트 턴 종료 시점에 Entire에 알려준다. 이를 통해 Entire는 언제 세션 활동을 기록하고 언제 멈출지 알 수 있다.

최근 Goose는 Open Plugins 훅 스펙을 따라 훅 지원을 구현했다. 이제 꿈을 이룰 수 있게 되었다.

에이전트가 갖춰야 할 것

에이전트를 Entire에 연결하려면 다음이 필요하다:

• 훅 또는 라이프사이클 메커니즘: 세션 시작, 프롬프트 제출, 턴 종료 시 외부 명령을 실행할 신뢰할 수 있는 방법이 필요하다. 이가 없으면 Entire는 세션을 관찰할 수 없다.
• 읽을 수 있는 세션 데이터: 실제 대화 내용이 포함된 트랜스크립트 또는 내보낼 수 있는 세션 스토어에 접근할 수 있어야 한다. 우리는 “Working…” 같은 일반적인 자리채움 텍스트가 아니라 실제 어시스턴트 응답과 정확한 툴 호출을 원한다.
• 안정적인 세션 ID: 훅 페이로드에서 추출할 수 있는 일관된 세션 ID가 필요하며, 가능하면 goose session --resume --session-id 같은 재개 명령과 짝을 이루어야 한다.
• 비대화형 CLI 모드: 예를 들어 goose run -t "prompt"처럼 명령을 깔끔하게 실행할 수 있어야 자동화된 라이프사이클 테스트를 크게 쉽게 만들 수 있다.

필요한 준비물

다음 항목들을 로컬에 설치해야 한다:

• 목표 에이전트의 CLI가 설치되고 인증되어 있어야 함
• Entire CLI 설치
• Go 툴체인 (External Agent는 Go로 작성됨)

먼저 이슈를 열어 Entire 팀과 목표 에이전트를 추가하고 싶다는 의사를 조율하라. 새로운 에이전트를 도입한다는 것은 장기적인 지원 약속을 의미한다!

선택 사항: 통합 구현에 사용할 에이전트. 나는 Claude Code와 Fable 5를 사용했다. 이렇게 하면 모든 코드를 직접 작성할 필요가 없었다. Claude Code가 Goose와 Entire를 연결하는 패턴을 그대로 따라줬다.

단계별 워크플로우

1. 에이전트 스킬 실행

external-agents 레포지토리에는 무거운 작업을 자동화해 주는 내장 개발자 스킬이 포함되어 있다: entire-external-agent. 레포를 클론하고, 좋아하는 AI 개발 도구에서 열어 다음을 실행한다:

/entire-external-agent

전체 화면 모드 진입


전체 화면 모드 종료

2. 세 단계 개발 흐름

Phase 1: Research – 스킬이 프로토콜 사양을 분석하고, 에이전트 바이너리 명령을 탐색하며, 특히 실제 훅 페이로드를 캡처하는 검증 스크립트를 작성한다.

Goose의 경우, 이 스크립트는 임시 워크스페이스에 캡처 플러그인을 연결하고 실제 goose run 프롬프트를 실행해 정확한 stdin 페이로드를 디스크에 덤프했다. 문서는 거짓말을 할 수 있지만 캡처된 페이로드는 절대 그렇지 않다. 이 단계에서는 세션 데이터가 깨끗한지 확인하고 모든 내용을 AGENT.md 요약 파일에 저장한다.

이 단계에서 발견된 점은 Goose 세션이 개별 파일이 아니라 전역 SQLite 데이터베이스에 저장된다는 것이었다. 따라서 바이너리는 goose session export --format json을 사용해 실시간으로 트랜스크립트를 추출해야 했다.

Phase 2: Write tests – 스킬이 필요한 프로토콜 서브커맨드를 유효한 JSON 형태로 스텁 처리한 새로운 Go 바이너리를 스캐폴딩한다. 그리고 여러분의 에이전트를 엔드‑투‑엔드 테스트 하네스에 등록한다. 이 시점에서 공유 컴플라이언스 스위트(entireio/external-agents-tests)는 실패해야 한다. 그 실패가 바로 여러분의 구체적인 개발 로드맵이 된다.

Phase 3: Implement – 이제 (여러분과 통합을 구현하는 에이전트가) 구체적인 테스트 실패를 가지고 테스트‑주도 개발 방식을 적용해 필요한 코드를 작성한다. 실패를 기반으로 코드를 단계별로 구현한다. Goose의 경우, 실패한 테스트는 훅 설치, 세션 읽기·쓰기 라운드트립, 트랜스크립트 검증까지 에이전트를 이끌었다. 마지막으로 에이전트는 Phase 1에서 기록한 실제 데이터를 사용해 유닛 테스트를 작성해 변환 코드가 완벽히 동작함을 증명한다.

Entire가 처음 여러분의 통합을 발견하면, “당신(외부 에이전트)이 실제로 지원하는 기능은 무엇인가요?” 라는 프로그래매틱 핸드쉐이크를 수행한다. 여러분의 외부 에이전트 바이너리(여기서는 Goose)가 자신의 역량을 선언한다. 이 목록을 통해 Entire는 어떤 작업을 여러분의 에이전트에 위임할 수 있는지 정확히 알게 된다.

Goose가 선언한 구체적인 역량은 다음과 같다:

• hooks: 바이너리가 Goose의 네이티브 플러그인 시스템을 이용해 세션 이벤트를 청취할 수 있음을 의미한다.
• transcript_analyzer: 바이너리가 원시 JSON 데이터를 읽어 사용자의 프롬프트, 툴 호출, 변경된 파일 등을 찾을 수 있음을 의미한다.
• transcript_preparer: 바이너리가 로컬 SQLite 데이터베이스에서 대