agent-control-channels

Agent control channels

The one rule

When the model must signal a structured decision to the host, that signal goes through a native structured channel — a tool call for actions/control, or a strict structured response schema for pure data that the app will render. It is not a marker or prompt-only JSON object the model types into its reply.

A typed marker (an XML-ish tag, a sentinel string, <<QUIET_RUN>>, a magic word) fails three ways at once:

• It leaks. Anything the model types into its reply is part of the reply. It streams to the user verbatim. "Why is it leaking?" is the symptom; the typed marker is the cause.
• It's emitted unreliably. The model stutters it, half-types it, rewords it, or wraps it in prose — because it's just more text being sampled, with no schema holding its shape.
• It forces brittle recovery. The host now regex-scrapes the prose to recover intent (extractXFromParts). That parser is permanently chasing the model's phrasing.

A tool call has none of these: it's a separate structured field, schema-validated, never rendered into the user-facing transcript, and reliably shaped because the API constrains it. The model invoking archive() cannot accidentally show the user the word "archive."

Prompt-only JSON is the same smell

Return only JSON is not a control channel. It is prose with braces. It is acceptable only as a fallback when the provider or runtime truly lacks tool calls and structured outputs.

For a menu, routing choice, suggested action list, app mode, or other host-consumed payload:

• use a tool/function call when the model is choosing an app action, changing state, invoking code, or handing the host a command;
• use a strict structured response schema when the model is only returning data that will be rendered, such as a UI card, menu, or explanation parts;
• keep the host parser as schema validation, not recovery from a natural-language prompt contract.

Do not ship a prompt that says "return only JSON" while the host JSONDecoders or JSON.parses the assistant text when the runtime supports one of those native channels.