Skip to content

Helpers

ACP Kit also ships helper packages that are useful around the adapter runtime but are not part of the root CLI itself.

Today the main helper package is codex-auth-helper.

codex-auth-helper

codex-auth-helper turns an existing local Codex login into a pydantic-ai Responses model.

It handles:

  • reading ~/.codex/auth.json
  • refreshing expired tokens
  • deriving the account id
  • constructing a Codex-specific AsyncOpenAI client
  • returning a ready-to-use CodexResponsesModel

Why It Exists

Codex-backed model usage is easy to get subtly wrong by hand.

The helper centralizes the backend-specific behavior that should stay stable:

  • Codex Responses endpoint wiring
  • auth refresh flow
  • openai_store=False
  • streamed Responses usage even when Pydantic AI takes a non-streaming request path

Minimal Usage

from codex_auth_helper import create_codex_responses_model
from pydantic_ai import Agent

model = create_codex_responses_model("gpt-5.4")
agent = Agent(model, instructions="You are a helpful coding assistant.")

ACP-side usage looks the same:

from codex_auth_helper import create_codex_responses_model
from pydantic_ai import Agent
from pydantic_acp import run_acp

agent = Agent(
    create_codex_responses_model("gpt-5.4"),
    name="codex-agent",
)

run_acp(agent=agent)

What It Does Not Do

  • it does not log you into Codex
  • it does not create ~/.codex/auth.json
  • it does not support Chat Completions style OpenAIChatModel
  • it does not replace Pydantic AI itself

Lower-level Factories

If you want more control, the helper also exposes:

  • create_codex_async_openai(...)
  • CodexAsyncOpenAI
  • CodexResponsesModel
  • CodexAuthConfig
  • CodexTokenManager

The full API is documented in API Reference.