deepagents documentation should use Response API by default

[astromaier (asmaier)]

In March 2025 OpenAI has announced the Response API, recommended for all new projects. Why is the langchain documentation and even the new deepagents framework still using the old chat completion API?

While backwards compatibility is important, I believe at least the documentation should not use an obsolete API anymore.

[<div> (false200)]

astromaier (@asmaier) fair question, but I think the situation is almost the opposite of what it looks like from the outside.

Deep Agents already defaults to the Responses API for OpenAI. When you pass an openai:... model string to create_deep_agent, the harness profile sets use_responses_api=True by default (see profiles/_openai.py). That is intentional — PDF attachments, built-in tools, and some agent features expect /v1/responses, not Chat Completions.

So the framework is not lagging behind OpenAI here. What is lagging a bit is making that obvious in the docs. There is an open docs issue (#3730) to call this out on the Models page, because right now you mostly discover it from source or API docstrings. Easy to read a Chat Completions-style example elsewhere and assume that is the default.

Why Chat Completions still shows up everywhere in LangChain docs

Most examples are written for the widest compatibility path:

• Third-party OpenAI-compatible gateways (LiteLLM, vLLM, Azure proxies, Bifrost, etc.) often only implement /v1/chat/completions
• ChatOpenAI(use_responses_api=False) is the escape hatch people need when a gateway 404s on Responses (#3973 is basically that report)
• ChatOpenAI is one abstraction over both APIs — Responses is documented in the ChatOpenAI integration section, including use_responses_api=True and output_version="responses/v1" for new apps

So it is less "docs stuck on obsolete API" and more "docs show the portable baseline, framework opts into Responses for real OpenAI agent workloads."

If you are on official OpenAI with Deep Agents today

You are probably already on Responses if you use openai:gpt-4o style strings. To be explicit:

from langchain_openai import ChatOpenAI
from deepagents import create_deep_agent

llm = ChatOpenAI(model="gpt-4o", use_responses_api=True, output_version="responses/v1")
agent = create_deep_agent(model=llm)

To force Chat Completions instead (gateways, local proxies):

# config.toml
[models.providers.openai.params]
use_responses_api = false

Bottom line

Your instinct is right that docs should not leave people guessing which API surface they are on. But Deep Agents is already Responses-first for OpenAI strings - the fix is clearer documentation, not flipping the framework default. Worth commenting on #3730 if you want that surfaced on the public Models page.