Water

water · manthanguptaa/water · ★ 288 · last commit 2026-03-24

Primitive shape

No installable primitives

Summary

Water — Summary

Water is a Python agent harness framework (pip: water-ai) that provides infrastructure around AI agents rather than being an agent framework itself. Its core abstraction is Flow — a composable pipeline builder with a fluent API supporting sequential, parallel, conditional, loop, map, DAG, and try-catch patterns. Water wraps any agent framework (LangChain, CrewAI, Agno, OpenAI, Anthropic) in a unified harness layer covering orchestration, resilience, observability, guardrails, approval gates, sandboxing, and deployment. Key primitives include create_task(), Flow.then()/.parallel()/.branch()/.loop()/.map()/.dag()/.try_catch(), create_agent_task(), create_agent_team(), FallbackChain, and PromptLibrary. The framework also ships a water CLI binary for flow management. Version 0.1.4.

Compared to seeds, Water most closely resembles taskmaster-ai in being a flow-execution harness that wraps AI agent work, but differs: where taskmaster-ai is MCP-anchored with JSON task files, Water is a pure Python library with a fluent flow API that chains any LLM provider. Unlike deepagents-langchain (LangGraph-specific), Water is LLM-framework-agnostic — it treats LangChain, CrewAI, and direct API calls as interchangeable task executors.

Overview

Water — Overview

Origin

Developed by Manthan Gupta (manthanguptaa). Published as water-ai on PyPI. Version 0.1.4, indicating early stage. The tagline is "The production-ready agent harness framework for Python."

Core Philosophy

From the README:

"Water is an agent harness framework — it provides the infrastructure around your AI agents, not the agents themselves. Orchestration, resilience, observability, guardrails, approval gates, sandboxing, and deployment tooling so you can focus on what your agents actually do."

"Works with any agent framework: LangChain, CrewAI, Agno, OpenAI, Anthropic, or your own custom agents."

Key Design Choice

Water is explicitly positioned as framework-agnostic harness infrastructure, not as an agent runtime. It does not provide LLM integration itself; it provides the execution environment around any LLM call.

Design Principles

Framework-agnostic: wrap any agent/LLM library
Composable flow patterns with fluent API
Production-ready: resilience, fallbacks, observability built in
Minimal base dependencies (only pydantic, fastapi, uvicorn by default)
Optional extras: [openai], [anthropic], [all], [dev]

Architecture

Water — Architecture

Distribution

Type: pip package (water-ai on PyPI)
Version analyzed: 0.1.4
Install: pip install water-ai
Optional extras: water-ai[openai], water-ai[anthropic], water-ai[all]
Required runtime: Python >=3.8
Base dependencies: pydantic >=2.0.0, fastapi >=0.104.0, uvicorn >=0.24.0

Repository Layout

water/                      # Main Python package
├── __init__.py
├── agents/                 # LLM agent utilities (create_agent_task, providers, etc.)
├── bench/                  # Benchmarking utilities
├── core/                   # Core flow engine (Flow, Task, etc.)
├── debug/                  # Debug utilities
├── eval/                   # Evaluation utilities
├── guardrails/             # Input/output guardrails
├── integrations/           # Third-party integrations
├── middleware/             # Middleware layers
├── observability/          # Metrics, tracing, logging
├── plugins/                # Plugin system
├── resilience/             # Retry, fallback, circuit breaker
├── server/                 # FastAPI serving layer
├── storage/                # State storage
├── tasks/                  # Task primitives
├── triggers/               # Trigger mechanisms
└── utils/
    └── cli.py              # water CLI entry point

cookbook/                   # Usage examples
tests/                      # Test suite

CLI Entry Point

water binary registered via [project.scripts] in pyproject.toml:

water = "water.utils.cli:main"

Config Files

No project-level configuration files required. Configuration is programmatic via Python code.

Target Tools

LLM-framework-agnostic: wraps LangChain, CrewAI, Agno, OpenAI SDK, Anthropic SDK, or custom agent implementations.

Components

Water — Components

Core Flow API

Component	Purpose
`Flow(id, description)`	Pipeline definition builder
`create_task(id, description, input_schema, output_schema, execute)`	Define a task node
`flow.then(task)`	Sequential: run task after current
`flow.parallel([tasks])`	Concurrent: run all tasks simultaneously
`flow.branch([(condition, task)])`	Conditional: route based on data predicate
`flow.loop(condition, task, max_iterations)`	Repeat while condition holds
`flow.map(task, over="field")`	Fan-out: run task per item in a list
`flow.dag(tasks, dependencies)`	DAG: explicit dependency-ordered execution
`flow.try_catch(try_tasks, catch_task, finally_task)`	Structured error handling
`flow.then(task, when=lambda)`	Conditional task execution
`flow.then(task, fallback=fallback_task)`	Fallback on failure
`flow.register()`	Register flow in the global registry
`flow.run(input)`	Execute the flow asynchronously
`SubFlow`	Embed a flow as a task node
`compose_flows(*flows)`	Compose multiple flows sequentially

Agent Layer

Component	Purpose
`create_agent_task(id, description, prompt_template, provider_instance, system_prompt)`	Single LLM agent task
`create_streaming_agent_task(...)`	Streaming LLM agent with `on_chunk` callback
`create_agent_team(team_id, roles, strategy)`	Multi-agent team with shared context
`AgentRole(id, provider, system_prompt)`	Define a team member role
`OpenAIProvider(model)`	OpenAI provider instance
`AnthropicProvider(model)`	Anthropic provider instance
`FallbackChain(providers, strategy)`	Automatic failover between providers
`PromptTemplate(template, defaults)`	Reusable prompt with variable interpolation
`PromptLibrary`	Registry of reusable templates
`Tool`, `Toolkit`, `ToolExecutor`	Tool use integration

Supporting Infrastructure

Component	Purpose
`guardrails/`	Input/output validation
`resilience/`	Retry, backoff, circuit breaker
`observability/`	Metrics, distributed tracing, logging
`server/`	FastAPI-based agent serving
`storage/`	State persistence
`triggers/`	Event-based flow triggering

CLI (`water` binary)

CLI subcommands are unknown — the source is in water/utils/cli.py but not documented in the README. The binary exists.

Prompts

Water — Prompts

Excerpt 1: Agent Task Definition (from README)

from water.agents import create_agent_task, OpenAIProvider, AnthropicProvider

agent = create_agent_task(
    id="writer",
    description="Write copy",
    prompt_template="Write about: {topic}",
    provider_instance=OpenAIProvider(model="gpt-4o"),
    system_prompt="You are a copywriter.",
)

Prompting technique: Template-based prompting with {variable} interpolation. System prompt is a separate field. The prompt_template and system_prompt are passed as Python strings at task definition time.

Excerpt 2: PromptLibrary composition (from README)

from water.agents import PromptTemplate, PromptLibrary

template = PromptTemplate(
    "You are a {{role}}. {{action}}: {{content}}",
    defaults={"role": "assistant"}
)
result = template.render(action="Summarize", content="...")

library = PromptLibrary()
library.register("system", "You are a {{role}}.")
library.register("task", "{{action}}: {{input}}")
combined = library.compose("system", "task", separator="\n\n")

Prompting technique: Mustache-style {{variable}} interpolation with defaults. PromptLibrary.compose() chains registered templates with a separator — prompt chaining via composition.

Prompting Architecture

Prompts are Python strings with {...} or {{...}} variable substitution
No static markdown prompt files are shipped
The PromptLibrary acts as a registry for reusable prompt components
Each create_agent_task() defines its own prompt; no shared base system prompt
Model and provider are specified per task, enabling per-task prompt optimization

Uniqueness

Water — Uniqueness

Differs from Seeds

Water is closest to taskmaster-ai among the seeds in being a flow-execution harness for AI tasks, but differs: taskmaster-ai is MCP-anchored with JSON task files and targets specific AI coding IDEs; Water is a pure Python library with a fluent flow API that treats any LLM provider as an interchangeable executor. Unlike claude-flow (MCP server, 305 tools, Claude-specific), deepagents-langchain (LangGraph-specific), or the other Python harnesses in this batch (OmniCoreAgent focuses on parallel tool batches; Pydantic AI Harness targets Pydantic AI specifically), Water is the only framework in this batch whose explicit design goal is to be an LLM-framework-agnostic harness layer.

Distinctive Position

Only framework with FallbackChain — automatic provider failover with first_success, round_robin, lowest_latency strategies
Most complete flow pattern vocabulary — 9 distinct composition patterns (sequential, parallel, branch, loop, map, DAG, SubFlow, try-catch, compose) in one API
Framework-agnostic philosophy — explicitly wraps LangChain, CrewAI, Agno, raw OpenAI/Anthropic SDK equally
compose_flows() macro-composition — sequential composition of independently defined flows into a larger pipeline

Observable Failure Modes

Version 0.1.4: very early; API stability not guaranteed
Stars (288) and last commit (2026-03-24) suggest the project may be slowing in activity
CLI subcommands undocumented — water binary exists but unclear what it does
No cross-session memory or persistent state documented
No built-in sandboxing or filesystem isolation

Inspired By

LangChain Expression Language (LCEL), Apache Airflow (DAG patterns), CrewAI (agent team metaphor).

Workflow

Water — Workflow

Flow Definition and Execution

from water import Flow, create_task
from pydantic import BaseModel

task = create_task(id="process", description="...", execute=my_fn)
flow = Flow(id="pipeline", description="My pipeline")
flow.then(task_a).then(task_b).register()

result = await flow.run({"input": "data"})

Supported Flow Patterns

Pattern	Method	Behavior
Sequential	`.then(task)`	Tasks run in order
Parallel	`.parallel([t_a, t_b, t_c])`	Tasks run concurrently, results merged
Conditional	`.branch([(cond, task)])`	Route based on data predicate
Loop	`.loop(cond, task, max=5)`	Repeat while condition holds
Map (fan-out)	`.map(task, over="items")`	Run task per item in a list
DAG	`.dag(tasks, dependencies={...})`	Explicit dependency ordering
SubFlow	`.then(sub.as_task())`	Nested flow composition
Try-catch	`.try_catch(try_tasks, catch, finally)`	Structured error handling
Composed	`compose_flows(a, b, c)`	Sequential multi-flow pipeline

Multi-Agent Team Strategies

team = create_agent_team(
    team_id="research_team",
    roles=[
        AgentRole(id="researcher", ...),
        AgentRole(id="writer", ...),
    ],
    strategy="sequential",  # or "round_robin", "dynamic"
)

Approval Gates

Not documented in the README. The guardrails/ module may include approval gates, but no explicit human-in-the-loop mechanism is described.

Artifacts

Water flows produce Python dict outputs from each task. No structured file system artifacts; outputs are data payloads passed between tasks.

Memory Context

Water — Memory and Context

State Passing

Water flows pass data as Python dicts between tasks
Each task receives the previous task's output as its input_data
No built-in cross-session memory; state is in-process during flow execution

Storage Module

water/storage/ module exists but is not documented in the README
Likely provides optional persistence for flow state

Multi-Agent Team Context

create_agent_team() provides shared context across team members
The strategy parameter (sequential, round_robin, dynamic) determines how team members access shared state

No Cross-Session Persistence by Default

Water 0.1.4 does not document a cross-session memory system. The framework is focused on synchronous flow execution, not on long-running session management.

Observability

water/observability/ module for metrics, tracing, and logging
No specific implementation details in the README

Orchestration

Water — Orchestration

Multi-Agent Pattern

Water supports sequential team coordination via create_agent_team():

team = create_agent_team(
    team_id="research_team",
    roles=[
        AgentRole(id="researcher", provider=OpenAIProvider("gpt-4o"), system_prompt="Research..."),
        AgentRole(id="writer", provider=AnthropicProvider("claude-sonnet"), system_prompt="Write..."),
    ],
    strategy="sequential",  # also: "round_robin", "dynamic"
)

Pattern: sequential or parallel-fan-out (via flow.parallel())

Flow-Level Parallelism

flow.parallel([task_a, task_b, task_c]) runs tasks concurrently using asyncio. Results are merged for the next step.

Multi-Model

Each AgentRole and each create_agent_task() specifies its own provider instance independently. No config-file-level routing; Python-code-level.

FallbackChain enables automatic provider failover:

chain = FallbackChain(
    providers=[OpenAIProvider("gpt-4o"), AnthropicProvider("claude-sonnet")],
    strategy="first_success",  # also: "round_robin", "lowest_latency"
)

Isolation Mechanism

None documented. Water flows run in-process; no sandbox or container isolation.

Execution Mode

one-shot — flow.run(input) executes a pipeline and returns when done. No continuous loop or event-driven mode documented.

Error Handling

.try_catch(try_tasks, catch_task, finally_task) provides structured error handling at the flow level. FallbackChain provides provider-level failover.

Ui Cli Surface

Water — UI/CLI Surface

CLI Binary: `water`

Binary name: water
Install: pip install water-ai (CLI is included)
Entry point: water.utils.cli:main
Subcommands: unknown (CLI source not documented in README)
Is thin wrapper: No — it is an independent CLI entry point

Local UI

None. Water is a pure library.

IDE Integration

None. No .claude/ files, no AI tool integration.

FastAPI Server

water/server/ provides a FastAPI-based serving layer for exposing flows as HTTP endpoints. This is not a monitoring UI but an agent-serving API.

Cross-Tool Portability

high — framework-agnostic; wraps any LLM provider (OpenAI, Anthropic, or custom). Not tied to any AI coding tool.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.

Distribution

Type: pip-package
License: Apache-2.0
Install: one-liner
Version: 0.1.4

Surfaces

CLI binary: water
Local UI: No

Components

Commands: 0
Skills: 0
Subagents: 0
Hooks: 0
MCP servers: 0
MCP tools: 0
Scripts: 0
Templates: 0

Workflow

Phases: 4
Approval gates: 0
Spec format: none
Spec storage: none
Delta or full: none

Orchestration

Multi-agent: Yes
Pattern: parallel-fan-out
Isolation: none
Consensus: none
Prompt chaining: Yes

Multi-model

Multi-model: Yes
BYOK: Yes
Modal: text

Execution

Mode: one-shot
Crash recovery: No
Compaction: No
Session handoff: No
Streaming: Yes

Memory

Type: none
Persistence: none
Search: none

Quality

TDD: No
TDD mechanism: none
Self-review: none

Git / Observability

Auto commit: No
Auto PR: No
Auto merge: No
Worktree/feat: No
Audit log: No
Audit format: none
Replay: No

Tools

Primary: any (framework-agnostic)
Targets: 5
Portability: high

Signals

Stars: 288
Last commit: 2026-03-24
Quality score: 1/10

Summary

Water — Summary

Overview

Water — Overview

Origin

Core Philosophy

Key Design Choice

Design Principles

Architecture

Water — Architecture

Distribution

Repository Layout

CLI Entry Point

Config Files

Target Tools

Components

Water — Components

Core Flow API

Agent Layer

Supporting Infrastructure

CLI (water binary)

Prompts

Water — Prompts

Excerpt 1: Agent Task Definition (from README)

Excerpt 2: PromptLibrary composition (from README)

Prompting Architecture

Uniqueness

Water — Uniqueness

Differs from Seeds

Distinctive Position

Observable Failure Modes

Inspired By

Workflow

Water — Workflow

Flow Definition and Execution

Supported Flow Patterns

Multi-Agent Team Strategies

Approval Gates

Artifacts

Memory Context

Water — Memory and Context

State Passing

Storage Module

Multi-Agent Team Context

No Cross-Session Persistence by Default

Observability

Orchestration

Water — Orchestration

Multi-Agent Pattern

Flow-Level Parallelism

Multi-Model

Isolation Mechanism

Execution Mode

Error Handling

Ui Cli Surface

Water — UI/CLI Surface

CLI Binary: water

Local UI

IDE Integration

FastAPI Server

Cross-Tool Portability

Related frameworks

CLI (`water` binary)

CLI Binary: `water`