​

Multi-turn conversations

Based on your use case, you may want to leverage our multi-turn capabilities. With multi-turn, agents can use prior conversation history when responding to new queries. This means agents will automatically use information in prior turns to resolve ambiguities in the query, fetch the appropriate retrievals, and generate the final answer.

​

Enabling multi-turn behavior

Enabling multi-turn is an agent-level setting. If multi-turn is enabled, at query-time you can pass a conversation_id, which will:

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 at the agent-level, 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

To enable or disable multi-turn for a given agent:

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)

To pass the conversation_id when querying:

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 [Beta]

Structured output mode is useful when you require query responses to follow a repeatable and easily parseable format. Example use cases include extracting pre-defined categories of information or generating responses that need to integrate seamlessly with downstream applications or workflows.

Contextual supports structured outputs in JSON format. To use structured ouputs:

1. First, 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. Then, pass the schema as part of your /query request. If you are using our Python SDK, the schema must be passed under the structrued_output key in the extra_body param.

   Python SDK

   Copy

   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. Finally, parse the returned message as a JSON

   Python

   Copy

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

Example output:

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