Skip to content

finding: serve-over-http never says message is string-only, so block input looks supported #246

Description

@sagi5060

Problem

guides/serve-over-http.mdx shows only a string message and never says a string is all the surface
takes. The Python API documents richer input on the same underlying methods, so a reader reasonably
expects parity and gets a 422:

$ curl -X POST .../agents/HandoverBot/chat \
  -d '{"session_id":"s1","message":[{"type":"text","text":"hi"}]}'
422  {"detail": "message must be a string, got list"}

Meanwhile reference/deck.mdx lists TextBlock/ImageBlock/AudioBlock/DataBlock/ResourceBlock
under What input accepts for run/stream — the methods the HTTP route calls. A clean-room
reviewer recorded parity as an explicit expectation during recon and found the gap only by testing it.

Proof of absence:

$ grep -rni "content.block\|ImageBlock\|content_blocks" docs/ README.md
docs/reference/deck.mdx: (3 hits)

Nothing in guides/serve-over-http.mdx.

The behavior itself is correct and deliberate — the v1 chat body is exactly {"session_id", "message"},
frozen byte-for-byte by tests/golden/ (see #227). This is the docs half only: images and audio are
Python-API-only, and the guide should say so where someone plans an integration rather than leaving it
to a 422.

Proposed shape

One short subsection in guides/serve-over-http.mdx, next to the first chat example:

### What the wire accepts

`message` is a string. The packaged surface is the frozen v1 body — `{"session_id", "message"}` —
so the content blocks the Python API accepts (`ImageBlock`, `AudioBlock`, ...) do not cross it, and
a list is refused with `422 message must be a string`. An application that needs rich input calls
`deck.run()` / `deck.stream()` from its own route.

And a matching line in reference/deck.mdx where the block list is introduced, saying which of those
blocks reach the packaged HTTP surface (none) — the page currently qualifies the list for the engine
but not for the wire.

Out of scope: changing the wire (frozen) and the design question of what asgi() is for (#227).

Notes

Done when

  • guides/serve-over-http.mdx states message is string-only and why, naming the 422
  • It points an application needing rich input at its own route over deck.run/deck.stream
  • reference/deck.mdx's block list says which blocks reach the packaged HTTP surface
  • No behavior change; tests/golden/ untouched

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsTouches docsfindingAn observation that needs attention and a deeper look — not yet a bug, not yet a plangood first issueGood for newcomers

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions