[jamesrochabrun]

Summary

Adds support for the Agents API (public beta), announced at OpenAI DevDay 2026. The Agents API exposes the managed Codex harness: hosted execution, memory, tools, and multi-agent support, with OpenAI handling sessions, orchestration, context compaction and recovery.

Stacked on #203 (GPT-6 models + Ultrafast tier).

New service methods

• createAgentSession(_:) — POST /v1/agents/sessions
• createAgentSessionStream(_:) — same endpoint with SSE streaming
• agentSessionEventStream(sessionID:) — GET /v1/agents/sessions/{id}/events (reopen the stream)
• submitAgentSessionEvents(sessionID:parameters:) — POST /v1/agents/sessions/{id}/events (follow-up messages, cancellations, approvals)
• listAgentSessionItems(sessionID:limit:order:after:) — GET /v1/agents/sessions/{id}/items
• deleteAgentSession(sessionID:) — DELETE /v1/agents/sessions/{id}

All requests send the OpenAI-Beta: agents=v1 header.

New types

• AgentSessionParameters — agent config (model, instructions, tools), environment (openai_hosted / none, desktop), input, stream. Tools: .computerUse(includeScreenshots:), .webSearch, and .custom as an escape hatch for shapes not yet modeled (e.g. MCP servers).
• AgentSessionEventsParameter / AgentSessionClientEvent — .message, .cancel, .custom (approvals).
• AgentSessionObject, AgentSessionItem, AgentSessionStreamEvent.

Beta-resilient decoding

OpenAI has not published the complete Agents API schemas, so response models are deliberately lenient:

• Documented fields are decoded as typed optionals; the complete payload is retained in a raw: OpenAIJSONValue member.
• Unrecognized stream event types decode as .unknown(String) instead of throwing — a decode failure would otherwise terminate the whole AsyncThrowingStream.
• submitAgentSessionEvents returns the raw JSON payload until the response schema is published.

AIProxy, Azure, and LocalModel services get fatalError stubs, consistent with how those services handle other unsupported endpoints (e.g. Conversations).

Testing

• 8 new unit tests covering parameter/event encoding against the documented JSON shapes, stream event decoding for all documented event types, the .unknown fallback, and raw-payload retention
• swift build and full test suite pass; swiftformat --lint clean

🤖 Generated with Claude Code