RetrievalAgentRequest
Request for the retrieval agent. Queries define which tables and indexes to search, each as an ordinary QueryRequest. Optional tree or graph exploration is configured by steps.retrieval.navigation, targeting one query by index. **Pipeline mode** (default, max_internal_iterations=0): Queries are executed directly without an LLM tool-calling loop. **Agentic mode** (max_internal_iterations > 0): The LLM decides which tools to call, using the queries to determine available tables and indexes. A query may contain only a table scope and caller constraints: build_query delegates to the query-builder agent, then search executes its validated QueryRequest. Refinements use the same canonical full-DSL validator, not keyword substitution. Authenticated row filters are enforced on every initial and generated operation in both modes, including scans, aggregates, and graph/tree traversal. They cannot be replaced or weakened by model tool arguments.
Properties
| Name | Type | Description |
|---|---|---|
| query | string | User's natural language query |
| queries | array | Queries to execute. Each query carries its own table via the QueryRequest table field. In pipeline mode (max_internal_iterations=0), these are executed directly. In agentic mode, these declare which t |
| messages | array | Optional conversational context for the current turn. Decisions remain the authoritative continuation input for bounded agent interactions. |
| agent_knowledge | string | Domain-specific knowledge to include in the agent's system prompt. Useful for providing context about the document collection. |
| accumulated_filters | array | Mandatory filters from prior interactions. These are converted to structured Antfly predicates and applied to every table and every search tool invocation, including generated follow-ups, graph/tree t |
| session_id | string | Correlation identifier for a bounded agent interaction. This is echoed back to the client and does not imply server-side session persistence. |
| decisions | array | Structured answers provided by the user as part of client-carried continuation. |
| interactive | boolean | If true, the agent may return clarification questions when needed. |
| max_internal_iterations | integer | Maximum number of model-generation rounds across retrieval and any delegated query-builder calls. All calls share the request deadline and cancellation. Tool calls are additionally capped at 20 overal |
| max_user_clarifications | integer | Maximum number of clarification turns the agent may request from the user. |
| require_decision_after | integer | Force a user-facing decision after this many unresolved internal passes. |
| max_context_tokens | integer | Maximum tokens for document context in tool responses. Documents exceeding this limit are pruned to fit. |
| reserve_tokens | integer | Tokens to reserve for system prompt, answer generation, and other overhead. Subtracted from max_context_tokens to determine available context budget. Defaults to 4000 if max_context_tokens is set. |
| stream | boolean | Enable SSE streaming vs JSON response |
| generator | object | Generator for the retrieval agent's LLM calls |
| chain | array | Chain of generators |
| tools | object | Default tool policy for this agent run. Step-specific tool policies narrow this default for their step; retrieval currently uses steps.retrieval.tools. |
| steps | object | Step configuration |
| document_renderer | string | Handlebars template that renders each retrieved document in the generation prompt. Requires steps.generation to be set. The template is rendered once per hit against `{id, score, fields}`, where `fiel |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://artifacts.apis.io/antfly/json-schema/antfly-retrieval-agent-request-schema.json",
"title": "RetrievalAgentRequest",
"description": "Request for the retrieval agent. Queries define which tables and indexes\nto search, each as an ordinary QueryRequest. Optional tree or graph exploration\nis configured by steps.retrieval.navigation, targeting one query by index.\n\n**Pipeline mode** (default, max_internal_iterations=0): Queries are executed\ndirectly without an LLM tool-calling loop.\n\n**Agentic mode** (max_internal_iterations > 0): The LLM decides which tools to\ncall, using the queries to determine available tables and indexes. A query\nmay contain only a table scope and caller constraints: build_query delegates\nto the query-builder agent, then search executes its validated QueryRequest.\nRefinements use the same canonical full-DSL validator, not keyword substitution.\n\nAuthenticated row filters are enforced on every initial and generated\noperation in both modes, including scans, aggregates, and graph/tree\ntraversal. They cannot be replaced or weakened by model tool arguments.\n",
"x-generated": "2026-11-10",
"x-method": "derived",
"x-generator": "derive-json-schema.py",
"x-source": "openapi/antfly-query-operations-api-openapi.yml#/components/schemas/RetrievalAgentRequest",
"type": "object",
"required": [
"query",
"queries"
],
"properties": {
"query": {
"type": "string",
"description": "User's natural language query"
},
"queries": {
"type": "array",
"items": {
"$ref": "#/$defs/QueryRequest"
},
"description": "Queries to execute. Each query carries its own table via the\nQueryRequest table field.\n\nIn pipeline mode (max_internal_iterations=0), these are executed directly.\nIn agentic mode, these declare which table and indexes are available.\n\n`filter_query` and `exclusion_query` are mandatory table predicates\nfor retrieval-agent execution. Predicates declared by any query for\na table are conjoined (or unioned for exclusions) and applied to\nevery initial query, generated refinement, probe, aggregation,\ngraph/tree traversal, root scan, and follow-up for that table.\nThey cannot be weakened by generated operations.\n"
},
"messages": {
"type": "array",
"items": {
"$ref": "#/$defs/ChatMessage"
},
"description": "Optional conversational context for the current turn. Decisions remain the authoritative continuation input for bounded agent interactions."
},
"agent_knowledge": {
"type": "string",
"description": "Domain-specific knowledge to include in the agent's system prompt.\nUseful for providing context about the document collection.\n"
},
"accumulated_filters": {
"type": "array",
"items": {
"$ref": "#/$defs/FilterSpec"
},
"description": "Mandatory filters from prior interactions. These are converted to\nstructured Antfly predicates and applied to every table and every\nsearch tool invocation, including generated follow-ups, graph/tree\ntraversal, aggregations, and root scans.\n"
},
"session_id": {
"type": "string",
"description": "Correlation identifier for a bounded agent interaction. This is echoed back to the client and does not imply server-side session persistence."
},
"decisions": {
"type": "array",
"items": {
"$ref": "#/$defs/AgentDecision"
},
"description": "Structured answers provided by the user as part of client-carried continuation."
},
"interactive": {
"type": "boolean",
"default": true,
"description": "If true, the agent may return clarification questions when needed."
},
"max_internal_iterations": {
"type": "integer",
"minimum": 0,
"maximum": 20,
"default": 0,
"description": "Maximum number of model-generation rounds across retrieval and any\ndelegated query-builder calls. All calls share the request deadline\nand cancellation. Tool calls are additionally capped at 20 overall.\n\n- 0: Pipeline mode — execute provided queries directly, no LLM loop\n- 1+: Agentic mode — LLM decides which tools to call\n"
},
"max_user_clarifications": {
"type": "integer",
"minimum": 0,
"maximum": 10,
"description": "Maximum number of clarification turns the agent may request from the user."
},
"require_decision_after": {
"type": "integer",
"minimum": 0,
"maximum": 20,
"description": "Force a user-facing decision after this many unresolved internal passes."
},
"max_context_tokens": {
"type": "integer",
"description": "Maximum tokens for document context in tool responses. Documents\nexceeding this limit are pruned to fit.\n"
},
"reserve_tokens": {
"type": "integer",
"description": "Tokens to reserve for system prompt, answer generation, and other overhead.\nSubtracted from max_context_tokens to determine available context budget.\nDefaults to 4000 if max_context_tokens is set.\n",
"default": 4000,
"minimum": 0
},
"stream": {
"type": "boolean",
"default": true,
"description": "Enable SSE streaming vs JSON response"
},
"generator": {
"$ref": "#/$defs/GeneratorConfig",
"description": "Generator for the retrieval agent's LLM calls"
},
"chain": {
"type": "array",
"items": {
"$ref": "#/$defs/ChainLink"
},
"description": "Chain of generators"
},
"tools": {
"$ref": "#/$defs/ChatToolsConfig",
"description": "Default tool policy for this agent run. Step-specific tool policies\nnarrow this default for their step; retrieval currently uses\nsteps.retrieval.tools.\n"
},
"steps": {
"$ref": "#/$defs/RetrievalAgentSteps",
"description": "Step configuration"
},
"document_renderer": {
"type": "string",
"description": "Handlebars template that renders each retrieved document in the\ngeneration prompt. Requires steps.generation to be set.\n\nThe template is rendered once per hit against `{id, score, fields}`,\nwhere `fields` is the hit's source. When omitted, each document's\nfields are encoded as TOON (Token-Oriented Object Notation), which\ncarries the same structure as JSON in fewer tokens.\n\nHelpers: `encodeToon` (options `indent`, 1 to 16, default 2; and\n`delimiter`: `comma`, `tab`, or `pipe`), `scrubHtml`, `eq`, and\n`media`. Values in `{{...}}` are HTML-escaped; use `{{{...}}}` for\nraw text.\n\nExamples:\n- `{{encodeToon this.fields}}`\n- `{{encodeToon this.fields delimiter=\"tab\"}}`\n- `Title: {{{this.fields.title}}}`\n"
}
},
"$defs": {
"AgentDecision": {
"type": "object",
"required": [
"question_id"
],
"properties": {
"question_id": {
"type": "string",
"description": "The question being answered"
},
"answer": {
"description": "User answer, scalar or structured depending on the question kind"
},
"approved": {
"type": "boolean",
"description": "Used for confirm/review steps where the draft may be accepted as-is"
}
}
},
"AggregationDateRange": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the date range bucket"
},
"from": {
"type": "string",
"x-go-type-skip-optional-pointer": false,
"description": "Start date (ISO 8601 or relative like \"now-7d\")"
},
"to": {
"type": "string",
"x-go-type-skip-optional-pointer": false,
"description": "End date (ISO 8601 or relative like \"now\")"
}
}
},
"AggregationRange": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the range bucket"
},
"from": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Lower bound (inclusive)"
},
"to": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Upper bound (exclusive)"
}
}
},
"AggregationRequest": {
"type": "object",
"required": [
"type"
],
"properties": {
"type": {
"$ref": "#/$defs/AggregationType"
},
"field": {
"type": "string",
"description": "Field to aggregate on. Required unless `fields` is supplied for a multi-field terms aggregation."
},
"mode": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/CardinalityMode"
}
],
"description": "Selection mode for a cardinality aggregation. `auto` (default) uses a materialized HyperLogLog sketch when one applies and is current, else falls back to an exact distinct scan. `exact` always scans. `approximate` requires a sketch and errors if none applies. Ignored for other types."
},
"fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ordered field list for multi-field terms aggregations. Each bucket key is a JSON string containing the serialized value array in the same order; clients should parse bucket.key as JSON."
},
"size": {
"type": "integer",
"x-go-type-skip-optional-pointer": false,
"description": "Maximum number of buckets to return (for bucketing aggregations)"
},
"ranges": {
"type": "array",
"items": {
"$ref": "#/$defs/AggregationRange"
},
"description": "Ranges for range aggregations"
},
"date_ranges": {
"type": "array",
"items": {
"$ref": "#/$defs/AggregationDateRange"
},
"description": "Date ranges for date_range aggregations"
},
"interval": {
"type": "number",
"format": "float",
"x-go-type": "float64",
"x-go-type-skip-optional-pointer": false,
"description": "Fixed interval for histogram aggregations"
},
"calendar_interval": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/CalendarInterval"
}
],
"description": "Calendar-aware interval for date_histogram aggregations"
},
"origin": {
"type": "string",
"x-go-type-skip-optional-pointer": false,
"description": "Origin for geohash_grid aggregation (format: \"lat,lon\")\nExample: \"37.7749,-122.4194\"\n"
},
"precision": {
"type": "integer",
"x-go-type-skip-optional-pointer": false,
"description": "Geohash precision (1-12) for geohash_grid aggregations"
},
"distance_ranges": {
"type": "array",
"items": {
"$ref": "#/$defs/DistanceRange"
},
"description": "Distance ranges for geo_distance aggregations"
},
"unit": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/DistanceUnit"
}
],
"description": "Distance unit for geo_distance aggregations"
},
"min_doc_count": {
"type": "integer",
"x-go-type-skip-optional-pointer": false,
"description": "Minimum document count for a bucket to be included"
},
"background_filter": {
"$ref": "#/$defs/RawQuery",
"description": "Background filter for significant_terms aggregations"
},
"algorithm": {
"x-go-type-skip-optional-pointer": false,
"allOf": [
{
"$ref": "#/$defs/SignificanceAlgorithm"
}
],
"description": "Significance algorithm for significant_terms aggregations"
},
"algebraic_join": {
"$ref": "#/$defs/AlgebraicAggregationJoin",
"description": "Algebraic join descriptor for bounded cross-table aggregation planning"
},
"sub_aggregations": {
"type": "object",
"additionalProperties": {
"$ref": "#/$defs/AggregationRequest"
},
"description": "Nested sub-aggregations"
}
}
},
"AggregationType": {
"type": "string",
"enum": [
"sum",
"avg",
"min",
"max",
"count",
"sumsquares",
"stats",
"cardinality",
"terms",
"range",
"date_range",
"histogram",
"date_histogram",
"geohash_grid",
"geo_distance",
"significant_terms"
],
"description": "Type of aggregation to compute:\n- Metrics: sum, avg, min, max, count, sumsquares, stats, cardinality\n- Bucketing: terms, range, date_range, histogram, date_histogram\n- Geo: geohash_grid, geo_distance\n- Analytics: significant_terms\n"
},
"AlgebraicAggregationJoin": {
"type": "object",
"required": [
"name",
"group_side",
"measure_side"
],
"properties": {
"name": {
"type": "string",
"description": "Algebraic join materialization or capability name"
},
"kind": {
"type": "string",
"enum": [
"none",
"bucket",
"window",
"bucket_window"
],
"x-go-type-skip-optional-pointer": false,
"description": "Temporal join mode for the algebraic materialization"
},
"group_side": {
"type": "string",
"description": "Join side that supplies grouping bucket values"
},
"measure_side": {
"type": "string",
"description": "Join side that supplies metric values"
}
}
},
"Analyses": {
"x-go-type-skip-optional-pointer": false,
"type": "object",
"properties": {
"pca": {
"type": "boolean"
},
"tsne": {
"type": "boolean"
}
}
},
"AntflyGeneratorConfig": {
"type": "object",
"description": "Configuration for the Antfly inference generative AI provider.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"antfly"
]
},
"model": {
"type": "string",
"description": "The name of the generator model."
},
"api_url": {
"type": "string",
"format": "uri",
"description": "The URL of the Inference API endpoint. Can also be set via ANTFLY_INFERENCE_URL environment variable."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-2.0).",
"minimum": 0.0,
"maximum": 2.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter.",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Top-k sampling parameter."
},
"timeout": {
"type": "integer",
"description": "HTTP response timeout in seconds for Inference API calls.",
"minimum": 1
}
},
"required": [
"provider",
"model"
]
},
"AntflyRerankerConfig": {
"type": "object",
"description": "Configuration for the Antfly inference reranking provider.",
"properties": {
"provider": {
"type": "string",
"enum": [
"antfly"
]
},
"api_key": {
"type": "string",
"description": "Optional bearer API key for remote Antfly inference. Supports secret references and defaults to ANTFLY_INFERENCE_API_KEY. Embedded inference does not resolve or use outbound credentials."
},
"model": {
"type": "string",
"description": "Optional reranking model name. When omitted, Antfly inference selects a model from its reranker model directory. Set this explicitly when more than one local reranker is installed."
},
"url": {
"type": "string",
"format": "uri",
"description": "The URL of the Inference API endpoint. Can also be set via ANTFLY_INFERENCE_URL environment variable."
}
},
"required": [
"provider"
]
},
"AnthropicGeneratorConfig": {
"type": "object",
"description": "Configuration for the Anthropic generative AI provider.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"anthropic"
]
},
"workspace_id": {
"type": "string",
"description": "Anthropic workspace for keys not scoped to a workspace. Defaults to ANTHROPIC_WORKSPACE_ID."
},
"model": {
"type": "string",
"description": "The full model ID of the Anthropic model to use.",
"default": "claude-sonnet-4-5-20250929"
},
"api_key": {
"type": "string",
"writeOnly": true,
"description": "Anthropic API key or secret reference. Defaults to ANTHROPIC_API_KEY."
},
"url": {
"type": "string",
"format": "uri",
"description": "Messages API base URL. Defaults to https://api.anthropic.com/v1."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate in the response."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"top_k": {
"type": "integer",
"description": "Top-k sampling parameter."
}
},
"required": [
"provider",
"model"
]
},
"AppleGeneratorConfig": {
"type": "object",
"description": "On-device Apple Foundation Models generation. Requires a macOS Apple provider build, Apple Intelligence enabled, and its system model ready. Supports text conversations; tool calling and media attachments are not supported.",
"properties": {
"provider": {
"type": "string",
"enum": [
"apple"
]
},
"max_tokens": {
"type": "integer",
"minimum": 1,
"default": 256
},
"temperature": {
"type": "number",
"minimum": 0,
"maximum": 2
}
}
},
"AutocompleteQuery": {
"type": "object",
"additionalProperties": false,
"description": "Analyzed bool-prefix search on a logical field. The planner selects\ndeclared search-as-you-type root, shingle and prefix representations.\nRequires a compatible representation; never silently becomes raw prefix search.\n",
"required": [
"autocomplete",
"field"
],
"properties": {
"autocomplete": {
"type": "string"
},
"field": {
"type": "string",
"minLength": 1
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"BedrockGeneratorConfig": {
"type": "object",
"description": "AWS Bedrock Converse generation, including image inputs and tools for\nmodels that support them. Uses the AWS default credential chain unless\nan explicit Bedrock API key is configured. Image capability is declared\nper target through inference_capabilities; model IDs are not allowlisted.\n",
"properties": {
"provider": {
"type": "string",
"enum": [
"bedrock"
]
},
"url": {
"type": "string",
"description": "Optional Bedrock Runtime endpoint override. Defaults to the regional AWS endpoint."
},
"api_key": {
"type": "string",
"description": "Optional Bedrock bearer API key or secret reference. Omit to use signed AWS requests and the default credential chain."
},
"model": {
"type": "string",
"description": "The Bedrock model ID to use."
},
"region": {
"type": "string",
"description": "AWS region. Defaults to AWS_REGION, then AWS_DEFAULT_REGION, then us-east-1."
},
"temperature": {
"type": "number",
"format": "float",
"description": "Controls randomness in generation (0.0-1.0).",
"minimum": 0.0,
"maximum": 1.0
},
"max_tokens": {
"type": "integer",
"description": "Maximum number of tokens to generate."
},
"top_p": {
"type": "number",
"format": "float",
"description": "Nucleus sampling parameter.",
"minimum": 0.0,
"maximum": 1.0
}
},
"required": [
"provider",
"model"
]
},
"BoolFieldQuery": {
"type": "object",
"properties": {
"bool": {
"type": "boolean"
},
"field": {
"type": "string"
},
"boost": {
"$ref": "#/$defs/Boost"
}
},
"required": [
"bool"
]
},
"BoolQuery": {
"type": "object",
"additionalProperties": false,
"required": [
"bool"
],
"description": "Canonical Boolean wrapper. Must clauses score; filter clauses constrain without scoring.",
"properties": {
"bool": {
"$ref": "#/$defs/BoolQueryBody"
}
}
},
"BoolQueryBody": {
"type": "object",
"additionalProperties": false,
"properties": {
"must": {
"$ref": "#/$defs/BoolQueryClause"
},
"should": {
"$ref": "#/$defs/BoolQueryClause"
},
"must_not": {
"$ref": "#/$defs/BoolQueryClause"
},
"filter": {
"$ref": "#/$defs/BoolQueryClause"
},
"minimum_should_match": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Minimum optional clauses required; omission follows the runtime's required-clause defaults."
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"BoolQueryClause": {
"oneOf": [
{
"$ref": "#/$defs/Query"
},
{
"type": "array",
"items": {
"$ref": "#/$defs/Query"
}
}
]
},
"BooleanQuery": {
"type": "object",
"additionalProperties": false,
"properties": {
"must": {
"$ref": "#/$defs/ConjunctionQuery"
},
"should": {
"$ref": "#/$defs/DisjunctionQuery"
},
"must_not": {
"$ref": "#/$defs/DisjunctionQuery"
},
"filter": {
"$ref": "#/$defs/Query"
},
"boost": {
"$ref": "#/$defs/Boost"
}
}
},
"Boost": {
"type": [
"number",
"null"
],
"format": "double",
"description": "A floating-point number used to decrease or increase the relevance scores of a query.",
"default": 1.0
},
"BraveSearchConfig": {
"type": "object",
"description": "Configuration for Brave Search API.\n\nBrave Search provides privacy-focused search with its own independent index.\n\n**Setup:**\n1. Sign up at https://brave.com/search/api/\n2. Get API key from dashboard\n\n**Docs:** https://api.search.brave.com/app/documentation\n",
"allOf": [
{
"$ref": "#/$defs/WebSearchConfig"
},
{
"type": "object",
"properties": {
"provider": {
"type": "string",
"enum": [
"brave"
]
},
"api_key": {
"type": "string",
"description": "Brave Search API key (or set BRAVE_API_KEY env var)"
},
"freshness": {
"type": "string",
"enum": [
"pd",
"pw",
"pm",
"py"
],
"description": "Freshness filter: pd=day, pw=week, pm=month, py=year"
},
"text_decorations": {
"type": "boolean",
"description": "Include text decorations (bold, italic markers)"
},
"spellcheck": {
"type": "boolean",
"description": "Enable spellcheck suggestions"
}
}
}
]
},
"CalendarInterval": {
"type": "string",
"enum": [
"minute",
"hour",
"day",
"week",
"month",
"quarter",
"year"
],
"description": "Calendar-aware interval for date_histogram aggregations"
},
"CardinalityMode": {
"type": "string",
"enum": [
"auto",
"exact",
"approximate"
],
"description": "Exact-vs-approximate selection for a cardinality aggregation:\n- auto: use a materialized HyperLogLog sketch when one applies and is\n current, else an exact distinct scan (default).\n- exact: always compute an exact distinct count.\n- approximate: require a matching sketch; error if none applies.\n"
},
"CatalogTableTarget": {
"type": "object",
"description": "An explicit native table target. Components are literal names; dots do not qualify a string table name.",
"properties": {
"database": {
"type": "string",
"default": "default"
},
"namespace": {
"type": "string",
"default": "public"
},
"table": {
"type": "string"
}
},
"required": [
"table"
],
"additionalProperties": false
},
"ChainCondition": {
"type": "string",
"enum": [
"always",
"on_error",
"on_timeout",
"on_rate_limit"
],
"default": "on_error",
"description": "Condition for trying the next generator in chain:\n- always: Always try next regardless of outcome\n- on_error: Try next on any error (default)\n- on_timeout: Try next only on timeout errors\n- on_rate_limit: Try next only on rate limit errors\n"
},
"ChainLink": {
"type": "object",
"description": "A single link in a generator chain with optional retry and condition",
"required": [
"generator"
],
"properties": {
"generator": {
"$ref": "#/$defs/GeneratorConfig"
},
"retry": {
"$ref": "#/$defs/RetryConfig",
"description": "Retry configuration for this generator"
},
"condition": {
"$ref": "#/$defs/ChainCondition",
"description": "When to try the next generator in chain"
}
}
},
"ChatGPTGeneratorConfig": {
"type": "object",
"description": "Personal ChatGPT plan for interactive generation. Credentials stay in the local runtime.",
"required": [
"provider",
"model",
"connection_id"
],
"properties": {
"provider": {
"type": "string",
"enum": [
"chatgpt"
]
},
"reasoning_effort": {
"$ref": "#/$defs/OpenAIReasoningEffort"
},
"model": {
"type": "string"
},
"connection_id": {
"type": "string",
"description": "Opaque personal registration owned by the authenticated caller."
}
}
},
"ChatMessage": {
"type": "object",
"description": "OpenAI-compatible message in a generation/chat conversation.",
"required": [
"role"
],
"properties": {
"extra_content": {
"type": "object",
"additionalProperties": true,
"description": "Opaque provider message metadata. Preserve unchanged when replaying assistant messages; native Anthropic content retains signed thinking blocks."
},
"role": {
"$ref": "#/$defs/ChatMessageRole"
},
"content": {
"$ref": "#/$defs/ChatMessageContent"
},
"tool_calls": {
"type": "array",
"items": {
"$ref": "#/$defs/ToolCall"
},
"description": "Tool calls made by the assistant (only for role=assistant)."
},
"tool_call_id": {
"type": "string",
"description": "ID of the tool call this message responds to (only for role=tool)."
},
"name": {
"type": "string",
"description": "Optional tool name for tool messages when model templates need it."
}
}
},
"ChatMessageContent": {
"x-go-type": "stdjson.RawMessage",
"x-go-type-import": {
"path": "encoding/json",
"name": "stdjson"
},
"description": "Message content. Supports two formats:\n- Simple string: \"Hello, how are you?\"\n- Array of content parts: [{\"type\": \"text\", \"text\": \"Hello\"}]\n",
"oneOf": [
{
"type": "string",
"description": "Simple text content."
},
{
"type": "array",
"description": "Array of multimodal content parts.",
"items": {
"$ref": "#/$defs/ContentPart"
}
}
]
},
"ChatMessageRole": {
"type": "string",
"enum": [
"user",
"assistant",
"system",
"tool"
],
"description": "Role of the message sender in a generation/chat conversation"
},
"ChatToolName": {
"type": "string",
"description": "Available tool names for retrieval agents.\n- add_filter: Add search filters (field constraints)\n- ask_clarification: Ask user for clarification\n- web_search: Search the web (requires web_search_connection or web_search_config)\n- fetch: Fetch URL content (subject to security controls)\n- semantic_search: Execute semantic/vector search against an index\n- full_text_search: Execute full-text BM25 search against an index\n- tree_search: Execute tree search with beam search navigation\n- graph_search: Execute graph traversal search\n- aggregate: Execute aggregations against an index\n",
"enum": [
"add_filter",
"ask_clarification",
"web_search",
"fetch",
"semantic_search",
"full_text_search",
"tree_search",
"graph_search",
"aggregate"
]
},
"ChatToolsConfig": {
"type": "object",
"description": "Configuration for retrieval agent tools.\n\nIf `enabled_tools` is empty/omitted, retrieval agents default to all retrieval tools\navailable for the request. Explicit retrieval policies should use semantic_search\nfor vector retrieval.\n\nFor models that don't support native tool calling (e.g., Ollama),\na prompt-based fallback is used with structured output parsing.\n",
"properties": {
"enabled_tools": {
"type": "array",
"items": {
"$ref": "#/$defs/ChatToolName"
},
"description": "List of tools to enable. If empty, retrieval agents default to all retrieval\ntools available for the request.\n"
},
"web_search_config": {
"$ref": "#/$defs/WebSear
# --- truncated at 32 KB (239 KB total) ---
# Full source: https://artifacts.apis.io/antfly/json-schema/antfly-retrieval-agent-request-schema.json
Work with this as data
Every JSON Schema here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for schemas
4 MCP tools reach this
find_json_schemasBrowse and filter every JSON Schema in the catalog.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
curl "https://apis.io/api/v1/json-schemas/antfly-retrieval-agent-request"
curl "https://apis.io/api/v1/json-schemas?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.