> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/productions/veadk/preview/en/get-started/quickstart) 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

```python ticket.py lines theme={null}
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:

```json lines theme={null}
{
  "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:

```python lines theme={null}
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](/productions/veadk/preview/en/components/agent/model#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