QuantedAgents

Type-safe agent SDK wrapping pydantic-ai with Pydantic BaseModel I/O enforcement, composable workflow primitives (Pipeline, Router, Loop, Parallel), hierarchical agent orchestration, and built-in observability.

Installation

pip install quanted-agents

Requires Python 3.13+.

Set the API key for whichever LLM provider you use:

export OPENAI_API_KEY="sk-..."
# or ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, ...

Quickstart

import asyncio
from pydantic import BaseModel
from quanted_agents import QuantedAgent

class Article(BaseModel):
    text: str

class Analysis(BaseModel):
    summary: str
    sentiment: str
    topics: list[str]

agent = QuantedAgent(
    "openai:gpt-4o-mini",
    input_type=Article,
    output_type=Analysis,
    system_prompt="Analyze the article: short summary, sentiment, key topics.",
)

async def main() -> None:
    result = await agent.run(Article(text="AI is reshaping healthcare ..."))
    print(result.data.summary)
    print(result.data.sentiment, result.data.topics)
    print(f"Tokens: {result.usage.input_tokens} in / {result.usage.output_tokens} out")

asyncio.run(main())

The input and output are real Pydantic models — validated, typed, and IDE-completable.

Why QuantedAgents

• Type-safe I/O — every agent declares an input and output BaseModel. Inputs are serialized for the LLM automatically; outputs are validated. No string-juggling.
• Composable workflows — Pipeline, Router, Loop, and Parallel are first-class primitives that nest recursively. Build complex agentic flows without leaving the type system.
• Hierarchical agents — parent agents can delegate to child agents as tools, with shared WorkflowBudget enforcement and configurable escalation policies.
• Observability built in — every run() returns usage, step timings, and a trace you can serialize to JSONL via TraceWriter / TraceSession.
• MCP support — connect to Model Context Protocol servers via MCPTool.
• Recovery primitives — JSON repair, structured re-prompting via a restructurer model, configurable retry policies.
• Claude Code skill included — bundled .claude/skills/quanted-agents/ makes Claude Code reach for this SDK by default when building agent workflows.

Workflow primitives at a glance

from quanted_agents import Pipeline, Router, Loop, Parallel

# Pipeline: run agents in sequence, piping output -> input
flow = Pipeline([extract_agent, classify_agent, summarize_agent])

# Router: pick a downstream agent based on a routing decision
router = Router(decider, branches={"refund": refund_agent, "support": support_agent})

# Loop: re-run until a condition is met (or a max iteration count)
loop = Loop(critic_agent, until=lambda r: r.data.is_acceptable, max_iterations=5)

# Parallel: fan out to N agents, gather typed results
fanout = Parallel([researcher_a, researcher_b, researcher_c])

All four nest inside each other and inside QuantedAgent tool definitions.

Documentation

• API Reference — every class, method, and parameter.
• Patterns Guide — 19 production patterns with runnable examples.
• Hierarchical Agents Guide — building parent/child agent systems.

Examples

Thirteen runnable examples in examples/, numbered by complexity:

Claude Code skill

The repository ships a Claude Code skill under .claude/skills/quanted-agents/. Drop it into any project and Claude Code will:

• Use quanted_agents as its default agent framework.
• Read the bundled SDK reference before writing agent code.
• Apply production defaults (restructurer model, recovery retries, soft budgets, trace logging).
• Prefer focused child agents over monolithic single agents.

To install the skill into a project:

mkdir -p /path/to/your/project/.claude/skills
cp -r .claude/skills/quanted-agents /path/to/your/project/.claude/skills/

Or globally for all your projects:

mkdir -p ~/.claude/skills
cp -r .claude/skills/quanted-agents ~/.claude/skills/

Contributing

Issues and pull requests welcome. See CONTRIBUTING.md for the development setup, code style, and PR process. Bug reports and feature requests use the issue templates.

By contributing you agree your contributions are licensed under Apache 2.0 (the project's license).

Security

For security vulnerabilities, please follow the disclosure process in SECURITY.md — do not open a public issue.

License

Licensed under the Apache License, Version 2.0. See NOTICE for attribution.

Copyright (c) 2026 Quanted.