RFC: Integration with Codex CLI

[noobHappylife]

Problem statement / motivation

This RFC discussed and present findings about Codex CLI. This aims to let agentic-api be able to bridge vLLM and Codex CLI.

A) The built-in tool types that Codex CLI uses, for agentic-api to work with Codex CLI. Will need to properly handle these tool types.
B) The Codex CLI auto-approval feature required an auto-approval model. So, for agentic-api to be compatible with this feature, will need to handle the auto-approval model properly.

A) Codex CLI built-in tool types

Codex CLI will call these tool types:

Type	Execution
type: "function"	Codex CLI executes
type: "namespace"	Codex CLI executes
type: "tool_search"	Codex CLI executes
type: "custom"	Codex CLI executes
type: "code_interpreter"	agentic-api executes
type: "web_search"	agentic-api executes

• type: function is essentially the common function tool call
• type code_interpreter and web_search are both OpenAI built-in tools that are executed server-side.
• while type "namespace", "tool_search", "custom" are function type that Codex CLI might send in a request. And the model is supposed to return the tool call signature and let Codex CLI execute and return the tool call result

Solutions:

• Likely agentic-api needs to recognize these tool type and internally mapped to a function tool call to pass to upstream vLLM.

---

Here are some examples to what the namespace", "tool_search", "custom" are.

• namespace — Tool Container

{
    "type": "namespace",
    "name": "mcp__github",
    "description": "GitHub tools",
    "tools": [
        {"name": "create_issue", "description": "Create issue", "parameters": {...}},
        {"name": "search_code", "description": "Search code", "parameters": {...}}
    ]
}

• tool_search — Deferred Tool Discovery

{
    "type": "tool_search",
    "description": "Search for deferred tools",
    "parameters": {
        "type": "object",
        "properties": {
            "query": {"type": "string", "description": "Search query"},
            "limit": {"type": "number", "description": "Max results"}
        },
        "required": ["query"]
    }
}

• custom — Custom/Freeform Tool

{
    "type": "custom",
    "name": "lark_parser",
    "description": "Parse Lark grammar files",
    "format": {
        "type": "grammar",
        "syntax": "lark",
        "definition": "..."
    }
}

---

B) Codex CLI auto-approval models

Codex uses a specific model for automatic approval review (when approval_policy is on-request or on-failure).

• When auto-approval is triggered, codex makes a request to the gateway:

{
    "model": "codex-auto-review",
    "messages": [...approval context...],
    "tools": [...]
}

Solutions:

• agentic-api can have an alias mapping such that codex-auto-review can mapped to a real upstream vLLM model.
• Or, agentic-api can implement a proper /v1/models (Codex CLI expect a shape different from vLLM's /v1/models) that Codex CLI recognize and in the return json, we can set a field "auto_review_model_override": "real-upstream-model"

The alias way is simpler, but a Codex CLI-style /v1/models can help with setting the model metadata that Codex CLI expects. Without it, will need to configure the configuration file directly.

P.S. There's supposed a fallback behavior where the auto-approval model will fallback to the existing running model, but I can't seem to trigger this behavior. More tests may be needed on this.

Alternatives considered

No response

Additional context

Any other findings or suggestions are welcome.

[ashwing]

Good writeup — the tool type taxonomy is really useful context. A few thoughts on implementation:

Type-aware routing is the critical enabler

Right now dispatch_tools treats all FunctionCall items as gateway-executable (see the MVP note in dispatch.rs:53-56). To support Codex, we need the dispatch layer to know which tools are client-side (function, namespace, tool_search, custom) vs gateway-side (web_search, code_interpreter). That means passing the request's tools array into dispatch_tools — already flagged as a follow-up in the code.

Once dispatch can classify, the Codex flow falls out naturally:

• Gateway tools → execute server-side, inject results, re-enter loop
• Client tools → LoopDecision::Done with status: requires_action so Codex executes them

Namespace → flatten feels like the right approach

vLLM only understands flat function tools. A pre-processing step that expands type: "namespace" containers into individual function definitions before forwarding to the backend is clean. The names are already namespaced (mcp__github.create_issue), so no collision risk. This is a pure transform — no new infrastructure needed.

On model aliases

The simple alias map (codex-auto-review → real model) at the config level seems right for MVP. It's just a string replacement before the inference call. A full /v1/models endpoint could come later but isn't blocking — Codex can be configured to use the model name directly.

Suggested phasing:

1. Type-aware dispatch (classify client vs gateway tools) — this unblocks everything
2. Namespace flattener (pure request transform)
3. Model alias config (one-liner in ExecutionContext)
4. /v1/models endpoint (nice-to-have, not blocking)

Happy to help with phase 1 — the dispatch layer is adjacent to work I'm already doing in the tool routing area.