전용 에이전트 프레임워크 대신 일반 프로그래밍 코드로 AI 에이전트의 실행 흐름을 직접 정의하고 제어하는 설계 패턴. 코드 자체가 오케스트레이션 레이어가 된다.
AI 에이전트를 구축할 때 보통 두 가지 선택지가 있다. LangChain, CrewAI, LangGraph 같은 전용 프레임워크를 쓰거나, Python이나 JavaScript 같은 일반 코드로 직접 에이전트 실행 흐름을 정의하는 것이다. 후자가 바로 코드 에이전트 하네스 접근 방식이다.
여기서 코드는 단순한 에이전트 호출 스크립트가 아니다. 에이전트가 어떤 순서로 실행되고, 어떤 조건에서 분기하고, 결과를 어떻게 다음 단계로 넘기는지 — 이 모든 오케스트레이션 로직을 코드로 명시적으로 표현한다. 프레임워크의 추상화 레이어 없이 코드가 직접 하네스 역할을 한다.
Claude Code의 워크플로우 스크립트가 대표적인 사례다. agent(), parallel(), pipeline() 같은 기본 함수를 조합해서 복잡한 멀티에이전트 파이프라인을 일반 JavaScript 코드로 작성한다. "코드 리뷰 에이전트 3개를 병렬로 실행하고, 결과를 모아 검증 에이전트에 넘긴다"는 로직이 parallel()과 pipeline() 호출 몇 줄로 표현된다.
이 방식은 프레임워크 없이도 에이전트 동작을 완전히 제어할 수 있다는 장점이 있다. 디버깅할 때는 코드를 그대로 읽으면 되고, 실행 흐름을 추적할 때도 별도 도구가 필요 없다.
전용 에이전트 프레임워크는 추상화된 액터(Actor), 노드(Node), 엣지(Edge) 같은 개념으로 에이전트를 정의한다. 반면 코드 에이전트 하네스에서는 이런 추상화 없이 직접 함수 호출과 제어 흐름으로 에이전트를 조율한다. 12-factor agents 원칙에서도 에이전트를 일반 소프트웨어처럼 다루라고 강조하는데, 이 철학과 맥을 같이한다.
코드 에이전트 하네스 방식은 투명성과 제어력이 높은 반면, 재사용 패턴을 직접 추상화해야 한다. 병렬 실행, 오류 처리, 재시도 로직 같은 공통 패턴을 팀에서 매번 구현하거나 내부 라이브러리로 만들어야 한다는 부담이 있다.