Antfly · Schema

ResearchAgentRequest

Request for the research agent. The agent plans sub-questions, runs a bounded retrieval researcher per sub-question in parallel, reflects on coverage, and writes a long-form report whose `[E#]` citations resolve to a deduplicated evidence registry. Researchers are ordinary retrieval-agent runs over `queries` with the same authorization, mandatory predicates and tool policy. They cannot widen tables, filters, tools or budgets.

Artificial IntelligenceSearchRetrievalVectorsHybrid

Properties

Name Type Description
query string The research question.
queries array Authorized table scopes, as for the retrieval agent. `filter_query` and `exclusion_query` are mandatory predicates for every researcher. May be empty when web search is enabled.
messages array Optional conversational context.
agent_knowledge string Domain context for every role.
accumulated_filters array Mandatory filters applied to every researcher search.
session_id string Correlation identifier echoed back to the client.
decisions array Structured user answers for client-carried continuation.
interactive boolean If true, the planner may return clarification questions instead of a plan.
generator object Default generator for every role.
chain array Default chain of generators for every role.
tools object Default tool policy for researchers, for example `web_search` and `fetch`.
steps object
budget object
research_state object Continuation state returned by an earlier run.
max_context_tokens integer Per-researcher tool-result context budget in tokens.
reserve_tokens integer Tokens reserved from max_context_tokens for prompts and answers.
stream boolean Enable SSE streaming vs JSON response.
View JSON Schema on GitHub

JSON Schema

antfly-research-agent-request-schema.json Raw ↑
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/antfly/json-schema/antfly-research-agent-request-schema.json",
  "title": "ResearchAgentRequest",
  "description": "Request for the research agent. The agent plans sub-questions, runs a\nbounded retrieval researcher per sub-question in parallel, reflects on\ncoverage, and writes a long-form report whose `[E#]` citations resolve\nto a deduplicated evidence registry.\n\nResearchers are ordinary retrieval-agent runs over `queries` with the\nsame authorization, mandatory predicates and tool policy. They cannot\nwiden tables, filters, tools or budgets.\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/ResearchAgentRequest",
  "type": "object",
  "required": [
    "query",
    "queries"
  ],
  "properties": {
    "query": {
      "type": "string",
      "description": "The research question."
    },
    "queries": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/QueryRequest"
      },
      "description": "Authorized table scopes, as for the retrieval agent. `filter_query`\nand `exclusion_query` are mandatory predicates for every researcher.\nMay be empty when web search is enabled.\n"
    },
    "messages": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChatMessage"
      },
      "description": "Optional conversational context."
    },
    "agent_knowledge": {
      "type": "string",
      "description": "Domain context for every role."
    },
    "accumulated_filters": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/FilterSpec"
      },
      "description": "Mandatory filters applied to every researcher search."
    },
    "session_id": {
      "type": "string",
      "description": "Correlation identifier echoed back to the client."
    },
    "decisions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/AgentDecision"
      },
      "description": "Structured user answers for client-carried continuation."
    },
    "interactive": {
      "type": "boolean",
      "default": false,
      "description": "If true, the planner may return clarification questions instead of a plan."
    },
    "generator": {
      "$ref": "#/$defs/GeneratorConfig",
      "description": "Default generator for every role."
    },
    "chain": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ChainLink"
      },
      "description": "Default chain of generators for every role."
    },
    "tools": {
      "$ref": "#/$defs/ChatToolsConfig",
      "description": "Default tool policy for researchers, for example `web_search` and `fetch`."
    },
    "steps": {
      "$ref": "#/$defs/ResearchAgentSteps"
    },
    "budget": {
      "$ref": "#/$defs/ResearchBudget"
    },
    "research_state": {
      "$ref": "#/$defs/ResearchState",
      "description": "Continuation state returned by an earlier run."
    },
    "max_context_tokens": {
      "type": "integer",
      "description": "Per-researcher tool-result context budget in tokens."
    },
    "reserve_tokens": {
      "type": "integer",
      "minimum": 0,
      "description": "Tokens reserved from max_context_tokens for prompts and answers."
    },
    "stream": {
      "type": "boolean",
      "default": true,
      "description": "Enable SSE streaming vs JSON response."
    }
  },
  "$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"
        }
      }
    },
    "AgentStatus": {
      "type": "string",
      "enum": [
        "clarification_required",
        "completed",
        "in_progress",
        "incomplete",
        "failed"
      ],
      "description": "Shared bounded-agent execution status"
    },
    "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/WebSearchProviderConfig",
          "description": "Inline web search provider configuration. Prefer web_search_connection for\nconfigured production agents; inline config remains useful for CLI/dev\nrequests. See specs/openapi/antfly/websearch.yaml for provider-specific\noptions.\n"
        },
        "web_search_connection": {
          "type": "string",
          "description": "Name of a configured connections.<id> resource with kind web_search.\nRequest-level tool options may reduce scope, but cannot expand the\nconnection's configured capabilities or policy.\n"
        },
        "fetch_config": {
          "$ref": "#/$defs/FetchConfig",
          "description": "URL fetching configuration. See specs/openapi/antfly/websearch.yaml\nfor available options and security controls.\n"
        },
        "max_tool_iterations": {
          "type": "integer",
          "default": 5,
          "minimum": 1,
          "maximum": 20,
          "description": "Maximum number of tool call iterations per turn.\nPrevents infinite loops in tool execution.\n"
        }
      }
    },
    "CloudflareGeneratorConfig": {
      "type": "object",
      "description": "Cloudflare Workers AI generation. Uses CLOUDFLARE_API_TOKEN or an Antfly secret reference.",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "cloudflare"
          ]
        },
        "account_id": {
          "type": "string",
          "minLength": 1
        },
        "gateway_id": {
          "type": "string",
          "minLength": 1,
          "description": "Optional AI Gateway ID, sent through cf-aig-gateway-id."
        },
        "model": {
          "type": "string",
          "default": "@cf/meta/llama-3.3-70b-instruct-fp8-fast"
        },
        "api_key": {
          "type": "string",
          "writeOnly": true
        },
        "url": {
          "type": "string",
          "description": "Optional deployment-owned endpoint override."
        },
        "max_tokens": {
          "type": "integer",
          "minimum": 1
        },
        "temperature": {
          "type": "number",
          "format": "float",
          "minimum": 0,
          "maximum": 2
        },
        "top_p": {
          "type": "number",
          "format": "float",
          "minimum": 0,
          "maximum": 1
        },
        "frequency_penalty": {
          "type": "number",
          "format": "float",
          "minimum": -2,
          "maximum": 2
        },
        "presence_penalty": {
          "type": "number",
          "format": "float",
          "minimum": -2,
          "maximum": 2
        }
      },
      "required": [
        "provider",
        "account_id",
        "model"
      ]
    },
    "CloudflareRerankerConfig": {
      "type": "object",
      "description": "Cloudflare Workers AI reranking. Uses CLOUDFLARE_API_TOKEN or an Antfly secret reference.",
      "properties": {
        "provider": {
          "type": "string",
          "enum": [
            "cloudflare"
          ]

# --- truncated at 32 KB (245 KB total) ---
# Full source: https://artifacts.apis.io/antfly/json-schema/antfly-research-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.
All 92 tools →

Call it yourself

curl for this page
This JSON Schema
curl "https://apis.io/api/v1/json-schemas/antfly-research-agent-request"
All schemas
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.