Preserve full message content from `CompiledSubAgent`

[SP-John]

Problem

When a CompiledSubAgent returns structured data alongside its final message (e.g., via additional_kwargs or by setting a ToolMessage.artifact), the upstream _return_command_with_state_update in subagents.py discards everything except .text:

message_text = result["messages"][-1].text.rstrip() if result["messages"][-1].text else ""
return Command(
    update={
        **state_update,
        "messages": [ToolMessage(message_text, tool_call_id=tool_call_id)],
    }
)

This means there is no supported way for a CompiledSubAgent to return structured data to the parent agent through the ToolMessage. The structured_response state key is explicitly excluded via _EXCLUDED_STATE_KEYS, additional_kwargs on the last message are dropped, and -- critically -- if content is a list of standard content blocks rather than a plain string, the non-text blocks are also lost.

LangChain Core's standard content blocks provide a typed, provider-agnostic way to carry structured data alongside text in a single message (e.g., NonStandardContentBlock for application-specific payloads). A CompiledSubAgent could naturally use this:

content = [
    {"type": "text", "text": "Summary of results..."},
    {"type": "non_standard", "value": {"sql": "SELECT ...", "tier": 2, "rows": 14}},
]
return {"messages": [AIMessage(content=content)]}

But because _return_command_with_state_update extracts .text (which flattens to only TextContentBlock entries), the NonStandardContentBlock is silently discarded.

The docs say:

The structured object itself is not returned to the parent agent. When using structured output with subagents, include the structured data in the ToolMessage.

But for CompiledSubAgent, users don't control the ToolMessage construction -- the framework creates it from .text only. The guidance is impossible to follow for compiled subagents, whether using additional_kwargs, artifact, or standard content blocks.

Use case

I have a CompiledSubAgent that runs a multi-node LangGraph pipeline. The final node produces a human-readable summary as the message content, plus a structured payload containing intermediate results built across the various nodes. The parent agent needs the summary for conversation, but the API consumer needs the structured payload for other purposes.

Today the only options are:

1. Serialize the structured data into the message text (increases parent context token cost, parent LLM may post-process it).
2. Monkey-patch _build_task_tool to propagate additional_kwargs or artifact (fragile, breaks on upstream changes).

Neither is great.

Requested feature

_return_command_with_state_update should forward the full content from the subagent's last message (preserving content blocks when present) rather than flattening to .text. It should also propagate artifact when the last message carries one. This would let CompiledSubAgent authors use any of LangChain Core's existing mechanisms -- content blocks, artifact, or plain text -- to return structured data alongside a human-readable summary.

Proposed solution

The most aligned fix is to forward the full content value (preserving content blocks when present) rather than flattening to .text. A one-line change in _return_command_with_state_update in deepagents/middleware/subagents.py:

def _return_command_with_state_update(result: dict, tool_call_id: str) -> Command:
    if "messages" not in result:
        error_msg = (
            "CompiledSubAgent must return a state containing a 'messages' key. "
            "Custom StateGraphs used with CompiledSubAgent should include 'messages' "
            "in their state schema to communicate results back to the main agent."
        )
        raise ValueError(error_msg)

    state_update = {k: v for k, v in result.items() if k not in _EXCLUDED_STATE_KEYS}
    last_msg = result["messages"][-1]

    # Forward full content (preserves content blocks) instead of flattening to .text
    raw_content = last_msg.content
    if isinstance(raw_content, str):
        raw_content = raw_content.rstrip()

    # Propagate artifact if the last message carries one
    artifact = getattr(last_msg, "artifact", None)

    return Command(
        update={
            **state_update,
            "messages": [ToolMessage(content=raw_content, tool_call_id=tool_call_id, artifact=artifact)],
        }
    )

Why this works:

• ToolMessage.content already accepts both str and list[dict] (content blocks). This is part of the LangChain Core message contract.
• When content is a plain string (the common case today), behavior is identical to the current code.
• When content is a list of standard content blocks, they are preserved. The parent agent's LLM sees the TextContentBlock entries as text, while NonStandardContentBlock entries survive for programmatic access by API consumers.
• artifact propagation covers the case where a CompiledSubAgent uses ToolMessage as its final message type.

Subagent graph usage (content blocks approach)

The final node in a CompiledSubAgent graph could use standard content blocks:

from langchain_core.messages import AIMessage

return {
    "messages": [AIMessage(content=[
        {"type": "text", "text": "inf_member -- Tier 2 (Guided), 14 rows\n\nSQL:\n..."},
        {"type": "non_standard", "value": {
            "sql": "SELECT state, COUNT(*) ...",
            "confidence_tier": 2,
            "data": [{"state": "CA", "count": 5}, ...],
            "columns": ["state", "count"],
        }},
    ])],
}

Or use artifact on a ToolMessage:

from langchain_core.messages import ToolMessage

return {
    "messages": [ToolMessage(content=summary, artifact=structured_payload, tool_call_id=...)],
}

Or continue using a plain string content (existing behavior, no change needed):

from langchain_core.messages import AIMessage

return {
    "messages": [AIMessage(content="Just a text summary, no structured data.")],
}

All three patterns would work with the proposed change.

Additional context

• Related forum discussion: https://forum.langchain.com/t/preventing-sub-agents-structured-output-post-processing-in-a-deep-agent/2824
• Related forum discussion: https://forum.langchain.com/t/can-subagents-in-deepagents-output-structured-response/2237
• The _EXCLUDED_STATE_KEYS comment in the source explicitly calls out that structured_response has "no clear meaning for returning them from a subagent to the main agent" -- but both ToolMessage.artifact and standard content blocks are well-defined mechanisms in LangChain Core that already exist and would be natural fits here.
• ToolMessage.artifact is documented in LangChain Core and is already used by tools that need to return data that shouldn't be sent to the model but should be available to downstream code.
• Standard content blocks (https://docs.langchain.com/oss/python/langchain/messages#standard-content-blocks) provide a typed, provider-agnostic way to carry structured data alongside text in message content. NonStandardContentBlock is specifically designed as an escape hatch for application-specific payloads. Forwarding full content instead of .text would make CompiledSubAgent consistent with how content blocks work everywhere else in LangChain.

Checked other resources

• This is a feature request, not a bug report.
• I searched existing issues and didn't find this feature.
• I checked the docs and README for existing functionality.
• This request applies to this repo (deepagents) and not an external package.

Area (Required)

• deepagents (SDK)
• cli

Feature description

Problem

When a CompiledSubAgent returns structured data alongside its final message (e.g., via additional_kwargs or by setting a ToolMessage.artifact), the upstream _return_command_with_state_update in subagents.py discards everything except .text:

message_text = result["messages"][-1].text.rstrip() if result["messages"][-1].text else ""
return Command(
    update={
        **state_update,
        "messages": [ToolMessage(message_text, tool_call_id=tool_call_id)],
    }
)

This means there is no supported way for a CompiledSubAgent to return structured data to the parent agent through the ToolMessage. The structured_response state key is explicitly excluded via _EXCLUDED_STATE_KEYS, and additional_kwargs on the last message are dropped.

The docs say:

The structured object itself is not returned to the parent agent. When using structured output with subagents, include the structured data in the ToolMessage.

But for CompiledSubAgent, users don't control the ToolMessage construction -- the framework creates it from .text only. The guidance is impossible to follow for compiled subagents.

Use case

I have a CompiledSubAgent that runs a multi-node LangGraph pipeline. The final node produces a human-readable summary as the message content, plus a structured payload containing various intermediate elements that I want to expose to additional tooling. The parent agent needs the summary for conversation, but the API consumer needs the structured payload for other purposes.

Today the only options are:

1. Serialize the structured data into the message text (increases parent context token cost, parent LLM may post-process it).
2. Monkey-patch _build_task_tool to propagate additional_kwargs or artifact (fragile, breaks on upstream changes).

Neither is great.

Requested feature

Allow CompiledSubAgent results to carry structured data through to the parent agent via ToolMessage.artifact. Specifically, _return_command_with_state_update should propagate the last message's artifact (if it's a ToolMessage) or additional_kwargs (if it's an AIMessage) onto the ToolMessage it constructs.

Proposed solution (optional)

A minimal change to _return_command_with_state_update in deepagents/middleware/subagents.py:

def _return_command_with_state_update(result: dict, tool_call_id: str) -> Command:
    if "messages" not in result:
        error_msg = (
            "CompiledSubAgent must return a state containing a 'messages' key. "
            "Custom StateGraphs used with CompiledSubAgent should include 'messages' "
            "in their state schema to communicate results back to the main agent."
        )
        raise ValueError(error_msg)

    state_update = {k: v for k, v in result.items() if k not in _EXCLUDED_STATE_KEYS}
    last_msg = result["messages"][-1]
    message_text = last_msg.text.rstrip() if last_msg.text else ""

    # Propagate structured artifact from subagent's final message
    artifact = None
    if hasattr(last_msg, "artifact") and last_msg.artifact is not None:
        artifact = last_msg.artifact
    elif hasattr(last_msg, "additional_kwargs"):
        artifact = last_msg.additional_kwargs.get("response_payload")

    return Command(
        update={
            **state_update,
            "messages": [ToolMessage(message_text, tool_call_id=tool_call_id, artifact=artifact)],
        }
    )

Alternatively, a more general approach: forward whatever artifact the last message has, regardless of the key name. This would let any CompiledSubAgent return structured data by setting artifact on a ToolMessage as the last message in its state:

artifact = getattr(last_msg, "artifact", None)

This is backward-compatible -- existing subagents that don't set artifact would produce ToolMessage(..., artifact=None), which is the current behavior.

Subagent graph usage

On the CompiledSubAgent side, the final node would return:

from langchain_core.messages import ToolMessage

return {
    "messages": [ToolMessage(content=summary, artifact=structured_payload, tool_call_id=...)],
}

Or, if the graph uses AIMessage (more natural for a final response node):

from langchain_core.messages import AIMessage

return {
    "messages": [AIMessage(content=summary, additional_kwargs={"response_payload": structured_payload})],
}

Either pattern would be supported by the proposed change.

Additional context (optional)

• Related forum discussion: https://forum.langchain.com/t/preventing-sub-agents-structured-output-post-processing-in-a-deep-agent/2824
• Related forum discussion: https://forum.langchain.com/t/can-subagents-in-deepagents-output-structured-response/2237
• The _EXCLUDED_STATE_KEYS comment in the source explicitly calls out that structured_response has "no clear meaning for returning them from a subagent to the main agent" -- but artifact propagation on ToolMessage is a well-defined mechanism in LangChain Core that already exists and would be the natural fit here.
• ToolMessage.artifact is documented in LangChain Core and is already used by tools that need to return data that shouldn't be sent to the model but should be available to downstream code.

[pc099]

Hey, SP-John can you assign this to me ?

[eyurtsev]

The convention right now is that the subagent must end its turn with an AIMessage rather than a ToolMessage.

If we propagated the content blocks from the AIMessage fully to the ToolMessage does that fix your use case?

(i.e., there won't be any artifacts)

---

Also could you explain your use case? What are you trying to do? Would be very helpful to figure out an appropriate solution

[SP-John]

The convention right now is that the subagent must end its turn with an AIMessage rather than a ToolMessage.

If we propagated the content blocks from the AIMessage fully to the ToolMessage does that fix your use case?

(i.e., there won't be any artifacts)

Also could you explain your use case? What are you trying to do? Would be very helpful to figure out an appropriate solution

Yes -- propagating the full AIMessage.content (including content blocks) to the ToolMessage would completely fix this. No artifact needed.

Use case

I have a CompiledSubAgent that wraps a multi-node LangGraph pipeline for document analysis. The pipeline does: intake -> classification -> entity extraction -> cross-referencing -> summary generation -> response formatting.

The final node needs to return two things:

1. A human-readable summary for the parent agent to use in conversation (e.g., "Found 3 relevant contracts matching your criteria, here are the key terms...").
2. A structured payload for API consumers to render rich UI -- extracted entities, source document references, classification labels, relevance scores, and page citations.

The parent LLM only needs the summary to continue the conversation. But downstream consumers (a frontend hitting the /threads/{id}/runs/wait endpoint) need the structured payload to render source cards, highlight cited passages, display classification tags, etc. The structured data should travel alongside the summary without being sent to the parent LLM's context.

What this looks like today vs. what content block propagation would enable

Today (workaround): I monkey-patch _build_task_tool to extract additional_kwargs["response_payload"] from the last AIMessage and pass it as ToolMessage.artifact. It works, but it's fragile.

With content block propagation, the final node would return:

return {
    "messages": [AIMessage(content=[
        {"type": "text", "text": summary},
        {"type": "non_standard", "value": {
            "entities": [{"name": "Acme Corp", "type": "organization", "mentions": 12}],
            "sources": [{"doc_id": "doc_7a3f", "page": 4, "relevance": 0.94}],
            "classification": "contract_amendment",
            "confidence": 0.91,
        }},
    ])],
}

The TextContentBlock would be sent to the parent LLM as the tool result text. The NonStandardContentBlock would be preserved in the ToolMessage.content list for API consumers to access programmatically, without inflating the parent's context or being post-processed by the parent LLM.

That would be a clean, no-patch solution.

[eyurtsev]

The NonStandardContentBlock would be preserved in the ToolMessage.content list for API consumers to access programmatically, without inflating the parent's context or being post-processed by the parent LLM.

Got it. End-goal is really to access everything programmatically, not to expose to the main agent

[SP-John]

Got it. End-goal is really to access everything programmatically, not to expose to the main agent

That's exactly right! Thanks for taking the time to ask clarifying questions. Let me know if there's anything else I can provide!