Skip to content

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:

{
  "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:
{
  "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.