Skip to main content
Depending on your use case, you may want to take advantage of Contextual AI’s multi-turn capabilities. With multi-turn enabled, agents can reference prior conversation history when responding to new queries. This allows them to resolve ambiguities, retrieve the most relevant information, and generate more accurate, context-aware responses.

​
Single-Turn vs. Multi-turn Example

To better understand the capabilities and benefits of multi-turn, review the side-by-side examples below comparing outputs with and without multi-turn enabled.
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 interest Caveats: 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.
Multi-turn allows agents to maintain conversational context between queries, enabling them to interpret follow-up questions like “When can this change?” in relation to the previous topic—in this example, the merger price. With this continuity, agents can retrieve and reason over relevant sections of the same document without restating the context, resulting in faster, more accurate, and more natural responses. Without multi-turn, the system treats each query in isolation, requiring the user to rephrase or repeat details, which can lead to incomplete or less precise answers.

​
Enabling Multi-turn Behavior

Multi-turn is configured at the agent level. When enabled, you can pass a conversation_id at query time to:
  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

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
)