deep-search model
deep-search is the first model available in our new responses endpoint. It adheres to the openai responses api schema, though some features of that api are not yet implemented. Here is what a request looks like:
curl -X 'POST'
'<https://api.ragie.ai/responses'>
-H 'accept: application/json'
-H 'Authorization: Bearer tnt_REDACTED'
-H 'Content-Type: application/json'
-d '{
"input": "If we exclude the impact of M&A, which segment has dragged down 3M'\''s overall growth in 2022?",
"instructions": "search for data in company financial filings. Expect to be searching over 10k filings",
"tools": \[
{
"type": "retrieve",
"partitions": [
"fin_bench"
]
}
],
"model": "deep-search",
"reasoning": {
"effort": "medium"
},
"stream": true
}'
Let’s dive into some of the parameters here:
- input - The query that deep-search will answer
- instructions - An optional system instruction that can be used to guide the search process
- tools - The tools that deep-search can use. Currently it supports and requires a single retrieve tool with a single
- partition. More options are coming soon!
- model - The model to run. Currently supports only deep-search
- reasoning - Defines the reasoning effort to use. The options available are “low”, “medium”, and “high”, defaulting to “medium”
- stream - When true streams the work the agent is performing in the SSE protocol. Event data matches the openai responses api. When false, respond with the final answer when ready. The final response may take some time, especially when the effort level is high, so be sure to configure a long timeout
The response also matches the responses api. The output array includes details of the run, with the final item of type message being the final output of the agent run as a string wrapped JSON object. The deep-search model responds somewhat like an opinionated structured output where the shape of that output is prescribed. There is one additional convenience field called output_parsed which includes a structured output of the full agent run as JSON. The schema of this object is:
{
"$defs": {
"Answer": {
"properties": {
"text": {
"description": "An answer to a question.",
"title": "Text",
"type": "string"
},
"evidence": {
"description": "The evidence used to derive the answer.",
"items": {
"type": "string"
},
"title": "Evidence",
"type": "array"
}
},
"required": [
"text"
],
"title": "Answer",
"type": "object"
},
"AnswerStep": {
"properties": {
"type": {
"const": "answer",
"default": "answer",
"title": "Type",
"type": "string"
},
"think": {
"title": "Think",
"type": "string"
},
"current_question": {
"title": "Current Question",
"type": "string"
},
"other_resolved_question_ids": {
"description": "A list of question ids that are no longer relevant to the current answer referenced by their IDs.",
"items": {
"type": "string"
},
"title": "Other Resolved Question Ids",
"type": "array"
},
"answer": {
"$ref": "#/$defs/Answer"
}
},
"required": [
"think",
"current_question",
"answer"
],
"title": "AnswerStep",
"type": "object"
},
"CodeInterpreterEvidence": {
"properties": {
"type": {
"const": "code_interpreter",
"default": "code_interpreter",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"code": {
"description": "The code that was executed.",
"title": "Code",
"type": "string"
},
"code_issue": {
"description": "The issue that the code was written to solve.",
"title": "Code Issue",
"type": "string"
},
"code_result": {
"description": "The result of the code that was executed.",
"title": "Code Result",
"type": "string"
}
},
"required": [
"text",
"code",
"code_issue",
"code_result"
],
"title": "CodeInterpreterEvidence",
"type": "object"
},
"CodeStep": {
"properties": {
"type": {
"const": "code",
"default": "code",
"title": "Type",
"type": "string"
},
"think": {
"title": "Think",
"type": "string"
},
"current_question": {
"title": "Current Question",
"type": "string"
},
"code_issue": {
"description": "The natural language description of the code issue you need to solve.",
"title": "Code Issue",
"type": "string"
},
"code": {
"default": "",
"description": "The code you generated to solve the code issue.",
"title": "Code",
"type": "string"
},
"code_result": {
"default": "",
"description": "The result of the code you generated after executing it.",
"title": "Code Result",
"type": "string"
}
},
"required": [
"think",
"current_question",
"code_issue"
],
"title": "CodeStep",
"type": "object"
},
"EvaluatedAnswerStep": {
"properties": {
"type": {
"const": "evaluated_answer",
"default": "evaluated_answer",
"title": "Type",
"type": "string"
},
"think": {
"title": "Think",
"type": "string"
},
"current_question": {
"title": "Current Question",
"type": "string"
},
"answer": {
"$ref": "#/$defs/Answer"
},
"other_resolved_question_ids": {
"description": "A list of questions ids that are no longer relevant to the current answer referenced by their IDs.",
"items": {
"type": "string"
},
"title": "Other Resolved Question Ids",
"type": "array"
},
"eval_passed": {
"title": "Eval Passed",
"type": "boolean"
},
"eval_reason": {
"title": "Eval Reason",
"type": "string"
}
},
"required": [
"think",
"current_question",
"answer",
"eval_passed",
"eval_reason"
],
"title": "EvaluatedAnswerStep",
"type": "object"
},
"ModelUsage": {
"properties": {
"model_name": {
"title": "Model Name",
"type": "string"
},
"input_tokens": {
"title": "Input Tokens",
"type": "integer"
},
"output_tokens": {
"title": "Output Tokens",
"type": "integer"
}
},
"required": [
"model_name",
"input_tokens",
"output_tokens"
],
"title": "ModelUsage",
"type": "object"
},
"PlanStep": {
"properties": {
"type": {
"const": "plan",
"default": "plan",
"title": "Type",
"type": "string"
},
"think": {
"title": "Think",
"type": "string"
},
"current_question": {
"title": "Current Question",
"type": "string"
},
"questions_to_answer": {
"description": "The questions that need to be answered to answer the original question.",
"items": {
"type": "string"
},
"title": "Questions To Answer",
"type": "array"
}
},
"required": [
"think",
"current_question"
],
"title": "PlanStep",
"type": "object"
},
"RagieEvidence": {
"properties": {
"type": {
"const": "ragie",
"default": "ragie",
"title": "Type",
"type": "string"
},
"text": {
"title": "Text",
"type": "string"
},
"id": {
"description": "The chunk id of the evidence.",
"title": "Id",
"type": "string"
},
"index": {
"description": "The index of the chunk in the document.",
"title": "Index",
"type": "integer"
},
"document_id": {
"description": "The document id of the document containing the chunk being used as evidence.",
"title": "Document Id",
"type": "string"
},
"document_name": {
"description": "The name of the document that contains the chunk being used as evidence.",
"title": "Document Name",
"type": "string"
},
"metadata": {
"additionalProperties": true,
"description": "The metadata of the chunk being used as evidence.",
"title": "Metadata",
"type": "object"
},
"document_metadata": {
"additionalProperties": true,
"description": "The metadata of the document that contains the evidence.",
"title": "Document Metadata",
"type": "object"
},
"links": {
"additionalProperties": {
"$ref": "#/$defs/SearchResultLink"
},
"description": "The links to the evidence.",
"title": "Links",
"type": "object"
}
},
"required": [
"text",
"id",
"index",
"document_id",
"document_name"
],
"title": "RagieEvidence",
"type": "object"
},
"Search": {
"properties": {
"search_requests": {
"items": {
"type": "string"
},
"title": "Search Requests",
"type": "array"
}
},
"required": [
"search_requests"
],
"title": "Search",
"type": "object"
},
"SearchResultLink": {
"properties": {
"href": {
"title": "Href",
"type": "string"
},
"type": {
"title": "Type",
"type": "string"
}
},
"required": [
"href",
"type"
],
"title": "SearchResultLink",
"type": "object"
},
"SearchStep": {
"properties": {
"type": {
"const": "search",
"default": "search",
"title": "Type",
"type": "string"
},
"think": {
"title": "Think",
"type": "string"
},
"current_question": {
"title": "Current Question",
"type": "string"
},
"search": {
"$ref": "#/$defs/Search",
"description": "The search request to be made."
}
},
"required": [
"think",
"current_question",
"search"
],
"title": "SearchStep",
"type": "object"
},
"SurrenderStep": {
"properties": {
"type": {
"const": "surrender",
"default": "surrender",
"title": "Type",
"type": "string"
},
"think": {
"title": "Think",
"type": "string"
},
"current_question": {
"title": "Current Question",
"type": "string"
},
"partial_answer": {
"$ref": "#/$defs/Answer",
"description": "The a potential partial answer when a full answer was not possible."
}
},
"required": [
"think",
"current_question",
"partial_answer"
],
"title": "SurrenderStep",
"type": "object"
},
"Usage": {
"properties": {
"models": {
"items": {
"$ref": "#/$defs/ModelUsage"
},
"title": "Models",
"type": "array"
}
},
"title": "Usage",
"type": "object"
}
},
"properties": {
"text": {
"description": "The final answer to the question.",
"title": "Text",
"type": "string"
},
"evidence": {
"description": "The evidence used to derive the answer.",
"items": {
"anyOf": [
{
"$ref": "#/$defs/CodeInterpreterEvidence"
},
{
"$ref": "#/$defs/RagieEvidence"
}
]
},
"title": "Evidence",
"type": "array"
},
"steps": {
"description": "The steps that led to the answer.",
"items": {
"anyOf": [
{
"$ref": "#/$defs/AnswerStep"
},
{
"$ref": "#/$defs/SearchStep"
},
{
"$ref": "#/$defs/PlanStep"
},
{
"$ref": "#/$defs/CodeStep"
},
{
"$ref": "#/$defs/SurrenderStep"
},
{
"$ref": "#/$defs/EvaluatedAnswerStep"
}
]
},
"title": "Steps",
"type": "array"
},
"usage": {
"$ref": "#/$defs/Usage",
"description": "The usage of the models."
}
},
"required": [
"text"
],
"title": "FinalAnswer",
"type": "object"
}
Streaming integration
A reference implementation of how to render a streaming UI for deep-search can be found here, in Base Chat, our open-source chat application. We can also provide support through our typical communication channels like Discord and email if you have any questions.
Rate limits
Rate limits are currently aggressive during our initial rollout, particularly on our free dev plan. You can contact us to discuss raising rate limits for your tenant.
Updated 1 day ago