Advanced Query Features

• Multi-turn Conversations - allows you to use prior conversation histories for information future responses.
• Structured Outputs - enables the use of structured return outputs for better responses and accurate answers.

​

Multi-turn Conversations

​

Single-Turn vs. Multi-turn Example

​

Enabling Multi-turn Behavior

1. Append the new query to the given conversation
2. Generate the response in a conversation-aware manner If you do not pass a conversation_id, Contextual will assume you are beginning a new conversation with the query in the request as the initial message. If multi-turn is disabled in your agent’s configuration, passing the conversation_id will only append the query to the given conversation’s history; the response will not be generated in a conversation-aware manner.

​

Code Snippets

from contextual import ContextualAI
client = ContextualAI(api_key=api_key) # input your key
agent_id = "" # input your agent_id
params = {
    "agent_configs": {
        "global_config": {
            "enable_multi_turn": True  # Set to False to disable multiturn
        }
    }
}
client.agents.update(agent_id=agent_id, extra_body=params)

from contextual import ContextualAI
client = ContextualAI(
    api_key=os.environ.get("CONTEXTUAL_API_KEY"),
)
response = client.agents.query.create(
  # replace with your agent's id
  agent_id=agent_id,
  # replace with your query
  messages=[{"content": "", "role": "user"}],
  # replace with a valid conversation_id
  conversation_id=conversation_id
)

​

Structured Outputs

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

   Copy

   # 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.

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

   Copy

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

{'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}]}