Open Response API Documentation

The Agentic Search tool uses AI to guide multi-step vector searches, refining queries and filters iteratively until finding the most comprehensive and relevant results for complex questions.

What It Is

Unlike the simpler File Search tool, the Agentic Search tool employs AI to break down complex questions, perform multiple search iterations, and intelligently refine queries until it finds the most relevant and complete information. It excels at research-oriented tasks requiring deep exploration.

NOTE for better results, we recommend using top models from https://huggingface.co/spaces/lmarena-ai/chatbot-arena-leaderboard

Complex Query: “What are the security implications of using JWT for authentication, and how should we implement proper token validation?”

Iteration 1: Exploring JWT Security

Query: “JWT authentication security implications”

Reasoning: Need to understand security risks before implementation details

Iteration 2: Token Validation Approaches

Query: “JWT token validation best practices”

Reasoning: Initial results showed common attacks, now need implementation guidance

Iteration 3: Implementation Examples

Query: “JWT validation implementation examples”

Reasoning: Need concrete code examples after understanding theoretical concepts

Comprehensive Answer

The search process revealed that JWT security implications include token hijacking, weak signature algorithms, and sensitive data exposure. Proper implementation requires validating the signature with a secure algorithm (at least HS256), checking expiration claims, validating issuer and audience claims, and implementing proper key rotation practices…

How Agentic Search Works

Configuration

Basic configuration requires a query parameter and vector store IDs:

curl --location 'http://localhost:8080/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--header 'x-model-provider: openai' \
--data '{
    "model": "gpt-4o",
    "tools": [
      {
        "type": "agentic_search",
        "vector_store_ids": ["vs_product_docs"]
      }
    ],
    "input": "What approaches can we take to implement rate limiting that scales across multiple service instances?",
    "instructions": "Perform a comprehensive search to evaluate different approaches."
}'

Configuration Parameters

Parameter	Description	Default	Recommended Range
`vector_store_ids`	List of vector store IDs to search	Required	N/A
`max_num_results`	Maximum number of final results to return	5	3-10
`max_iterations`	Maximum number of search iterations	10	5-15
`seed_strategy`	Strategy for initial seed queries	”hybrid"	"topk”, “hybrid”
`alpha`	Balance between vector and keyword search weights	0.5	0.1-0.9
`initial_seed_multiplier`	Multiplier for initial seed generation	3	2-5
`enable_presence_penalty_tuning`	Enable dynamic tuning of presence penalty	false	true/false
`enable_frequency_penalty_tuning`	Enable dynamic tuning of frequency penalty	false	true/false
`enable_temperature_tuning`	Enable dynamic tuning of temperature	false	true/false
`enable_top_p_tuning`	Enable dynamic tuning of top p	false	true/false
`filters`	Optional filters to narrow search results	null	Depends on use case

The Agentic Search tool is designed to work well with default settings for most use cases. Start with minimal configuration and only adjust parameters if you need to fine-tune the behavior for specific scenarios.

Response Format

The Agentic Search tool returns a comprehensive response including:

{
  "data": [
    {
      "file_id": "file_abc123",
      "filename": "architecture/authentication.md",
      "score": 0.94,
      "content": "JWT security implications include potential vulnerabilities if not properly implemented...",
      "annotations": [...]
    },
    {
      "file_id": "file_def456",
      "filename": "security/token-validation.md",
      "score": 0.92,
      "content": "Best practices for JWT validation include signature verification, expiration checking...",
      "annotations": [...]
    }
  ],
  "search_iterations": [
    {
      "iteration": 1,
      "query": "JWT authentication security implications",
      "reasoning": "Need to understand security risks before implementation details"
    },
    {
      "iteration": 2,
      "query": "JWT token validation best practices",
      "reasoning": "Initial results showed common attacks, now need implementation guidance"
    }
  ],
  "knowledge_acquired": "The search process revealed that JWT security implications include token hijacking, weak signature algorithms, and sensitive data exposure..."
}

When to Use It

The Agentic Search tool is designed for complex research scenarios requiring deep exploration across multiple documents.

Recommended For	Consider Alternatives For
Multi-faceted research questions Technical strategy development Comparative analysis of approaches Complex problem-solving Deep topic exploration	Simple factual queries Time-critical questions Resource-constrained environments Questions requiring minimal context

Use Cases for Agentic Search

For simpler, direct queries where immediate results are needed, consider using the File Search Tool instead.

Example Queries

Multi-faceted Research

{
  "query": "What are the security implications of using JWT for authentication, and how should we implement proper token validation?"
}

Comparative Analysis

{
  "query": "Compare the performance characteristics of MongoDB and PostgreSQL for our application's workload pattern"
}

Technical Strategy

{
  "query": "What approaches can we take to implement rate limiting that scales across multiple service instances?"
}

Complex Problem-Solving

{
  "query": "How can we optimize our API's response time for mobile clients with unreliable connections?"
}

Advanced Tuning

Seed Strategy Options

The seed_strategy parameter determines how initial search queries are generated:

“hybrid” (default)

Combines vector and keyword search approaches for balanced results. Best for general-purpose searching across diverse document collections.

”topk”

Uses top-K retrieval, focusing on the most similar documents by vector similarity. Better for specialized document collections with consistent terminology.

Alpha Parameter Tuning

The alpha parameter (0.0-1.0) balances vector search vs. keyword search weights:

More Keyword (0.1)Balanced (0.5)More Semantic (0.9)

Higher values (0.7-0.9): More weight to vector semantic search, better for conceptual questions
Middle values (0.4-0.6): Balanced approach, good for most questions
Lower values (0.1-0.3): More weight to keyword search, better for specific technical terms

If a reranker is enabled in the system configuration, the provided alpha value is ignored and a fixed value of 0.5 is used for pre-reranking result selection only.

Initial Seed Multiplier

This parameter controls how many initial search seeds are generated:

Lower (2)

More focused

Default (3)

Balanced

Higher (5)

More diverse

Dynamic Parameter Tuning

The following parameters enable dynamic adjustment of the underlying model’s parameters based on search results:

Enable Presence/Frequency Penalty Tuning

Enable Temperature/Top-P Tuning

Dynamic parameter tuning options are disabled by default for maximum compatibility with model providers. Enable them only if your model supports these parameters.

Integration Examples

Tool Usage with OpenAI Models

curl --location 'http://localhost:8080/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $OPENAI_API_KEY' \
--header 'x-model-provider: openai' \
--data '{
    "model": "gpt-4o",
    "tools": [{
      "type": "agentic_search",
      "vector_store_ids": ["vs_architecture_docs", "vs_engineering_blogs"],
      "max_num_results": 5,
      "max_iterations": 10,
      "seed_strategy": "hybrid",
      "alpha": 0.7,
      "initial_seed_multiplier": 3,
      "filters": {
        "type": "and",
        "filters": [
          {
            "type": "eq",
            "key": "category",
            "value": "architecture"
          },
          {
            "type": "eq",
            "key": "verified",
            "value": true
          }
        ]
      }
    }],
    "input": "What are the architectural tradeoffs between microservices and monoliths?",
    "instructions": "Provide a comprehensive analysis based on the retrieved information."
}'

The agentic_search tool automatically performs multiple search iterations and provides the results to the AI model in the same request. This creates an advanced RAG experience where the model can access comprehensive research without additional API calls.

GitHub Example Implementation

For a complete working example of the Agentic Search tool, check out this Python example on GitHub. This example demonstrates:

Setting up the RAG system with sample documents
Creating and configuring the AgenticSearchTool
Performing searches with different strategies and parameters
Comparing results from different search approaches
Integration with the OpenAI Agents SDK

Configuring Research Depth

For research tasks requiring different levels of depth, you can adjust the configuration:

async function conductResearchWithDepth(query, depth = "standard") {
  // Configure search parameters based on research depth
  const toolConfig = {
    type: "agentic_search",
    vector_store_ids: ["vs_research_docs", "vs_case_studies"],
    filters: {
      type: "and",
      filters: [
        { type: "eq", key: "verified", value: true }
      ]
    }
  };
  
  // Adjust parameters based on depth requirement
  if (depth === "deep") {
    toolConfig.max_iterations = 15;
    toolConfig.max_num_results = 8;
    toolConfig.alpha = 0.8;  // More semantic focus
    toolConfig.enable_temperature_tuning = true;
  } else if (depth === "quick") {
    toolConfig.max_iterations = 5;
    toolConfig.max_num_results = 3;
    toolConfig.seed_strategy = "topk";
  }
  
  const response = await openai.responses.create({
    model: "gpt-4o",
    tools: [toolConfig],
    input: query,
    instructions: "Provide a comprehensive analysis based on the retrieved information."
  });
  
  return response;
}

Best Practices

Ask Specific Queries

While the Agentic Search tool excels at complex queries, questions should still be specific and focused.

Good Example:

{
  "query": "What are the best practices for implementing a CI/CD pipeline for a microservices architecture deployed on Kubernetes?"
}

Less Effective:

{
  "query": "Tell me about DevOps"
}

Provide Context When Relevant

Include relevant context in your query to help guide the search process.

Good Example:

{
  "query": "We're experiencing memory leaks in our Node.js application running in production. What debugging approaches and tools should we consider?"
}

Less Effective:

{
  "query": "How to fix memory leaks?"
}

Monitor and Adjust Iterations

Think Tool

For logging thoughts and reasoning processes

File Search Tool

For direct vector store searches

When to Choose Agentic Search vs. File Search

The Agentic Search tool shines for complex, multi-faceted queries requiring deep exploration, while File Search is better for direct, factual queries when you know exactly what you’re looking for.

Use Agentic Search when: You need comprehensive research on complex topics, comparative analysis, or multi-step problem solving.
Use File Search when: You need quick answers to specific questions, looking up known information, or when resource constraints are a concern.

Get Started

Announcements

Model Providers

Use Cases & Demos

OpenResponses API

Retrieval (RAG)

Built-In Tools

Agentic Search Tool

What It Is

Configuration

Configuration Parameters

Response Format

When to Use It

Example Queries

Multi-faceted Research

Comparative Analysis

Technical Strategy

Complex Problem-Solving

Advanced Tuning

Seed Strategy Options

“hybrid” (default)

”topk”

Alpha Parameter Tuning

Initial Seed Multiplier

Dynamic Parameter Tuning

Integration Examples

Tool Usage with OpenAI Models

GitHub Example Implementation

Configuring Research Depth

Best Practices

Think Tool

File Search Tool

When to Choose Agentic Search vs. File Search

Get Started

Announcements

Model Providers

Use Cases & Demos

OpenResponses API

Retrieval (RAG)

Built-In Tools

​What It Is

​Configuration

​Configuration Parameters

​Response Format

​When to Use It

​Example Queries

​Multi-faceted Research

​Comparative Analysis

​Technical Strategy

​Complex Problem-Solving

​Advanced Tuning

​Seed Strategy Options

“hybrid” (default)

”topk”

​Alpha Parameter Tuning

​Initial Seed Multiplier

​Dynamic Parameter Tuning

​Integration Examples

​Tool Usage with OpenAI Models

​GitHub Example Implementation

​Configuring Research Depth

​Best Practices

​Related Tools

Think Tool

File Search Tool

When to Choose Agentic Search vs. File Search

What It Is

Configuration

Configuration Parameters

Response Format

When to Use It

Example Queries

Multi-faceted Research

Comparative Analysis

Technical Strategy

Complex Problem-Solving

Advanced Tuning

Seed Strategy Options

Alpha Parameter Tuning

Initial Seed Multiplier

Dynamic Parameter Tuning

Integration Examples

Tool Usage with OpenAI Models

GitHub Example Implementation

Configuring Research Depth

Best Practices

Related Tools