agent-runtime-kit

agent-runtime-kit is a typed, async Python runtime API for running coding-agent tasks through the Claude Agent SDK, OpenAI Codex SDK, or Google Antigravity SDK without writing provider-specific plumbing. It is aimed at Python 3.10+ developers embedding coding agents into their own applications, who need a consistent surface for tasks, results, events, capability checks, and diagnostics across providers. Each adapter keeps the provider's permissions and supported inputs explicit: shared AgentTask and AgentResult types do not silently discard unsupported options such as per-task MCP servers or cost budgets, and mismatches raise typed errors. Unlike routers, queues, or hosted agent frameworks, it is strictly a runtime layer—your application decides when and where a task runs.

Features

• One async API, three providers. AgentKit runs the same task shape against Claude Agent SDK, OpenAI Codex SDK, or Google Antigravity SDK. Swap the runtime, keep the orchestration code.

async with AgentKit() as kit:
    result = await kit.run(runtime, goal="Summarize the repository layout")
    if not result.is_success:
        raise RuntimeError(result.error or result.finish_reason)

• Offline-first development. FakeAgentRuntime returns deterministic results with no vendor SDK, no credentials, and no network — ideal for tests and CI.

• Capability checks you can trust at the boundary. Probe a runtime before committing to a task; unsupported combinations fail fast and loudly.

caps = kit.capabilities(runtime)
if not caps.supports_mcp_servers:
    ...  # adjust task instead of discovering rejection mid-run

• Per-provider differences kept honest. Where adapters diverge (e.g. per-task MCP servers, per-server env values, cost budgets), the difference is surfaced — not normalized away.

• Sessions and deadlines. Long-running work supports session continuity, deadlines, and cancellation through the shared runtime surface.

• Diagnostics built in. Preflight probes and typed error reporting make provider setup issues diffable without reading vendor logs first.

• Async, typed, Python 3.10+. Full type annotations on the public surface; ADRs and an API-stability policy document what's covered.

• A runtime layer, not a framework. No router, queue, scheduler, or hosted service. You decide when and where a task runs; the kit handles the provider boundary.

How it works

agent-runtime-kit sits between your application and each vendor SDK. You describe a task once with AgentTask; the kit selects the runtime adapter, validates that the requested inputs are supported, executes the task, and normalizes provider output into AgentResult plus a stream of typed events.

AgentKit.run(runtime, goal, inputs)
        │
        ├─ capability check ──► typed error on unsupported input
        ├─ readiness probe ───► advisory only (task may still fail)
        ├─ runtime adapter ───► provider SDK (Claude / Codex / Antigravity)
        └─ normalize ─────────► AgentResult + events + diagnostics

Core objects

Execution flow

• Construct the kit. Use async with AgentKit() so provider resources are released on exit.
• Choose a runtime. Pass a fake runtime, a provider adapter instance, or let the kit resolve the configured provider.
• Validate inputs. Inputs unsupported by the chosen provider raise typed errors instead of being dropped.
• Probe readiness (optional). Availability and setup checks report whether a task is worth attempting; they cannot guarantee provider acceptance.
• Run the task. Events are yielded as the provider works; the final result is returned.
• Inspect the result. Branch on result.is_success and read result.output, result.error, or result.finish_reason.

Provider differences

The adapters share AgentTask and AgentResult, but each exposes different capabilities. Set only what the provider supports:

Unsupported inputs raise typed errors at validation time rather than failing mid-run. Native model selection is used unless you set a model explicitly.

Events and diagnostics

async with AgentKit() as kit:
    diag = await kit.diagnose(runtime)
    if not diag.available:
        raise RuntimeError(diag.reason)

    async for event in kit.stream(runtime, goal="Summarize the repo"):
        handle(event)

    result = kit.last_result
    if not result.is_success:
        raise RuntimeError(result.error or result.finish_reason)

Scope

The kit is a runtime layer, not a router, queue, hosted service, or full agent framework. Scheduling, retries across providers, and persistence remain the application's responsibility.

Compatibility

agent-runtime-kit targets Python 3.10+ and supports the three provider SDKs below. Each provider is optional: install only the extra you need, and the core package runs offline with FakeAgentRuntime.

• Python: 3.10 or newer. Type hints use the modern union and built-in generics syntax.
• Async only: all runtimes are driven through async APIs; a synchronous facade is not provided.
• Typed results: every adapter returns the same AgentResult shape, but provider-specific inputs are validated and unsupported ones raise typed errors rather than being dropped.
• Provider SDKs are not pinned to the core install. The core package imports without any vendor SDK present.

Capability differences

The shared AgentTask type does not imply identical provider behavior. Unsupported fields are rejected at validation time.

Call describe_capabilities() on a runtime before building a task when you need to branch on features:

from agent_runtime_kit import ClaudeAgentRuntime

runtime = ClaudeAgentRuntime()
caps = runtime.describe_capabilities()
if not caps.supports_mcp_servers:
    raise RuntimeError("this runtime cannot accept MCP servers")

Version and SDK evolution

Provider SDKs change independently of this package. Adapters validate at the boundary and surface drift as typed diagnostics instead of silent fallbacks. Readiness probes report whether a task is worth attempting; they cannot guarantee a provider will accept a request.

Platform notes

• Windows, macOS, and Linux are supported wherever the chosen provider SDK runs.
• Real provider tasks may require credentials, network access, and may incur costs; the fake runtime requires none of these.
• Tool use is governed by each provider's native permission model. See the permission guidance before granting write access.

Requirements

• Provider extras are opt-in. A task can only run against a provider SDK that is present in the environment. Missing SDKs surface as typed availability errors rather than import failures at package load.
• Capabilities differ per provider. Some inputs are rejected with