Roadmap

agentling is a tiny async framework for reliable, observable, tool-using agents: a clean ReAct loop, typed memory, streaming events, recoverable failures, and progressive-disclosure skills, in a codebase small enough to read in one sitting.

Shipped: v0.1.0#

The first release: the core framework plus a production-hardening pass. Agent and AgentSession, an OpenAI-compatible model adapter, @tool, typed memory with JSON persistence, streaming events, progressive-disclosure skills, timeouts and cancellation, malformed-output recovery, and a runnable examples suite. See the changelog for the full notes.

Next: reliability (v0.2)#

Top priority. Harden and clean up the v0.1 surface before adding features. There is no point building on foundations with sharp edges.

• Session lifecycle. An idle interrupt() no longer silently kills the next run, and using one session concurrently raises a clear error instead of quietly corrupting memory.
• Honest errors. Make the exception hierarchy real: the documented error types are actually raised, so except AgentlingError behaves as promised.
• Broader compatibility. Stop rejecting valid tool calls from OpenAI-compatible backends (some omit ids mid-stream); synthesize them instead.
• Sampling controls. Expose temperature, max_tokens, seed, and friends on the model, so deterministic evals and cost caps are possible.
• Cleaner semantics. final_answer no longer leaks into the event stream, context-window trimming applies on every path, and resuming a session no longer duplicates the task.
• Robustness. Safe, async-capable step callbacks; Python 3.13 and 3.14 in CI; stricter typing; and a batch of small correctness fixes.

Then: observability and evaluation (v0.3)#

Make every run inspectable and testable.

• Lifecycle tracing. A dependency-free tracing layer over the whole lifecycle (run, step, model call, tool call) capturing inputs, outputs, token usage, timing, and errors.
• OpenTelemetry adapter. Emit standard GenAI spans so traces flow to Langfuse, LangSmith, Arize Phoenix, and any OTLP backend through one integration, not a bespoke plugin per vendor.
• Offline testing and evals. A public, deterministic testing model, so you can run and test your agent with no API key, plus an evaluation harness with datasets and evaluators that works locally or against a hosted experiment backend.

Later: more models (v0.4)#

Meet people where their models already are.

• OpenAI-compatible tier. A documented provider matrix and light ergonomics for OpenRouter, Groq, Together, Fireworks, DeepSeek, Mistral, xAI, local servers (Ollama, vLLM, LM Studio), and Azure OpenAI. Most already work by pointing at a base URL.
• Native Anthropic (Claude). A first-class adapter on the Messages API with tool use, streaming, usage, and prompt caching, beyond the lossy compatibility endpoint.
• More. Native Gemini; optionally a litellm bridge and AWS Bedrock or Vertex.

Exploring: beyond the milestones#

Ideas we like but have not committed to a milestone:

• Structured output (JSON mode and response schemas).
• A human-in-the-loop hook to approve, deny, or modify a tool call before it runs (guardrails).
• An MCP bridge recipe: wrap an MCP tool as an agentling tool.
• An exhaustive failure-mode test suite and a trust policy for skill-provided tools.

Toward 1.0#

Once reliability, observability, and the model surface settle, 1.0 is about committing to a stable public API and semantic-versioning guarantees.

Influence the roadmap#

This is an open, early project and the priorities above are open to input. Open an issue to propose something, describe a use case we are missing, or tell us which item matters most to you. Bug reports and small PRs are especially welcome: see the contributing guide.