Metadata-Version: 2.4
Name: agent-runtime-kit
Version: 0.5.0
Summary: One typed runtime API for Claude, Codex, and Antigravity agent SDKs.
Project-URL: Homepage, https://github.com/ebarti/agent-runtime-kit
Project-URL: Repository, https://github.com/ebarti/agent-runtime-kit
Project-URL: Issues, https://github.com/ebarti/agent-runtime-kit/issues
Author: Eloi Barti
License-Expression: MIT
License-File: LICENSE
Keywords: agent-runtime,agent-sdk,agents,antigravity,async-python,claude,claude-code,codex,coding-agents,developer-tools,google-antigravity,mcp,openai-codex,runtime-api,sdk,typed-python
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: jsonschema<5,>=4.18
Provides-Extra: all
Requires-Dist: claude-agent-sdk<0.3,>=0.2.87; extra == 'all'
Requires-Dist: google-antigravity<0.2,>=0.1.2; extra == 'all'
Requires-Dist: openai-codex<0.2,>=0.1.0b3; extra == 'all'
Provides-Extra: antigravity
Requires-Dist: google-antigravity<0.2,>=0.1.2; extra == 'antigravity'
Provides-Extra: claude
Requires-Dist: claude-agent-sdk<0.3,>=0.2.87; extra == 'claude'
Provides-Extra: codex
Requires-Dist: openai-codex<0.2,>=0.1.0b3; extra == 'codex'
Description-Content-Type: text/markdown

# agent-runtime-kit

`agent-runtime-kit` is a small Python runtime layer for agent SDKs. It gives
applications one typed async API for dispatching an agentic task through Claude
Agent SDK, OpenAI Codex SDK, or Google Antigravity SDK while keeping provider
capabilities visible.

**Tags:** `agent-sdk` `agent-runtime` `coding-agents` `claude-code`
`openai-codex` `google-antigravity` `mcp` `typed-python` `async-python`
`developer-tools`

## About

`agent-runtime-kit` is for Python developers who want to run coding-agent tasks
through vendor runtimes without rewriting their application around each SDK. It
normalizes the runtime boundary: task inputs, capability checks, event streams,
tool audits, package/readiness diagnostics, and typed results.

The library keeps vendor differences visible. Claude, Codex, and Antigravity
still expose different capabilities, permission models, setup requirements, and
unsupported fields. `agent-runtime-kit` gives those differences a consistent
shape instead of hiding them behind a lowest-common-denominator wrapper.

The package is intentionally not a router, benchmark harness, queue, hosted
service, or full agent framework. It is the reusable layer underneath those
systems: task models, runtime capabilities, event sinks, package/readiness
diagnostics, and adapters.

## Install

If you want all first-party runtimes available, install the `all` extra:

```bash
pip install "agent-runtime-kit[all]"
```

Install the vendor-SDK-free core when you only need the public models, fake
runtime, registry, diagnostics types, or you plan to add provider SDKs later:

```bash
pip install agent-runtime-kit
```

Install a single provider extra when your application only dispatches through
one vendor runtime:

```bash
pip install "agent-runtime-kit[claude]"
pip install "agent-runtime-kit[codex]"
pip install "agent-runtime-kit[antigravity]"
```

Provider extras are a packaging boundary, not a separate API. They keep the
core importable without vendor SDKs, avoid forcing every user to install every
CLI binary or compiled runtime wheel, and contain dependency drift when one
fast-moving vendor SDK changes independently of the others. Missing adapters
raise typed setup errors that point to the matching extra.

```python
import asyncio

from agent_runtime_kit import AgentTask, FakeAgentRuntime


async def main() -> None:
    runtime = FakeAgentRuntime(output="done")
    result = await runtime.run(AgentTask(goal="Summarize this repository"))
    print(result.output)


asyncio.run(main())
```

The core package has no Claude, Codex, or Antigravity dependency. Vendor SDKs
are added through optional extras.

## Real Providers

`AgentKit` is the keyword-native hub: it registers the built-in runtimes,
caches them per kind, and turns Python types into structured output.

```python
import asyncio
from dataclasses import dataclass

from agent_runtime_kit import AgentKit, ReadinessStatus


@dataclass
class RepoSummary:
    name: str
    languages: list[str]


async def main() -> None:
    async with AgentKit() as kit:
        readiness = await kit.readiness_for("claude")
        if readiness.status is ReadinessStatus.NOT_READY:
            raise RuntimeError(readiness.message)
        result = await kit.run(
            "claude",
            goal="Summarize this repository",
            permissions="strict",
            output_type=RepoSummary,
        )
        print(result.parsed.languages if result.parsed else result.error)


asyncio.run(main())
```

Adapters also work standalone when you need vendor-specific configuration:

```python
import asyncio

from agent_runtime_kit import AgentTask, ReadinessStatus, check_readiness
from agent_runtime_kit.adapters import ClaudeAgentRuntime


async def main() -> None:
    runtime = ClaudeAgentRuntime(default_model="claude-sonnet-4-6")
    readiness = await check_readiness(runtime)
    if readiness.status is ReadinessStatus.NOT_READY:
        raise RuntimeError(readiness.message)
    result = await runtime.run(AgentTask(goal="Summarize this repository"))
    print(result.output)


asyncio.run(main())
```

## Runtime Fields

`AgentTask` supports goal, system prompt, model, reasoning effort, working
directory, permission profile, MCP stdio servers, session/resume handles, output
schema, budget, metadata, and an async event sink. (`model` and
`reasoning_effort` are first-class fields; the legacy `metadata["model"]` /
`metadata["reasoning_effort"]` aliases still work.) Where a runtime cannot honor
a field (for example only Claude maps `budget_usd`; Codex and Antigravity reject
it with a typed `UnsupportedTaskInputError`) the adapter raises rather than
silently dropping it.

Model selection follows one explicit precedence chain: `AgentTask.model`, then
legacy `metadata["model"]`, then an adapter's `default_model=` constructor
override, then the provider's native configuration/default. Adapters omit the
vendor model option at the final step rather than pinning a library-owned model.
Results record `metadata["model_source"]`; `metadata["model"]` appears only when
the kit knows the selected value.

Call `validate_task(runtime, task)` (or `kit.validate_task("codex", task)`) to
inspect every statically detectable incompatibility before dispatch. The
returned `TaskSupportReport` is side-effect-free and lists source fields such as
`budget_usd` and `permissions.network`; `run()` still fails closed on the first
issue. Third-party runtimes can opt into provider-specific checks with the
`TaskSupportProvider` protocol, while older `AgentRuntime` implementations
continue to work through capability-based fallback checks.

`availability()` is deliberately synchronous, side-effect-free, and package-only.
Use `await check_readiness(runtime)` (or `kit.readiness_for(...)`) for an explicit,
bounded credential/setup probe. `READY_TO_ATTEMPT` means setup was positively
detected, not that a future provider call is guaranteed to succeed;
`INDETERMINATE` lets callers decide whether to attempt provider-chain or local
login authentication. Probe failures and timeouts never include credential values.

`AgentResult` returns output, finish reason (see `FinishReason`), locally
validated structured output, usage, cost, session id, tool-call audits, and
provider metadata. `is_success` is true only for a natural, error-free
completion. Unknown usage and cost fields are `None`; reported zero remains
distinct. `parsed_output_available` distinguishes an absent payload from valid
JSON `null` (both use `parsed_output=None`). `artifacts` is a reserved field: no
built-in runtime populates it yet, so it is always an empty tuple today.

## Docs

- [Quickstart](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/quickstart.md)
- [Provider diagnostics](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/providers.md)
- [Capability matrix](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/capability-matrix.md)
- [API stability](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/api-stability.md)
- [Live smoke tests](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/live-smoke.md)
- [Deadlines and cancellation](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/task-control.md)
- [SDK evolution agent](https://github.com/ebarti/agent-runtime-kit/blob/main/docs/sdk-evolution-agent.md)
