Add structured agent output support

[felixarntz]

ACP v2 has no standard way for a Client to ask an Agent to produce output matching a JSON Schema. session/prompt carries the user prompt, while prompt capabilities describe accepted input content types, not the requested output format.

Why this matters

Many harnesses support structured output via a CLI flag, often including support for a JSON schema. In interactive TUI usage of the harnesses, this behavior is typically not supported, but users are increasingly running agent tasks in the cloud, and for many such automated tasks structured output is crucial. And from a technical perspective, many harnesses support structured output even in follow-up turns for existing sessions (including those started interactively).

Our AI SDK HarnessAgent abstraction supports typed output, but the ACP adapter can only implement it through per-Agent metadata mappings. For example, one ACP profile may expect an outputSchema value under _meta, while another may not support the feature at all:

{
  type: 'session-prompt-meta',
  path: ['outputSchema'],
}

This prevents Clients from discovering support or using one interoperable implementation across Agents. It is analogous to the system-prompt gap discussed in #414: a standard request field would remove private adapter mappings.

Proposed shape

Add an optional, capability-gated response format to session/prompt:

{
  "sessionId": "sess_123",
  "prompt": [{ "type": "text", "text": "Summarize the changes." }],
  "responseFormat": {
    "type": "json",
    "name": "summary",
    "schema": {
      "type": "object",
      "properties": {
        "summary": { "type": "string" },
        "risk": { "type": "string", "enum": ["low", "medium", "high"] }
      },
      "required": ["summary", "risk"],
      "additionalProperties": false
    }
  }
}

The Agent would advertise support through the existing v2 capability tree, for example with a session.prompt.responseFormat capability object. Clients would send the field only when the Agent advertises it, so unsupported Agents remain fully compatible.

Because the v2 prompt lifecycle acknowledges prompt acceptance and reports processing through session/update, the proposal should also define how the final structured result is represented and correlated with the turn. It could use existing agent_message content containing serialized JSON, or a dedicated structured-output content variant.

Open questions

• Which JSON Schema dialect and subset should ACP require or advertise?
• Should the format be strictly per-prompt, or should ACP also support a session-level default?
• How should structured output be represented while streaming and replayed through session/update?
• How should an Agent report an unsupported schema, an invalid result, or a turn that ends without satisfying the requested format?
• Should tool calls and intermediate agent messages be allowed before the final structured result?

Harness support

All lists are non-comprehensive and just samples of the ecosystem.

Support for structured output against JSON schema:

• Antigravity
• Claude Code
• Cline
• Codex
• Deep Agents
• Grok Build
• OpenCode

Support for unstructured JSON object output:

• fx (though this will likely support structured output soon too)

No support for JSON output:

• Cursor
• GitHub Copilot
• Pi

Looking for

Feedback on the capability name, schema shape, and output representation. If this direction fits ACP v2, we can draft an RFD and test it against multiple ACP harnesses.