> ## Documentation Index > Fetch the complete documentation index at: https://masaic-ai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](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...
## Configuration Basic configuration requires a query parameter and vector store IDs: ```bash Basic Configuration theme={null} 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." }' ``` ```bash Advanced Configuration theme={null} 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_architecture_docs", "vs_code_examples"], "max_num_results": 5, "max_iterations": 8, "seed_strategy": "hybrid", "alpha": 0.7, "initial_seed_multiplier": 3, "enable_temperature_tuning": true } ], "input": "What approaches can we take to implement rate limiting that scales across multiple service instances?", "instructions": "Perform an in-depth analysis of different rate limiting approaches and provide recommendations." }' ``` ### 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: ```json theme={null} { "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
For simpler, direct queries where immediate results are needed, consider using the File Search Tool instead. ## Example Queries ### Multi-faceted Research ```json theme={null} { "query": "What are the security implications of using JWT for authentication, and how should we implement proper token validation?" } ``` ### Comparative Analysis ```json theme={null} { "query": "Compare the performance characteristics of MongoDB and PostgreSQL for our application's workload pattern" } ``` ### Technical Strategy ```json theme={null} { "query": "What approaches can we take to implement rate limiting that scales across multiple service instances?" } ``` ### Complex Problem-Solving ```json theme={null} { "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: 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. 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 ```bash cURL theme={null} 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." }' ``` ```python Python theme={null} from openai import OpenAI client = OpenAI( base_url="http://localhost:6644/v1", api_key="your_openai_api_key" ) response = client.responses.create( 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." ) print(response) ``` ```javascript JavaScript theme={null} import OpenAI from "openai"; const openai = new OpenAI({ baseURL: "http://localhost:6644/v1", apiKey: "your_openai_api_key" }); async function conductResearch() { const response = await openai.responses.create({ 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." }); console.log(response); } conductResearch(); ``` 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](https://github.com/masaic-ai-platform/openai-agents-python/blob/main/examples/open_responses/rag.py). 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: ```javascript theme={null} 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 While the Agentic Search tool excels at complex queries, questions should still be specific and focused. **Good Example**: ```json theme={null} { "query": "What are the best practices for implementing a CI/CD pipeline for a microservices architecture deployed on Kubernetes?" } ``` **Less Effective**: ```json theme={null} { "query": "Tell me about DevOps" } ``` Include relevant context in your query to help guide the search process. **Good Example**: ```json theme={null} { "query": "We're experiencing memory leaks in our Node.js application running in production. What debugging approaches and tools should we consider?" } ``` **Less Effective**: ```json theme={null} { "query": "How to fix memory leaks?" } ``` 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 For logging thoughts and reasoning processes 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.