Skip to content

Helpers

ACP Kit also ships helper packages that are useful around the adapter runtime but are not themselves adapter packages.

Today the main helper packages are:

  • codex-auth-helper
  • acpremote

Helper docs:

acpremote

acpremote is the transport helper package.

It handles:

  • exposing any existing acp.interfaces.Agent over WebSocket
  • exposing stdio ACP commands over WebSocket
  • mirroring a remote ACP endpoint back into a local ACP agent boundary
  • serving /acp metadata and /healthz alongside the WebSocket endpoint

Use it when you already have an ACP server and need remote transport, not when you need to adapt a framework runtime into ACP for the first time.

If the runtime is still a Python target, the usual path is:

  1. resolve it through acpkit
  2. expose it through pydantic-acp or langchain-acp
  3. use acpremote only when you need WebSocket transport or a local mirror

Read the full transport guide in acpremote Overview.

codex-auth-helper

codex-auth-helper turns an existing local Codex login into either:

  • a pydantic-ai Responses model
  • a LangChain ChatOpenAI model pinned to the Responses API

It handles:

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

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

Pydantic AI:

from codex_auth_helper import create_codex_responses_model
from pydantic_ai import Agent

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

Pass instructions= explicitly to create_codex_responses_model(...). On the Pydantic path you can also add Agent(instructions=...) when you want agent-owned instructions on top of the factory default.

LangChain:

from codex_auth_helper import create_codex_chat_openai
from langchain.agents import create_agent

graph = create_agent(
    model=create_codex_chat_openai(
        "gpt-5.4",
        instructions="You are a helpful coding assistant.",
    ),
    tools=[],
    name="codex-graph",
)

create_codex_chat_openai(...) requires instructions=. There is no implicit default on the LangChain path.

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",
        instructions="You are a helpful ACP coding assistant.",
    ),
    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 provide generic Chat Completions wiring
  • it does not replace Pydantic AI itself

Lower-level Factories

If you want more control, the helper also exposes:

  • create_codex_async_openai(...)
  • create_codex_openai(...)
  • create_codex_chat_openai(...)
  • CodexAsyncOpenAI
  • CodexOpenAI
  • CodexResponsesModel
  • CodexAuthConfig
  • CodexTokenManager

The full API is documented in API Reference.