AI Agents

Agents are AI-powered assistants that can perform complex, multi-step tasks using a suite of tools. Create custom agents tailored to your specific workflows and research needs.

Overview

ZenSearch agents can:

• Execute multi-step research tasks autonomously
• Use specialized tools for search, database queries, and analysis
• Maintain context across conversation turns
• Provide comprehensive, well-researched answers

Agent Page

Accessing Agents

1. Click Agents in the left sidebar
2. Browse available templates and your custom agents
3. Create new agents or edit existing ones

Interface Sections

Templates

Pre-built agent configurations for common use cases:

• View template details
• See enabled tools
• Preview system prompts
• Click Use Template to create an agent

My Agents

Your custom agent instances:

• Edit agent configuration
• Delete agents
• Start a chat session
• View tool configurations

Creating an Agent

Step 1: Start New Agent

Click Create Agent or Use Template to begin.

Step 2: Configure Basics

Field	Description	Required
Name	Display name for the agent	Yes
Icon	Visual identifier (9 options)	Yes
Description	Brief summary of capabilities	No
System Prompt	Instructions defining agent behavior	Yes
Start Message	Initial greeting or prompt	No

Step 3: Select Tools

Choose which tools the agent can use:

Document Tools

Tool	Description
search_documents	Search across collections
get_document	Retrieve full document content
summarize_document	Generate document summaries

Database Tools

Tool	Description
search_database_schema	Discover database structure
query_database	Execute read-only SQL queries
get_table_info	Get table columns and types

Knowledge Graph Tools

Tool	Description
get_document_entities	Extract entities from documents
search_knowledge_graph	Find entity relationships
get_entity_details	Get detailed entity information

Utility Tools

Tool	Description
calculate	Perform mathematical calculations
get_datetime	Get current date and time

Step 4: Set Knowledge Scope

Optionally filter which collections the agent can access:

1. Click Knowledge Base dropdown
2. Select specific collections
3. Leave empty for all collections

Step 5: Save

Click Save to create your agent.

Writing System Prompts

The system prompt defines your agent's personality and behavior.

Best Practices

1. Define the role clearly

   You are a technical documentation assistant specializing
   in helping developers understand our codebase.

2. Specify capabilities

   You can search documentation, retrieve code examples,
   and explain technical concepts.

3. Set boundaries

   Focus only on technical questions. For HR or policy
   questions, direct users to the appropriate resources.

4. Define response style

   Provide concise, accurate answers with code examples
   when relevant. Always cite your sources.

Example System Prompts

Research Assistant

You are a research assistant helping users find and
synthesize information from company documents.

Capabilities:
- Search across all connected data sources
- Summarize long documents
- Compare information from multiple sources
- Provide cited answers

Guidelines:
- Always cite your sources with specific document names
- If information conflicts, highlight the discrepancy
- Ask clarifying questions when queries are ambiguous
- Provide confidence levels for your answers

Sales Intelligence Agent

You are a sales intelligence agent helping the sales team
understand prospects, deals, and market trends.

You have access to:
- Salesforce CRM data
- HubSpot marketing data
- Company presentations and proposals

When answering questions:
- Provide specific data points with dates
- Compare current metrics to historical data
- Identify trends and patterns
- Suggest actionable insights

Code Expert

You are a code expert for our engineering team.

Capabilities:
- Search code repositories
- Explain complex code patterns
- Find usage examples
- Identify dependencies

Guidelines:
- Include code snippets in your responses
- Link to relevant documentation
- Explain the "why" behind code decisions
- Suggest best practices when appropriate

Using Agents

Starting a Chat

1. Go to Agents page
2. Click Chat on any agent
3. You'll be taken to Ask page with agent activated

Agent Indicator

When an agent is active, you'll see:

• Agent banner with name and icon
• Agent badge on messages
• Different response behavior

Switching Agents

1. Click the agent selector on the Ask page
2. Choose a different agent or disable
3. Agent context switches immediately

Agent Execution

How Agents Work

1. Receive Query: Agent receives your question
2. Plan (if enabled): Creates a strategy
3. Execute: Runs tools iteratively
4. Synthesize: Combines results into answer

Execution Flow

Query → Planning → Tool Execution → Synthesis → Response
          ↓              ↓
       Strategy      Iteration Loop
                    (up to max_iterations)

Iteration Limits

Agents have configurable limits:

Setting	Default	Description
Max Iterations	5	Maximum planning loops
Max Tool Calls	10	Maximum tool invocations
Timeout	60s	Maximum execution time

Observing Progress

During execution, you'll see real-time updates:

[Planning]
Creating a strategy to answer your question...

[Iteration 1/5]
├── Thinking: I need to find revenue data first
├── Calling: search_documents
│   Query: "quarterly revenue 2024"
└── Result: Found 6 documents

[Iteration 2/5]
├── Thinking: Now I need specific Q4 numbers
├── Calling: query_database
│   SQL: "SELECT quarter, revenue FROM sales..."
└── Result: 4 rows returned

[Synthesizing]
Combining information from 6 documents and database query...

Agent Templates

Available Templates

ZenSearch provides templates for common use cases:

Template	Description	Tools
Research Assistant	General research and synthesis	search, summarize
Data Analyst	Database queries and analysis	database tools, calculate
Code Expert	Code search and explanation	search, get_document
Knowledge Navigator	Entity and relationship discovery	knowledge graph tools

Customizing Templates

1. Click Use Template
2. Modify name, description, or prompt
3. Add or remove tools
4. Save as your own agent

Best Practices

Agent Design

1. Single purpose: One agent per major use case
2. Minimal tools: Only enable needed tools
3. Clear prompts: Specific, actionable instructions
4. Scoped access: Limit to relevant collections

Using Agents Effectively

1. Be specific: Detailed questions get better results
2. Provide context: Mention relevant timeframes, projects
3. Review sources: Verify agent findings in cited documents
4. Iterate: Ask follow-up questions for depth

When to Use Agents vs Chat

Use Agent	Use Direct Chat
Multi-step research	Simple fact lookup
Data analysis	Quick questions
Comparative studies	Definition queries
Report generation	Document retrieval

Troubleshooting

Agent Not Responding

1. Check iteration/timeout limits
2. Verify tool permissions
3. Ensure collections have content
4. Try simplifying the question

Incorrect Tool Usage

1. Review system prompt clarity
2. Check tool selection
3. Verify collection scope
4. Adjust prompt instructions

Slow Execution

1. Complex queries take longer
2. Database queries may be slow
3. Large collections need more search time
4. Consider narrowing scope

Next Steps

• Knowledge - Manage data sources
• Search - Advanced search features
• API - Agent API reference