langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-21 20:05:30 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[GH-ISSUE #3734] [deepagents] Document SystemMessage and content_blocks for system_prompt #2754

New Issue
Open
opened 2026-06-05 17:26:38 -04:00 by yindo · 0 comments
yindo commented 2026-06-05 17:26:38 -04:00
Owner
Copy Link
Copy Source

Originally created by @AdemBoukhris457 on GitHub (Apr 25, 2026).
Original GitHub issue: https://github.com/langchain-ai/docs/issues/3734

Type of issue

request for content

Language

Python

Description

Summary

create_deep_agent accepts system_prompt as str | SystemMessage | None, but the Deep Agents documentation only shows string examples. Readers may not know they can pass a @[SystemMessage] with structured content_blocks, or how the library merges that with the built-in base prompt.

Library behavior (reference)

In deepagents graph.py, when system_prompt is a @[SystemMessage], the final system message is built by preserving the caller’s content_blocks and appending a text block that contains the Deep Agents base prompt (after any profile/base assembly). When system_prompt is a string, behavior is simple string concatenation with the base prompt.

Relevant implementation: libs/deepagents/deepagents/graph.py (system prompt assembly before create_agent).

The public create_deep_agent docstring documents the string case (“If a string, it's concatenated…”) but does not describe the SystemMessage / content_blocks path in the same detail.

Documentation gap

Across pages such as customization, overview, streaming, etc., examples use system_prompt="..." or triple-quoted strings only. Missing from user-facing docs:

  • That SystemMessage is a supported type for top-level system_prompt.
  • That structured content_blocks are preserved (not flattened) and the framework base prompt is added as an additional text block.
  • A minimal copy-pastable example (e.g. SystemMessage(content_blocks=[{"type": "text", "text": "..."}])) and when to prefer it over a plain string.

Out of scope / caveats (optional callout in docs)

  • Subagent specs often use string system_prompt fields; clarify in docs where SystemMessage applies (main agent vs subagents) so users do not assume parity everywhere.

Suggested fix

Add a short subsection (for example under Customize Deep Agents or Context engineering) or a Note on the main customization page:

  1. Supported types for system_prompt on @[create_deep_agent].
  2. One Python example using SystemMessage + content_blocks.
  3. One sentence describing merge order: user blocks first, then appended text block with the base deep agent prompt.

Optional: extend the create_deep_agent API docstring in the deepagents repo to describe the SystemMessage branch (can be a separate issue if docs team only tracks this repo).

Acceptance criteria

  • User-facing Deep Agents docs mention SystemMessage as a valid system_prompt type for the main agent.
  • Docs explain that content_blocks are preserved and the base prompt is appended as a text block.
  • At least one example uses SystemMessage / content_blocks (not only strings).
Originally created by @AdemBoukhris457 on GitHub (Apr 25, 2026). Original GitHub issue: https://github.com/langchain-ai/docs/issues/3734 ### Type of issue request for content ### Language Python ### Description ## Summary `create_deep_agent` accepts `system_prompt` as `str | SystemMessage | None`, but the Deep Agents documentation only shows string examples. Readers may not know they can pass a @[`SystemMessage`] with structured `content_blocks`, or how the library merges that with the built-in base prompt. ## Library behavior (reference) In **deepagents** `graph.py`, when `system_prompt` is a @[`SystemMessage`], the final system message is built by **preserving** the caller’s `content_blocks` and **appending** a text block that contains the Deep Agents base prompt (after any profile/base assembly). When `system_prompt` is a string, behavior is simple string concatenation with the base prompt. Relevant implementation: `libs/deepagents/deepagents/graph.py` (system prompt assembly before `create_agent`). The public `create_deep_agent` docstring documents the string case (“If a string, it's concatenated…”) but does not describe the `SystemMessage` / `content_blocks` path in the same detail. ## Documentation gap Across pages such as **customization**, **overview**, **streaming**, etc., examples use `system_prompt="..."` or triple-quoted strings only. Missing from user-facing docs: - That **`SystemMessage`** is a supported type for top-level `system_prompt`. - That **structured `content_blocks`** are preserved (not flattened) and the framework base prompt is added as an additional text block. - A minimal **copy-pastable example** (e.g. `SystemMessage(content_blocks=[{"type": "text", "text": "..."}])`) and when to prefer it over a plain string. ## Out of scope / caveats (optional callout in docs) - **Subagent** specs often use string `system_prompt` fields; clarify in docs where `SystemMessage` applies (main agent vs subagents) so users do not assume parity everywhere. ## Suggested fix Add a short subsection (for example under **Customize Deep Agents** or **Context engineering**) or a **Note** on the main customization page: 1. Supported types for `system_prompt` on @[`create_deep_agent`]. 2. One Python example using `SystemMessage` + `content_blocks`. 3. One sentence describing merge order: user blocks first, then appended text block with the base deep agent prompt. Optional: extend the `create_deep_agent` API docstring in the **deepagents** repo to describe the `SystemMessage` branch (can be a separate issue if docs team only tracks this repo). ## Acceptance criteria - [ ] User-facing Deep Agents docs mention `SystemMessage` as a valid `system_prompt` type for the main agent. - [ ] Docs explain that `content_blocks` are preserved and the base prompt is appended as a text block. - [ ] At least one example uses `SystemMessage` / `content_blocks` (not only strings).
yindo added the externaldeepagents labels 2026-06-05 17:26:38 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label deepagents external
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#2754
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?