Codex 에이전트 루프 해체하기

• Codex CLI는 로컬 환경에서 안전하고 효율적으로 고품질 소프트웨어 변경을 수행하는 에이전트로 설계됨
• 핵심 구조인 에이전트 루프(agent loop) 는 사용자 입력, 모델 추론, 도구 호출을 순환적으로 연결해 의미 있는 작업을 수행
• 루프 과정에서 생성되는 프롬프트 구성, 컨텍스트 윈도 관리, 프롬프트 캐싱이 성능과 안정성의 핵심 요소로 작동
• Codex는 Responses API를 통해 모델과 통신하며, 각 요청은 완전한 JSON 페이로드로 구성되어 무상태(stateless) 동작을 유지
• 이러한 구조는 Zero Data Retention(ZDR) , 프롬프트 캐싱, 자동 압축(compaction) 등 고급 기능을 가능하게 하며, 대규모 에이전트 설계의 기반을 형성

Codex 에이전트 루프 개요

• Codex CLI는 사용자, 모델, 도구 간 상호작용을 조율하는 루프 구조를 중심으로 동작
  • 사용자의 입력을 받아 모델에 전달할 프롬프트(prompt) 를 구성
  • 모델이 응답을 생성하거나 도구 호출(tool call) 을 요청하면, 에이전트가 이를 실행하고 결과를 다시 프롬프트에 추가
  • 모델이 더 이상 도구 호출을 하지 않고 assistant 메시지를 생성하면 한 턴이 종료됨
• 각 턴은 대화(conversation) 의 일부로, 이전 메시지와 도구 호출 내역이 모두 다음 요청의 프롬프트에 포함됨
• 프롬프트 길이는 모델의 컨텍스트 윈도(context window) 제한에 영향을 받기 때문에, Codex는 이를 관리해야 함

Responses API와 Codex의 통신 구조

• Codex CLI는 모델 추론을 위해 Responses API에 HTTP 요청을 보냄
  • API 엔드포인트는 설정에 따라 다르며, OpenAI, ChatGPT, Azure, 로컬(LM Studio, Ollama 등) 환경에서 모두 사용 가능
• API 요청은 JSON 페이로드로 구성되며 주요 필드는 다음과 같음
  • system/developer 메시지: 모델의 기본 맥락 설정
  • instructions: 모델이 호출할 수 있는 도구 목록
  • tools: Codex CLI, Responses API, 사용자(MCP 서버 등)가 제공하는 도구 정의
  • input: 대화 내역 및 환경 정보를 포함한 메시지 리스트
• Codex는 ~/.codex/config.toml 설정과 프로젝트 내 AGENTS.md, skills 파일 등을 읽어 사용자 지침과 환경 정보를 자동 삽입

프롬프트 구성과 이벤트 처리

• Codex는 각 메시지를 JSON 객체(type, role, content)로 구성해 Responses API에 전송
• 서버는 이 JSON을 기반으로 모델 프롬프트를 생성하고, SSE(Server-Sent Events) 스트림으로 응답을 반환
  • response.output_text.delta 이벤트는 스트리밍 출력에 사용
  • response.output_item.added 이벤트는 다음 요청의 input에 추가되어 루프를 지속
• 이전 프롬프트가 새 프롬프트의 정확한 접두(prefix) 가 되도록 설계되어, 프롬프트 캐싱(prompt caching) 을 활용 가능

성능 최적화: 캐싱과 무상태 설계

• Codex는 previous_response_id를 사용하지 않아 완전한 무상태(stateless) 요청 구조를 유지
  • 이는 Zero Data Retention(ZDR) 고객 지원과 데이터 보존 최소화를 가능하게 함
• 프롬프트 캐싱은 동일한 접두부를 재사용해 샘플링 비용을 선형화(linear) 함
  • 캐시 히트는 프롬프트의 정확한 접두 일치에서만 발생
  • 도구 목록, 모델, 샌드박스 설정, 작업 디렉터리 변경은 캐시 미스를 유발
• MCP 도구의 동적 변경은 캐시 손실을 일으킬 수 있어, Codex는 새 메시지 삽입 방식으로 변경 사항을 반영

컨텍스트 윈도 관리와 자동 압축(compaction)

• 대화가 길어지면 컨텍스트 윈도 초과를 방지하기 위해 대화 압축(compaction) 을 수행
  • 초기에는 /compact 명령으로 수동 요약을 수행했으나, 현재는 Responses API의 /responses/compact 엔드포인트를 자동 사용
  • 이 엔드포인트는 type=compaction 항목과 암호화된 encrypted_content 를 반환해 모델의 이해를 유지
• Codex는 auto_compact_limit을 초과하면 자동으로 압축을 실행해 대화 지속성을 확보

결론 및 향후 방향

• Codex의 에이전트 루프는 모델 추론, 도구 호출, 캐싱, 컨텍스트 관리를 통합한 핵심 구조
• 이 구조는 고성능·무상태·보안 중심의 에이전트 설계를 가능하게 함
• 이후 게시물에서는 CLI 아키텍처, 도구 사용 구현, 샌드박싱 모델 등 Codex의 내부 구조를 추가로 다룰 예정