Python Client Overview

Embedded Python client for DeerFlow agent system

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