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.

Python or TypeScript?

This user guide is Python-first, but every concept applies to both adk-fluent (Python) and adk-fluent-ts (TypeScript). Code samples with a synced Python / TypeScript tab stay in sync once you pick one — click TypeScript on any block and the rest of the site follows.

If you’re using TypeScript, read the TypeScript (adk-fluent-ts) landing page first. It covers install, imports, and the full operator → method-chain mapping (>> → .then(), | → .parallel(), * → .times(), // → .fallback(), @ → .outputAs()).

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 & Reactive Runtimes

Build Claude-Code-class autonomous agents and reactive, event-driven systems. The H namespace provides safety, observability, and runtime layers. The R namespace adds state-driven reactivity where agents activate on signal changes – conversation phases, quality scores, completion flags – without polling or manual dispatch.

Chapter	What you’ll learn
Harness	The H namespace, 5-layer architecture, EventBus, permissions, sandbox, budgets, REPL
Reactor	R namespace, Signal, SignalPredicate, Builder.on(), R.compile(), priority scheduling, preemption, AgentToken – declarative reactive agents
Hooks	H.hooks(), HookDecision, HookEvent, HookMatcher, session-scoped intervention at 12 ADK lifecycle points
Permissions	PermissionPolicy, PermissionDecision, five modes (default/accept_edits/plan/bypass/dont_ask), PermissionPlugin, approval memory
Plan Mode	Plan/execute latch, PlanMode, PlanModePolicy, enter_plan_mode / exit_plan_mode tools, read-only planning phase
Session	SessionStore, SessionSnapshot, auto-fork / auto-restore, tape replay, persistence
Durable Events	SessionTape seq/cursor/tail, TapeBackend (JSONL/InMemory/Null/Chain), stream_from_cursor, workflow lifecycle events
Subagents	SubagentSpec, SubagentRunner, dynamic spawner, make_task_tool, isolated child contexts
Compression	ContextCompressor, CompressionStrategy, pre_compact hooks, keep-recent / drop-old / summarize
Budget	BudgetPolicy, BudgetMonitor, BudgetPlugin, threshold callbacks, token / cost limits
Usage	UsageTracker, CostTable, TurnUsage, per-agent aggregation, cost-per-model accounting
Virtual Filesystem	FsBackend Protocol, LocalBackend, MemoryBackend, SandboxedBackend, workspace_tools_with_backend, sandbox-safe tool I/O

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

Foundations

• Foundations
  • Read in order
• Architecture & Core Concepts
  • The Three Channels
  • What include_contents Actually Does
  • What output_key Actually Does
  • What the S Module Does Today
  • What’s Actually Missing
  • What the Thoughtful Library Does
• Builders
  • Constructor Arguments
  • Method Chaining (Fluent API)
  • .build() – Terminal Method
  • __getattr__ Forwarding
  • Typo Detection
  • .explain() – Introspection
  • .validate() – Early Error Detection
  • .clone() and .with_() – Variants
  • Serialization
  • IR Compilation
  • Data Contracts
  • Dependency Injection
  • Middleware
  • Escape Hatches
  • Workflow Builders
  • Combining Builder and Operator Styles
• Expression Language
  • Operator Summary
  • Reading an expression
  • Immutability
  • >> – Pipeline (Sequential)
  • Function Steps
  • | / .parallel() – Parallel (Fan-Out)
  • * / .times() – Loop
  • @ / .outputAs() – Typed Output
  • // / .fallback() – Fallback Chain
  • Route("key").eq(...) – Deterministic Routing
  • Conditional Gating
  • Full Composition
  • Backend Compatibility
• Data Flow Between Agents
  • The Five Concerns
  • The Three Composition Modules: P, C, S
  • What Gets Sent to the LLM
  • P Module: Prompt Composition
  • C Module: Context Engineering
  • S Module: State Transforms
  • Input: What the Agent Accepts (Tool Mode)
  • Output: What Shape the Response Takes
  • Storage: Where the Response Goes
  • Contracts: Static Annotations
  • End-to-End Compilation: From Builder to LLM Call
  • Inspecting Data Flow
  • Common Patterns
  • T Module: Tool Composition
  • A Module: Artifact Operations

Building agents

• Building agents
  • Chapters
• Prompt Builder
  • Basic Usage
  • Core Sections
  • Composability
  • Building and Inspection
  • Conditional and Dynamic Sections
  • Structural Transforms
  • LLM-Powered Transforms
  • Sugar
  • Template Variables
  • Static Instructions and Context Caching
  • Dynamic Context Injection
• One-Shot Execution
  • .ask(prompt)
  • .ask_async(prompt)
  • .stream(prompt)
  • .events(prompt)
  • .session()
  • .map(prompts, concurrency=5)
  • .map_async(prompts, concurrency=5)
  • .test(prompt, contains=, matches=, equals=)
  • .to_app(config=None)
  • Execution Method Summary
  • Choosing an Execution Method
  • Interplay with Other Modules
  • Best Practices
• Callbacks
  • When each callback fires
  • Callback Methods
  • Additive Semantics
  • Conditional Callbacks
  • Guards
  • Middleware Stacks with .apply()
  • Error Handling
  • Complete Example
  • Callbacks vs. Middleware
  • Interplay with Other Modules
  • Best Practices
• Presets
  • When to Use Presets vs. Middleware vs. Callbacks
  • Basic Usage
  • How Presets Work
  • Composing Presets
  • Use Cases
  • Interplay with Other Modules
  • Best Practices
• State Transforms
  • Basic Usage
  • Transform Reference
  • S.pick(*keys)
  • S.drop(*keys)
  • S.rename(...)
  • S.default(...)
  • S.merge(...)
  • S.transform(key, fn)
  • S.compute(...)
  • S.guard(pred)
  • S.log(*keys)
  • STransform Composition
  • Complete Example
• Structured Data
  • Which one do I need?
  • Storing Output in State: .writes(key)
  • Typed Output: .returns() and @ Schema
  • Input Schema: .accepts()
  • State Access Patterns
  • Complete Example
• Context Engineering
  • Quick Start
  • Which C.* do I want?
  • The Problem
  • Primitives Reference
  • C.none()
  • C.default()
  • C.userOnly() / C.user_only()
  • C.fromState() / C.from_state()
  • C.fromAgents() / C.from_agents()
  • C.excludeAgents() / C.exclude_agents()
  • C.window(n)
  • C.template(str)
  • S.capture(key)
  • C.budget(max_tokens=)
  • C.priority(tier=)
  • Composition
  • Integration with Agent Builder
  • Complete Example
  • What Gets Sent to the LLM

Patterns & control flow

• Patterns & control flow
  • Chapters
• Composition Patterns
  • review_loop — Refinement Loop
  • cascade — Fallback Chain
  • fan_out_merge — Parallel Research + Merge
  • chain — Sequential Composition
  • conditional — If/Else Branching
  • supervised — Approval Workflow
  • map_reduce — Fan-Out Over Items
  • Durable Execution
• Visibility
  • The Real Problem
  • Topology-Inferred Visibility
  • Policies Reference
  • Pipeline-Level Policies
  • Per-Agent Overrides
  • VisibilityPlugin
  • Interplay with Other Modules
  • Complete Example
  • Best Practices
• Transfer Control
  • Overview
  • Transfer Control Flags
  • Control Matrix
  • Choosing the Right Method
  • Common Patterns
  • Flow Selection
  • Complete Example
  • Tips
• Memory
  • When to Use Memory
  • Quick Start
  • Modes Reference
  • preload
  • on_demand
  • both
  • Using .memory() in Pipelines
  • Auto-Save
  • Interplay with Other Modules
  • Complete Example
  • Best Practices

Safety & observability

• Safety & observability
  • Chapters
• Middleware
  • When to Use Middleware vs. Callbacks vs. Presets vs. Guards
  • Attaching Middleware
  • The M Module
  • Middleware Protocol
  • Writing Custom Middleware
  • How Middleware Works
  • Interplay with Other Modules
  • Best Practices
  • Backend Awareness
• Guards (G Module)
  • Quick Start
  • Design Principle
  • Guard Types
  • Composition
  • Provider Protocols
  • Backwards Compatibility
  • How Guards Compile
  • IR Integration
  • See Also
• Evaluation
  • Quick Start
  • Three Tiers
  • Criteria
  • Eval Cases
  • Reports
  • File-Based Eval Sets
  • User Simulation (Personas)
  • Integration with Other Modules
  • pytest Integration
  • Suite Configuration
  • API Summary
• Testing
  • Why Test Agents?
  • Testing Layers
  • Contract Verification
  • Mock Backend
  • AgentHarness
  • pytest Integration
  • Interplay with Other Modules
  • Best Practices

Backends & execution

• Backends & execution
  • Chapters
• IR and Backends
  • Why IR?
  • IR Nodes
  • Backend Protocol
  • ExecutionConfig
  • Visualization
• Execution Backends
  • How It Works
  • Selecting a Backend
  • Backend Comparison
  • Engine Capabilities
  • Backend Registry
  • Choosing a Backend
• Temporal Guide
  • Why Temporal?
  • Setup
  • Basic Usage
  • Determinism Rules
  • IR → Temporal Mapping
  • Patterns
  • Constraints and Limitations
  • Worker Setup
  • Comparison: When to Use What

Distributed agents

• Distributed agents
  • Chapters
• A2A – Agent-to-Agent Communication
  • Architecture
  • RemoteAgent – Consuming Remote Agents
  • A2AServer – Publishing Local Agents
  • A2A Middleware
  • A2A Tool Composition
  • Composition Patterns
  • State Bridging
  • Graceful Degradation
• A2UI – Agent-to-UI Composition
  • Architecture
  • Quick Start
  • Component Factories
  • Layout Operators
  • Data Binding and Validation
  • Surfaces
  • Presets
  • Cross-Namespace Integration
  • Agent Integration
  • Introspection
  • A2UI Protocol Version
  • Cookbook Examples

Harness (hooks, permissions, reactor)

• Skills – Composable Agent Packages
  • When Skills Make Life Easy
  • Architecture
  • Writing a Skill File
  • Loading and Running Skills
  • Composing Skills
  • Skill Discovery
  • ADK Native SkillToolset (T.skill())
  • Introspection
  • Skill Builder API Reference
  • Best Practices
  • Cookbook Examples
• Building Harnesses – From Agent to Autonomous Runtime
  • The Fork in the Road
  • The Five Layers
  • Harness sub-packages (the short tour)
  • Layer 1: Intelligence
  • Layer 2: Tools
  • Layer 3: Safety
  • Layer 4: Observability
  • Layer 5: Runtime
  • Putting It All Together
  • Design Philosophy
• Hooks — The Unified Observation and Intervention Layer
  • What hooks are for
  • The shape of a hook
  • Registering hooks
  • Installing the registry
  • Decision semantics in detail
  • Folding multiple hooks
  • Cookbook
  • Relationship to ADK callbacks
  • API reference
• Permissions
  • Quick start
  • The four pieces
  • PermissionDecision
  • Permission modes
  • Precedence rules
  • Composing policies
  • Patterns: glob vs regex
  • Interactive approval
  • Installing the plugin at the App layer
  • Agent-level callback adapter
  • ApprovalMemory
  • Cookbook
  • Relationship to hooks
  • API reference
• Plan mode
  • Latch state machine
  • The five pieces
  • Quick start
  • The latch
  • The policy wrapper
  • The plugin
  • Relationship to PermissionMode.PLAN
• Session store, fork & replay
  • The five pieces
  • Quick start
  • ForkManager deep dive
  • SessionTape deep dive
  • Putting it together
• Durable event log – seq, cursors, tail & backends
  • One log, many views
  • Cursors & seq
  • Async tail
  • Pluggable backends
  • Workflow lifecycle events
  • Stream from a cursor
  • EventRecord view
  • When to use what
• Reactor – reactive signals, priorities & interrupts
  • The mental model
  • Signals
  • Predicates
  • Reactor rules & priority
  • AgentToken & TokenRegistry
  • Priorities of the primitives
  • When to use what
• Subagents
  • Why subagents?
  • Quick start
  • Core types
  • H namespace sugar
  • Testing
  • Design notes
• Compression
  • The two pieces
  • Quick start
  • pre_compact hook integration
  • Bridge to BudgetMonitor
  • Testing
  • Design notes
• Budget
  • The three pieces
  • Quick start
  • Threshold
  • BudgetPolicy
  • BudgetMonitor
  • BudgetPlugin
  • Composition
  • Testing
  • Design notes
• Usage tracking
  • The four pieces
  • Quick start
  • Cost tables
  • Per-agent breakdown
  • Interaction with _budget
  • Manual records
• Virtual filesystem – pluggable backends for workspace tools
  • The three backends
  • The FsBackend protocol
  • Quick start
  • The sandbox decorator
  • Building a custom backend
  • When to reach for what

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