Skip to main content

​
Introduction

The DeerFlowClient is an embedded Python client that provides direct programmatic access to DeerFlow’s agent capabilities without requiring LangGraph Server or Gateway API processes.
The Python Client implements the same protocol as the Gateway API, making it easy to switch between embedded mode and HTTP streaming without changing your event-handling logic.

​
Installation

The client is included in the DeerFlow backend package: 
from src.client import DeerFlowClient

​
Basic Usage

​
Simple Chat

from src.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("Analyze this paper for me", thread_id="my-thread")
print(response)

​
Streaming Responses

for event in client.stream("hello"):
    print(event.type, event.data)

​
Query Configuration

# List available models
models = client.list_models()
print(models)

# List skills
skills = client.list_skills()
print(skills)

​
Initialization Options

The client accepts several configuration parameters:
​
config_path
str | None
default:"None"
Path to config.yaml. Uses default resolution if None.
​
checkpointer
LangGraph Checkpointer
default:"None"
LangGraph checkpointer instance for state persistence. Required for multi-turn conversations on the same thread_id. Without a checkpointer, each call is stateless.
​
model_name
str | None
default:"None"
Override the default model name from config.
​
thinking_enabled
bool
default:"True"
Enable model’s extended thinking mode.
​
subagent_enabled
bool
default:"False"
Enable subagent delegation capabilities.
​
plan_mode
bool
default:"False"
Enable TodoList middleware for plan mode.

​
Example: Custom Configuration

client = DeerFlowClient(
    config_path="/path/to/config.yaml",
    model_name="gpt-4",
    thinking_enabled=False,
    subagent_enabled=True
)

​
Gateway API Alignment

The DeerFlowClient is designed to align with the Gateway API:
  • Event types match the LangGraph SSE protocol
  • Response schemas mirror Gateway API responses
  • File operations use the same virtual path structure
This means you can develop locally with the embedded client and deploy with the Gateway API without changing your code.

​
Multi-Turn Conversations

Multi-turn conversations require a checkpointer at initialization. Without one, each stream() / chat() call is stateless — thread_id is only used for file isolation (uploads / artifacts).
from langgraph.checkpoint.memory import MemorySaver

checkpointer = MemorySaver()
client = DeerFlowClient(checkpointer=checkpointer)

# First turn
response1 = client.chat("My name is Alice", thread_id="conversation-1")

# Second turn - context is preserved
response2 = client.chat("What's my name?", thread_id="conversation-1")

​
Agent Recreation

The system prompt (including date, memory, and skills context) is generated when the internal agent is first created and cached until the configuration key changes.
Call reset_agent() to force a refresh in long-running processes: 
client.reset_agent()
This is useful after:
  • External changes to memory
  • Skill installations
  • Configuration updates that should be reflected in the system prompt

​
API Reference

For detailed method documentation, see:

Chat

Single-message request/response

Streaming

Real-time event streaming

Configuration

Models, skills, memory, and file management

Build docs developers (and LLMs) love

Get started for freeTalk to us