SystemMessage vs systemPrompt Option
People think SystemMessage holds the system prompt, and it does not. The systemPrompt option is the set of rules the agent gets before your task. SystemMessage is a message the SDK sends back to your code. The first one, init, reports the session ID, the model and the tools. Later ones mark events, such as a chat being squeezed into a summary.
SystemMessage
The message for session events. The first one says how the session was set up.
SystemMessage is the message type for events in a session. Its subtype says which one. init comes first and carries the session ID, the model, the tools and other setup facts. compact_boundary comes after the chat is made shorter. Other subtypes carry short status notes.
systemPrompt Option
The option that sets what the agent is told before any task.
systemPrompt is the Agent SDK option that sets the agent's system prompt. In Python it is system_prompt. Left out, the SDK uses a minimal prompt that covers tool calls and little else. A string replaces it with your own. The claude_code preset loads Claude Code's full prompt, and append adds your lines to the end of it.
In one line
- SystemMessage
- The message for session events. The first one says how the session was set up.
- systemPrompt Option
- The option that sets what the agent is told before any task.