DeerFlow Integration with The Grid | config.yaml Setup

Set up DeerFlow with The Grid in config.yaml. Add ChatOpenAI models, point to the Grid endpoint, and set use_responses_api to false.

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 if you haven't.

• A Grid account at 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:

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:

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.

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.

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.

3. Route auxiliary features to a cheap tier

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

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

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:

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

A 200 response confirms the backend is wired up.

Troubleshooting

404 errors from The Grid. You're missing use_responses_api: false on at least one Grid model entry. Add the flag, restart DeerFlow.

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.

401 Unauthorized. Your Grid key is a trading key, not a consumption key. Generate a new consumption key.

402 Payment Required. Your credits are at zero. Top up at app.thegrid.ai. Enable Auto Top Up to keep long sessions running.

503 balance_replenishing. A transient Grid-side state while credits replenish. Retry after a few seconds. If it persists, contact Grid support.

Model missing from the DeerFlow UI. Check the entry has a unique name field under models: and restart DeerFlow.