RFD: Client-Provided System Prompt

[wpfleger96]

Proposes adding an optional systemPrompt string field to session/new, giving clients a standard way to provide system-level instructions that agents can deliver to the LLM's system prompt slot.

ACP is currently the only major agent protocol without a dedicated system prompt field — MCP, OpenAI, and Anthropic's Messages API all have one. Every ACP implementation has independently implemented non-standard workarounds: _meta extensions, user-message injection, filesystem indirection. This RFD proposes a single interoperable solution.

• Adds systemPrompt?: string to SessionNewParams — additive, fully backward compatible
• Agents that don't receive the field continue working unchanged
• Mid-session updates deferred to a future session/update_system_prompt method if needed

Motivated by Discussion #414.

[alexhancock]

I think it's good

One bit of feedback that comes to mind: if it is to remain a "SHOULD" for agents to thread it to the llm's system prompt slot, it may be good for the client to know if the agent is ignoring it.

Two solutions:

1. Consider making it a MUST for the agent to attempt to handle it
2. Make some kind of notification or value that comes back on the session/new response indicating to the client whether it is being used with the llm

Number 2 may also be needed for error cases where the system prompt couldn't be inserted into a facility for this on the llm side.

[wpfleger96]

@alexhancock thanks for the feedback! I agree with both and just pushed an update with these changes:

• upgrade from SHOULD to MUST for incorporating the system prompt. I couldn't find any real-world use cases where an ACP agent couldn't/wouldn't honor a system prompt so giving clients a stronger guarantee with MUST feels right here
• add systemPromptStatus field on the session/new response: it returns accepted or rejected (with a reason) so clients know whether their system prompt addition was used or not. This covers the error cases you mentioned and if the client doesn't send a systemPrompt, the field is omitted from the response

[aleclarson]

2. Make some kind of notification or value that comes back on the session/new response indicating to the client whether it is being used with the llm

Number 2 may also be needed for error cases where the system prompt couldn't be inserted into a facility for this on the llm side.

• add systemPromptStatus field on the session/new response: it returns accepted or rejected (with a reason) so clients know whether their system prompt addition was used or not. This covers the error cases you mentioned and if the client doesn't send a systemPrompt, the field is omitted from the response

It seems wrong to have the session created if the systemPrompt option can't be applied. Wouldn't it be better for the agent to respond with an error result instead?

[wpfleger96]

2. Make some kind of notification or value that comes back on the session/new response indicating to the client whether it is being used with the llm
   Number 2 may also be needed for error cases where the system prompt couldn't be inserted into a facility for this on the llm side.

• add systemPromptStatus field on the session/new response: it returns accepted or rejected (with a reason) so clients know whether their system prompt addition was used or not. This covers the error cases you mentioned and if the client doesn't send a systemPrompt, the field is omitted from the response

It seems wrong to have the session created if the systemPrompt option can't be applied. Wouldn't it be better for the agent to respond with an error result instead?

@aleclarson good call, that's a much cleaner design. I just pushed an update that drops systemPromptStatus entirely so if the agent can't apply the system prompt, session/new returns a standard JSON-RPC error and the session isn't created. this avoids an ambiguous middle state where a session exists but without the client's intended instructions. let me know what you think!