COcontextualai
/agents/{id}/query

Query

Changed on

Start a conversation with an Agent and receive its generated response, along with relevant retrieved data and attributions.

post/agents/{agent_id}/query/acl

Request

  • Base URL
    https://api.contextual.ai/v1
  • URL
    https://api.contextual.ai/v1/agents/{agent_id}/query/acl
  • Auth
    HTTP bearer

Path parameters

agent_idstring uuid required

Agent ID of the agent to query

Query parameters

retrievals_onlyboolean

Set to true to fetch retrieval content and metadata, and then skip generation of the response.

include_retrieval_content_textboolean

Set to true to include the text of the retrieved contents in the response. If false, only metadata about the retrieved contents will be included, not content text. This parameter is ignored if retrievals_only is true, in which case content_text will always be returned. Content text and other metadata can also be fetched separately using the /agents/{agent_id}/query/{message_id}/retrieval/info endpoint.

Request body

streamboolean

Set to true to receive a streamed response

conversation_idstring uuid

An optional alternative to providing message history in the messages field. If provided, all messages in the messages list prior to the latest user-sent query will be ignored.

llm_model_idstring

Model ID of the specific fine-tuned or aligned LLM model to use. Defaults to base model if not specified.

Response

Successful Response

conversation_idstring uuid required

A unique identifier for the conversation. Can be passed to future /query calls to continue a conversation with the same message history.

message_idstring uuid

A unique identifier for this specific message

dynamic_agent_traceobject

Tool calls and thinking events for the response

outputsobject

Outputs of the agent

rl_training_contextobject

RL training context for multi-turn training. Automatically included when policy_output is provided. Contains: full_message_history (complete conversation for next turn), message_history (original input), research_items (tool calls + results), tool_calls_summary (simplified), chunks_info (retrieved content).

Changes