answer.session_id as session_id to ask a follow-up: the
agent resumes the conversation, so a question like “and for 2023?” means what it
means in context. Only the API key that started a conversation may continue it;
a conversation whose turn is still running answers 409 session_busy. A
changed scope or access grants starts a fresh conversation and returns a new
session_id.
The agent may ask back instead of guessing when a question is genuinely
ambiguous (allow_clarification, on by default). The result’s
answer.clarification_questions then lists the questions and answer.answer
is null. Reply with clarification_answers and the same session_id, or ask a
rephrased question. A turn that sends clarification_answers never asks again.
output_schema (a JSON Schema, object root) asks for one turn’s answer as
JSON: answer.structured_answer holds the parsed value, or null if the answer
still missed the schema after its corrections. A field the source does not state comes back null, whatever type the schema gives it.
It applies only to the turn that
sends it: to keep structured answers across a conversation, send it on every
turn, including the reply to clarifying questions. A clarifying turn returns its
questions with structured_answer null.
The result is an automatic_agent result: answer — citations, SQL receipts
and confidence — and, when the agent answered from a catalog query, a catalog
table whose next_cursor pages through POST .../filtered-search.
Scope a conversation with path_prefix (a folder), paths (exact uploaded
files, no limit on how many), or both. The two add up. Unknown or inaccessible
paths are refused with 404 before a job exists.
See Search.