# Kedi A2A Structured Output Extension v1

**Extension URI:**
`https://docs.kedi-lang.org/a2a/extensions/structured-output/v1/`

This optional A2A extension lets a Kedi client request a JSON-Schema result from
a Kedi-served agent. Generic A2A text invocation remains unchanged.

## Agent Card Declaration

An implementation supporting per-request schemas advertises an
`AgentExtension` with the extension URI and these parameters:

```json
{
  "version": 1,
  "mode": "request-schema",
  "schemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "maxSchemaBytes": 32768,
  "resultArtifactName": "kedi-structured-output",
  "schemaEncodings": ["json-utf8", "protobuf-value"],
  "resultEncodings": ["json-utf8", "protobuf-value"]
}
```

Clients accept `mode` values `fixed` and `request-schema`. Kedi's v1 server
publishes `request-schema`. The extension is optional for raw text requests.

## Request

For a structured request, the client must:

1. include the extension URI in `Message.extensions`;
2. request the `application/json` output mode; and
3. place this object in `SendMessageRequest.metadata`:

```json
{
  "kediStructuredOutput": {
    "version": 1,
    "resultEncoding": "json-utf8",
    "schemaJson": "{\"type\":\"object\",\"properties\":{\"answer\":{\"type\":\"string\"}},\"required\":[\"answer\"],\"additionalProperties\":false}",
    "schema": {
      "type": "object",
      "properties": {
        "answer": {"type": "string"}
      },
      "required": ["answer"],
      "additionalProperties": false
    }
  }
}
```

`schemaJson` is the authoritative JSON document when present. Unlike numeric
values inside protobuf `Struct`, a JSON string preserves integer constraints
and enum values larger than `2**53`. The `schema` object is a legacy fallback;
Kedi includes it only when its numbers can pass through protobuf doubles
without changing their values. Invalid `schemaJson` never falls back to `schema`.
Requests with only the legacy `schema` object remain supported.

The UTF-8 JSON encoding of the schema must not exceed the advertised limit.
Kedi validates the schema before invoking the served adapter. Remote `$ref` and
`$id` resolution are unsupported, schema nesting is bounded, and invalid
schemas fail the task rather than reaching a model.

## Successful Result

The completed task contains one final artifact with:

- name `kedi-structured-output`;
- the extension URI in `Artifact.extensions`;
- media type `application/json`; and
- for `resultEncoding: json-utf8`, one `raw` part containing the UTF-8 JSON
  document that validates against the request schema. JSONRPC represents the
  bytes as base64, not as free-form model text.

Kedi clients request `json-utf8`. This preserves nested integer and floating-point
types, including large integer identifiers, across streaming, task retrieval,
and persisted results. It does not coerce floats into integers or relax capture
validation. Non-finite numbers and malformed JSON are rejected.

When `resultEncoding` is absent or `protobuf-value`, the server uses the legacy
data part. It rejects results that would lose numeric value in this encoding.
Legacy protobuf results do not preserve the distinction between `78` and `78.0`;
both peers must support `json-utf8` for lossless typed results. Updated clients
still read legacy data parts. If both forms are present in one artifact, the
raw JSON part takes precedence, and malformed raw JSON cannot fall back to data.

The server validates the result before completing the task. The client validates
it again before assigning Kedi captures. Progress data, unrelated artifacts,
and plain text are never interpreted as the typed result.

## Failure Behavior

- A structured request to a peer that does not advertise the extension fails
  before the task is sent.
- A missing, malformed, oversized, wrongly named, or schema-invalid result fails
  without partial capture assignment.
- The extension does not authorize tools, transfer local configuration, or
  imply support for Kedi artifacts.
- v1 does not define repair-model retries, partial structured fields, remote
  schema references, or usage/cost accounting.

The task and context lifecycle otherwise follows A2A v1 semantics.