# DeerFlow

DeerFlow is a super-agent harness that orchestrates sub-agents, memory, sandboxes, and skills on top of LangGraph and LangChain. The Grid plugs in as a standard OpenAI-compatible provider through `config.yaml`. Define the model entries, point `base_url` at The Grid, and the lead agent and sub-agents start routing through market-priced inference.

## Prerequisites

* DeerFlow installed with the backend running. Follow the [Install guide](https://github.com/bytedance/deer-flow/blob/main/Install.md) if you haven't.
* A Grid account at [app.thegrid.ai](https://app.thegrid.ai).
* Credits in your account. The Grid is prepaid.
* A Grid consumption API key from **Settings → API Keys → Create Consumption Key**.

## Setup

### 1. Add the key to `.env`

In DeerFlow's root directory:

```bash
THEGRID_API_KEY=your-consumption-api-key-here
```

### 2. Add Grid instruments to `config.yaml`

Open `config.yaml` (copy from `config.example.yaml` if you haven't already). Under `models:`, add Grid instruments. Use IDs from the [current instruments list](/docs/instrument-specifications/current-instruments.md):

```yaml
models:
  - name: agent-prime
    display_name: "Grid: Agent Prime"
    use: langchain_openai:ChatOpenAI
    model: agent-prime
    api_key: $THEGRID_API_KEY
    base_url: https://api.thegrid.ai/v1
    use_responses_api: false
    supports_thinking: false
    supports_vision: false

  - name: agent-max
    display_name: "Grid: Agent Max"
    use: langchain_openai:ChatOpenAI
    model: agent-max
    api_key: $THEGRID_API_KEY
    base_url: https://api.thegrid.ai/v1
    use_responses_api: false
    supports_thinking: false
    supports_vision: false

  - name: text-standard
    display_name: "Grid: Text Standard"
    use: langchain_openai:ChatOpenAI
    model: text-standard
    api_key: $THEGRID_API_KEY
    base_url: https://api.thegrid.ai/v1
    use_responses_api: false
    supports_thinking: false
    supports_vision: false

  - name: code-prime
    display_name: "Grid: Code Prime"
    use: langchain_openai:ChatOpenAI
    model: code-prime
    api_key: $THEGRID_API_KEY
    base_url: https://api.thegrid.ai/v1
    use_responses_api: false
    supports_thinking: false
    supports_vision: false
```

The first model in the list becomes DeerFlow's default. Put `agent-prime` first if you want it as the default for the lead agent and sub-agents.

{% hint style="warning" %}
`use_responses_api: false` is required. Recent `ChatOpenAI` versions default to the Responses API (`/v1/responses`), and The Grid serves Chat Completions. Without this flag, calls return 404.
{% endhint %}

{% hint style="warning" %}
`supports_thinking: false` is required for Grid instruments. DeerFlow's thinking-token logic targets OpenAI's extended thinking format. The Grid handles reasoning internally; you don't pass thinking-token configuration.
{% endhint %}

### 3. Route auxiliary features to a cheap tier

In the same `config.yaml`, point title generation, summarization, and memory at Text Standard:

```yaml
title:
  enabled: true
  model_name: text-standard

summarization:
  enabled: true
  model_name: text-standard

memory:
  enabled: true
  model_name: text-standard
```

These features fire frequently and don't need frontier-quality models.

### 4. Restart DeerFlow

```bash
make doctor
make dev
```

`make doctor` checks dependencies (including nginx) before the dev server starts.

## Verification

Open the DeerFlow UI at `http://localhost:2026` and start a conversation. Pick a Grid model from the picker (or rely on the default). Try: "Research the latest trends in AI inference pricing and summarize them." A coherent response confirms the integration is live.

If `make doctor` flags nginx as missing and you want a headless check, hit the gateway directly:

```bash
curl http://localhost:<gateway-port>/health
```

A 200 response confirms the backend is wired up.

## Troubleshooting

{% hint style="warning" %}
**404 errors from The Grid.** You're missing `use_responses_api: false` on at least one Grid model entry. Add the flag, restart DeerFlow.
{% endhint %}

{% hint style="warning" %}
**Crash on startup with `ValueError: Environment variable THEGRID_API_KEY not found`.** The `$THEGRID_API_KEY` reference in `config.yaml` triggers a hard crash if `.env` is missing the variable. Confirm `.env` is in DeerFlow's root and contains `THEGRID_API_KEY=your-key`.
{% endhint %}

{% hint style="warning" %}
**401 Unauthorized.** Your Grid key is a trading key, not a consumption key. Generate a new consumption key.
{% endhint %}

{% hint style="warning" %}
**402 Payment Required.** Your credits are at zero. Top up at [app.thegrid.ai](https://app.thegrid.ai). Enable Auto Top Up to keep long sessions running.
{% endhint %}

{% hint style="info" %}
**503 balance\_replenishing.** A transient Grid-side state while credits replenish. Retry after a few seconds. If it persists, contact Grid support.
{% endhint %}

{% hint style="info" %}
**Model missing from the DeerFlow UI.** Check the entry has a unique `name` field under `models:` and restart DeerFlow.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/integrations/deerflow.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.