Deep Agents (deepagents)

Common errors

• AttributeError: 'RunnableWithFallbacks' object has no attribute 'startswith'

  cause The `create_deep_agent` function, in version 0.4.12, expects the `model` parameter to be either a string identifier or an instance of `BaseChatModel`, but `RunnableWithFallbacks` (used for model fallbacks in LangChain) does not directly inherit from `BaseChatModel`, causing a string-specific check to fail.
  fix Ensure the model passed to `create_deep_agent` is a `BaseChatModel` or a string. If using fallbacks, you may need to wrap `RunnableWithFallbacks` in a custom `BaseChatModel` implementation or pass a string identifier for the primary model and handle fallbacks externally, or extend the `resolve_model` logic to explicitly handle `RunnableWithFallbacks`.

• ModuleNotFoundError: No module named 'deepagents_cli.execution'

  cause This error typically occurs when running older example scripts that rely on an internal or deprecated module path within the `deepagents-cli` package, which has likely been refactored or removed in newer versions.
  fix Update your `deepagents-cli` installation to the latest version. If the error persists with example code, check the official `deepagents` GitHub repository for the most current examples and their corresponding execution methods, as the `deepagents_cli.execution` module might no longer exist or be exposed directly.

• channel name 'file' already exists

  cause This error indicates that a communication channel, specifically named 'file', is being registered more than once with differing types, often due to duplicate tool or subagent initializations or registrations without proper namespacing.
  fix Review your tool and subagent registration code to ensure that each communication channel has a unique name. Implement checks to prevent re-registering channels or utilize namespacing for tools and subagents to avoid conflicts, especially when sharing tools between subagents.

• AttributeError: 'list' object has no attribute 'split'

  cause This error occurs within the `_parse_skill_metadata` function when the `allowed-tools` field in a `SKILL.md` file is provided as a list instead of an expected space-separated string.
  fix Ensure that the `allowed-tools` entry in your `SKILL.md` files is a single string with tool names separated by spaces, rather than a YAML list. For example, use `allowed-tools: tool1 tool2` instead of `allowed-tools: [tool1, tool2]`.

• ImportError: cannot import name 'CompiledSubAgents' from 'deepagents'

  cause This error suggests that the `CompiledSubAgents` class, or a similar component, is either no longer exported directly from the top-level `deepagents` package, has been renamed, or its import path has changed in a later version of the library.
  fix Consult the official `deepagents` documentation or API reference for the correct import path and name of the subagent compilation utility. If `CompiledSubAgents` has been removed or replaced, adapt your code to use the recommended alternative for compiling subagents, which might involve a different class or function from a more specific submodule.

Warnings

• gotcha Default model is Claude Sonnet (anthropic), not GPT-4o. Requires ANTHROPIC_API_KEY if no custom model passed. Fails with AuthenticationError if key not set.
  Fix: Pass model= explicitly: create_deep_agent(model=init_chat_model('openai:gpt-4o')) to use OpenAI.
• gotcha create_deep_agent returns a compiled LangGraph StateGraph — not a plain callable. Must invoke with {'messages': [...]} dict, not a plain string.
  Fix: agent.invoke({'messages': [{'role': 'user', 'content': 'your prompt'}]})
• gotcha Result is a dict, not a string. Final answer is at result['messages'][-1].content. Agent may also create files accessible at result['files'].
  Fix: result['messages'][-1].content for text output. result.get('files', {}) for any files created.
• gotcha Because it returns a LangGraph graph, it supports streaming, checkpointers, human-in-the-loop, and LangSmith tracing natively — but requires LangGraph-style usage patterns.
  Fix: Use agent.stream() for streaming. Pass checkpointer= for persistence. Set LANGSMITH_TRACING=true for tracing.
• gotcha LLMs trained before mid-2025 have no knowledge of deepagents. Will hallucinate LangChain agent patterns or generic ReAct agents instead.
  Fix: Always use create_deep_agent() from deepagents — not langchain's create_react_agent or create_tool_calling_agent.
• breaking The `deepagents` library requires Python 3.11 or higher. Installation will fail with a 'No matching distribution found' error on older Python versions.
  Fix: Upgrade your Python environment to 3.11 or newer to install `deepagents`.
• breaking When using OpenAI models (e.g., 'openai:gpt-4o'), the OPENAI_API_KEY environment variable or `api_key` parameter must be set. Fails with openai.OpenAIError if not provided.
  Fix: Set the OPENAI_API_KEY environment variable or pass `api_key` to `init_chat_model` (e.g., `init_chat_model('openai:gpt-4o', api_key='your_key')`).

Install

• pip install deepagents Python (SDK)
• pip install deepagents langchain-openai Python (SDK + OpenAI)

Imports

• create_deep_agent
  wrong:

  from deepagents import create_deep_agent
  
  agent = create_deep_agent()
  result = agent.invoke('Research LangGraph')  # wrong — not a plain string

  correct:

  from deepagents import create_deep_agent
  from langchain.chat_models import init_chat_model
  
  # Custom model
  model = init_chat_model('openai:gpt-4o')
  agent = create_deep_agent(
      model=model,
      tools=[],
      system_prompt='You are a research assistant.'
  )
  
  # invoke with messages dict — not plain string
  result = agent.invoke({
      'messages': [{'role': 'user', 'content': 'Research LangGraph'}]
  })
  print(result['messages'][-1].content)

  create_deep_agent returns a compiled LangGraph graph. invoke() takes a dict with 'messages' key, not a plain string. Response is also a dict — access result['messages'][-1].content for final answer.

Quickstart

Minimal deepagents agent with OpenAI model.

# pip install deepagents langchain-openai
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

model = init_chat_model('openai:gpt-4o')

agent = create_deep_agent(
    model=model,
    system_prompt='You are a helpful research assistant.'
)

result = agent.invoke({
    'messages': [{
        'role': 'user',
        'content': 'Write a short summary of what LangGraph is'
    }]
})

print(result['messages'][-1].content)