채팅창 대신 손이 생긴 API

무엇이 바뀌었나

확인 오픈AI가 에이전트 API(Agents API)를 모든 개발자 대상 공개 베타로 냈다. 코딩 에이전트 코덱스를 실제로 돌리는 하네스 — 컨텍스트 압축, 도구 호출, 하위 에이전트 조정을 처리하는 실행 계층 — 를 오픈AI가 직접 운영·유지하고, 개발자는 그 위에 API 호출 한 번으로 올라타는 구조다.

확인 공식 문서에 실제 요청 형태가 그대로 적혀 있다. 엔드포인트는 https://api.openai.com/v1/agents/sessions, 베타 헤더 OpenAI-Beta: agents=v1이 필수다. 요청에 모델·지시문·실행 환경· 작업 입력을 담아 보내면, 에이전트가 실제로 코드를 만들고 실행한 결과를 스트리밍으로 돌려준다.

왜 중요한가

이 사이트 교육 과정 L1·02 도구 지형도에서 "채팅창에 물으면 설명이 오고, 도구를 쥐여준 자리에서 물으면 실제로 실행된다"고 적었다. 에이전트 API는 그 "도구를 쥐여주는 자리"를 만드는 일 자체를 대신 해 준다. 전에는 개발자가 컨텍스트 압축 로직, 도구 호출 순서, 하위 작업 쪼개기를 직접 짜야 코덱스 비슷한 걸 흉내 낼 수 있었는데, 이제는 API 요청 하나에 그 실행 계층이 딸려 온다.

확인 대신 그 대가로 통제권 하나를 내준다 — 데이터가 미국 밖으로 안 나가야 하거나 처리 즉시 지워져야 하는 자료라면, 지금은 이 API에 그대로 태울 수 없다. 편의와 통제권을 맞바꾸는 구도는 이 사이트에서 여러 번 다룬 패턴이다.

직접 해 보기 — 10분

1. API 키를 확인한다. platform.openai.com에 로그인해 있는 계정이라면 기존 API 키를 그대로 쓸 수 있다. 새로 만든다면 결제 수단 등록 여부부터 확인한다 — 이 API도 결국 토큰·도구 사용량만큼 과금된다.
2. 터미널에 아래 요청을 그대로 붙여 넣는다. 공식 문서에 실린 예시를 그대로 옮긴 것이다. 현재 디렉터리 파일 트리를 출력하는 스크립트를 에이전트가 직접 만들고 실행까지 한다.

   curl --no-buffer --fail-with-body https://api.openai.com/v1/agents/sessions \
     -H "OpenAI-Beta: agents=v1" \
     -H "Authorization: Bearer $OPENAI_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "agent": {
         "model": "gpt-6-astra",
         "instructions": "Write clean code, run it, and report the actual output."
       },
       "environment": { "type": "openai_hosted" },
       "input": "Create tree.py, a Python script that prints a readable tree of the files in the current directory. Run it and show me the output.",
       "stream": true
     }'

3. 스트리밍 출력을 그대로 지켜본다. 코드를 쓰는 단계, 실행하는 단계, 결과를 보고하는 단계가 이벤트로 순서대로 찍힌다. 채팅창에 같은 문장을 입력했을 때와 무엇이 다른지 — 설명이 아니라 실행 결과가 온다는 점 — 을 직접 비교해 본다.
4. 헤더를 빠뜨리면 어떻게 되는지도 한 번 봐 둔다. OpenAI-Beta: agents=v1을 빼고 같은 요청을 보내면 에러가 난다. 베타 기능이라 스펙이 아직 안정판이 아니라는 뜻으로 받아들이면 된다.
5. 사용량 페이지에서 실제 비용을 확인한다. platform.openai.com의 Usage 화면에서 이 요청이 토큰·샌드박스 항목으로 얼마 찍혔는지 본다. "API 자체는 무료"라는 말과 "0원이 나온다"는 다른 이야기다.

한 줄 정리

1. 코덱스를 돌리던 하네스가 API 한 번으로 열렸다 — 이용료는 없고 토큰·도구·샌드박스만 과금된다.
2. 데이터는 미국 리전 한정이고 제로 데이터 리텐션은 안 된다 — 민감한 자료는 아직 넣지 않는다.
3. 채팅과 다른 점은 결과가 설명이 아니라 실행으로 온다는 것 — 직접 curl 한 번 찍어 보면 그 차이가 바로 보인다.