Add RFD: Streamable HTTP & WebSocket Transport

[alexhancock]

Adding an RFD for a streamable HTTP and websocket transport

[alexhancock]

cc @jh-block @benbrandt

[alpgul]

A project has already been developed for this feature, and I believe it would be better to keep it as a separate project to avoid increasing code maintenance overhead.

[agentcooper]

From what I understand Acp-Session-Id here is a transport specific ID. It is a confusing name because ACP session ID is expected to be created later on session/new (https://agentclientprotocol.com/protocol/session-setup#session-id).

[alexhancock]

This is a good point, thanks for catching.

Do you think it's sane to drop the transport specific id and have no Acp-Session-Id included in requests unless a session/new has been performed? Also interested in alternative resolutions.

[mikhailshilkov]

unless a session/new has been performed

session/prompt has a session_id parameter in its request, which seems to be a separate session ID (actual session ID, not tranport ID). It has to be different from Acp-Session-Id because the same Acp-Session-Id can call session/new multiple times, if I understand it correctly. I'm not sure how exactly Acp-Session-Id is supposed to be used in the proposal.

[anna239]

Do you think it's sane to drop the transport specific id and have no Acp-Session-Id included in requests

This won't work, as capabilities defined during the initialize phase, so when the client sends their session/new request, the server should know which this Session id. But I agree that the name is confusing here.

[anna239]

@alexhancock do I understand it correctly that you suggest opening multiple SSE (first on initialize request, then on session/new and then on session/prompt)? When are those streams closed and how does the agent decide which stream does some update belong to?

[alexhancock]

@alexhancock do I understand it correctly that you suggest opening multiple SSE (first on initialize request, then on session/new and then on session/prompt)?

Intent is to follow the request patterns of MCP's streamable http transport https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#sending-messages-to-the-server. From that spec:

"Every JSON-RPC message sent from the client MUST be a new HTTP POST request to the MCP endpoint"

When are those streams closed

"After all JSON-RPC responses have been sent, the server SHOULD close the SSE stream."

how does the agent decide which stream does some update belong to?

I don't have a perfect answer to this off the top of my head, but it likely relates to the discussion here about session ids.

Should there perhaps be a session id which only corresponds to the concept of ACP Session ID (nothing transport level) and then a request id to correspond to one client request within a session?

Open to ideas!

[anna239]

@alexhancock

"After all JSON-RPC responses have been sent, the server SHOULD close the SSE stream."

does it mean, that f.i. the first SSE stream that was opened for initialize request will be closed once initialize response is streamed? I think this won't work as the agent can send some data to the client after initialize response but before session/new is called

[alexhancock]

@alexhancock

"After all JSON-RPC responses have been sent, the server SHOULD close the SSE stream."

does it mean, that f.i. the first SSE stream that was opened for initialize request will be closed once initialize response is streamed? I think this won't work as the agent can send some data to the client after initialize response but before session/new is called

The way I had been thinking about it, each SSE stream opened by a POST request closes after its response is sent. But the agent can still reach the client between requests using a dedicated GET listener stream, similar to this part of MCP's specification of its streamable HTTP transport (https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#listening-for-messages-from-the-server)

The client MAY issue an HTTP GET to the MCP endpoint. This can be used to open an SSE stream, allowing the server to communicate to the client, without the client first sending data via HTTP POST.

For the specific case you mentioned, if the agent needs to send data after initialize but before session/new, the client could receive this if it has the GET-initiated listener stream open. The server would send messages on that stream, not on the POST-initiated stream from the initialize request.

However, I'm wondering if we should consider a simpler alternative that's more aligned with idiomatic SSE usage:

Option 1 (current proposal): Multiple streams as described above and in the current draft of the RFD

• Request-scoped POST streams that close after response
• Optional GET listener stream for out-of-band messages
• Follows MCP's pattern closely

Option 2 (alternative): Single long-lived stream

• Client opens one GET stream at session start, keeps it open
• ALL server→client messages flow on this stream
• POSTs return 202 Accepted and close their response instead of opening streams
• Simpler mental model, more idiomatic SSE

The second option would be a deviation from MCP's spec, but might be better suited to ACP's more bidirectional nature and the high volume of notifications from long-running prompts. It would also naturally solve the concern you raised about messages between requests. This option would likely need to rely more heavily on cookie-based session affinity.

I'm curious what you and others think - does the multi-stream approach make sense for ACP, or would a single long-lived stream be simpler and more practical? Open to ideas and feedback.

Also agree we need to clean up the semantics of Acp-Session-Id generally in this proposal and get to clarity there. Also open to ideas/approaches to that.

[alexhancock]

@agentcooper @mikhailshilkov @anna239

I have pushed a new revision of the doc to address feedback.

1. It now proposes two concepts, an Acp-Connection-Id header to model a client/server connection that has been initialized with capabilities per this discussion.
2. It clarifies how streams will work (both per POST and single session specific long-running GET) per this discussion.

I would really like opinions/feedback on these resolutions to the original issues from the first draft, and any alternative ideas if you see opportunities to improve the proposal. Thank you!

cc @jh-block @benbrandt @DOsinga

[anna239]

@alexhancock thank you, current proposal looks good! We have some protocol changes we're planning for some time already, they're related to how ACP works with prompt request. We'd like to review those and see if it makes sense to deliver them before HTTP implementation, I'm sorry for the delay, we need several more days for it