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

Memory Tools

Tool	Description
recall_memory	Retrieve previously saved knowledge during execution. Searches across memory types: fact, preference, insight, procedure, summary
save_memory	Store important information discovered during execution for future recall. Assign a memory type and importance score

Memory tools allow agents to build persistent knowledge over time. For example, an agent can save a user's preferred report format as a preference, then recall it in future conversations without the user repeating themselves.

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)

Parallel Tool Execution

When an agent needs to call multiple tools that don't depend on each other, it executes them concurrently rather than sequentially. This significantly reduces response time for multi-tool tasks.

For example, if an agent needs to search two different collections and query a database, all three calls run at the same time instead of one after another.

Reasoning Trace

Each agent step includes a collapsible "thinking" block that shows the agent's internal reasoning. This transparency lets you understand why the agent chose a particular tool, what it expected to find, and how it interpreted results.

Reasoning traces are visible in the progress display:

[Iteration 1/5]
├── Thinking: The user wants Q4 revenue broken down by region.
│   I'll search financial reports first, then query the sales
│   database for exact figures.
├── Calling: search_documents
│   Query: "Q4 2024 revenue by region"
└── Result: Found 6 documents

Click any thinking block to expand or collapse it. Traces are preserved in conversation history for later review.

Progressive Retrieval

When an agent detects that its initial search results have low confidence or insufficient coverage, it autonomously fetches additional context. The agent re-queries with refined terms, broader scope, or alternative phrasings until it reaches a satisfactory confidence level or exhausts its iteration budget.

This means the agent self-corrects rather than producing a low-quality answer from limited sources.

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...

Canvas Artifacts Creation

Agents can create canvas artifacts — persistent, versioned content objects such as reports, analyses, code files, or structured documents. When an agent produces a substantial piece of content, it can save it as an artifact that you can revisit, edit, and iterate on.

Artifacts are created automatically when the agent determines the output warrants a persistent document. You can also prompt the agent explicitly:

"Create a report summarizing our Q4 performance"
"Write an onboarding checklist for new engineers"
"Draft a project proposal based on these requirements"

See the Canvas & Artifacts page for full details on versioning, diff view, and editing.

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

Agent Instructions

Agent instructions provide contextual guidance that shapes how agents behave. Instructions are scoped to specific teams, collections, or individual agents, and can be filtered by user role.

How Instructions Work

Instructions are injected into the agent's system prompt based on the current context:

• Team-scoped: Apply to all agents within a team (e.g., "Always use formal language")
• Collection-scoped: Apply when the agent searches a specific collection (e.g., "Financial data is in USD unless stated otherwise")
• Agent-scoped: Apply to a single agent instance (e.g., "Focus on technical accuracy over brevity")

Role-Based Filtering

Instructions can be restricted to specific roles. For example, an instruction like "Include cost data in reports" might only apply to users with the Admin or Editor role, while Viewers see a simplified version.

Agent Automations

Automations let you trigger agents on external events without manual intervention. An automation connects a trigger (the event that starts the agent) to a delivery method (where the result goes).

Triggers

Trigger	Description
Cron Schedule	Run on a recurring schedule (e.g., daily summary at 9 AM)
Slack Message	Activate when a message matches a pattern in a Slack channel
Webhook	Activate when an external system sends a webhook event

Delivery Methods

Method	Description
Webhook	POST the agent's response to an endpoint
Slack	Send the response to a Slack channel or thread
Email	Send the response via email

Example Automations

• Daily Digest: Cron trigger at 8 AM, agent summarizes new documents from the past 24 hours, delivers via Slack
• Ticket Triage: Webhook trigger from Zendesk, agent classifies and routes the ticket, delivers via webhook back to Zendesk
• Weekly Report: Cron trigger every Monday, agent compiles metrics from connected databases, delivers via email

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

• Canvas & Artifacts - Persistent content objects
• Integrations - Agent tool integrations
• Knowledge - Manage data sources
• Search - Advanced search features
• API - Agent API reference