claude-to-deerflow

DeerFlow Skill

Communicate with a running DeerFlow instance via its HTTP API. DeerFlow is an AI agent platform built on LangGraph that orchestrates sub-agents for research, code execution, web browsing, and more.

Architecture

DeerFlow exposes two API surfaces behind an Nginx reverse proxy:

Environment Variables

All URLs are configurable via environment variables. Read these env vars before making any request.

When making curl calls, always resolve the URL like this:

# Resolve base URLs from env (do this FIRST before any API call)
DEERFLOW_URL="${DEERFLOW_URL:-http://localhost:2026}"
DEERFLOW_GATEWAY_URL=

Available Operations

1. Health Check

Verify DeerFlow is running:

2. Send a Message (Streaming)

This is the primary operation. It creates a thread and streams the agent's response.

Step 1: Create a thread

Response: {"thread_id": "<uuid>", ...}

Step 2: Stream a run

The response is an SSE stream. Each event has the format:

Key event types:

• metadata — run metadata including run_id
• values — full state snapshot with messages array
• messages-tuple — incremental message updates (AI text chunks, tool calls, tool results)
• end — stream is complete

Context modes (set via context):

• Flash mode: thinking_enabled: false, is_plan_mode: false, subagent_enabled: false
• Standard mode: thinking_enabled: true, is_plan_mode: false, subagent_enabled: false
• Pro mode: thinking_enabled: true, is_plan_mode: true, subagent_enabled: false
• Ultra mode: thinking_enabled: true, is_plan_mode: true, subagent_enabled: true

3. Continue a Conversation

To send follow-up messages, reuse the same thread_id from step 2 and POST another run with the new message.

4. List Models

Returns: {"models": [{"name": "...", "provider": "...", ...}, ...]}

5. List Skills

Returns: {"skills": [{"name": "...", "enabled": true, ...}, ...]}

6. Enable/Disable a Skill

7. List Agents

Returns: {"agents": [{"name": "...", ...}, ...]}

8. Get Memory

Returns user context, facts, and conversation history summaries.

9. Upload Files to a Thread

Supports PDF, PPTX, XLSX, DOCX — automatically converts to Markdown.

10. List Uploaded Files

11. Get Thread History

12. List Threads

Usage Script

For sending messages and collecting the full response, use the helper script:

See scripts/chat.sh for the implementation. The script:

1. Checks health
2. Creates a thread
3. Streams the run and collects the final AI response
4. Prints the result

Parsing SSE Output

The stream returns SSE events. To extract the final AI response from a values event:

• Look for the last event: values block
• Parse its data JSON
• The messages array contains all messages; the last one with type: "ai" is the response
• The content field of that message is the AI's text reply

Error Handling

• If health check fails, DeerFlow is not running. Inform the user they need to start it.
• If the stream returns an error event, extract and display the error message.
• Common issues: port not open, services still starting up, config errors.

Tips

• For quick questions, use flash mode (fastest, no planning).
• For research tasks, use pro or ultra mode (enables planning and sub-agents).
• You can upload files first, then reference them in your message.
• Thread IDs persist — you can return to a conversation later.