Agents

Agents are the core of LEGIONHERCULES. They are AI assistants that can reason, plan, and execute tasks using available tools.

What is an Agent?

An agent in LEGIONHERCULES is an autonomous entity that:

1. Receives tasks - Natural language instructions
2. Reasons - Thinks about how to accomplish the task
3. Uses tools - Executes file operations, bash commands, web searches
4. Responds - Provides results back to the user

Built-in Agents

LEGIONHERCULES comes with three pre-configured agents:

Default Agent

General-purpose agent for everyday tasks.

name: default
description: Default general-purpose agent
tools:
  - file_read
  - file_write
  - file_edit
  - bash
  - web_search

Best for: - General questions - File operations - Web research - Mixed tasks

Coder Agent

Optimized for programming tasks.

name: coder
description: Code-focused agent
system_prompt: |
  You are an expert programmer. You help write, review, and debug code.
  You have access to file operations and bash commands to work with codebases.
  Be concise and provide working code examples.
tools:
  - file_read
  - file_write
  - file_edit
  - bash

Best for: - Writing code - Code review - Debugging - Project setup

Researcher Agent

Optimized for research and information gathering.

name: researcher
description: Research-focused agent with web search
system_prompt: |
  You are a research assistant. You help find information and answer questions.
  You have access to web search to find current information.
  Provide well-sourced answers with citations.
tools:
  - web_search
  - file_read
  - file_write

Best for: - Web research - Fact checking - Information synthesis - Current events

Using Agents

Command Line

# Use default agent
legionhercules chat

# Use coder agent
legionhercules chat --agent coder

# Use researcher agent
legionhercules chat --agent researcher

Programmatically

from legionhercules.core.agent import Agent, AgentConfig
from legionhercules.llm.ollama_provider import OllamaProvider
from legionhercules.tools.base import ToolRegistry

# Create configuration
config = AgentConfig(
    name="my_agent",
    description="Custom agent",
    model="llama3.2",
    system_prompt="You are a helpful assistant.",
    tools=["file_read", "bash"],
)

# Create agent
llm = OllamaProvider(model="llama3.2")
tools = ToolRegistry.create_default_registry()
agent = Agent(config, llm, tools)

# Execute task
from legionhercules.core.task import Task

task = Task(description="Read the README.md file")
result = await agent.execute_task(task)
print(result.output)

Creating Custom Agents

Via Configuration File

Edit ~/.legionhercules/config.yaml:

agents:
  - name: data_analyst
    description: Specialized in data analysis
    system_prompt: |
      You are a data analysis expert. You help analyze datasets,
      create visualizations, and extract insights.
      Always explain your analysis clearly.
    tools:
      - file_read
      - file_write
      - bash
    max_iterations: 15

Via Python API

from legionhercules.config.manager import ConfigManager
from legionhercules.config.settings import AgentSettings

# Get config manager
config = ConfigManager()

# Create new agent
agent = AgentSettings(
    name="data_analyst",
    description="Data analysis specialist",
    system_prompt="You analyze data...",
    tools=["file_read", "bash"],
)

# Add to config
config.add_agent("data_analyst", "Data analyst", "You analyze data...")

Agent Configuration Options

Option	Type	Default	Description
name	str	required	Unique agent name
description	str	""	Agent description
model	str	"llama3.2"	Ollama model to use
temperature	float	0.7	Creativity (0.0-2.0)
max_tokens	int	4096	Max response tokens
system_prompt	str	""	System instructions
tools	list	[]	Enabled tools
max_iterations	int	10	Max tool iterations
timeout_seconds	float	120.0	Task timeout

System Prompts

The system prompt defines the agent's behavior. Tips for writing good system prompts:

Be Specific

# Bad
system_prompt: "You are helpful."

# Good
system_prompt: |
  You are a Python expert. When writing code:
  - Follow PEP 8 style guidelines
  - Include type hints
  - Write docstrings
  - Add error handling

Define Boundaries

system_prompt: |
  You are a code reviewer. Your job is to:
  - Identify bugs and issues
  - Suggest improvements
  - Check for security vulnerabilities

  Do NOT:
  - Rewrite entire files
  - Change functionality without reason
  - Skip explaining your findings

Include Examples

system_prompt: |
  You are a commit message writer.

  Format: <type>: <subject>

  Types:
  - feat: New feature
  - fix: Bug fix
  - docs: Documentation
  - refactor: Code restructuring

  Example: "feat: add user authentication"

Parallel Agent Execution

Run multiple agents simultaneously:

from legionhercules.core.orchestrator import AgentOrchestrator

# Create orchestrator
orchestrator = AgentOrchestrator(llm, tools)

# Create tasks for different agents
tasks = [
    Task(description="Analyze code", context={"agent_name": "coder"}),
    Task(description="Research topic", context={"agent_name": "researcher"}),
]

# Execute in parallel
results = await orchestrator.execute_parallel(tasks)

Best Practices

1. Start Simple - Use the default agent first
2. Specialize - Create agents for specific workflows
3. Limit Tools - Only give agents tools they need
4. Test Prompts - Iterate on system prompts
5. Monitor Usage - Check which agents work best