Skip to content

Agents

Agents are the core of Hector. Each agent has an LLM, tools, and instructions that define its behavior.

Basic Agent Configuration

Minimal Agent

version: "2"

llms:
  default:
    provider: openai
    model: gpt-4o
    api_key: ${OPENAI_API_KEY}

agents:
  assistant:
    llm: default

This creates an agent at http://localhost:8080/agents/assistant.

Complete Agent

agents:
  assistant:
    name: Customer Support Assistant
    description: Helps customers with product questions
    llm: default
    tools: [search, write_file]
    streaming: true
    visibility: public
    instruction: |
      You are a customer support assistant for ACME Corp.
      Use the search tool to find relevant documentation.
      Be helpful, concise, and professional.

Agent Properties

Basic Properties

name: Display name shown in UI and agent card

agents:
  assistant:
    name: Research Assistant  # Human-readable name

description: Explains the agent's purpose

agents:
  assistant:
    description: Researches topics and synthesizes information

llm: References an LLM configuration

llms:
  fast:
    provider: openai
    model: gpt-4o-mini

  powerful:
    provider: anthropic
    model: claude-haiku-4-5
    api_key: ${ANTHROPIC_API_KEY}

agents:
  assistant:
    llm: powerful

tools: List of available tools

agents:
  assistant:
    tools:
      - search        # Document search
      - read_file     # Read files
      - write_file    # Write files
      - execute_command  # Execute shell commands

Instructions

instruction: System prompt that defines behavior

agents:
  assistant:
    instruction: |
      You are a helpful assistant.

      When searching documents:
      - Use the search tool first
      - Cite sources in your response

      When writing code:
      - Include comments
      - Follow best practices

Supports template placeholders:

agents:
  assistant:
    instruction: |
      You are {role?}.
      User: {user:name}
      Project: {app:project_name}

global_instruction: Applies to all agents in a multi-agent system

agents:
  coordinator:
    global_instruction: |
      All agents must:
      - Cite sources
      - Use UTC timestamps
      - Format code blocks with language tags

Prompt Configuration

For advanced prompt control:

agents:
  assistant:
    prompt:
      role: Senior Software Engineer
      guidance: |
        Focus on:
        - Code quality
        - Performance
        - Security best practices

Streaming

Enable token-by-token streaming:

agents:
  assistant:
    streaming: true  # Default: false

With streaming enabled:

  • Responses stream as they generate
  • Users see output immediately
  • Lower perceived latency

Agent Visibility

Control discoverability and access:

agents:
  # Public agent (default)
  public-assistant:
    visibility: public  # Visible in discovery, HTTP accessible

  # Internal agent
  internal-analyst:
    visibility: internal  # Only visible when authenticated

  # Private agent
  private-helper:
    visibility: private  # Not exposed via HTTP, internal use only

Visibility levels:

  • public (default): Visible in agent discovery, accessible via HTTP
  • internal: Visible only to authenticated users, requires authentication
  • private: Hidden from discovery, not accessible via HTTP (for sub-agents/tools)

Input and Output Modes

Specify supported MIME types:

agents:
  analyst:
    input_modes:
      - text/plain
      - application/json
      - image/png
    output_modes:
      - text/plain
      - application/json

Common modes:

  • text/plain - Plain text
  • application/json - JSON data
  • image/png, image/jpeg - Images
  • audio/mpeg - Audio

Context Management

Manage conversation history to fit within LLM context limits:

Buffer Window Strategy

Keep last N messages:

agents:
  assistant:
    context:
      strategy: buffer_window
      window_size: 20  # Keep last 20 messages

Token Window Strategy

Keep messages within token budget:

agents:
  assistant:
    context:
      strategy: token_window
      budget: 8000         # Max tokens
      preserve_recent: 5   # Always keep last 5 messages

Summary Buffer Strategy

Summarize old messages when exceeding budget:

agents:
  assistant:
    context:
      strategy: summary_buffer
      budget: 8000           # Token budget
      threshold: 0.85        # Summarize at 85% usage
      target: 0.7            # Reduce to 70% after summarizing
      summarizer_llm: fast   # Use cheaper model for summarization

No Strategy (Default)

Include all history (no filtering):

agents:
  assistant:
    context:
      strategy: none  # Default: include all messages

RAG Integration

Auto-Injected Context

Automatically inject relevant documents into prompts:

agents:
  assistant:
    document_stores: [docs, codebase]  # Access specific stores
    include_context: true               # Auto-inject relevant docs
    include_context_limit: 5            # Max 5 documents
    include_context_max_length: 500     # Max 500 chars per doc

When include_context: true:

  • User messages are used to search document stores
  • Top K relevant documents are retrieved
  • Documents are injected into the system prompt
  • Agent receives context automatically

Let the agent decide when to search:

agents:
  assistant:
    document_stores: [docs, codebase]
    tools: [search]  # Agent calls search explicitly

Agent uses search tool when needed:

  • More control over when to search
  • Can search multiple times
  • Can refine search queries

Scoped Access

Limit which document stores an agent can access:

agents:
  # Access specific stores
  researcher:
    document_stores: [docs, codebase]

  # No RAG access
  restricted:
    document_stores: []

  # Access all stores (default)
  admin:
    # Omit document_stores for access to all

Multi-Agent Patterns

Sub-Agents (Pattern 1: Transfer Control)

Create specialized agents that handle specific tasks:

agents:
  coordinator:
    llm: default
    sub_agents: [researcher, writer]
    instruction: |
      Route user requests to specialized agents:
      - Use transfer_to_researcher for research tasks
      - Use transfer_to_writer for content creation

  researcher:
    llm: default
    tools: [search]
    instruction: |
      Research topics thoroughly.
      Return findings to the coordinator.

  writer:
    llm: default
    tools: [write_file]
    instruction: |
      Write high-quality content.
      Save to files when requested.

With sub_agents, transfer tools are auto-created:

  • transfer_to_researcher
  • transfer_to_writer

When called, control transfers to that agent.

Agent Tools (Pattern 2: Callable Tools)

Use agents as tools that return results:

agents:
  analyst:
    llm: default
    agent_tools: [sentiment_analyzer, data_processor]
    instruction: |
      Analyze user input using available tools:
      - sentiment_analyzer: Determines sentiment
      - data_processor: Processes raw data

  sentiment_analyzer:
    llm: default
    instruction: |
      Analyze sentiment and return: positive, negative, or neutral.

  data_processor:
    llm: default
    instruction: |
      Process and format data into structured output.

With agent_tools, tools are created for each agent:

  • Agent maintains control
  • Sub-agent processes input and returns result
  • Result is structured data

Structured Output

Force agents to return JSON matching a schema:

agents:
  classifier:
    llm: default
    structured_output:
      schema:
        type: object
        properties:
          category:
            type: string
            enum: [technical, sales, support]
          priority:
            type: string
            enum: [low, medium, high]
          confidence:
            type: number
            minimum: 0
            maximum: 1
        required: [category, priority, confidence]

Agent responses will match the schema:

{
  "category": "technical",
  "priority": "high",
  "confidence": 0.92
}

Skills (A2A Discovery)

Advertise agent capabilities for federation:

agents:
  specialist:
    skills:
      - id: data-analysis
        name: Data Analysis
        description: Analyzes datasets and generates insights
        tags: [analytics, statistics]
        examples:
          - "Analyze this sales data"
          - "What trends do you see?"

      - id: visualization
        name: Data Visualization
        description: Creates charts and graphs
        tags: [charts, graphs]
        examples:
          - "Create a bar chart"
          - "Visualize this data"

Skills appear in agent card for A2A discovery.

Remote Agents

Connect to external A2A agents:

agents:
  external-specialist:
    type: remote
    url: https://external-service.com
    headers:
      Authorization: Bearer ${API_TOKEN}
    timeout: 30s

Auto-fetch agent card:

agents:
  external-specialist:
    type: remote
    url: https://external-service.com
    agent_card_url: https://external-service.com/.well-known/agent.json

Or use local agent card:

agents:
  external-specialist:
    type: remote
    url: https://external-service.com
    agent_card_file: ./cards/specialist.json

Workflow Agents

Sequential Agents

Run sub-agents in sequence:

agents:
  pipeline:
    type: sequential
    sub_agents: [step1, step2, step3]

  step1:
    instruction: Process input data

  step2:
    instruction: Transform processed data

  step3:
    instruction: Generate final output

Parallel Agents

Run sub-agents in parallel:

agents:
  parallel-processor:
    type: parallel
    sub_agents: [analyzer1, analyzer2, analyzer3]

  analyzer1:
    instruction: Analyze from perspective 1

  analyzer2:
    instruction: Analyze from perspective 2

  analyzer3:
    instruction: Analyze from perspective 3

Results are aggregated and returned.

Loop Agents

Run sub-agents repeatedly:

agents:
  iterative-refiner:
    type: loop
    sub_agents: [refiner]
    max_iterations: 5

  refiner:
    instruction: |
      Refine the content.
      Escalate when satisfactory.

Loops until:

  • Sub-agent escalates (signals completion)
  • max_iterations reached

Examples

Research Assistant

agents:
  researcher:
    name: Research Assistant
    llm: default
    tools: [search, write_file]
    document_stores: [research-docs]
    streaming: true
    instruction: |
      You are a research assistant.

      Process:
      1. Search for relevant documents
      2. Synthesize information
      3. Cite sources
      4. Save findings to files when requested

Customer Support

agents:
  support:
    name: Customer Support
    llm: default
    tools: [search]
    document_stores: [kb]
    include_context: true
    include_context_limit: 3
    context:
      strategy: summary_buffer
      budget: 4000
    instruction: |
      You are a customer support agent.
      Help customers using the knowledge base.
      Be friendly and professional.

Multi-Agent Coordinator

agents:
  coordinator:
    name: Task Coordinator
    llm: default
    sub_agents: [researcher, analyst, writer]
    instruction: |
      Coordinate tasks among specialists:
      - Researcher: Gathers information
      - Analyst: Analyzes data
      - Writer: Creates content

      Route tasks to the appropriate specialist.

  researcher:
    llm: default
    tools: [search]
    visibility: private
    instruction: Research topics and gather information

  analyst:
    llm: default
    agent_tools: [data-processor]
    visibility: private
    instruction: Analyze data and provide insights

  writer:
    llm: default
    tools: [write_file]
    visibility: private
    instruction: Create polished content

Best Practices

Instruction Design

Be specific and actionable:

# ✅ Good
instruction: |
  You are a code reviewer.

  Review process:
  1. Check for security issues
  2. Verify error handling
  3. Assess code clarity
  4. Suggest improvements

  Format responses as:
  - Issues: [list]
  - Suggestions: [list]

# ❌ Bad
instruction: Review code

Tool Selection

Provide necessary tools only:

# ✅ Good - Scoped tools
agents:
  researcher:
    tools: [search, read_file]

# ❌ Bad - Unnecessary tools
agents:
  researcher:
    tools: [search, read_file, write_file, execute_command, delete_file]

Context Management

Choose appropriate strategy for your use case:

# Short conversations: buffer_window
agents:
  chatbot:
    context:
      strategy: buffer_window
      window_size: 20

# Long conversations: summary_buffer
agents:
  assistant:
    context:
      strategy: summary_buffer
      budget: 8000

Visibility

Use visibility for security:

agents:
  # Public-facing
  customer-support:
    visibility: public

  # Internal tools
  admin-assistant:
    visibility: internal

  # Sub-agents/helpers
  data-processor:
    visibility: private

Next Steps