Skip to content

Agents

This guide explains how to create and configure AI agents in Raikoo. Agents are dedicated AI entities that can chat with users, process external messages, and execute within workflows. Each agent has its own system prompt, tool configuration, and model settings.

Understanding Agents in Raikoo

Agents in Raikoo are configurable AI assistants that provide specialized capabilities for different tasks and contexts. They offer:

  • Dedicated Identity - Each agent has its own system prompt defining its expertise and behavioral instructions
  • Custom Tool Access - Configure which tools each agent can use, with per-agent customization
  • Model Flexibility - Choose the AI model that best fits the agent's purpose
  • Multi-Context Usage - Use agents in chat, workflows, and external integrations
  • Hierarchical Delegation - Agents can invoke other agents as sub-agents for complex task breakdown

Agents are the primary interface between users and Raikoo's AI capabilities, serving as the foundation for interactive conversations, automated workflows, and external message processing.

Agent Types

Raikoo supports two types of agents based on scope:

Organization-Level Agents

Organization-level agents are shared across all projects within an organization:

  • Global Availability - Accessible from any project in the organization
  • Centralized Management - Configured once and used everywhere
  • Shared Resources - Changes propagate to all projects using the agent
  • Use Cases - General-purpose assistants, company-wide support bots, shared specialists

To create an organization-level agent, leave the Project field empty when configuring the agent.

Project-Level Agents

Project-level agents are scoped to a specific project:

  • Project Isolation - Only available within the designated project
  • Context-Specific - Tailored to project-specific data and workflows
  • Independent Configuration - Changes don't affect other projects
  • Use Cases - Project-specific assistants, specialized analysis agents, domain experts

To create a project-level agent, select a project when configuring the agent.

Accessing Agents

To access agents in your organization:

Organization-Level Agents

  1. Navigate to your organization's dashboard
  2. Click on "Agents" in the left navigation menu under Organization Settings
  3. You'll see a list of all organization-level agents

Project-Level Agents

  1. Navigate to a project
  2. Click on "Agents" in the project navigation menu
  3. You'll see agents scoped to that project, plus organization-level agents

Permissions Required

You need appropriate organization or project permissions to view, create, edit, or delete agents.

Creating an Agent

To create a new agent:

  1. From the Agents page, click the "Create" button
  2. You'll be taken to the agent editor with three tabs:
    • Info - Basic information and model settings
    • System Prompt - The agent's identity and instructions
    • Tools - Tool configuration and access

Configuring Basic Info

In the Info tab:

  1. Name (required)

    • Enter a clear, descriptive name for your agent
    • Example: "Data Analyst", "Customer Support Bot", "Code Reviewer"

  2. Description (optional)

    • Explain what this agent does and when to use it
    • Helps team members understand the agent's purpose
    • Example: "Analyzes sales data and generates insights"

  3. Fallback Model (optional)

    • Select which AI model the agent uses by default
    • If not specified, the system uses the default model for the context
    • Different models offer varying capabilities and performance characteristics

  4. Project (organization-level agents only)

    • Leave empty for a global agent available organization-wide
    • Select a project to scope the agent to that project only

Naming Best Practice

Use names that clearly indicate the agent's role or specialty, such as "SQL Expert" or "Document Summarizer". This helps users quickly identify the right agent for their needs.

Configuring the System Prompt

In the System Prompt tab:

The system prompt is where you define your agent's identity, expertise, and behavioral instructions. This replaces the deprecated "persona" concept and gives you complete control over how the agent behaves.

What to Include in a System Prompt:

  1. Identity and Role

    • Who the agent is and what it does
    • Example: "You are a data analyst specializing in sales metrics"

  2. Expertise and Knowledge

    • What the agent knows about
    • Domain-specific context
    • Example: "You have deep knowledge of SQL, data visualization, and statistical analysis"

  3. Behavioral Instructions

    • How the agent should respond
    • Communication style and tone
    • Example: "Provide concise, data-driven answers with clear explanations"

  4. Constraints and Guidelines

    • What the agent should or shouldn't do
    • Safety and quality guidelines
    • Example: "Always verify data sources before making claims"

Example System Prompt:

You are a SQL expert and data analyst for the company's analytics team.
Your role is to help users query databases, analyze data, and generate
insights from company data.

Your expertise includes:
- Writing efficient SQL queries for PostgreSQL and MySQL
- Data analysis and statistical interpretation
- Creating clear data visualizations and reports
- Understanding business metrics and KPIs

When helping users:
- Always ask clarifying questions if the request is ambiguous
- Explain your SQL queries and analysis approach
- Provide context for your findings and recommendations
- Flag any data quality issues you discover
- Keep responses focused and actionable

Important constraints:
- Never modify production data without explicit confirmation
- Always use read-only queries unless write access is explicitly requested
- Protect sensitive data and follow data privacy guidelines

System Prompt Best Practices

  • Be specific about the agent's role and capabilities
  • Include concrete examples of desired behavior
  • Set clear boundaries and constraints
  • Keep it focused - overly long prompts can dilute effectiveness
  • Test and iterate based on actual agent performance

Configuring Tools

In the Tools tab:

Tools give your agent the ability to perform actions like querying databases, reading files, making API calls, and more. Configure which tools the agent can access and customize their behavior.

Adding a Tool:

  1. Click the "Add Tool" button
  2. Select the tool type from the dropdown
  3. Configure the tool's settings:
    • Custom Function Name (optional) - Override the default tool name
    • Custom Description (optional) - Provide agent-specific instructions for this tool
    • Tool-Specific Configuration - Settings unique to this tool type

Tool Configuration Options:

Different tools have different configuration requirements:

  • Database Tools - Require database connection selection
  • File Tools - May require workspace or file path configuration
  • API Tools - May require authentication credentials
  • Custom Tools - Have tool-specific parameters

Customizing Tool Names and Descriptions:

You can customize how tools appear to the agent:

  • Custom Function Name - Changes the name the agent sees (e.g., query_sales_db instead of sql_query)
  • Custom Description - Provides agent-specific context for when to use this tool

Example: For a sql_query tool connected to a sales database, you might: - Custom name: query_sales_data - Custom description: "Query the sales database for order, customer, and product data. The database contains tables: orders, customers, products, order_items."

Managing Tools:

  • Edit - Click the edit icon to modify tool configuration
  • Remove - Click the delete icon to remove a tool from the agent
  • Reorder - Drag tools to reorder them (visual organization only)

Max Tool Roundtrips:

This setting controls how many tool call iterations the agent can make before it must provide a final response:

  • Default: 1000 (effectively unlimited for most use cases)
  • Purpose: Prevents infinite loops and excessive tool usage
  • When to Adjust: Lower for simple agents, keep high for complex research agents

For a complete list of available tools and their capabilities, see the Tool Reference documentation.

Sub-Agent Capabilities

The "Agent" tool enables hierarchical task delegation by allowing an agent to invoke another agent as a sub-agent. This powerful capability enables complex task breakdown and specialized processing.

How Sub-Agents Work

When an agent has the Agent tool configured:

  1. The parent agent decides a task needs specialized handling
  2. It calls the agent tool with a specific task and context
  3. The sub-agent executes with its own tools and system prompt
  4. The sub-agent returns results to the parent agent
  5. The parent agent incorporates the results into its response

Sub-Agent Configuration

When adding the Agent tool to an agent:

  • Agent (required) - Select which agent to delegate tasks to
  • Model Override (optional) - Override the sub-agent's default model
  • Max Tool Roundtrips (optional) - Limit tool iterations for the sub-agent (default: 10)

Use Cases for Sub-Agents

Specialized Processing: 

Research Agent → Data Analysis Sub-Agent → SQL Expert Sub-Agent

Task Decomposition: 

Project Manager Agent → Code Review Sub-Agent
                     → Documentation Sub-Agent
                     → Testing Sub-Agent

Domain Expertise: 

General Assistant → Legal Compliance Sub-Agent (for legal questions)
                 → Financial Analysis Sub-Agent (for financial data)

Best Practices for Sub-Agents

  • Clear Task Definitions - Teach parent agents to provide specific, well-defined tasks to sub-agents
  • Appropriate Tooling - Give sub-agents the tools they need, not more
  • Limit Nesting Depth - Avoid deeply nested sub-agent chains (2-3 levels max)
  • Set Roundtrip Limits - Use reasonable limits to prevent excessive processing

Using Agents

Agents operate in three primary contexts:

Chat

Interactive conversation with agents via the Chat interface:

  1. Navigate to a project
  2. Open the Chat tool
  3. Select an agent from the agent picker
  4. Start a conversation

In chat mode: - Agents respond to user messages in real-time - Tool usage is transparent with visual indicators - Conversations maintain context across multiple turns - Users can switch between agents during a conversation

Workflows

Agents execute operations within automated workflows:

Agent Operation:

The Agent operation in workflows allows you to: - Send a task to a specific agent - Capture the agent's response - Use agent outputs in subsequent operations - Pass workflow context to the agent

Example workflow: 

1. File Upload Trigger
2. Agent Operation: "Analyze this document and extract key points"
3. Agent Operation: "Generate a summary email based on these key points"
4. Send Email Operation

System Operations:

Agents also power system operations like: - File processing - Data transformation - Content generation - Analysis and reporting

External Triggers

Agents process inbound messages from external systems:

Supported Integrations:

  • Microsoft Teams - Agents respond to Teams messages
  • Slack - Agents handle Slack channel and direct messages
  • Email - Agents process incoming emails
  • Webhooks - Agents respond to custom webhook triggers

How It Works:

  1. External system sends a message to Raikoo
  2. The configured agent receives the message
  3. Agent processes the request using its tools
  4. Agent sends response back to the external system

For details on setting up external integrations, see the External Integrations guide.

Best Practices

Crafting Effective System Prompts

Be Specific: 

Good: "You are a SQL expert who helps users query the sales database."
Bad: "You are helpful."

Include Examples: 

When users ask about sales trends, respond with:
1. A clear summary of the trend
2. Supporting data points
3. Potential explanations

Set Clear Boundaries: 

You can:
- Query read-only data
- Generate reports and visualizations
- Explain data patterns

You cannot:
- Modify production data without confirmation
- Share customer PII
- Make business decisions for users

Choosing Tools

Principle of Least Privilege: - Only enable tools the agent actually needs - Don't give write access unless required - Remove unused tools to reduce complexity

Tool Organization: - Group related tools on specialized agents - Use clear custom names and descriptions - Test tool combinations to ensure they work well together

Common Tool Combinations:

Data Analyst Agent: - SQL Query - SQL Schema - Create Image (for charts) - Write File (for reports)

Document Assistant Agent: - Read File - List Files - Vector Store Query - Markdown to Word

Automation Agent: - HTTP Request - Execute JavaScript - Send Email - Call Workflow

Setting Roundtrip Limits

Conservative (1-5 roundtrips): - Simple Q&A agents - Single-action agents - Tightly scoped assistants

Moderate (10-20 roundtrips): - General-purpose assistants - Multi-step task agents - Data analysis agents

Liberal (100+ roundtrips): - Research agents - Complex automation agents - Exploratory analysis agents

Very High (1000): - Development agents - Deep research agents - Open-ended problem solvers

Testing and Iteration

Start Simple: 1. Create a basic agent with minimal tools 2. Test with representative queries 3. Add tools as needed 4. Refine the system prompt based on performance

Monitor Performance: - Review agent conversations and tool usage - Identify common failure patterns - Adjust system prompts to address issues - Add or modify tools based on actual needs

Iterate Continuously: - Agents improve with refinement - Collect user feedback - Update prompts and tools regularly - Document what works and what doesn't

Security Considerations

Tool Access Control

  • Audit Tool Configuration - Regularly review which agents have access to which tools
  • Limit Write Access - Database and file modification tools should be carefully controlled
  • Sensitive Operations - Require additional confirmation for destructive actions

System Prompt Security

  • Avoid Embedding Secrets - Never put API keys or passwords in system prompts
  • Use Tool Configuration - Store sensitive information in tool configuration, not prompts
  • Review Changes - Track and audit system prompt modifications

Sub-Agent Trust

  • Validate Sub-Agent Configuration - Ensure sub-agents have appropriate tool access
  • Monitor Delegation - Track which agents are calling which sub-agents
  • Set Appropriate Limits - Use roundtrip limits to prevent runaway sub-agent chains

Troubleshooting

Agent Not Responding as Expected

Check System Prompt: - Is it clear and specific? - Does it include relevant context? - Are there conflicting instructions?

Review Tool Configuration: - Does the agent have the tools it needs? - Are tool descriptions clear? - Are tool credentials valid?

Verify Model Selection: - Is the right model selected? - Does the model have the capabilities needed?

Tool Errors

Permission Issues: - Check database connection read-only settings - Verify tool configuration for write access - Ensure credentials are valid

Configuration Problems: - Validate tool-specific settings - Test tools independently - Review error messages in conversation

Performance Issues

Excessive Tool Usage: - Agent making too many tool calls - System prompt may need refinement - Consider lowering max roundtrips

Slow Responses: - Check if tools have timeouts - Verify network connectivity to external resources - Review query complexity for database tools

Next Steps

Now that you understand agents, you can:

  • Create Specialized Agents - Build agents for specific use cases in your organization
  • Configure Tool Access - Enable agents to work with databases, files, and external APIs
  • Build Workflows - Incorporate agents into automated workflows
  • Set Up External Integrations - Connect agents to Teams, Slack, or email
  • Explore Sub-Agent Patterns - Create hierarchical agent systems for complex tasks

Agents are the foundation of Raikoo's AI capabilities. By carefully configuring system prompts, tools, and access controls, you can create powerful AI assistants that serve your organization's specific needs.