toki
24735a5914
- Update agent contract documentation for openai-compatible API - Update automation-runtime-bridge milestone tracking - Add edge smoke tests for openai CLI workspace - Add node CLI adapters (codex, opencode, oneshot, persistent) - Add e2e openai-cli-workspace script - Add agent task tracking for execution contract
104 lines
3.8 KiB
Markdown
104 lines
3.8 KiB
Markdown
# 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:
|
|
|
|
```http
|
|
POST /v1/responses
|
|
Content-Type: application/json
|
|
```
|
|
|
|
CLI agent 실행으로 라우팅되는 요청의 최소 형태:
|
|
|
|
```json
|
|
{
|
|
"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로 전달해야 한다.
|
|
|
|
## NomadCode Authoring Handoff
|
|
|
|
NomadCode Core가 IOP Edge HTTP 표면으로 workspace authoring 작업을 넘길 때의 최소 요청 형태:
|
|
|
|
```json
|
|
{
|
|
"model": "codex",
|
|
"input": "Todo 항목에 필요한 산출물을 현재 checkout에 작성해줘.",
|
|
"metadata": {
|
|
"workspace": "/config/workspace/nomadcode-slot-123",
|
|
"task_id": "todo-123",
|
|
"source": "nomadcode"
|
|
}
|
|
}
|
|
```
|
|
|
|
NomadCode task/source context는 flat `metadata.task_id`와 `metadata.source`로 전달할 수 있다.
|
|
동일한 의미의 structured 형태가 필요하면 `metadata.nomadcode.task_id`와 `metadata.nomadcode.source`를 사용하며, flat alias와 structured 값이 함께 있으면 structured 값을 우선한다.
|
|
|
|
이 handoff는 `model`, `input`, `metadata.workspace`, task/source metadata만으로 충분해야 한다.
|
|
호출자는 `metadata.cli`, root-level `iop` wrapper, IOP CLI 직접 실행, prompt 본문 workspace 주입을 요구받지 않는다.
|
|
|
|
Workspace-bound route는 workspace가 없거나 상대 경로이면 OpenAI-compatible error로 거부한다.
|
|
존재하지 않는 경로, 권한 오류, agent process exit failure는 기본 cwd fallback으로 숨기지 않고 호출자가 실패로 구분할 수 있어야 한다.
|
|
|
|
## Chat Completions
|
|
|
|
`/v1/chat/completions`도 같은 metadata 원칙을 따른다. CLI route의 workspace는 `metadata.workspace`에 둔다.
|
|
|
|
```json
|
|
{
|
|
"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로 매핑하는 방식을 우선한다.
|