Structured Outputs

Contextual AI How-to Guide

Contextual AI supports structured outputs in JSON format. Use structured output mode when responses must follow a consistent, easily parsed format—for example, to extract defined data fields or integrate with downstream applications and workflows.

This feature is currently in beta, with attributions and other capabilities planned for future release.

To use structured ouputs:

1. Define your schema, which must be valid JSON and include the json_schema key.
   Python

   # define schema
   schema = {
    "json_schema": {
           "type": "object",
           "properties": {
               "regions": {
                   "type": "array",
                   "items": {
                       "type": "object",
                       "properties": {
                           "region": {"type": "string"},
                           "revenue": {"type": "number"},
                           "share_of_revenue": {"type": "number"}
                       },
                       "required": ["region", "revenue", "share_of_revenue"]
                   }
               }
           },
           "required": ["regions"]
       }
   }
   

2. Pass the schema as part of your /query request.

Contextual AI Python SDK users must include the schema under the structured_output key in the extra_body parameter.

Python SDK

from contextual import ContextualAI
# initialize your client
client = ContextualAI(
    api_key=os.environ.get("CONTEXTUAL_API_KEY"),
)
# define your schema and add it to the payload object under the
# structured_output key
payload = {
    "structured_output": schema
}
# pass the payload in the "extra_body" field, along with your other
# query parameters
response = client.agents.query.create(
	# replace with your agent's id
	agent_id=""
	# replace with your query
	messages=[{"content": "what was the regional revenue breakdown in 2022", "role": "user"}],
	# pass the schema in the `extra_body` param
	extra_body=payload
)

3. Parse the returned message as JSON-formatted data:
   Python

   import json
   results = json.loads(response.message.content)
   

The resulting structured output can then be used for a variety of downstream applications:

{'regions': [{'region': 'Americas',
   'revenue': 28079,
   'share_of_revenue': 44.0},
  {'region': 'Europe, Middle East & Africa',
   'revenue': 25301,
   'share_of_revenue': 39.5},
  {'region': 'Asia & Pacific', 'revenue': 10486, 'share_of_revenue': 16.4}]}