# Deep Agents

Deep Agents is LangChain's batteries-included agent harness. `create_deep_agent()` ships with planning, a filesystem, shell access, sub-agents, and context summarization on top of LangGraph. The Grid plugs in as a standard OpenAI-compatible model, but one setting matters more than anything else: you must force Chat Completions over the Responses API, or every request returns 404.

## Prerequisites

* Python 3.10+ with `deepagents` installed: `uv add deepagents langchain-openai`.
* 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. Set the key as an environment variable

```bash
export GRID_API_KEY="your-consumption-api-key-here"
```

Or add it to `.env` and load via `python-dotenv`.

### 2. Build a `ChatOpenAI` instance pointed at The Grid

This is the step that matters. Construct the model explicitly and pass the instance to `create_deep_agent`. Use an instrument from the [current instruments list](/docs/instrument-specifications/current-instruments.md):

```python
import os
from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent

model = ChatOpenAI(
    model="agent-prime",
    api_key=os.environ["GRID_API_KEY"],
    base_url="https://api.thegrid.ai/v1",
    use_responses_api=False,
)

agent = create_deep_agent(model=model)
```

{% hint style="warning" %}
`use_responses_api=False` is mandatory. Recent `langchain-openai` versions default `ChatOpenAI` to the Responses API. The Grid serves Chat Completions only, so the default produces 404 on every call. This is the #1 failure mode.
{% endhint %}

{% hint style="warning" %}
Do NOT use `create_deep_agent(model="openai:agent-prime")` or any `"openai:..."` string. The string syntax triggers Deep Agents' OpenAI harness profile, which forces `use_responses_api=True` and routes through `/v1/responses`. Always pass a pre-built `ChatOpenAI` instance.
{% endhint %}

### 3. (Optional) Tier sub-agents by task type

Each sub-agent's `model` field accepts a `BaseChatModel` instance. Use this to put the main loop on Agent Prime and delegate cheap classification work to Text Standard:

```python
def grid(instrument: str) -> ChatOpenAI:
    return ChatOpenAI(
        model=instrument,
        api_key=os.environ["GRID_API_KEY"],
        base_url="https://api.thegrid.ai/v1",
        use_responses_api=False,
    )

planner_sub = {
    "name": "deep-planner",
    "description": "Hard multi-step planning with long context.",
    "system_prompt": "You are a careful planner. Produce numbered, verifiable steps.",
    "model": grid("agent-max"),
}

classifier_sub = {
    "name": "fast-classifier",
    "description": "Cheap extraction and classification.",
    "system_prompt": "Classify or extract. Be terse.",
    "model": grid("text-standard"),
}

agent = create_deep_agent(
    model=grid("agent-prime"),
    subagents=[planner_sub, classifier_sub],
)
```

Sub-agents that omit `model` inherit the main agent's model. Always pass `ChatOpenAI` instances for sub-agents too, so `use_responses_api=False` stays explicit.

### 4. Invoke the agent

```python
result = agent.invoke({
    "messages": [{"role": "user", "content": "Plan a small research project on AI inference pricing and draft an outline."}]
})
print(result["messages"][-1].content)
```

## Verification

A realistic shakeout that exercises planning, filesystem, and a sub-agent:

```python
result = agent.invoke({
    "messages": [{
        "role": "user",
        "content": (
            "1. Use write_todos to plan a research task on AI inference markets. "
            "2. Delegate topic classification to fast-classifier. "
            "3. Use deep-planner to produce a 5-step outline. "
            "4. Write the outline to outline.md."
        ),
    }]
})
```

If all four steps complete without 404s, your setup works end to end.

## Troubleshooting

{% hint style="warning" %}
**404 on every request.** You forgot `use_responses_api=False`, or you used the `"openai:..."` string shortcut. Build a `ChatOpenAI` instance with the flag set and pass it directly.
{% endhint %}

{% hint style="warning" %}
**401 Unauthorized.** Confirm `GRID_API_KEY` is set, that it's a consumption key (not a trading key), and that `base_url` is exactly `https://api.thegrid.ai/v1` with no trailing path.
{% 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, and wrap `agent.invoke` in a 402 retry. The harness itself does not retry balance errors.
{% endhint %}

```python
import time
from openai import APIStatusError

for attempt in range(3):
    try:
        result = agent.invoke({"messages": [...]})
        break
    except APIStatusError as e:
        if e.status_code == 402:
            time.sleep(5)
            continue
        raise
```

{% hint style="info" %}
**JS/TS Deep Agents.** The same Responses API trap applies in `deepagentsjs`. Use `@langchain/openai`'s `ChatOpenAI` with the equivalent flag, pointed at `https://api.thegrid.ai/v1`.
{% 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/deepagents.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.