Aikit Runtime

aikit-runtime

One governed runtime for serious AI agents.

Build provider-aware agents in Rust, Python, and TypeScript without reimplementing streaming, tools, policy, routing, budgets, audit, memory, or sessions in every language.

[](https://github.com/matakartal/aikit-runtime/actions/workflows/ci.yml) [](https://github.com/matakartal/aikit-runtime/actions/workflows/release.yml) [](Cargo.toml) [](crates/aikit-py/pyproject.toml) [](crates/aikit-node/package.json) [](#license)

One core. Three SDKs. Four native providers. Four compatible endpoints. One policy boundary.

[Quick start](#quick-start) · [CLI](#command-line-interface) · [Architecture](#architecture) · [Governance](#governed-tool-execution) · [SDKs](#one-runtime-three-sdks) · [Documentation](#documentation)

---

aikit-runtime keeps correctness-sensitive agent behavior in one Rust core and exposes it through thin native bindings. Anthropic, OpenAI, Google, and DeepSeek retain their native wire formats, while your application gets one canonical runtime contract.

Why aikit?

| One runtime | Provider-native | Governed execution | |---|---|---| | Rust owns the agent loop; Python and Node call the same implementation. | Provider-specific reasoning, tool calls, citations, usage, and metadata stay intact. | Every side effect passes schema validation, hooks, permissions, budgets, and audit. | | Typed developer experience | Agent primitives included | Production controls built in | | Streaming text, structured objects, multimodal messages, typed errors, and cancellation. | Tools, subagents, parallel fan-out, councils, memory, sessions, routing, and retries. | Fail-closed containment, metadata-safe audit, cost limits, scoped tools, and explicit approvals. |

Architecture

flowchart TB
    subgraph Apps[Application code]
        R[Rust]
        P[Python]
        N[TypeScript / Node.js]
    end

    R --> F[Rust facade: aikit]
    P --> PY[PyO3 binding]
    N --> JS[napi binding]

    F --> CORE
    PY --> CORE
    JS --> CORE

    subgraph CORE[aikit-runtime-core]
        direction LR
        MSG[Canonical messagesstreaming + objects]
        LOOP[Agent looptools + subagents]
        GOV[Governancehooks + permissions]
        OPS[Budgets + routingaudit + state]
        MSG --> LOOP --> GOV --> OPS
    end

    CORE --> A[AnthropicMessages]
    CORE --> O[OpenAIResponses]
    CORE --> G[GoogleGemini]
    CORE --> D[DeepSeekChat Completions]
    CORE --> C[Compatible endpointsOpenRouter · Groq · Mistral · xAI]

    CORE --> HOST[Host callbacks]
    CORE --> BUILTIN[Jailed built-in tools]
    BUILTIN --> BOUNDARY[Seatbelt · Linux namespaces + seccompWindows Job · hardened Docker]

The bindings translate host values and async callbacks at the edge. They do not duplicate policy, provider translation, or orchestration logic.

Quick start

The repository includes a deterministic provider, so you can exercise the complete runtime with no API key and no network call.

git clone https://github.com/matakartal/aikit-runtime.git
cd aikit-runtime
cargo run -p aikit-runtime --example quickstart

Expected output:

Araç sonucunu aldım; görevi tamamladım.

Command-line interface

The source-first CLI makes the runtime usable without writing an application. Its default model is the deterministic, offline mock-1 provider:

cargo run -p aikit-cli -- run "Explain aikit in one sentence"
cargo run -p aikit-cli -- chat
cargo run -p aikit-cli -- providers
cargo run -p aikit-cli -- doctor
cargo run -p aikit-cli -- eval evals/smoke.json

Choose a configured provider explicitly only when you intend to make a network call:

XAI_API_KEY='...' cargo run -p aikit-cli -- run --model grok-4.5 "Say hello"

The CLI supports text, JSON, and JSONL output, stable exit codes, stdin prompts, canonical multi-turn history, secret-safe provider discovery, containment diagnostics, deterministic eval gates, and shell completion generation. See the [CLI guide](crates/aikit-cli/README.md) for the full contract.

Rust

use aikit::Agent;

#[tokio::main]
async fn main() -> Result> {
    let answer = Agent::new()
        .generate_text("Say hello in Turkish", "mock-1", 128)
        .await?;

    println!("{}", answer.text);
    Ok(())
}

Run it from this checkout:

cargo run -p aikit-runtime --example quickstart

Python

Build the native binding once, then use the same core from Python:

python3 -m venv .venv
.venv/bin/pip install "maturin==1.14.1"
.venv/bin/maturin develop --manifest-path crates/aikit-py/Cargo.toml

import asyncio
import aikit

async def main() -> None:
    agent = aikit.Agent.from_env({})
    answer = await agent.generate_text("Say hello in Turkish")
    print(answer["text"])

asyncio.run(main())

TypeScript / Node.js

./scripts/build-node.sh

const { Agent } = require("./crates/aikit-node");

async function main() {
  const agent = Agent.fromEnv({});
  const answer = await agent.generateText("Say hello in Turkish");
  console.log(answer.text);
}

main();

Built for agent workloads

| Capability | What aikit provides | |---|---| | Streaming | Incremental text, reasoning, tool-call, tool-result, usage, and terminal events. | | Structured output | JSON Schema plus async semantic validation, bounded repair, streaming attempts, Pydantic and Zod materialization. | | Evaluation | Deterministic text, tool-trajectory, terminal-state, usage, turn, and model-attempt gates over the current invocation. | | Canonical messages | Text, reasoning, tools, media, citations, usage, and provider-owned metadata without flattening. | | Governance | Global allow / ask / deny, declarative JSON policy, async approval, lifecycle hooks, and authoritative denial. | | Plan mode | Whole-approach HITL: the agent proposes a plan; a human approves, revises, or rejects before tools run. | | Smart approval | Keyless risk scoring auto-allows low-risk ask calls and escalates the rest to a human. | | Reliability rules | Declarative tool ordering, prerequisites, and use caps — separate from security permissions. | | Off-prompt output | Large or sensitive tool results stored by reference so they do not fill the model context. | | Guardrails | Deterministic secret/PII redaction, regex blocking, and fail-closed MCP safety-server interop. | | Self-extension | Human-governed capability requests: the agent asks for a tool it lacks, a human decides, the grant is recorded — never a silent escalation. | | Tool runtime | Host callbacks plus opt-in Read, Write, Edit, Glob, Grep, and contained Bash. | | MCP | Bounded stdio and Streamable HTTP client with tools, resources, prompts, auth/session propagation, exact allow/deny visibility filters, and governed execution. | | Routing | Explicit or automatic model selection from a caller-owned catalog with hard capability and cost gates. | | Resilience | Typed failures, bounded retry, pre-stream fallback, cancellation, deadlines, and terminal outcomes. | | Orchestration | Scoped subagents, ordered parallel fan-out, council synthesis, quorum, and shared budget accounting. | | State | Namespaced memory, revisioned sessions, JSON/transactional SQLite persistence, canonical recording, and resume. | | Compaction | Opt-in transcript bounding: keep the task anchor and recent tail within a token budget, preserving tool pairing. | | Web and browser | HTTPS allowlisted fetch/search plus an existing-session WebDriver executor; browser registration requires an explicit assertion of caller-owned pre-request egress enforcement. | | Observability | Typed audit lifecycle, metadata-only redaction by default, JSONL sinks, and an optional Rust OpenTelemetry bridge. |

Governed tool execution

Tool authorization happens immediately before the side effect—not in a prompt and not in a UI convention.

flowchart TD
    START[Model emits tool call] --> SCHEMA[Compile and validate input schema]
    SCHEMA -->|invalid| REJECT[Return typed error]
    SCHEMA --> PRE[Run scoped PreTool hooks]
    PRE -->|block| REJECT
    PRE --> POLICY{Permission decision}
    POLICY -->|deny| DENY[Authoritative denialexecutor is never called]
    POLICY -->|ask| APPROVE{Host approval}
    POLICY -->|allow| VALIDATE[Revalidate rewritten input]
    APPROVE -->|deny| DENY
    APPROVE -->|allow / rewrite| VALIDATE
    VALIDATE --> EXEC[Execute exactly once]
    EXEC --> POST[PostTool or failure hooks]
    POST --> AUDIT[Record audit + usage + outcome]
    AUDIT --> CONTINUE[Return result to model]
    DENY --> CONTINUE
    REJECT --> CONTINUE

A denied tool never reaches its callback. Approval and hook rewrites are schema-validated again before execution.

Example: policy around a host tool

agent = aikit.Agent.from_env({})

async def lookup(payload: dict) -> str:
    return f"price:{payload['symbol']}"

agent.add_tool(
    "lookup",
    "Look up one market symbol",
    {
        "type": "object",
        "properties": {"symbol": {"type": "string"}},
        "required": ["symbol"],
        "additionalProperties": False,
    },
    lookup,
)

agent.set_permissions([
    {"id": "approve-lookups", "effect": "ask", "tool": "lookup"},
])

async def approve(request: dict):
    return "allow" if request["input"]["symbol"] == "AAPL" else "deny"

agent.can_use_tool(approve)

The same lifecycle exists in Rust and TypeScript; only the host callback syntax changes.

Declarative policy, plan mode, and reliability

Rust also ships higher-level governance primitives that compose with the same engine:

// Declarative JSON → enforcing PermissionEngine
use aikit_core::PolicySpec;
let engine = PolicySpec::from_json(r#"{
  "mode": "allow",
  "deny": ["Bash(rm -rf *)"],
  "ask": ["Bash(git push *)"],
  "allow": ["Read(*)"]
}"#)?.build()?;

// Plan mode: review the whole approach before any tool runs
// cargo run -p aikit-runtime-core --example plan_mode

// Smart approval: auto-allow Low risk, escalate the rest
// cargo run -p aikit-runtime-core --example smart_approval

// Reliability: deploy only after test, at most once
// cargo run -p aikit-runtime-core --example reliability

See the [feature reference](docs/FEATURES.md#governance-and-hooks) for plan review, risk scoring, reliability rules, off-prompt tool output, and capability requests.

Provider fidelity

aikit uses native adapters rather than forcing every provider through one lossy compatibility shape.

| Provider | Native API | Reasoning continuation | Structured output | Vision | |---|---|---|---|---:| | Anthropic | Messages | Signed thinking replayed unchanged | Native JSON Schema constraint | Yes | | OpenAI | Responses | Opaque reasoning item replayed unchanged | Strict JSON Schema | Yes | | Google | Gemini generateContent | Thought signature retained on the exact function-call part | responseJsonSchema | Yes | | DeepSeek | Chat Completions | Full reasoning_content retained for tool continuation | JSON mode + validation and repair | No |

OpenRouter, Groq, Mistral, and xAI are supported through isolated OpenAI-compatible endpoints. They do not inherit native-provider fidelity claims automatically; capability checks still apply.

Grok through xAI

Set XAI_API_KEY, then select Grok with either its natural model id or the explicit xAI namespace:

agent = aikit.Agent.from_env({"XAI_API_KEY": "..."})
answer = await agent.generate_text("Hello from Grok", model="grok-4.5")
# Equivalent explicit form: model="xai:grok-4.5"

The adapter uses xAI's OpenAI-compatible Chat Completions endpoint. Model availability can change; choose a model currently enabled for your xAI account.

Generated objects report their actual fidelity:

• native_constrained
• forced_tool_call
• prompted_and_parsed

Your application can branch on that grade instead of assuming every JSON-shaped answer has the same guarantee.

After JSON Schema succeeds, an optional async semantic validator can return Accept, Retry(reason), or Reject(reason). Retry uses the existing bounded repair budget; reject and callback failures stop with a typed structured-output error. Validators must be pure/idempotent, and aikit never copies the candidate object into validator errors or audit events automatically. Retry reasons are provider-facing, so return a safe summary rather than the raw object. Reject and callback-error details are returned to the host but persist only as generic audit failure markers; keep those details secret-free too because an application may log exceptions.

One runtime, three SDKs

| Concept | Rust | Python | TypeScript | |---|---|---|---| | Agent | Agent::new() | aikit.Agent() | new Agent() | | Text | generate_text | generate_text | generateText | | Streaming | stream_text | stream_text | streamText | | Structured output | generate_object | generate_object | generateObject | | Outcome evaluation | evaluate_outcome | evaluate_outcome | evaluateOutcome | | Tool registration | tool / executor | add_tool | addTool | | Permissions | Governance | set_permissions | setPermissions | | Memory | remember / recall | remember / recall | remember / recall | | Parallel agents | parallel | parallel | parallel | | Persistent audit | JsonlAuditSink | configure_jsonl_audit | configureJsonlAudit |

Cross-language conformance runs canonical scenarios through all three SDKs and compares normalized results byte for byte.

Multimodal and structured input

All text and object surfaces accept a string or canonical message history:

messages = [{
    "role": "user",
    "content": [
        {"type": "text", "text": "Describe this chart"},
        {
            "type": "media",
            "media_type": "image/png",
            "source": {"kind": "url", "url": "https://example.com/chart.png"},
        },
    ],
}]

result = await agent.generate_text(messages, model="your-model")

Unsupported media is rejected with a typed error instead of being silently dropped.

Tools and containment

Built-in tools are explicit and scoped:

agent.register_builtin_tools(["./workspace"])
agent.configure_jsonl_audit("./state/audit.jsonl")
agent.use_memory_file("./state/memory.json", namespace="project-a")
agent.use_session_file("./state/sessions.json")

| Surface | Boundary | |---|---| | Read / Write / Edit / Glob / Grep | Descriptor-relative jail, registered roots only, no symlink following. | | Built-in Bash | Required containment: probed macOS Seatbelt, Linux namespaces+seccomp, Windows Job Objects, or hardened digest-pinned Docker. | | Host callbacks | Your application process and your responsibility to isolate further when needed. |

If required containment is unavailable, built-in Bash is denied before process launch.

Source module map

aikit-runtime is currently distributed from this GitHub repository. Registry packages are a release gate, not a claim about artifacts that exist today.

| Ecosystem | Workspace package | Import / library | |---|---|---| | Rust facade | aikit-runtime | aikit | | Rust core | aikit-runtime-core | aikit_core | | Python | aikit-runtime | import aikit | | Node wrapper | aikit-runtime | local checkout wrapper | | Node native binaries | aikit-runtime-{platform} | selected locally by the wrapper |

The current v0.3.0-alpha.1 tree is a source-first implementation preview. Keyless source, binding, and local package-layout checks run in CI. Use the checkout commands in [Quick start](#quick-start); no npm, PyPI, or crates.io publication is claimed for this candidate.

Supported binary targets

| Platform | Python ABI3 wheel | Node native package | |---|---:|---:| | Linux x64, glibc >= 2.28 | Yes | Yes | | Linux ARM64, glibc >= 2.28 | Yes | Yes | | macOS ARM64 | Yes | Yes | | macOS x64 | Yes | Yes | | Windows x64 | Y

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: matakartal
• Source: matakartal/aikit-runtime
• License: Apache-2.0
• Homepage: https://github.com/matakartal/aikit-runtime#readme

Install and usage instructions live in the source repository linked above.