agentlite

Project Overview

Building a Claude-powered agent in Python typically forces a choice: use the Anthropic SDK directly and hand-roll the agent loop, prompt caching, and permission handling — or adopt a massive framework like LangChain and debug through ~150K lines of abstractions. agentlite sits in between: ~2,000 lines of focused, debuggable code with the agent loop, tool definitions, prompt caching, and permission system all built in.

MIT-licensed, available on PyPI, 80% unit test coverage, CI green on 4 Python versions (3.10–3.13). It wraps Anthropic's official SDK with deliberate architectural decisions: fail-safe defaults, prompt-caching discipline, and production-grade safety brakes.

Usage — A Working Agent in 8 Lines

$ pip install agentlite-py

Note: PyPI distribution name is agentlite-py, Python import is agentlite.

from agentlite import Agent, tool

@tool
def get_weather(city: str) -> str:
    """Return the current weather for a city."""
    return f"{city}: 22°C, sunny"

agent = Agent(model="claude-opus-4-7", tools=[get_weather])
agent.run("What's the weather in Istanbul?")

That's it. Type hints become JSON Schema automatically, the docstring becomes the model's instruction, and the loop is managed inside the library. No boilerplate.

Key Features

Feature	What it does
`@tool` decorator	Python function → `Tool` object (schema auto-generated via introspection)
Agent loop	tool_use ↔ tool_result feedback loop with a `max_turns` safety brake
Streaming	`agent.stream_text()` — token-by-token output (for UX)
Prompt caching	Enabled by default — system prompt + tools auto-wrapped in `cache_control`, ~80% input cost reduction on repeated requests
Permission system	`@tool(requires_confirmation=True)` → user is asked, denial is reported back to the model
Dependency injection	Custom `client` and `confirm_fn` → mock for tests, hook into GUI/Slack in production

Architecture

A single while loop wrapping three layers. The Anthropic SDK sits underneath, Tool defines the contract, Agent orchestrates.

user_message │ ▼ [ Agent.run ] ────────────────────────┐ │ │ ▼ │ [ messages.create ] ── tools + system │ while turn ≤ max_turns: │ + cache_control │ ▼ │ stop_reason == "end_turn"? ─── YES ───┴──► return final text │ │ NO (tool_use) ▼ [ permission check ] ── read_only? confirm? deny? │ ▼ allowed [ tool.call(**input) ] │ ▼ tool_result → append to messages → LOOP BACK

Design Decisions

Few abstractions, lots of measurement. ~2K LOC, 80% test coverage. The opposite of LangChain's "everything is a lego" philosophy — small surface area, debuggable.
Safe by default. Prompt caching, max_turns brake, mandatory type hints — the correct behavior is automatic unless the user explicitly opts out.
Polymorphic decorator. Both @tool and @tool(...) work; existing user code is never broken.
Dependency injection — client and confirm_fn can be supplied externally; testability is a first-class concern.

Comparison

	LangChain	OpenAI Agents	Anthropic SDK	agentlite
LoC	~150K	~5K	in SDK	~2K
Prompt caching	manual	none	manual	automatic
Permission model	none	none	none	built-in
Primary model	vendor-agnostic	OpenAI	Anthropic	Anthropic-first
Learning curve	steep	medium	low	very low

Tech Stack

Language: Python 3.10+
Dependency: only anthropic (deliberately single external dependency)
Package layout: src/ layout, pyproject.toml (modern, no setup.py)
Tests: pytest, 17 unit tests, 80% coverage, runs in 0.4s
CI: GitHub Actions, Python 3.10 / 3.11 / 3.12 / 3.13 matrix
Type checking: mypy (strict mode)
Linting: ruff
License: MIT

Roadmap

🚧 v0.2 — streaming + tool loop integration
🚧 v0.3 — sub-agent spawning (@subagent)
🚧 v0.4 — multi-provider (OpenAI, Gemini backends)
🚧 v0.5 — MCP server support
🎯 v1.0 — stable API, semantic versioning, production-ready