anycode

AnyCode

Multi-agent AI orchestration framework for Python

Developed and maintained by Quantlix.

Alpha status and production boundary: AnyCode is under active development. Supported top-level APIs and persisted formats have explicit compatibility contracts, but pre-1.0 minor releases may require migration. Production use is workload-specific: bounded deployments are eligible only after the production readiness checklist passes and the operator supplies host and network isolation, identity, durable storage, secrets management, monitoring, and incident controls. Direct safety-critical, critical-infrastructure, or unrestricted irreversible use is a no-go.

AnyCode is a Python framework for building coordinated AI agent teams. It helps developers compose autonomous LLM agents, connect them to typed tools, schedule dependent tasks, share memory, stream output, route work across providers, and inspect long-running agent workflows with explicit lifecycle and verification data.

If you are researching Python multi-agent orchestration, LLM agent frameworks, AI task scheduling, MCP tool integration, RAG memory, agent handoff, or DAG-based agent workflows, AnyCode is designed to give you a compact and strongly typed foundation to explore those patterns.

What Is AnyCode?

AnyCode is an async-first orchestration layer for AI agents. A single agent can run a one-shot task, while a team can coordinate planning, implementation, review, memory, tool use, and validation through a shared runtime.

The framework focuses on practical harness engineering:

• Agent teams with shared memory and inter-agent messaging.
• Dependency-aware task execution using DAG scheduling and wavefront concurrency.
• Provider-agnostic LLM integration through a typed LLMAdapter protocol.
• Pydantic-validated tool calls and immutable runtime models.
• Observability, guardrails, structured output, checkpointing, HITL approval, MCP tools, routing, cost tracking, RAG memory, and verification gates.

AnyCode is built for experimentation, evaluation, local development, research prototypes, and bounded automation. A pinned deployment can be eligible for production when its workload-specific controls and evidence pass the readiness review; the package alone is not a production guarantee.

Current Package

Detail	Value
Distribution	anycode-py
Import package	anycode
Current version	0.10.0
Python	>=3.12
Project status	Alpha
License	MIT
Runtime style	Async-first
Core model style	Frozen Pydantic models
Build backend	Hatchling

Why Developers Use AnyCode

AnyCode is useful when you want more than a single chat loop. It gives each agent a role, a model, tool access, task context, lifecycle events, and measurable results.

Key use cases include:

• Build multi-agent AI workflows in Python.
• Run planner, builder, reviewer, and evaluator agents as one coordinated team.
• Execute task graphs with dependencies instead of manually sequencing prompts.
• Mix Anthropic, OpenAI, Google Gemini, Ollama, Azure OpenAI, and AWS Bedrock models.
• Register local tools or discover external tools through Model Context Protocol servers.
• Add validation layers such as structured output, content validators, cost budgets, approval gates, and quality sensors.
• Evaluate harness changes with deterministic fake adapters before using live LLM calls.

Shipped Capabilities

Area	What is available today
Getting started	Agent(name=..., tools=[...]), the @tool decorator, run_sync, and provider auto-detection
Multi-agent	Crew over the wavefront scheduler, with TaskSpec dependencies and expected_output
Control flow	Workflow state graphs with conditional edges, loops, fan-out, reducers, and a step cap
Long-horizon	planning=, subagents=, and workspace= on the same Agent — no separate deep-agent class
Core orchestration	AnyCode, Agent, AgentRunner, AgentPool, Team, TaskQueue, and Scheduler
Team coordination	MessageBus, SharedMemory, task queues, event callbacks, and team-level results
Task scheduling	Explicit TaskSpec dependencies, topological sort, wavefront execution, and cascading failure handling
Providers	Anthropic, OpenAI, Google Gemini, Ollama, AWS Bedrock, Azure OpenAI, plus custom LLMAdapter implementations
Tools	Built-in bash, file_read, file_write, file_edit, grep, and list_files tools, plus custom Pydantic tools
MCP	Connect to MCP servers, discover tools, register prefixed MCP tools, and scope MCP tools per agent
Safety and control	Guardrails, token and cost budgets, output validators, turn hooks, structured output, HITL approval gates
Persistence	In-memory, SQLite, Redis, vector memory, ChromaDB support, checkpoint stores, and resume support
Portable infrastructure	Pluggable durability backends, execution identity, external policy enforcement, GenAI telemetry mapping, sandbox adapters, and hosting lifecycle contracts
Routing and handoff	Intelligent task routing, route decision reports, handoff requests, and context-preserving handoff execution
Advanced runtime	Cost reports, self-reflection, critic loops, DAG visualization, RAG memory, lifecycle states, stop reasons, and context engineering reports
Verification	Built-in ruff, pyright, pytest, schema, and regex sensors with quality gate decisions
Evaluation	Scenario loading, deterministic fake responses, benchmark reports, markdown rendering, and report comparison
Developer experience	CLI commands, YAML/TOML config, examples cookbook, CLI inspection, and deterministic eval reports
AI agent affordances	anycode api and anycode.describe() for a machine-readable API map, plus a recipes page
Extension ecosystem	Typed Plugin bundles (tools, provider factories, sensors, hooks) registered via engine.register_plugin() or auto-discovered through the anycode.plugins entry-point group
Service client	Dependency-free TypeScript preview for lifecycle, artifact, cancellation, and resumable-stream operations in Node.js 20+ and modern browsers

Operational guides cover durability backends, execution identity and policy, policy-constrained model routing, sandbox providers, service hosting, and GenAI telemetry.

Architecture At A Glance

AnyCode orchestrator
  -> Team coordination
     -> AgentPool with bounded concurrency
     -> TaskQueue with dependency-aware scheduling
     -> MessageBus and SharedMemory
  -> AgentRunner
     -> LLMAdapter protocol
     -> ToolExecutor and ToolRegistry
     -> Guardrails, structured output, lifecycle, context policy, verification gates
  -> Optional systems
     -> Checkpointing, approval, MCP, routing, cost, reflection, RAG, evaluation

The main design rule is simple: the framework owns the harness, while providers and tools stay replaceable. Models are typed, immutable, and validated at runtime boundaries.

Getting Started Guide

1. Requirements

• Python 3.12 or newer.
• uv for dependency management.
• At least one LLM API key for live examples.

2. Install AnyCode

For a new or existing Python project:

uv add "anycode-py[anthropic]"

For CLI and YAML/TOML configuration support:

uv add "anycode-py[cli]"

For the full optional ecosystem:

uv add "anycode-py[all]"

3. Add API Keys

Create a local .env file or export environment variables in your shell.

ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key
GOOGLE_API_KEY=your-google-key

Only one supported provider is required to run the basic examples. Never commit API keys.

4. Run One Agent

from dotenv import load_dotenv

from anycode import Agent, tool

load_dotenv()


@tool
def word_count(text: str) -> int:
    """Count the words in a block of text."""
    return len(text.split())


editor = Agent(
    name="editor",
    instructions="You are a concise copy editor. Use your tools rather than guessing.",
    tools=[word_count],
)

result = editor.run_sync("How many words are in: 'the quick brown fox jumps over it'?")
print(result.output)
print(f"tokens: in={result.token_usage.input_tokens} out={result.token_usage.output_tokens}")

The provider and model are detected from whichever API key is present, the tool schema comes from the function signature, and its description comes from the docstring. Pass provider= and model= to be explicit, and use await agent.run(...) inside async code.

5. Run A Crew With Dependencies

from dotenv import load_dotenv

from anycode import Agent, Crew, TaskSpec

load_dotenv()

researcher = Agent(name="researcher", role="a research analyst", goal="gather the facts", tools=[])
writer = Agent(name="writer", role="a technical writer", goal="turn facts into prose", tools=[])

crew = Crew(
    agents=[researcher, writer],
    tasks=[
        TaskSpec("Research", "List three tradeoffs of vector databases.", agent=researcher),
        TaskSpec(
            "Write",
            "Turn those tradeoffs into a short briefing.",
            agent=writer,
            depends_on=["Research"],
            expected_output="Under 120 words, no bullet points.",
        ),
    ],
    verbose=True,
)

result = crew.run_sync()
print(result)

Independent tasks run concurrently; depends_on feeds one task's output into the next. Drop tasks and call crew.run("some goal") to have the first agent plan the work itself. Crew is a facade over the AnyCode engine, which stays public — see Run a multi-agent team for the engine-level API.

5b. Compose A Workflow With Branching

from anycode import END, START, Agent, Workflow

workflow = Workflow()
workflow.add_node("draft", Agent(name="writer", tools=[]), input_key="topic", output_key="draft")
workflow.add_edge(START, "draft")
workflow.add_conditional_edge("draft", lambda state: END if state["draft"] else "draft")

result = workflow.compile().run_sync({"topic": "hybrid search"})
print(result.state["draft"], result.path)

Use a crew when the work is a dependency graph, and a workflow when you need branching, looping, or retry. See Workflows.

6. Use YAML Or TOML Config

Install the CLI extra first:

uv add "anycode-py[cli]"

Create team.yaml:

name: guide-crew
shared_memory: true
max_concurrency: 3

agents:
  - name: planner
    provider: anthropic
    model: claude-haiku-4-5
    system_prompt: Create concise technical plans.
    tools: []

  - name: writer
    provider: anthropic
    model: claude-haiku-4-5
    system_prompt: Write clear developer documentation.
    tools: []

tasks:
  - title: Plan guide
    description: Outline a getting started guide for AnyCode.
    assignee: planner

  - title: Draft guide
    description: Write the guide from the plan.
    assignee: writer
    depends_on:
      - Plan guide

verification:
  - name: regex
    kind: computational
    phases:
      - after_team
    block_on_failure: true
    options:
      pattern: AnyCode
      expect: match

Run it:

uv run anycode run team.yaml

Or load the same config in Python:

import asyncio

from anycode import AnyCode


async def main() -> None:
    engine = AnyCode.from_config("team.yaml")
    result = await engine.run_team_from_config()
    print(result.model_dump_json(indent=2, exclude_none=True))


asyncio.run(main())

CLI Reference

The CLI is available through the cli extra.

uv run anycode init my-agent-project
uv run anycode run team.yaml
uv run anycode run --agent helper --provider anthropic --model claude-haiku-4-5 --prompt "Summarize async Python."
uv run anycode inspect tools
uv run anycode inspect providers
uv run anycode inspect team team.yaml
uv run anycode inspect config team.yaml
uv run anycode eval run tests/fixtures/eval/runtime_reliability_deterministic.yaml --variant baseline --markdown
uv run anycode eval compare artifacts/eval/baseline.json artifacts/eval/candidate.json
uv run anycode version

anycode init creates a small project with team.yaml, main.py, .env.example, a tools/ package, and .gitignore.

Providers And Optional Extras

Extra	Purpose
cli	anycode CLI, Rich output, YAML parsing
telemetry	OpenTelemetry tracing and exporters
persistence	SQLite memory and checkpoint support
redis	Redis memory backend
vector	ChromaDB vector memory backend
google	Google Gemini adapter
ollama	Local Ollama adapter over HTTP
bedrock	AWS Bedrock adapter
azure	Azure OpenAI adapter
mcp	Model Context Protocol client and tool discovery
sandbox	Daytona sandbox adapter

Provider support is protocol-based. You can bring your own adapter by implementing the LLMAdapter interface.

Built-In Tools

Tool	Purpose
bash	Execute shell commands with timeout and captured output
file_read	Read file contents with line and size controls
file_write	Create or overwrite files and parent directories
file_edit	Replace targeted text in existing files
grep	Search files using regex, with ripgrep when available
list_files	List project files while respecting repository ignore rules

Custom tools use Pydantic input models and are registered through define_tool() and ToolRegistry.

Examples Cookbook

The examples/ directory contains 44 runnable scripts. They are arranged from beginner workflows to runtime reliability demos.

Examples	Theme
01_solo_worker.py to 04_hybrid_tooling.py	Single agents, teams, dependency pipelines, custom and built-in tools
05_production_features.py	Telemetry, guardrails, and structured output
06_pluggable_memory.py to 08_hitl_approval.py	Memory stores, checkpointing, and human approval
09_multi_provider.py to 12_intelligent_routing.py	Provider mixing, MCP tools, handoff, and routing
13_cost_tracking.py to 17_yaml_config.py	Cost reports, reflection, RAG memory, DAG visualization, and YAML config
18_execution_lifecycle.py to 21_eval_suite.py	Lifecycle events, adaptive context, quality gates, and evaluation suites
22_deterministic_eval.py to 25_runtime_cancellation.py	Fake adapters, context pressure, verification gates, and cancellation telemetry
26_context_engineering.py	Huge-context model profiles, section budgets, first-class section inputs, and usage reports
27_plugin_ecosystem.py	Plugin bundles wiring custom tools, provider factories, and sensors into the engine
28_durable_runs.py to 30_scheduled_wakeups.py	Durable resumable runs, session chaining, and scheduled wakeups
31_streaming_runtime.py to 34_list_files.py	Provider-token streaming, reasoning-model controls, authenticated MCP over HTTP, and fast file listing
35_lifecycle_contract.py to 36_runtime_baseline.py	Complete team verification evidence and reproducible local-runtime baselines
37_semantic_contract.py	Versioned semantic events, fenced operations, artifact integrity, and independent projections
38_pluggable_durability.py to 39_backend_failure_soak.py	Backend portability, migrations, leases, fencing, and failure-soak behavior
40_operational_portability.py	Execution identity, policy enforcement, model routing, and GenAI telemetry mapping
41_sandbox_catalog.py to 43_modal_sandbox.py	Sandbox provider catalog, capability reports, fail-closed guards, and live Vercel and Modal sandbox lifecycles
44_ollama_robustness.py	Ollama thinking, structured outputs, streaming, tool calls, and error handling against a live server

Run an example from the repository root:

uv run python examples/01_solo_worker.py

Most live examples require ANTHROPIC_API_KEY or OPENAI_API_KEY. Deterministic evaluation examples can run without live LLM credentials.

Development Setup

Clone the repository and install dependencies with uv:

git clone https://github.com/Quantlix/anycode.git
cd anycode
uv sync --locked --group dev

Run the local verification commands:

uv run python scripts/check_versions.py
uv run python -m ruff check .
uv run python -m ruff format --check src/
uv run python -m pyright
uv run python -m pytest
uv run python -m mkdocs build --strict
uv run python scripts/check_docs.py

The default pytest configuration excludes integration tests. Integration tests may require Docker services or provider credentials.

Security And Responsible Use

AnyCode agents can be connected to tools that read files, write files, execute commands, call providers, and access external systems through MCP. Treat every tool-enabled agent as a privileged automation process.

Required safeguards for any deployment:

• Run tool-enabled agents as a non-root identity inside a container, VM, or equivalent isolation boundary.
• Set explicit agent tool lists and apply ToolSecurityPolicy with narrow path, shell, and environment access.
• Use fake adapters or deterministic evaluation before live model calls.
• Inject API keys from a protected secret source and keep them out of prompts, source, images, and logs.
• Use durable idempotency plus human approval for sensitive or irreversible actions.
• Allowlist production plugins and MCP endpoints, then enforce network egress outside the framework.
• Review the security and threat model and complete the production readiness checklist.

Report suspected vulnerabilities through the private process in SECURITY.md. Do not disclose vulnerability details in a public issue.

FAQ

Is AnyCode production ready?

Production readiness is workload-specific. AnyCode remains alpha, but a pinned release can support bounded, reversible, operator-monitored workloads when every mandatory readiness control passes. Customer-facing, multi-tenant, sensitive-data, or irreversible workflows require stronger application-owned isolation, authorization, storage, and operations. Direct safety-critical control, critical infrastructure control, and autonomous high-impact decisions are no-go uses for AnyCode as the sole decision or control system.

What makes AnyCode different from a single-agent loop?

AnyCode gives you a team runtime: multiple agents, explicit task dependencies, shared memory, inter-agent messaging, scheduling strategies, provider routing, and structured run results.

Can I use different LLM providers in one workflow?

Yes. Agents can use different providers and models in the same team. Routing can also select a model per task based on task complexity and configured rules.

Can AnyCode run without live API keys?

Some examples require live providers. The deterministic evaluation suite and FakeAdapter support local tests without live LLM credentials.

Does AnyCode support custom tools?

Yes. Tools are defined with Pydantic input models, registered at runtime, and executed through the same validation path as built-in tools.

Contributing

Issues, discussions, and pull requests are welcome. Read CONTRIBUTING.md for setup, branch naming, compatibility review, tests, documentation, and pull request requirements. Repository collaborators use MAINTAINERS.md for governance, change approval, backports, and release ownership.

License

AnyCode is released under the MIT License. See LICENSE for details.