AI agent를 만드는 가장 단순한 코드는 이런 형태입니다.
while not done:
model_call()
tool_call()
observe()
하지만 production에서는 곧 질문이 늘어납니다.
- context가 너무 길어지면?
- process가 죽으면 어디서 재개하지?
- tool call 중간 상태는?
- 며칠짜리 작업은?
- sandbox 파일은?
- subagent는 누가 관리하지?
OpenAI의 Agents API는 이 중 상당 부분을 managed Codex harness로 제공합니다.
세 가지 출발점을 구분하면 쉽습니다
OpenAI 공식 가이드는 새로운 agent application에서 선택지를 다음처럼 나눕니다.
Agents API
→ OpenAI가 managed Codex harness와 durable session 운영
Codex SDK
→ 내 infrastructure에서 Codex harness 실행
Responses API
→ model call과 agent loop를 직접 소유
핵심 차이는 모델이 아니라 harness를 누가 운영하는가입니다.
Agents API가 관리해주는 것
공식 문서 기준 Agents API는 다음을 관리합니다.
- session orchestration
- context compaction
- recovery
- durable session state
- agent loop
필요하면 OpenAI-hosted sandbox나 외부 sandbox를 연결할 수 있습니다.
즉 개발자는 tool과 application logic에 더 집중할 수 있습니다.
직접 Loop가 더 좋은 경우도 있습니다
Managed harness가 항상 정답은 아닙니다.
다음 요구사항이 강하다면 직접 loop가 더 적합할 수 있습니다.
- 모든 model call 순서를 직접 제어
- 독자적인 memory/context algorithm
- 특수한 retry policy
- 여러 provider를 섞은 routing
- 내부 orchestration system과 밀접한 통합
- 세밀한 latency 최적화
통제권을 얻는 대신 운영해야 할 것이 늘어납니다.
CodeBridge Mini Lab: 같은 Tool Agent를 두 방식으로 만들어보기
작은 repository inspector agent를 가정합니다.
Tool:
list_files
read_file
run_tests
A 버전:
직접 while loop
직접 messages 관리
직접 retry
B 버전:
managed session
same tools
same task
비교 항목:
application code lines
recovery code
state persistence
observability
average completion time
failure handling
여기서 단순히 코드 줄 수가 적은 쪽을 고르는 것이 목적은 아닙니다. 내가 통제해야 할 부분과 맡겨도 되는 부분을 구분하는 것이 목적입니다.
Durable Session이 중요한 이유
긴 agent task는 한 HTTP request 안에서 끝난다는 보장이 없습니다.
Task 시작
→ 작업 진행
→ 외부 승인 대기
→ 다시 이어서 실행
Agents API의 session은 이런 지속 작업을 전제로 합니다. 애플리케이션은 같은 session에 후속 입력을 보내거나 진행 중 agent를 steer할 수 있습니다.
Sandbox와 Harness는 다른 층입니다
이 구분도 중요합니다.
Harness
→ 무엇을 다음에 할지 orchestration
Sandbox
→ 파일/명령/패키지를 실제로 다루는 실행 환경
Managed harness를 쓰면서 자체 sandbox를 연결할 수도 있고, harness와 sandbox 모두 직접 운영할 수도 있습니다.
결론: Agent API 선택은 '편한 SDK'보다 소유권 문제입니다
Agent framework를 비교할 때 기능 목록만 보면 비슷해 보입니다.
더 좋은 질문은 다음입니다.
context, retry, recovery, state, sandbox를 누가 책임질 것인가?
제품의 핵심 차별화가 agent orchestration 자체라면 직접 소유할 가치가 있습니다. 반대로 orchestration이 공통 인프라에 가깝다면 managed harness가 개발 속도와 운영 안정성에서 유리할 수 있습니다.