adk-fluent¶
adk-fluent
Fluent builder API for Google ADK. One agent in 1 line, one pipeline in 3, any topology in an expression. Same native objects at .build().
pip install adk-fluent
Your first agent — one line¶
from adk_fluent import Agent
answer = Agent("helper", "gemini-2.5-flash").ask("Say hello.")
# => "Hi! How can I help?"
import { Agent } from "adk-fluent-ts";
const answer = await new Agent("helper", "gemini-2.5-flash").ask("Say hello.");
// => "Hi! How can I help?"
No builder boilerplate, no Runner, no Session — .ask() handles it
for one-shot calls. Ready for more? Pipeline flex below shows the
same fluent API doing sequential + parallel + context filtering in
three lines (vs twenty-two in native ADK).
Pipeline flex — when you need more¶
This is the same fluent API at scale. Skim it now, come back after the getting-started page.
from adk_fluent import Agent, C
research = (
Agent("analyzer", "gemini-2.5-flash").instruct("Decompose the query.").writes("plan")
>> (Agent("web", "gemini-2.5-flash").instruct("Search web.").context(C.from_state("plan")).writes("web")
| Agent("papers", "gemini-2.5-flash").instruct("Search papers.").context(C.from_state("plan")).writes("papers"))
>> Agent("writer", "gemini-2.5-flash").instruct("Synthesize findings from {web} and {papers}.")
).build()
import { Agent, C } from "adk-fluent-ts";
const research = new Agent("analyzer", "gemini-2.5-flash")
.instruct("Decompose the query.")
.writes("plan")
.then(
new Agent("web", "gemini-2.5-flash")
.instruct("Search web.")
.context(C.fromState("plan"))
.writes("web")
.parallel(
new Agent("papers", "gemini-2.5-flash")
.instruct("Search papers.")
.context(C.fromState("plan"))
.writes("papers"),
),
)
.then(
new Agent("writer", "gemini-2.5-flash")
.instruct("Synthesize findings from {web} and {papers}."),
)
.build();
from google.adk.agents.llm_agent import LlmAgent
from google.adk.agents.sequential_agent import SequentialAgent
from google.adk.agents.parallel_agent import ParallelAgent
analyzer = LlmAgent(name="analyzer", model="gemini-2.5-flash",
instruction="Decompose the query.", output_key="plan")
web = LlmAgent(name="web", model="gemini-2.5-flash",
instruction="Search web.", output_key="web",
include_contents="none") # context filtering
papers = LlmAgent(name="papers", model="gemini-2.5-flash",
instruction="Search papers.", output_key="papers",
include_contents="none")
writer = LlmAgent(name="writer", model="gemini-2.5-flash",
instruction="Synthesize findings from {web} and {papers}.")
parallel = ParallelAgent(name="search", sub_agents=[web, papers])
research = SequentialAgent(
name="research",
sub_agents=[analyzer, parallel, writer],
)
Every .build() returns a real ADK object – fully compatible with adk web, adk run, and adk deploy. Click a tab — your Python/TypeScript choice is remembered across every code sample on this site.
Note
Python + TypeScript monorepo adk-fluent ships as two sibling packages from a single monorepo:
adk-fluent(PyPI) — Python 3.11+, underpython/. Reference implementation; this site is Python-first.adk-fluent-ts(npm) — TypeScript, underts/. Mirrors the same builders and namespaces with method-chained operators. See the TypeScript user guide and the TS README.
Both packages are generated from the same shared/manifest.json, so parity is enforced at generation time. Throughout this site, conceptual guides apply to both languages; code samples with a Python / TypeScript tab selector stay in sync once you pick one.
What’s New in v0.17.0¶
State-driven reactivity with R.signal(), SignalPredicate composition, Builder.on() for declarative rules, R.compile() for zero-ceremony wiring. Agents activate on conversation phase changes, quality scores, completion flags – no polling.
Declarative UI composition with UI.text(), UI.button(), UI.form(). Expression operators | and >> for layouts. Data binding and validation built in.
Declarative agent packages with SKILL.md. Autonomous coding runtimes with H namespace. Five layers from tools to REPL.
Output validation with G.pii(), G.toxicity(), G.length(), G.schema(). Compose with | pipe operator.
Zero-cost import adk_fluent — loads 1 module instead of ~1,468. ADK dependencies deferred to .build() time.
Fluent evaluation with E.case(), E.criterion(), E.persona(). LLMJudge for LLM-powered evaluation.
Docs now include a version switcher. Browse docs for any release, with /latest/ always pointing to the most recent build.
Why adk-fluent?¶
135 Builders, Full Autocomplete
Every builder ships with .pyi stubs. Type Agent("name"). and your IDE shows all methods with type hints, parameter docs, and ADK mapping.
Expression Algebra
>> sequential, | parallel, * loops, @ typed output, // fallback. Compose any topology in a single expression.
Always in Sync
Builders are auto-generated from installed ADK. When ADK updates, regenerate and get new features immediately. Zero maintenance.
Three Pathways¶
Once you know the builder basics, adk-fluent splits into three distinct development pathways – a fork in the road that matches how you think about agent building.
Pipeline Path
Python-first builders
Full Python control with expression operators (>> | * @ //) and 9 namespace modules. Build any topology with type-checked, IDE-friendly builders.
Agent("a") >> Agent("b") | Agent("c")
Best for: Custom workflows, complex routing, dynamic topologies
Expression Language →Skills Path
Declarative agent packages
YAML + Markdown → executable agent graphs. Domain experts write prompts and topology. One file is docs, coding-agent context, and a runnable pipeline.
Skill("research/") >> Skill("writing/")
Best for: Stable topologies, reusable libraries, non-Python teams
Skills Guide →Harness Path
Autonomous coding runtimes
Build Claude-Code-class agents with the H namespace. Five layers: intelligence, tools, safety, observability, runtime. Permissions, sandboxing, token budgets.
H.workspace() + H.web() + H.git()
Best for: Autonomous agents, file/shell access, multi-turn runtimes
Harness Guide →All three compose together – a harness loads skills for domain expertise, skills wire agents as pipelines internally, and pipelines use the full expression algebra. See the Decision Guide for a flowchart.
Common Starting Points¶
“I’m building agents from scratch” – Start with Getting Started, then choose your path.
“I want full Python control with operators” – Take the Pipeline Path. >> | * @ // compose any topology.
“I want declarative, reusable agent packages” – Take the Skills Path. YAML + Markdown = docs + runtime.
“I want an autonomous coding agent” – Take the Harness Path. Five layers from tools to REPL.
“I have native ADK code and want to simplify it” – Start with the Migration Guide, then browse the Cookbook for your pattern.
“I need a specific pattern (routing, loops, parallel)” – Jump to Patterns or search the Cookbook by use case.
“I want my AI coding agent to know adk-fluent” – Set up Editor & AI Agent Setup for rules files, skills, and MCP servers.
“I’m using TypeScript, not Python” – Start with the TypeScript user guide. Every conceptual chapter in this site applies to both languages; code samples have a synced Python / TypeScript tab.
PyPI · GitHub · Changelog · Contributing
Getting Started
User Guide
API Reference
Cookbook
All Recipes (Auto-Generated)
Examples
Flux catalog
Contributing
Project