feat(sdk): improve system prompt configurability

[ccurme (ccurme)]

We introduce a minimal structured representation of the base system prompt and widen the type for system_prompt in create_deep_agent to allow users to specify it:

class SystemPromptConfig(TypedDict, total=False):
    prefix: str | SystemMessage | None   # before base
    base: str | SystemMessage | None      # omitted --> built-in base prompt
    suffix: str | SystemMessage | None    # after base


def create_deep_agent(
    ...,
    system_prompt: str | SystemMessage | SystemPromptConfig | None = None,
    ...,
): ...

Usage patterns:

create_deep_agent(...)  # keep default base (unchanged)

create_deep_agent(..., system_prompt="...")  # prepends default base (unchanged)

create_deep_agent(..., system_prompt={"base": "..."})  # overwrites default base (new)

create_deep_agent(..., system_prompt={"base": None})  # no system prompt except from middleware

create_deep_agent(..., system_prompt={"prefix": "...", "suffix": "..."})  # sandwiches the default base prompt

The primary motivation here is to let users modify the base prompt BASE_AGENT_PROMPT = """You are a deep agent..., which is currently fixed:

• It contains statements around identity that may not hold for all applications (e.g., “You are a deep agent”)
• It includes some guidance that may not be appropriate in all situations (e.g., asking for clarification)

We also expose a rendering function render_system_prompt which takes a SystemPromptConfig and builds the prompt. We use this in deepagents-code to clean up regex parsing that was used to modify the ### Model Identity section of the prompt during model switches. We can now build it into "suffix" (or "prefix" if desired) and assemble the prompt. This ends up moving the location of the ### Model Identity section.
^ deferring this

[codspeed-hq]

Merging this PR will not alter performance

✅ 21 untouched benchmarks
⏩ 79 skipped benchmarks¹

---

_{Comparing cc/system-prompt-config (8a0007e) with main (de2f7d2)}

Footnotes

1. 79 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace