Agentic Search Tool

Tackle complex research questions with AI-guided iterative searching

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”

Iteration 2: Token Validation Approaches

Query: “JWT token validation best practices”

Iteration 3: Implementation Examples

Query: “JWT validation implementation examples”

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:

Basic Configuration

curl --location 'http://localhost:6644/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR_API_KEY' \
--data '{
    "model": "openai@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

Controls automatic tuning of penalties to avoid repetitive content and encourage diversity in search iterations.

• enable_presence_penalty_tuning: Dynamically adjusts presence penalty
• enable_frequency_penalty_tuning: Dynamically adjusts frequency penalty

Enable these options if you notice search iterations getting stuck in repetitive patterns.

Enable Temperature/Top-P Tuning

Controls automatic tuning of sampling parameters to balance creativity and precision.

• enable_temperature_tuning: Dynamically adjusts temperature
• enable_top_p_tuning: Dynamically adjusts top-p sampling

Enable these options for exploratory research where creativity in query refinement is beneficial.

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

curl --location 'http://localhost:6644/v1/responses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $OPENAI_API_KEY' \
--data '{
    "model": "openai@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: "openai@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

For critical research queries, monitor the search iterations and adjust parameters if needed.

• If iterations seem unfocused, consider reducing initial_seed_multiplier
• If iterations aren’t exploring enough aspects, try increasing max_iterations
• If results are too literal, increase alpha for more semantic search weight

Related Tools

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.