[feat] /invoke absorbs /messages + align agent env var names

[junaway]

Context

The agent playground talked to a separate /messages endpoint for its streamed chat, while every other workflow used /invoke. Two endpoints meant two code paths to keep in sync, and /messages carried session/stream/format logic that /invoke lacked. This branch makes /invoke the single agent-capable endpoint so the frontend can drop /messages entirely, and folds in the earlier agent env-var naming cleanup this work sits on.

Changes

/invoke absorbs /messages via three negotiations.

1. Transport. Accept is HTTP sugar over request.flags.stream: text/event-stream negotiates a stream, application/json a batch. A streaming handler aggregates to a batch when a batch is requested instead of returning 406.

2. Message format. x-ag-messages-format: vercel projects the Vercel UI Message Stream on the way out and converts inbound UIMessage[] to canonical agenta messages on the way in. HTTP-only; in code, messages are always agenta.

3. Session. session_id is resolved (echoed, or minted as bare uuid4().hex) once in the normalizer, written onto the request and the trace context, and echoed on every response through the body field, x-ag-session-id, and baggage ag.session.id. Trace/span/session propagation is now symmetric, inbound and outbound.

The agent handler reads request.flags.stream and request.session_id off the request instead of receiving them as injected params. The frontend agent lane (agentRequest.ts) now posts to /invoke directly with the vercel format header and data.inputs.messages, instead of rewriting the URL to /messages.

Frontend request body, before:

{ session_id, references, data: { messages, parameters } }

After:

{ session_id, references, data: { inputs: { messages }, parameters } }
headers: { Accept: text/event-stream, x-ag-messages-format: vercel }

Fixes surfaced while wiring this (verified in a running stack).

• An errored handler returns a batch error response even when a stream was requested. The route now surfaces it as JSON with the real status code instead of a 406 that masked the actual error.
• store_session passed a namespace kwarg that a raw OTel NonRecordingSpan rejects, so it threw on every agent request and session.id never landed on the span. It now falls back to a flat session.id key.
• The session_id read was coupled to the trace/span link parse inside one suppress() block, so a malformed link dropped the session id from the response. The two are now decoupled.

Also in this branch. The earlier agent env-var naming pass (fa1da68): rename the agent feature's own AGENTA_* vars to one scheme, and add AGENTA_AGENT_RUNNER_HOST to the gh compose variants.

Tests / notes

• SDK unit suite green (1026 tests), including a new matrix for the four handler shapes (sync/async x fn/generator), the three negotiations, session-id propagation, and the error-batch-on-stream path.
• Agent service handler tests updated for the new request-based signature.
• Frontend agentRequest unit tests updated to the new envelope and headers (123 playground tests green).
• Stack-verified end to end: a real agent run over /invoke streams when credentialed, and surfaces the runner's real error (not a 406) when not.
• Follow-up not in this PR: hard removal of the /messages route, the vercel/routing.py adapter, and the is_agent gate, once this is merged and the swap is proven in production.

What to QA

• Open the agent playground for an agent workflow and send a message. The conversation streams token by token (now through /invoke, not /messages).
• Send a multi-turn conversation. Prior turns replay correctly and the session id stays stable across turns.
• Regression: trigger a run with a misconfigured model or missing provider key. The panel shows the real error message, not a generic 406 / empty stream.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview, Comment	Jun 26, 2026 11:25am

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

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: 0dc1b4c8-17be-4a49-9df6-3b51d5486b99

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 chore-agent-env-flag-naming

---

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.}

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.