Anthropic Managed Agents의 오픈소스 구현체 Castor-Server 개발기 및 아키텍처 인사이트

실용적 조언

Anthropic Managed Agents 사용 시 이벤트가 수신되지 않는다면 SDK 대신 직접 HTTP 스트리밍을 구현하여 테스트할 것
에이전트의 대화 기록을 수정해야 할 경우 원본 메시지 리스트를 건드리지 말고 별도의 상태 채널을 활용할 것
LiteLLM을 활용하여 Anthropic 전용 API를 다른 LLM 제공자로 전환하여 비용과 유연성을 확보할 것

섹션별 상세

공식 SDK가 프로토콜 업데이트를 따라가지 못해 발생하는 이벤트 누락 버그를 발견했다. anthropic-python 0.93.0 버전의 Stream 클래스가 메시지 API 이벤트명만 처리하도록 하드코딩되어 있어, 새로운 세션 상태나 도구 관련 이벤트를 모두 무시하는 현상이 확인됐다. curl이나 raw httpx를 통한 직접적인 바이트 수준 통신으로는 정상 작동함을 입증하며, SDK 의존성보다 와이어 포맷 호환성이 더 신뢰할 수 있는 구현 방식임을 강조했다.

에이전트 런타임에서 결정론적 재현(Deterministic Replay)의 중요성을 확인했다. Castor 커널은 시스템 호출 저널을 사용하여 에이전트를 재실행하는데, HITL 중단 후 재개 시 메시지 리스트를 직접 수정하면 해시값이 불일치하여 ReplayDivergenceError가 발생한다. 이를 해결하기 위해 대화 상태를 별도의 채널로 분리하여 읽기 전용으로 관리함으로써, 에이전트 코드를 순수 함수처럼 유지하고 타임 트래블 및 포크 기능을 구현 가능하게 했다.

SQLite에서 PostgreSQL로 백그라운드 데이터베이스를 전환하는 과정에서 비동기 세션 관리 버그를 식별했다. FastAPI 경로에서 요청 스코프의 DB 세션을 asyncio.create_task로 전달할 경우, 응답 반환 시 세션이 닫혀 백그라운드 작업이 중단되는 현상이 발생했다. SQLite는 인메모리 특성상 이를 허용했으나 실제 운영 DB에서는 치명적이므로, 백그라운드 작업은 반드시 독립적인 세션을 생성해야 한다는 실무적 교훈을 얻었다.

python

async def handle_user_message(db, ...):
    # ... logic ...

# FastAPI route
@app.post("/message")
async def post_message(request: Request, db: Session = Depends(get_db)):
    asyncio.create_task(handle_user_message(db, ...)) # Bug: session closed when request returns
    return {"status": "ok"}

FastAPI에서 요청 스코프의 DB 세션을 백그라운드 태스크로 전달할 때 발생하는 세션 종료 버그 예시

에이전트 프레임워크의 가치는 단순한 엔드포인트 목록이 아닌 실행 모델의 결정론적 특성에 달려 있다. castor-server는 결정론적 substrate를 기반으로 설계되어, 에이전트의 의도를 미리 확인하는 스캔(scan), 특정 시점에서 실행 흐름을 분기하는 포크(fork), 리소스별 실시간 예산 추적 등을 200줄 미만의 코드로 구현했다. 이는 상태 비저장 방식의 일반적인 에이전트 런타임으로는 구현하기 어려운 아키텍처적 차별점이다.

용어 해설

관리형 에이전트(Managed Agents): — Anthropic이 제공하는 HTTP 서비스로, 에이전트의 생성, 실행, 도구 호출 및 인간 개입(HITL) 과정을 API 뒤로 캡슐화하여 관리하는 기능이다. 에이전트의 생명주기를 직접 관리할 필요 없이 세션 단위로 제어할 수 있게 해준다.
결정론적 재현(Deterministic Replay): — 에이전트의 실행 과정을 시스템 호출(syscall) 단위로 기록하여, 동일한 입력과 환경에서 항상 똑같은 상태로 복구하거나 재실행할 수 있게 하는 기술이다. 에이전트가 중단된 지점부터 정확히 다시 시작하거나 과거 시점으로 되돌아가는 기능을 구현하는 데 필수적이다.
인간 개입 루프(HITL (Human-In-The-Loop)): — AI 에이전트가 작업을 수행하는 도중 중요한 결정이나 도구 실행 전에 인간의 승인이나 수정을 거치도록 설계된 워크플로우이다. 에이전트의 자율적 오류를 방지하고 안전성을 높이는 핵심 메커니즘이다.
와이어 호환성(Wire Compatibility): — 네트워크를 통해 전송되는 데이터의 형식(바이트 수준)이 일치하여, 특정 SDK를 사용하지 않더라도 동일한 API 엔드포인트와 통신할 수 있는 상태를 의미한다. 이는 공식 라이브러리의 버그나 제약에서 벗어나 독립적인 구현체를 만들 수 있게 한다.

언급된 도구

castor-server추천

Anthropic Managed Agents와 와이어 호환되는 오픈소스 에이전트 서버

LiteLLM추천

다양한 LLM 제공자를 통합된 API로 호출하기 위한 라이브러리

Roche추천

에이전트의 Bash 실행을 위한 격리된 Docker 컨테이너 샌드박스

언급된 리소스

GitHubcastor-server GitHub