What causes "Agent initialization failed" in langchain-ai/deepagents?

Inspect your `agent_factory` and ensure it always returns a compiled agent (never None) for every `AgentSessionContext`

langchain-ai/deepagents · critical · RuntimeError

Agent initialization failed

Error message

Agent initialization failed

What it means

`ServerConnection.prompt` raises this RuntimeError when, after attempting to reset/create the agent for the session, `self._agent` is still None. The agent is produced by the user-supplied `_agent_factory`; a factory that returns None (or a reset that never assigns) leaves the server unable to serve any prompt. It is a defensive guard, so hitting it means the configured agent factory is broken or incompatible.

Source

Thrown at libs/acp/deepagents_acp/server.py:966

            TextContentBlock
            | ImageContentBlock
            | AudioContentBlock
            | ResourceContentBlock
            | EmbeddedResourceContentBlock
        ],
        session_id: str,
        message_id: str | None = None,  # noqa: ARG002  # ACP protocol interface parameter
        **kwargs: Any,  # noqa: ARG002  # ACP protocol interface parameter
    ) -> PromptResponse:
        """Process a user prompt and stream the agent response."""
        if self._agent is None or (
            self._agent_session_id is not None and self._agent_session_id != session_id
        ):
            self._reset_agent(session_id)

        if self._agent is None:
            msg = "Agent initialization failed"
            raise RuntimeError(msg)

        if getattr(self._agent, "checkpointer", None) is None:
            self._agent.checkpointer = MemorySaver()  # Guarded by getattr check above
        agent = self._agent

        # Reset cancellation flag for new prompt
        self._cancelled = False

        # Convert ACP content blocks to LangChain multimodal content format
        content_blocks = []

        for block in prompt:
            if isinstance(block, TextContentBlock):
                content_blocks.extend(convert_text_block_to_content_blocks(block))
            elif isinstance(block, ImageContentBlock):
                content_blocks.extend(convert_image_block_to_content_blocks(block))
            elif isinstance(block, AudioContentBlock):
                content_blocks.extend(convert_audio_block_to_content_blocks(block))

View on GitHub (pinned to a1af029e6e)

Solutions

Inspect your `agent_factory` and ensure it always returns a compiled agent (never None) for every `AgentSessionContext`
Wrap factory internals so exceptions propagate instead of being caught and falling through to a None return
Verify the object passed as the factory is actually callable returning an agent, not the agent itself (a bare CompiledStateGraph is accepted directly)
Reproduce with a minimal script: construct the server with your factory, call `_reset_agent('test')`, and print the returned agent to confirm it is non-None

Example fix

# before
server = ACPServerConnection(agent_factory=lambda ctx: None)
# after
def make_agent(ctx: AgentSessionContext):
    return create_deep_agent(model=my_model, tools=[...])
server = ACPServerConnection(agent_factory=make_agent)

Defensive patterns

Strategy: validation

Validate before calling

agent = agent_factory(ctx)
if agent is None:
    raise RuntimeError("agent_factory must return an agent, got None")
assert callable(getattr(agent, "ainvoke", None)) or isinstance(agent, CompiledStateGraph)

Type guard

def is_agent(obj: object) -> bool:
    return obj is not None and (callable(getattr(obj, "astream", None)) or hasattr(obj, "ainvoke"))

Try / catch

try:
    resp = await conn.prompt(blocks, session_id)
except RuntimeError as exc:
    if "Agent initialization failed" in str(exc):
        logging.exception("ACP agent factory returned no agent; check agent_factory")
    raise

Prevention

Always return a real agent from agent_factory — never None on any code path
Test the factory in isolation: assert it returns a non-None agent for a representative AgentSessionContext
Let exceptions from factory internals propagate instead of swallowing them
Reuse the factory example from the ACP docs/server tests rather than hand-rolling one

When it happens

Trigger: Calling `prompt()` on an ACP server connection where `_reset_agent(session_id)` (libs/acp/deepagents_acp/server.py:962) left `self._agent` as None — typically because the `agent_factory` callable returned None instead of a LangGraph/DeepAgent instance, or the factory was misconfigured so no agent was ever constructed.

Common situations: Passing `lambda ctx: None` or a factory with a broken return path when constructing the ACP server; a factory that swallows exceptions and returns None; using an agent object type the reset logic doesn't handle so re-initialization silently fails; reusing a session id after `_forget_session` cleared `_agent` and the factory no longer rebuilds it.

Related errors

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/05b331d9bc67f3ff. Report an issue: GitHub.