User Guide

Write agents in 1-3 lines. Get native ADK objects. Keep full control.

This guide takes you from “I know how to build a simple agent” to “I can design production multi-agent systems with data contracts, context engineering, middleware, and evaluation.” Read sequentially for the full journey, or jump to the topic you need.

Quick taste — every concept in 8 lines

from adk_fluent import Agent, S, C

support = (
    S.capture("message")                                    # S: State transforms
    >> Agent("classify", "gemini-2.5-flash")
       .instruct("Classify intent.")                        # P: Prompt (via .instruct)
       .context(C.none())                                   # C: Context engineering
       .writes("intent")                                    # Data flow: named state keys
    >> Agent("resolve", "gemini-2.5-flash")
       .instruct("Resolve the {intent} issue.")             # {key} = reads from state
       .tool(lookup_customer)                                # Tools: plain functions
       .writes("resolution")
)

Each line maps to a concept you’ll learn below. Hover over any builder method in your IDE to see its type signature.

Three Pathways

adk-fluent offers three distinct development pathways. All produce native ADK objects – they solve different problems at different abstraction levels. Pick the one that matches your use case, or combine them.

Pipeline Path
Python-first builders with >> | * operators and 9 namespace modules. Full programmatic control.
Most development starts here.

Skills Path
YAML + Markdown → agent graphs. Domain experts write prompts and topology. One file = docs + runtime.
Reusable, cross-team, config-driven.

Harness Path
Build autonomous coding runtimes with the H namespace. 5 layers: intelligence, tools, safety, observability, runtime.
File/shell access, permissions, REPL.

Not sure which? See the Decision Guide. All three compose: harnesses load skills, skills wire pipelines, pipelines use the full expression algebra.

Foundations

Start here if you’re new to adk-fluent.

Chapter	What you’ll learn
Architecture & Concepts	How builders wrap ADK, the IR tree, and the compilation pipeline
Best Practices	Opinionated guidance on when to use what
Framework Comparison	Side-by-side with LangGraph, CrewAI, and native ADK

Pipeline Path – Building Agents in Python

The core of the library. Full programmatic control with expression operators, namespace modules, and type-checked builders.

Chapter	What you’ll learn
Builders	Constructor args, method chaining, .build(), typo detection, .explain(), serialization
Expression Language	All 9 operators (>>, |, *, @, //, >> with functions, Route, race, dispatch)
Data Flow	.writes(), .reads(), {key} templates, state propagation between agents
Prompts	The P module: P.role(), P.task(), P.constraint(), section ordering, composition
Execution	.ask(), .stream(), .session(), .map(), .events()

Advanced Pipeline Capabilities

Chapter	What you’ll learn
Callbacks	.before_agent(), .after_model(), .guard(), error callbacks
Presets	Reusable configuration bundles with .use()
State Transforms	The S module: S.pick(), S.merge(), S.guard(), S.branch(), composition
Structured Data	@ Schema, .returns(), .produces(), .consumes(), contract checking
Context Engineering	The C module: C.none(), C.from_state(), C.window(), token budgets
Patterns	review_loop, map_reduce, cascade, fan_out_merge, conditional, supervised

Skills Path – Declarative Agent Packages

Turn YAML + Markdown into executable agent graphs. One file is simultaneously documentation, coding-agent context, and a runnable pipeline.

Chapter	What you’ll learn
Skills	Skill(), SkillRegistry, T.skill(), SKILL.md format, composition with operators, tool injection

Harness Path – Autonomous Coding Runtimes

Build Claude-Code-class autonomous agents. Five composable layers: intelligence, tools, safety, observability, and runtime.

Chapter	What you’ll learn
Harness	The H namespace, 5-layer architecture, EventBus, permissions, sandbox, budgets, REPL

Infrastructure

Production concerns that apply across all three pathways.

Chapter	What you’ll learn
Visibility	.show(), .hide(), .transparent(), topology control
Transfer Control	.isolate(), .stay(), .no_peers()
Memory	.memory(), .memory_auto_save(), persistent agent memory
IR & Backends	.to_ir(), compilation, backend abstraction
Execution Backends	.engine(), ADK / Temporal / asyncio, capability matrix, backend selection
Temporal Guide	Durable execution, crash recovery, determinism rules, Temporal patterns
Middleware	The M module: M.retry(), M.log(), M.cost(), M.circuit_breaker(), composition
Guards	The G module: G.pii(), G.toxicity(), G.schema(), input/output validation
Evaluation	The E module: E.case(), E.criterion(), eval suites, comparison reports
Testing	.mock(), .test(), check_contracts(), AgentHarness, pytest integration
A2A	Remote agent-to-agent communication: RemoteAgent, A2AServer, discovery, resilience
A2UI	Declarative agent UIs: UI namespace, components, operators, surfaces, presets

Backend maturity at a glance

Backend	Status	Key Feature
ADK	Stable — production-ready, default	Native ADK objects, streaming, adk web/run/deploy
Temporal	In Development — API may change	Durable execution, crash recovery, distributed
asyncio	In Development — reference impl	Zero-dependency IR interpreter
DBOS / Prefect	Conceptual — not yet implemented	Under research

Start with ADK. If you need durability, see Execution Backends.

Reference

Resource	Description
Error Reference	Every error with cause and fix-it code
ADK Samples	Official ADK samples ported to adk-fluent
Decision Guide	“Which pattern should I use?” flowchart

Interactive Visual References

Rich interactive diagrams — open in a new tab for the full experience, or explore the embedded previews below.

Module Lifecycle Reference ↗

Where each module (S, C, P, A, M, T, E, G) fires during execution. Swim-lane timeline, interaction grid, and step-through walkthrough.

BUILD PRE LLM POST TOOL

P·C·S Visual Reference ↗

How Prompt, Context, and State modules compose to assemble what the LLM sees. Factory catalogs, composition rules, and assembly order.

Prompt Context State

Operator Algebra Reference ↗

All 9 operators with SVG flow diagrams, code examples, and composition rules. >>, |, *, @, //, Route, and more.

Sequential Parallel Loop Schema Fallback

Data Flow Reference ↗

The five orthogonal data-flow concerns: .reads(), .returns(), .writes(), .accepts(), and .produces(). Timeline, confusion matrix, and decision flowchart.

Context Output Storage Input Contract

Delegation & Transfer Reference ↗

.sub_agent() vs .agent_tool() control flow, transfer control matrix (.isolate(), .stay(), .no_peers()), and common topologies.

Transfer AgentTool Isolate Topology

Execution Modes Reference ↗

Sync vs async execution: .ask() vs .ask_async(), streaming, environment compatibility matrix, and the RuntimeError trap.

Sync Async Stream Batch

A2A Topology Reference ↗

Local vs remote agents, A2A mesh topology, state bridging (.sends() / .receives()), resilience middleware, and discovery methods.

Local Remote A2A Resilience