Creating Agents

Configure agents with custom behaviors, tools, and capabilities.

Agent Configuration Options

Basic Settings

Field	Description	Example
Name	Unique identifier	research_agent
Display Name	Human-readable name	Research Assistant
Description	Agent's purpose	Handles research tasks with web search and RAG
Category	Grouping for organization	research, support, analysis

AI Configuration

Field	Description	Example
System Prompt	Defines behavior and personality	You are a research assistant...
Model	LLM model to use	gpt-4, gpt-3.5-turbo
Temperature	Creativity level (0.0-2.0)	0.3 for focused, 0.9 for creative
Max Tokens	Maximum response length	1000

Tool Configuration

Field	Description	Options
Built-in Tools	Available tools to use	rag_search, web_search, code_execution
MCP Servers	Custom tools to include	ORDER_API, WEATHER
Tool Choice	When to use tools	auto, required, none
Max Iterations	Maximum tool iterations	5
Tool Resources	Tool-specific settings	See below

Built-in Tools

RAG Search Tool

{
    "builtin_tools": {
        "rag_search": {
            "default_collection": "docs",
            "top_k": 5,
            "similarity_threshold": 0.7
        }
    }
}

Web Search Tool

{
    "builtin_tools": {
        "web_search": {
            "enabled": true,
            "max_results": 10
        }
    }
}

Code Execution Tool

{
    "builtin_tools": {
        "code_execution": {
            "timeout": 30,
            "allowed_libraries": ["pandas", "numpy", "matplotlib"]
        }
    }
}

MCP Servers

Configure external tools via MCP:

{
    "mcp_servers": ["ORDER_API", "WEATHER"]
}

Tool Choice Strategies

Strategy	Description	Use Case
auto	Agent decides when to use tools	General purpose
required	Must use at least one tool	Data analysis, research
none	Disable tools completely	Simple Q&A

Tool Resources Configuration

Configure resources for specific tools:

{
    "tool_resources": {
        "code_execution": {
            "timeout": 60,
            "allowed_libraries": ["pandas", "numpy", "scikit-learn"]
        },
        "rag_search": {
            "default_top_k": 10  # More results for research
        }
    }
}

Step-by-Step Creation

Step 1: Basic Research Agent

import requests

response = requests.post(
    "http://localhost/api/v1/agent/configs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "research_agent",
        "display_name": "Research Assistant",
        "description": "Agent for research tasks with web search and RAG",
        "category": "research",
        "system_prompt": "You are a research assistant. Use web search for current information and RAG for internal documentation. Always cite your sources.",
        "model": "gpt-4",
        "temperature": 0.3,
        "builtin_tools": ["rag_search", "web_search"],
        "tool_choice": "auto",
        "max_iterations": 5
    }
)

agent_id = response.json()["id"]
print(f"Created agent: {agent_id}")

Step 2: Data Analysis Agent

import requests

response = requests.post(
    "http://localhost/api/v1/agent/configs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "data_analysis_agent",
        "display_name": "Data Analyst",
        "description": "Agent for data analysis with code execution",
        "category": "analysis",
        "system_prompt": "You are a data analyst. Use code execution to process data, generate insights, and create visualizations. Explain your methods clearly.",
        "model": "gpt-4",
        "temperature": 0.2,
        "builtin_tools": ["code_execution"],
        "tool_choice": "required",
        "max_iterations": 10,
        "tool_resources": {
            "code_execution": {
                "timeout": 60,
                "allowed_libraries": ["pandas", "numpy", "matplotlib", "seaborn"]
            }
        }
    }
)

agent_id = response.json()["id"]
print(f"Created agent: {agent_id}")

Step 3: Customer Support Agent with MCP

import requests

response = requests.post(
    "http://localhost/api/v1/agent/configs",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "name": "support_agent",
        "display_name": "Support Bot",
        "description": "Customer support with order lookup and documentation",
        "category": "support",
        "system_prompt": "You are a helpful customer support agent. Use RAG to find answers in documentation. Check order status using the order tool. If needed, transfer to a human agent.",
        "model": "gpt-3.5-turbo",
        "temperature": 0.7,
        "builtin_tools": ["rag_search"],
        "mcp_servers": ["ORDER_API"],
        "tool_choice": "auto"
    }
)

agent_id = response.json()["id"]
print(f"Created agent: {agent_id}")

Best Practices

System Prompt Design

Good:

"You are a research assistant. Use web search for current information and RAG for internal documentation. When you find information, cite your sources clearly. If information is not available in your knowledge base, state that explicitly."

Avoid:

"You are an AI assistant designed to help users accomplish tasks through various tools and APIs..."  # Too verbose
"As a sophisticated language model, I will assist you by..."  # Unnecessary preamble

Temperature Guidelines

Task Type	Recommended Temperature
Factual queries	0.1-0.3
Code generation	0.1-0.3
Creative writing	0.7-1.2
Data analysis	0.2-0.5

Tool Selection

• Start Simple: Begin with few tools, add complexity as needed
• Test Individually: Verify each tool works before combining
• Consider Costs: Some tools (web search, code execution) may incur costs
• Monitor Usage: Track which tools are used most frequently

Agent Examples

Research Assistant

# See examples/rag-web-search.md

Data Analyst

# See examples/code-execution.md

Customer Support

# See examples/multi-step.md

Troubleshooting

Agent Not Using Tools

Problem: Agent doesn't call any tools

Solutions:

• Verify tool_choice is not set to none
• Check tools are in builtin_tools list
• Ensure system prompt encourages tool use: "Use the available tools when appropriate."

Tool Execution Fails

Problem: Tool returns error

Solutions:

• Verify tool configuration (API keys, URLs)
• Check parameters are valid
• Review error messages in agent response
• Retry with different parameters if needed

Max Iterations Exceeded

Problem: Agent hits iteration limit without completing task

Solutions:

• Increase max_iterations in configuration
• Simplify the task for the agent
• Improve system prompt to be more focused
• Review tool outputs for inefficiencies

Next Steps

• Available Tools - Learn about all available tools
• Chat with Your Agent - Start using agents
• Examples - See code samples for common use cases
• Custom Tools via MCP - Build custom tools