# Lite Agent

> A pluggable, lightweight agent-core SDK — swappable strategies, onion middleware, typed event stream.

## SDK

- [Agent SDK overview](/lite-agent-sdk/sdk/overview.md): @lite-agent/sdk is the batteries-included way to build agents with lite-agent: a working tool set, skills, subagents, persistent sessions, and a permission gate behind a small @anthropic-ai/claude-agent-sdk-shaped API (query / createLiteAgent / tool). Pair it with a @lite-agent/provider for the model — every battery is a toggleable default over the core strategies, so you start productive and opt into control only where you need it.
- [Getting started](/lite-agent-sdk/sdk/getting-started.md): This page takes you from install to a permission-gated, multi-turn agent in four steps.
- [Agent loop](/lite-agent-sdk/sdk/core-concepts/agent-loop.md): Every run — a one-shot query() or a send() on a LiteAgent — is driven by the same kernel turn loop: encode the conversation, stream the model, run the requested tools, feed the results back, repeat. Understanding the loop explains everything else in the SDK: permissions, sandboxing, and compaction are not special cases hard-coded into the agent — they are strategies and middleware plugged into these five steps. You don't configure the loop itself; you observe it through events and customize it by swapping strategies or adding middleware.
- [Sessions](/lite-agent-sdk/sdk/core-concepts/sessions.md): A session is a persistent, resumable conversation. With createLiteAgent, every run is event-sourced to disk through a Checkpointer, and the agent owns a current session: successive send() calls share the full conversation, you can list and resume past sessions across restarts, and you can roll a session back to any earlier prompt. You get durable multi-turn agents without writing any storage code. Nothing to enable — persistence is on by default via the built-in fileCheckpointer:
- [Events](/lite-agent-sdk/sdk/core-concepts/events.md): Every run yields a typed AgentEvent stream — the single channel for streaming text to a UI, showing tool activity, and servicing approvals and user questions. Events are observe only: handling them never changes agent behavior, so you can build any rendering or logging layer on top without touching the agent. You already consume the stream whenever you iterate query(): Events forwarded from a subagent carry an agentId; the main agent's events don't.
- [Custom tools](/lite-agent-sdk/sdk/tools/custom-tools.md): Tools are how the model acts on the world. Beyond the built-in tools, tool() lets you define your own — a typed function the model can call — from a Zod schema. The schema validates every call before your code runs, so your handler only ever sees well-formed input. Custom tools are appended after the built-ins and go through the same permission gate and allowedTools / disallowedTools filtering.
- [Built-in tools](/lite-agent-sdk/sdk/tools/builtin-tools.md): @lite-agent/sdk ships a working tool set out of the box — shell access, workspace-scoped file tools, a persistent task list, subagent dispatch, and more — so a fresh agent is productive with zero setup. All built-ins are registered by default and can be filtered or disabled per tool or per capability.
- [Subagents](/lite-agent-sdk/sdk/tools/subagents.md): The Agent tool delegates large or context-heavy subtasks to subagents that run in isolated sessions: each child sees only the prompt you pass it (never the parent conversation) and returns only its final text. Isolation keeps the parent's context clean — you get the answer without paying for the exploration that produced it.
- [Skills](/lite-agent-sdk/sdk/tools/skills.md): A skill is a directory containing a SKILL.md file — instructions the model loads on demand instead of paying for them in every prompt. The system prompt lists each skill's name and description; the model pulls in the full body with the load_skill tool only when it decides the skill is relevant. You get a large library of specialized instructions at near-zero standing context cost.
- [System prompt](/lite-agent-sdk/sdk/behavior/system-prompt.md): Every lite-agent run starts from a system prompt that grounds the model in your workspace: where it may work, which tools to prefer, and which skills and subagents exist. The SDK builds a good one for you with buildSystemPrompt — workdir, model name, available skills, and available subagents are all filled in automatically — and lets you replace or extend it when your agent needs its own voice, rules, or domain context.
- [Structured output](/lite-agent-sdk/sdk/behavior/structured-output.md): Free-text answers are fine for chat, but when your agent feeds another program you want a typed, validated result, not prose to parse. Set outputSchema — a Zod object schema — and the run's final answer is forced through it: the SDK registers a final_answer tool with your schema as its parameters, instructs the model to call it exactly once when done, validates the arguments, and surfaces them as result.output.
- [Tasks](/lite-agent-sdk/sdk/behavior/tasks.md): Multi-step work needs a plan the model can see and update — and that survives context compaction and restarts. The Tasks capability gives the agent a persistent task list modeled on Claude Code's Tasks API: four built-in tools (TaskCreate / TaskUpdate / TaskGet / TaskList), on-disk storage shared across sessions of the same project, and a per-turn reminder that keeps the current list in front of the model without polluting the transcript.
- [Permissions](/lite-agent-sdk/sdk/control/permissions.md): Every tool call an agent makes passes a permission gate before it runs. policy() matches calls against allow / ask / deny rule sets — by tool name glob, or by the call's actual input — so you decide which actions run silently, which need a human, and which never happen. Precedence is always deny > ask > allow: a mis-ordered allow can never shadow a deny. This is how you keep an autonomous agent inside the lines you drew, with an audit trail to prove it.
- [Sandbox](/lite-agent-sdk/sdk/control/sandbox.md): The sandbox confines every shell command the agent runs inside an OS boundary — macOS Seatbelt or Linux bubblewrap — with restricted filesystem and network access. Where the permission gate decides whether a command runs, the sandbox constrains what it can touch while running — and because the boundary is enforced by the OS on the running process, it holds regardless of what the model decided to run. It cannot be talked out of with clever command strings. This is the second, independent layer of defense in depth. The adapter is @lite-agent/sandbox-anthropic, backed by @anthropic-ai/sandbox-runtime.
- [Checkpointing](/lite-agent-sdk/sdk/control/checkpointing.md): Every run is event-sourced: the session is persisted as an append-only log of SessionEvents through the Checkpointer contract. That buys you durable sessions (resume after a restart), and time travel — roll a session back to any earlier checkpoint, undoing both the conversation and the file changes the agent made. Persistence is on by default via fileCheckpointer; swap in the SQLite backend when several processes must share sessions.
- [Observability](/lite-agent-sdk/sdk/control/observability.md): Everything an agent does is already a typed stream of AgentEvents — text deltas, tool calls, results, permission decisions, background completions. Observability means tapping that stream: feed it to your UI live, and/or persist it to a durable, hash-chained JSONL audit log with jsonlEventSink / recordEventStream. No separate tracing SDK needed.
- [Background tasks](/lite-agent-sdk/sdk/control/background.md): Long-running work doesn't have to block the agent. With background: true (the default), the agent can detach slow shell commands and subagent batches into background tasks, keep working in the foreground, and pick up the results when they land. You get incremental output polling, cancellation, and a background_completed event per finished task — all surfaced through the normal event stream.

## Core

- [Core overview](/lite-agent-sdk/core/overview.md): @lite-agent/core is the pluggable, event-driven agent kernel of lite-agent: a lean, provider-agnostic core built from swappable strategy interfaces, an onion middleware pipeline, and a typed event stream. Use it when you want to assemble your own agent from primitives — full control over the model, the tools, the persistence, and every layer in between — without forking a framework. Its public API is shaped after @anthropic-ai/claude-agent-sdk, but the kernel is self-built, so it can also drive local small models via pluggable tool-call codecs.
- [The kernel](/lite-agent-sdk/core/kernel.md): The kernel is the turn loop at the heart of @lite-agent/core: encode → call → decode → execute → feed back, repeated until the model stops. Understanding it pays off everywhere — it tells you exactly where a strategy plugs in, where a middleware wraps, and when an event fires. The kernel itself knows nothing about permissions or compaction — those are middleware. The loop body is just "encode → call → decode → execute → feed back".
- [Strategies](/lite-agent-sdk/core/strategies.md): Every moving part of the kernel is a strategy interface — one implementation per role, hot-swappable at agent construction. This is how lite-agent stays provider-agnostic and host-agnostic: instead of forking the kernel, you swap the part. All nine interfaces are exported as types from @lite-agent/core.
- [Middleware](/lite-agent-sdk/core/middleware.md): Middleware is how you add cross-cutting behavior to the kernel without touching it: logging, retries, permission gates, compaction. A middleware is an added layer around the turn loop — the kernel folds your layers into the classic onion, so each one sees the call on the way in and the result on the way out. Permissions and compaction in lite-agent are themselves just middleware, which proves the seam: anything they do, your own layer can do too.
- [Events](/lite-agent-sdk/core/events.md): Every run of the kernel yields a single typed stream: AgentEvent, a discriminated union covering everything the loop does — model calls, tool executions, approvals, compaction, errors, and the final result. This is how you build UIs, logs, and telemetry on top of lite-agent: consume the stream and render it. Events are observe only — handling an event never changes agent behavior.
- [Tool-call codecs](/lite-agent-sdk/core/codecs.md): A ToolCallCodec is the strategy that bridges tool semantics and whatever protocol your model actually speaks: it encodes tool specs into the outgoing ModelRequest and decodes the assistant's reply back into { text, calls }. The codec is what makes the kernel provider-agnostic in both directions — the same kernel drives a frontier API with native function calling or a local 7B model with prompt engineering, and swapping protocols is a one-line change.
- [Context compaction](/lite-agent-sdk/core/compaction.md): Long-running agents eventually hit the model's context window. lite-agent's compaction capability shrinks the conversation without breaking tool_call/tool_result pairing — every cut is turn-aligned — and it comes in two composable layers: a deterministic toolkit you wire in as middleware, and an automatic ContextEngine that manages context pressure for you.
- [Session persistence](/lite-agent-sdk/core/persistence.md): lite-agent persists every session as an append-only, event-sourced log behind the Checkpointer contract. Because the log — not the message array — is the source of truth, you get crash recovery, optimistic concurrency, and time travel (fork a session from any point) for free, and the storage backend is a swappable strategy: in-memory for tests, a file store in the SDK by default, or SQLite when several processes share sessions.
- [Model providers](/lite-agent-sdk/core/providers.md): Model providers are the ModelProvider strategies that connect the kernel to a real model API. @lite-agent/provider ships two maintained adapters — anthropic() for the Anthropic Messages API and openai() for OpenAI Chat Completions — and because the whole Chat Completions family shares one wire format, the same adapter also drives OpenAI-compatible and local endpoints (Ollama, vLLM, LM Studio, llama.cpp). Both adapters translate the provider's SSE stream into normalized ModelChunks and map every failure to ProviderError, so middleware like retry() works uniformly across vendors.
- [Strict local assembly](/lite-agent-sdk/core/local.md): @lite-agent/local runs agents against local models (Ollama, vLLM, LM Studio, llama.cpp) with SQLite persistence, mandatory OS sandboxing, deny-by-default permissions, and a tamper-evident audit log — all wired together with safe defaults. Use it when the model and the data must never leave the machine, and you want the safety posture enforced rather than configured. The guiding principle is fail-closed: every layer refuses to run unless its safety invariant holds. A non-loopback endpoint, a sandbox that cannot initialize, a malformed permission file, or a custom tool without security metadata all abort startup instead of degrading silently. Requires macOS or Linux, Node ≥ 20, and a running local model server. better-sqlite3 and @anthropic-ai/sandbox-runtime are pulled in as transitive native/runtime dependencies.
- [Testing utilities](/lite-agent-sdk/core/testing.md): The kernel is testable without any network access. @lite-agent/core ships a scripted ModelProvider test double (fakeProvider) so agent-loop tests are deterministic, plus two conformance suites — providerConformance and checkpointerConformance — that validate any custom strategy implementation against the exact contract the kernel relies on. If you write your own provider or persistence backend, running these suites is the cheapest way to know you got the contract right.

## Examples

- [examples/cli](/lite-agent-sdk/examples/cli.md): An interactive REPL (examples/cli, package @lite-agent/example-cli) that wires the full stack on top of @lite-agent/sdk: streaming agent loop via createLiteAgent, driven by a provider from @lite-agent/providerpermission gate — asks before bash / write_file / edit_fileOS-level sandbox via @lite-agent/sandbox-anthropic — degrades to noop on unsupported environmentsask_user — the model can ask you questions (free text or numbered options)session management — list / resume / clear / delete sessions from the REPLmulti-line paste, ESC to interrupt a run Use it as a runnable reference for how to wire your own app.