iop/agent-contract/provided/openai-compatible-api.md

OpenAI-Compatible API Contract

계약 메타

• id: iop.openai-compatible-api
• provider: iop
• status: active
• human docs: docs/openai-compatible-api-contract.md

범위

이 문서는 외부 프로젝트가 IOP Edge의 OpenAI-compatible HTTP 표면을 호출할 때 확인할 계약 원문이다. IOP 내부 실행은 adapter + target 기준이며, OpenAI-compatible 경계에서는 호환성을 위해 model을 사용한다. IOP 고유 실행 문맥은 별도 iop wrapper field를 만들지 않고 OpenAI request의 metadata에 둔다.

Responses API

Endpoint:

POST /v1/responses
Content-Type: application/json

CLI agent 실행으로 라우팅되는 요청의 최소 형태:

{
  "model": "codex",
  "input": "현재 워크스페이스의 테스트 상태를 확인해줘.",
  "metadata": {
    "workspace": "/config/workspace/iop"
  }
}

필드 의미:

• model: Edge가 내부 adapter + target으로 해석할 외부 route 이름이다.
• input: agent에게 전달할 사용자 요청이다.
• metadata.workspace: CLI process를 실행할 작업 디렉터리다. CLI agent route에서는 필수 실행 문맥이다.

금지:

• metadata.cli 같은 CLI 전용 wrapper를 추가하지 않는다.
• root-level iop 같은 별도 wrapper field를 추가하지 않는다.
• workspace를 prompt 본문에 섞어 전달하지 않는다.

현재 구현 메모:

• /v1/responses는 non-streaming 요청만 지원한다.
• 기존 metadata 계약인 metadata.request_id, metadata.nomadcode.task_id, metadata.nomadcode.source, metadata.inference.target은 유지한다.
• CLI route의 metadata.workspace는 이 문서의 계약 기준이다. 구현은 이 값을 Edge service의 run workspace와 Node CLI adapter의 process working directory로 전달해야 한다.

Chat Completions

/v1/chat/completions도 같은 metadata 원칙을 따른다. CLI route의 workspace는 metadata.workspace에 둔다.

{
  "model": "codex",
  "messages": [
    {
      "role": "user",
      "content": "현재 워크스페이스의 테스트 상태를 확인해줘."
    }
  ],
  "metadata": {
    "workspace": "/config/workspace/iop"
  }
}

Routing

Edge 설정이 openai.model_routes[]를 제공하면 model은 먼저 route catalog에서 해석된다. 매칭 route가 없으면 기존 fallback 규칙에 따라 openai.target 또는 요청의 model을 내부 target으로 사용한다.

CLI agent를 OpenAI-compatible API로 노출할 때는 route catalog에서 해당 model을 명시적으로 adapter: "cli"와 target profile로 매핑하는 방식을 우선한다.