docs(agent): agent protocol RFC (POST /messages, sessions, SSE streaming)

[mmabrouk]

What

Adds the normative protocol spec for the agent chat interface as a new RFC document:
docs/design/agent-workflows/agent-protocol-rfc.md. This PR contains only that file.

It specifies a new endpoint, POST /messages, that sits next to the existing workflow
/invoke (which does not change). The spec covers:

• Sessions. An optional session_id in the request and response body, with normative
  resolution rules (mint / create-with-id / resume) scoped to (project_id, session_id).
• Streaming. A Server-Sent Events response in the Vercel AI SDK v5/v6 "UI Message Stream"
  format, so the frontend consumes it with useChat directly. Includes the part registry,
  the mapping from our internal AgentEvents to Vercel parts, headers, framing, and a full
  example transcript.
• Inputs. The conversation as a first-class data.messages (UIMessage shape), plus
  named variables in data.inputs.
• POST /load-session. Returns a session's history so the client can rebuild the UI.

Written IETF-style (RFC 2119 keywords, message formats, sequence diagrams) so a frontend or
backend engineer can build against it directly.

Why

The current single request/response /invoke cannot stream an agent's work or hold a
multi-turn conversation server-side. This RFC defines the contract for both, additively,
without touching /invoke.

Notes

• Draft, for review.
• Docs only. No code changes.
• The companion design doc (rationale and trade-offs), referenced as streaming-and-sessions.md,
  lands separately. Its relative link resolves once that doc is in the tree.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 18, 2026 3:13pm

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 3b9c5637-4bad-4cdb-aac6-d3942fe0f96f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agent-protocol-rfc

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}