Structured output

Structured output asks an agent to return predefined fields for extraction, classification, and downstream processing. Pass a Pydantic model class to output_schema to provide structural constraints. Applications must still validate responses and handle empty output, invalid formats, and unmet business rules

Define a schema and create an agent

Complete installation and model configuration and select a model that supports structured output. This example uses Literal to constrain categories and priorities; listing values in a field description alone does not enforce them

ticket.py

import asyncio
from typing import Literal
from pydantic import BaseModel, Field, ValidationError
from veadk import Agent, Runner

class Ticket(BaseModel):
    summary: str = Field(description="A one-sentence summary of the issue")
    category: Literal["billing", "bug", "feature_request", "other"]
    priority: Literal["low", "medium", "high"]

agent = Agent(
    name="ticket_extractor",
    instruction="Extract one support ticket from the user's message.",
    output_schema=Ticket,
)

async def main():
    raw = await Runner(agent=agent, app_name="structured_output").run(
        messages="The billing page crashes every time I open it. Please fix it urgently.",
        session_id="ticket-demo",
    )
    try:
        ticket = Ticket.model_validate_json(raw)
    except ValidationError:
        print("The response is not a valid ticket. Do not save it as a completed record.")
        return
    print(ticket.model_dump_json(indent=2))

if __name__ == "__main__":
    asyncio.run(main())

Parse the response

Run python ticket.py. A successful result resembles this JSON; wording and classification can vary:

{
  "summary": "The billing page crashes whenever it is opened",
  "category": "bug",
  "priority": "high"
}

Runner.run returns text, not a Ticket instance. Ticket.model_validate_json(raw) parses JSON and validates fields. The example handles validation failures, not model request exceptions. Production applications should distinguish request failures from invalid results and also check business rules, such as whether a ticket contains enough information

Parameter	Type	Default	Description
`output_schema`	Pydantic model class	`None`	Structure of the final response; pass `Ticket`, not `Ticket()`
`output_key`	`str \| None`	`None`	Stores the final result in session state; ADK parses and validates it when a schema is configured
`enable_responses`	`bool`	`False`	Uses the Volcengine Ark Responses API
`enable_responses_cache`	`bool`	`True`	Controls Responses caching; explicitly disabled in the structured output example

Use native Ark structured output

Both the model and endpoint must support the Ark Responses API and JSON Schema. Replace the agent definition above with:

agent = Agent(
    name="ticket_extractor",
    instruction="Extract one support ticket from the user's message.",
    output_schema=Ticket,
    enable_responses=True,
    enable_responses_cache=False,
)

VeADK converts the schema to the Responses API json_schema format with strict: true. Accepted schemas and supported constraints depend on the model and service. This does not guarantee successful requests or factually correct business data Responses caching has compatibility restrictions with structured output. VeADK removes conflicting cache settings from relevant requests. Setting enable_responses_cache=False makes this choice explicit. See Responses API for other settings

Tool and runtime limitations

Use the default adk runtime; configuring output_schema with codex or piagent fails
Google ADK 2.2 supports output_schema alongside tools, applying structure to the final response; verify tool and transfer compatibility with your model, API, and ADK version
To separate tool work from extraction, complete retrieval or tool tasks first, then use a dedicated structured-output agent to produce the final record

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Define a schema and create an agent

Parse the response

Use native Ark structured output

Tool and runtime limitations

​Define a schema and create an agent

​Parse the response

​Use native Ark structured output

​Tool and runtime limitations

Define a schema and create an agent

Parse the response

Use native Ark structured output

Tool and runtime limitations