Overview

Gwenflow is built from a handful of objects that compose: an LLM client talks to a provider, an agent drives it in a loop with tools and a history, and a flow chains agents and data steps in a graph. Everything else (skills, memory, retrieval, durability, telemetry) attaches to one of these.

The building blocks

Object	Import	Role
LLM client	`ChatOpenAI`, `ChatAnthropic`, `ChatGoogle`, …	One call to a model: `invoke`, `ainvoke`, `stream`, `astream`. Every provider shares the base class `ChatBase` and returns a `ModelResponse`. See Models.
Agent	`Agent`	The agentic loop: system prompt, history, tools, limits, usage. Returns an `AgentResponse`. See Agents.
Tool	`Tool`, `BaseTool`	A function the model may call, described by a JSON schema built from its signature and docstring. See Tools.
History	`ChatMemoryBuffer`, `ChatSummaryMemoryBuffer`	The conversation of an agent, kept within the model’s context window. See Context management.
Skill	`Skill`, `SkillsDirectory`	Instructions (and optional scripts) the agent loads only when a task calls for them. See Skills.
Long-term memory	`MemoryToolset`	Markdown files the agent reads and edits across conversations. See Long-term memory.
Flow	`Flow`, `FlowRunner`, `AutoFlow`	A DAG of nodes (agents, HTTP calls, readers, databases), run with independent branches in parallel. See Flows.
Retriever	`Retriever`	Chunks, embeds and searches documents, and injects the best matches into the prompt. See Retrieval.
Durability	`TemporalDurability`	Runs model requests, tool calls and flow nodes as Temporal activities. See Durable execution.
Telemetry	`Telemetry`, `tracer`	OpenTelemetry spans for every agent run, LLM call, tool call and flow node. See Telemetry.

A run, step by step

agent.run("What's the exchange rate of the Euro?")
  │
  ├─ build the system prompt   instructions, skills, memory, retrieved references, context
  ├─ append the user message   to the history (compacted first if it nears the window)
  │
  └─ loop, up to max_turns
       ├─ llm.invoke(history, tools)            → ModelResponse (text, thinking, tool calls)
       ├─ no tool call?  → final answer, stop
       ├─ tool needs approval?  → pause, finish_reason = "approval_required"
       └─ run each tool call, append the results, loop
  │
  └─ AgentResponse   content, parsed, messages, events, usage, finish_reason

System prompt. Built from the agent’s instructions (or a fixed system_prompt), the list of its skills, its long-term memory, the JSON schema of a response_model, references from its retriever and the context passed to the run.
History. The new message joins the agent’s history. Before every request the history is measured against the model’s context window and compacted when it nears the limit.
Model call. The LLM client sends the history and the tool schemas, and returns a provider-neutral ModelResponse.
Tools. Each tool call is executed and its result appended as a tool message; the loop goes back to the model. Calls to delegated agents (team members, sub-agents) run in parallel.
Answer. When the model answers without calling a tool, the run ends with finish_reason="stop". It also ends at max_turns, or pauses when a tool needs a human’s approval.

Sync, async and streaming

Every operation has four forms, with the same arguments:

	Blocking	Streaming
Sync	`agent.run()`, `llm.invoke()`	`agent.run_stream()`, `llm.stream()`
Async	`await agent.arun()`, `await llm.ainvoke()`	`agent.arun_stream()`, `llm.astream()`

A stream yields events as they happen (text deltas, thinking, tool starts and ends) and ends with the complete response. See Streaming.

Lazy imports

import gwenflow stays light: the vendor SDKs (anthropic, google-genai, mistralai), the tools, the readers and the MCP client load on first use. from gwenflow import ChatAnthropic works as usual; the SDK is only imported at that moment. Avoid from gwenflow import *, which resolves every name and loses the saving.

Identifiers

Agents, runs, responses and flows get UUIDv7 identifiers: unique and sortable by creation time. Inside a Temporal workflow they are generated deterministically, so a replay produces the same ones.

Get started

Concepts

Models

Agents

Multi-agent

Extend

Memory

Flows

Knowledge

Production

Project

The building blocks

A run, step by step

Sync, async and streaming

Lazy imports

Identifiers

​The building blocks

​A run, step by step

​Sync, async and streaming

​Lazy imports

​Identifiers

The building blocks

A run, step by step

Sync, async and streaming

Lazy imports

Identifiers