[github-actions]

kagent-dev/kagent#3284 — feat(outputschema): allow format, pattern and type lists, add opt-in outputSchemaStrict

Docs versions: 1.x (first shipped in v1.0.0-rc1)

No code-path rule covers 11 touched file(s). The planner could route these only by identifier search, so the candidate pages may miss what they changed, including in the other mode:

• docs/architecture/structured-output.md
• go/adk/pkg/agent/agent.go
• go/adk/pkg/outputschema/convert.go
• go/adk/pkg/outputschema/gemini.go
• go/adk/pkg/outputschema/pattern.go
• go/adk/pkg/outputschema/strict.go
• ...and 5 more

What changes for users: AgentTemplate structured-output schemas can now use format, RE2 pattern, and type lists such as ["string","null"]. Users can also set spec.outputSchemaStrict: true to ask OpenAI, Azure OpenAI, and Foundry in the OpenAI format to constrain generation to the schema; the default is false.

What the docs now say: The Structured output guide now lists the expanded portable schema profile, explains provider-specific schema handling, adds a strict schema adherence section for outputSchemaStrict, and adds the new schema failure messages to troubleshooting.

Not verified: No cluster in CI; the configuration is unrun and internal links are unchecked.

How kagent-3284 was drafted, and what was not verified

• Code PR: feat(outputschema): allow format, pattern and type lists, add opt-in outputSchemaStrict kagent#3284
• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x, first shipped in v1.0.0-rc1
• Category: scoped-edit / pr

Plan, and what changed it

• Planned: Add outputSchemaStrict, format, pattern, and type-list coverage where structured output is documented.
• Learned: The offered model-provider pages matched incidental apiFormat and maxTokens fields, while docs-site/content/kagent/1.x/agents/structured-output.md owns the outputSchema guide and was found by the required literal-string grep.
• Did: Updated the structured-output guide instead of scattering provider notes across the incidental target pages.

Why a documentation change is necessary

The existing Structured output guide said type accepted only one value and that pattern and format were rejected. The pull request changes that surface: schemas can now use type lists, supported string formats, and RE2 patterns, and users can opt in to provider strict mode with outputSchemaStrict. Without the page update, readers would avoid valid schemas and would not know how to restore strict provider enforcement for OpenAI-family providers.

What changed on disk

docs-site/content/kagent/1.x/agents/structured-output.md — Updated the supported schema profile, added provider handling details, documented outputSchemaStrict, and expanded troubleshooting for strict-mode, pattern, and Gemini schema failures.

How to verify this change

1. In a kagent 1.x cluster with the my-first-harness Harness and an OpenAI, Azure OpenAI, or Foundry ModelConfig, apply an AgentTemplate that sets spec.outputSchemaStrict: true and uses a schema with format: date-time, pattern: ^OPS-[0-9]+$, required, and additionalProperties: false.
2. Run kubectl get agent <agent-name> -n kagent -o json | jq '[.status.conditions[] | select(.type == "Compatible")]'. The Compatible condition should report status: "True".
3. Change the same schema to omit additionalProperties: false, reapply it, and rerun the condition command. The Compatible condition should report UnsupportedConfiguration with a message that starts with outputSchemaStrict:.

Proposed release note

No proposed-release-note.md: markers.notes_placeable is false for this product. Suggested text for a reviewer to reuse: Structured output schemas now accept format, RE2 pattern, and type lists such as ["string","null"]. Set outputSchemaStrict: true on an AgentTemplate to ask OpenAI, Azure OpenAI, and Foundry in the OpenAI format to enforce the schema during generation; the default is false.

What was not verified

• The configuration was not applied to a cluster, so the configuration is unrun.
• Hugo was not run, so internal links are unchecked.

How the pages were chosen (triage report)

Feature clusters

Kept apart on purpose. Merging wrongly produces a guide that documents two things and explains neither, so these are reported for a person to merge rather than grouped automatically:

• feat(outputschema): allow format, pattern and type lists, add opt-in outputSchemaStrict kagent#3284 and fix(substrate): scope Substrate reads and page tokens to the watched namespaces kagent#3261 both have docs-site/content/kagent/1.x/observability/launch-ui.md as a candidate, but for one of them it is one page among more than 3, so they are kept apart; merge them if both drafts do land there

Draft a documentation change

kagent-dev/kagent#3284 — feat(outputschema): allow format, pattern and type lists, add opt-in outputSchemaStrict

• Product: kagent (upstream) → kagent-dev/website
• Docs version: 1.x
• Summary (read from the body): An AgentTemplate outputSchema cannot use format, pattern, or a type list such as ["string","null"]. So a schema cannot ask for an ISO date, a ticket ID like OPS-123, or an optional string. OpenAI follows format and pattern only in strict mode, so this PR also adds outputSchemaStrict.
• Not tested: no cluster was available, so every command in this diff is unrun
• No rule covers 11 touched file(s). The candidate pages below come from the files that DID match a rule, so they may scope this narrower than the change is. Read these before deciding the change is only about the pages listed:
  • docs/architecture/structured-output.md
  • go/adk/pkg/agent/agent.go
  • go/adk/pkg/outputschema/convert.go
  • go/adk/pkg/outputschema/gemini.go
  • go/adk/pkg/outputschema/pattern.go
  • go/adk/pkg/outputschema/strict.go
  • ...and 5 more

Draft branch: pr-tracker-draft-kagent-3284

---

Important

The test suite has not run on this pull request. It was opened by github-actions[bot], and GitHub does not start workflows for pull requests opened with the repository's own token. This repository's checks are held as action_required until somebody presses Approve and run on the Checks tab. Checks that come from GitHub Apps rather than Actions, such as DCO, run on their own.

Please approve the checks before reviewing the content: an absence of failures here means the tests have not run, not that they passed.

[Rachael-Graham]

Covered by #652 (v1.0.0-rc1 docs update).