​
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.
w/ Multi-turnw/o Multi-turn
Step 1Query: What is the merger priceQuery: What is the merger price
Response:
Direct Answer: The merger price is $11.50 per share in cash.Rationale: This is explicitly stated in Section 2.1(a) of the contract, which defines the “Per Share Merger Consideration” as $11.50 per share in cash, without interestCaveats: This price applies to all shares except for: (1) shares owned by Parent, Merger Sub, or their wholly owned subsidiaries (referred to as “Cancelled Shares”), (2) shares held in treasury by the Company, and (3) shares held by dissenting shareholders (referred to as “Dissenting Shares”)		Response:
Direct Answer: The merger price is $11.50 per share in cash.Rationale: This is explicitly stated in Section 2.1(a) of the contract, which defines the “Per Share Merger Consideration” as $11.50 per share in cash, without interestCaveats: This price applies to all shares except for: (1) shares owned by Parent, Merger Sub, or their wholly owned subsidiaries (referred to as “Cancelled Shares”), (2) shares held in treasury by the Company, and (3) shares held by dissenting shareholders (referred to as “Dissenting Shares”)
Turn 2Query: And when can this change?Query: And when can this change?
Response:
Direct Answer: The merger price of $11.50 per share in cash can be adjusted only in the event of a reclassification, stock split, combination, stock dividend or distribution, recapitalization, subdivision, merger, issuer tender or exchange offer, or other similar transaction that changes the number of shares outstanding.Rationale: This is specified in Section 2.5 of the contract, which states that if the number of Shares or securities convertible into Shares changes due to certain corporate actions, “the Per Share Merger Consideration shall be equitably adjusted to provide to Parent and the holders of Shares the same economic effect as contemplated by this Agreement prior to such event.Caveats: The adjustment is specifically limited to maintaining the same economic effect as originally contemplated, and the contract does not provide for adjustments due to other factors such as market conditions or changes in the company’s financial performance.		Response:
Direct Answer: The change can occur after a 4-day notice period and only in response to an Intervening Event or a Superior Proposal, subject to certain conditions and requirements.Rationale: This is based on Section 6.1(e) which outlines the specific conditions under which a Change of Recommendation can occur. It requires a 4-day notice period (the “Notice Period”) and must be in response to either an Intervening Event or a Superior Proposal. The Board must also determine that failing to make the change would be inconsistent with their fiduciary duties.Caveats: The change must follow specific procedural requirements including delivery of a written notice (Company Notice) with material details, and the Board must consult with financial advisors and outside legal counsel.

​
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 outputs is currently in beta and is missing some functionality, like attributions
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. 
    # 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. 
    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 
    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}]}