Skip to content

What is an Agent?

An agent in Hector is an AI-powered entity that can understand requests, reason about them, use tools to accomplish tasks, and provide intelligent responses. Unlike simple chatbots, Hector agents are declaratively configured, tool-enabled, and designed for interoperability.

Key Concepts

Declarative Configuration

Agents are defined entirely in YAML—no code required:

agents:
  assistant:
    name: "My Assistant"
    llm: "gpt-4o"
    prompt:
      system_role: "You are a helpful assistant."
    tools: ["write_file", "search"]

That's it. Hector handles the rest.

Agent-to-Agent (A2A) Protocol

Every Hector agent implements the A2A protocol, enabling:

  • Interoperability - Agents can call other agents across networks
  • Standards-based - Compatible with any A2A-compliant service
  • Distributed systems - Build agent networks spanning multiple servers

Agent Lifecycle

When you send a message to an agent:

  1. Request arrives via REST, gRPC, WebSocket, or CLI
  2. Memory loads - Agent retrieves conversation history
  3. Reasoning begins - LLM processes the request
  4. Tools execute - Agent performs actions if needed
  5. Response returns - Result sent back to client
  6. History saves - Conversation stored for context

Agent Components

Every agent consists of these core components:

1. LLM Provider

The language model that powers the agent's intelligence:

agents:
  assistant:
    llm: "gpt-4o"  # References an LLM configuration

llms:
  gpt-4o:
    type: "openai"
    model: "gpt-4o-mini"
    api_key: "${OPENAI_API_KEY}"

See LLM Providers for details.

2. Prompt

Defines the agent's personality, instructions, and behavior:

agents:
  assistant:
    prompt:
      system_role: |
        You are an expert software engineer.
        Provide clear, concise answers.

See Prompts for details.

3. Memory

Manages conversation history and context:

agents:
  assistant:
    memory:
      working:
        strategy: "buffer_window"
        window_size: 10
      longterm:

        storage_scope: "session"

See Memory for details.

4. Tools

Capabilities the agent can use:

agents:
  assistant:
    tools:
      - "write_file"
      - "execute_command"
      - "search"
      - "agent_call"

See Tools for details.

5. Reasoning Strategy

How the agent thinks and makes decisions:

agents:
  coordinator:
    reasoning:
      strategy: "supervisor"  # For multi-agent orchestration

See Reasoning Strategies for details.

Agent Types

Native Agents

Agents defined in your Hector configuration:

agents:
  assistant:
    # Full agent configuration

These run locally in your Hector instance.

External A2A Agents

Remote agents accessed via the A2A protocol:

agents:
  external_specialist:
    type: "a2a"
    url: "https://external-agent.example.com"
    credentials:
      type: "bearer"
      token: "${EXTERNAL_TOKEN}"

These run on other servers but can be called like local agents.

See Multi-Agent Orchestration for details.

Agent Modes

Hector agents can run in different modes:

Local Mode

Agent runs in-process for a single command:

hector call assistant "Hello"
  • Use when: Quick experiments, CI/CD, scripting
  • Pros: Simple, no server needed
  • Cons: No persistence between calls

Server Mode

Agents hosted as a persistent service:

hector serve --config config.yaml
  • Use when: Production deployments, multiple clients
  • Pros: Persistent, scalable, multi-user
  • Cons: Requires server infrastructure

Client Mode

Connect to a remote Hector server:

hector call assistant "Hello" --server http://remote:8080
  • Use when: Distributed systems, shared agents
  • Pros: Centralized management, resource sharing
  • Cons: Network dependency

See CLI Reference for mode details.

Zero-Config Mode

Hector can create a default agent automatically:

export OPENAI_API_KEY="sk-..."
hector call "Hello"  # No config file needed!

Behind the scenes, Hector creates: - Default agent named "assistant" - OpenAI GPT-4o mini LLM - Basic prompt - No tools enabled

Perfect for quick experiments and prototyping.

Configuration Structure

A complete agent configuration:

# LLM providers
llms:
  gpt-4o:
    type: "openai"
    model: "gpt-4o-mini"
    api_key: "${OPENAI_API_KEY}"
    temperature: 0.7

# Agent definition
agents:
  assistant:
    name: "My Assistant"
    llm: "gpt-4o"

    prompt:
      system_role: |
        You are a helpful assistant.

    tools:
      - "write_file"
      - "search"

    memory:
      working:
        strategy: "buffer_window"
        window_size: 10

    reasoning:
      strategy: "chain_of_thought"

See Configuration Reference for all options.

What Makes Hector Agents Different?

Feature Hector Traditional Frameworks
Configuration Pure YAML Code + config
Interoperability A2A native Custom APIs
Memory Built-in strategies Manual implementation
Multi-agent Native supervisor Custom orchestration
Tools Built-in, MCP, plugins Manual integration
Deployment Three modes Server only

Next Steps

Learn about the core components of agents: