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 messages<br/>streaming + objects]
        LOOP[Agent loop<br/>tools + subagents]
        GOV[Governance<br/>hooks + permissions]
        OPS[Budgets + routing<br/>audit + state]
        MSG --> LOOP --> GOV --> OPS
    end

    CORE --> A[Anthropic<br/>Messages]
    CORE --> O[OpenAI<br/>Responses]
    CORE --> G[Google<br/>Gemini]
    CORE --> D[DeepSeek<br/>Chat Completions]
    CORE --> C[Compatible endpoints<br/>OpenRouter · Groq · Mistral · xAI]

    CORE --> HOST[Host callbacks]
    CORE --> BUILTIN[Jailed built-in tools]
    BUILTIN --> BOUNDARY[Seatbelt · Linux namespaces + seccomp<br/>Windows 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 for the full contract.

Rust

use aikit::Agent;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    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

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 denial<br/>executor 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 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.

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