Agents API와 Agents SDK 선택 기준: 상태 관리 위치로 먼저 나누기

에이전트 선택은 기능표보다 상태 관리 위치가 먼저입니다

AI 에이전트를 붙이려는 개발팀이 가장 자주 하는 실수는 기능 이름부터 비교하는 것입니다. MCP를 지원하는지, tool calling이 되는지, multi-agent orchestration이 있는지부터 봅니다. 물론 중요합니다. 하지만 실무에서 더 먼저 정해야 할 것은 “상태를 누가 관리하는가”입니다.

OpenAI Agents 문서는 시작점을 네 가지로 나눕니다. OpenAI가 관리하는 Codex harness로 장기 작업을 돌리려면 Agents API, 애플리케이션 안에서 agent loop와 handoff를 제어하려면 Agents SDK, 모델 응답을 직접 제어하려면 Responses API, 임베디드 채팅 경험은 ChatKit을 보라고 설명합니다. 이 구분은 기술 스택 선택이 아니라 책임 경계 선택입니다.

상태 관리 위치를 잘못 고르면 나중에 구조를 갈아엎게 됩니다. 처음에는 Agents API가 빠르지만, 승인 흐름과 내부 권한 모델을 세밀하게 통제해야 하면 SDK 쪽이 맞을 수 있습니다. 반대로 SDK로 모든 것을 직접 만들면 유연성은 크지만 세션 저장, 도구 실행, sandbox, 관측가능성까지 직접 챙겨야 합니다.

Agents API가 맞는 경우

Agents API는 OpenAI가 관리하는 Codex harness를 실행하고, underlying agent infrastructure를 맡는 구조입니다. 문서에는 automatic context compaction, multi-agent orchestration, programmatic tool calling, MCP server support가 포함된다고 설명되어 있습니다. 장기 작업을 빠르게 붙이고 싶은 팀에게 적합합니다.

예를 들어 고객 지원 티켓을 읽고 관련 코드 위치를 조사한 뒤 수정 후보를 만들거나, 문서 저장소를 분석해 마이그레이션 계획을 작성하는 작업이 있습니다. 이런 작업은 여러 단계가 필요하고 중간 상태가 중요합니다. 하지만 모든 orchestration을 직접 만들 필요가 없다면 managed runtime이 시간을 줄여줍니다.

단점도 명확합니다. 에이전트가 어디서 실행되고, 어떤 sandbox를 쓰고, 도구 실행 권한을 어떻게 제한할지 정책을 이해해야 합니다. 빠르게 시작할 수 있다는 이유로 보안·감사 요구사항을 뒤로 미루면 나중에 막힙니다. Agents API는 “덜 만든다”는 장점이 있지만, “검토하지 않아도 된다”는 뜻은 아닙니다.

Agents SDK가 맞는 경우

Agents SDK는 애플리케이션이 agent loop, storage, approval, runtime integration을 더 많이 통제하는 방식입니다. 문서 표현대로라면 SDK의 runner가 agent loop와 handoff를 처리하지만, 배포와 저장소, 승인 흐름, 런타임 통합은 애플리케이션 쪽 책임이 커집니다.

이 방식은 사내 시스템과 깊게 묶인 에이전트에 어울립니다. 예를 들어 결재 시스템, 내부 권한, 고객 데이터 접근, 감사 로그, 사내 queue와 연결해야 하는 경우입니다. 에이전트가 어떤 단계에서 멈추고 사람 승인을 받아야 하는지, 어떤 도구 호출은 금지해야 하는지, 어떤 결과는 내부 DB에 저장해야 하는지를 직접 설계할 수 있습니다.

대신 구현 난이도는 올라갑니다. 세션 저장소, retry 정책, tool schema, 권한 검증, observability를 직접 챙겨야 합니다. 작은 팀이 처음부터 SDK로 모든 것을 만들면 에이전트 기능보다 플랫폼 작업에 시간을 더 쓸 수 있습니다. 그래서 SDK는 “통제가 필요한 이유”가 명확할 때 선택하는 편이 좋습니다.

Responses API가 맞는 경우

Responses API는 모델 호출과 흐름을 직접 제어하려는 팀에 맞습니다. 이미 자체 orchestration이 있고, 에이전트라는 추상화보다 request/response 단위 제어가 중요한 경우입니다. 예를 들어 기존 workflow engine, queue, worker, audit log가 있고 AI 호출만 하나의 step으로 넣는 구조입니다.

이 방식은 가장 유연하지만 가장 많은 것을 직접 책임집니다. 대화 기록, tool 결과, 재시도, 부분 실패, 비용 추적, 권한을 모두 애플리케이션이 관리해야 합니다. 반대로 이미 검증된 백엔드 구조가 있다면 Responses API가 가장 예측 가능할 수 있습니다.

실무에서는 “우리가 agent platform을 만들 것인가, AI 기능을 제품 흐름에 넣을 것인가”를 먼저 물어야 합니다. 전자라면 SDK나 Agents API를 검토하고, 후자라면 Responses API가 단순할 수 있습니다.

선택 기준을 표로 정리하기

아래 표는 기능 수가 아니라 운영 책임 기준으로 나눈 것입니다.

이 표만으로 결론을 내리면 안 됩니다. 하지만 초기 논의를 정리하는 데는 충분합니다. “MCP가 되나요?”보다 “상태와 승인 흐름을 어디에 둘 건가요?”가 먼저입니다.

아키텍처 결정 전에 확인할 질문

첫째, 작업이 몇 분짜리인지 몇 시간짜리인지 확인합니다. 장기 작업이면 중간 상태와 재개 가능성이 중요합니다. 둘째, 도구 실행 권한을 누가 검증하는지 정합니다. 에이전트가 파일, DB, 외부 API에 접근한다면 approval 설계가 필요합니다. 셋째, 실패했을 때 누가 복구하는지 정합니다. managed runtime이라도 비즈니스 복구 로직은 제품팀 책임입니다.

넷째, 관측가능성(Observability)을 어디서 볼지 정합니다. 사용량, tool call, 오류, 사람 승인, 최종 산출물이 한곳에 남아야 합니다. 다섯째, sandbox가 필요한지 봅니다. 코드 실행, 파일 처리, 외부 명령이 들어가면 실행 환경 격리가 필요합니다.

이 질문에 답하지 않은 상태에서 API를 고르면, 나중에 “왜 이 상태가 저장되지 않았지?”, “왜 이 도구가 실행됐지?”, “왜 비용이 이렇게 나왔지?” 같은 문제가 생깁니다.

실행 체크리스트

• 먼저 에이전트 상태를 OpenAI, SDK 세션, 자체 DB 중 어디에 둘지 정합니다.
• 승인 흐름이 단순하면 Agents API, 사내 권한과 깊게 연결되면 Agents SDK를 우선 검토합니다.
• 이미 자체 workflow engine이 있다면 Responses API로 AI step만 넣는 방식을 검토합니다.
• MCP, tool calling, sandbox는 기능이 아니라 권한 모델과 함께 설계합니다.
• 장기 작업은 resume, timeout, partial failure, audit log 기준을 먼저 적습니다.
• PoC는 가장 위험한 통합 지점 하나를 골라 검증합니다.

Agents API와 Agents SDK의 차이는 “어느 쪽이 더 좋다”가 아닙니다. 상태와 책임을 어디에 둘 것인가의 차이입니다. 다음 에이전트 프로젝트를 시작한다면 첫 회의의 질문은 이것이면 충분합니다. 이 에이전트가 실패했을 때, 어떤 상태를 누가 보고 복구할 수 있어야 하나요?