hector

package module
v1.17.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 31, 2025 License: MIT Imports: 0 Imported by: 0

README 

██╗  ██╗███████╗ ██████╗████████╗ ██████╗ ██████╗ 
██║  ██║██╔════╝██╔════╝╚══██╔══╝██╔═══██╗██╔══██╗
███████║█████╗  ██║        ██║   ██║   ██║██████╔╝
██╔══██║██╔══╝  ██║        ██║   ██║   ██║██╔══██╗
██║  ██║███████╗╚██████╗   ██║   ╚██████╔╝██║  ██║
╚═╝  ╚═╝╚══════╝ ╚═════╝   ╚═╝    ╚═════╝ ╚═╝  ╚═╝

Go Version License A2A Protocol Documentation Go Report Card

Config-first AI agent framework

Build AI agents using YAML configuration or the Go API. Supports multi-agent orchestration, RAG, and A2A protocol.

Documentation | Quick Start | Configuration

Hector Studio (Desktop)

The native desktop GUI for Hector. Manage your agents and workspaces with a rich visual interface.

Quick Start

Hector uses a unified configuration system. You can start with CLI flags (which seed the config) or a config file directly.

Using CLI Flags

go install github.com/verikod/hector/cmd/hector@latest
export OPENAI_API_KEY="sk-..."

hector serve --model gpt-4o --tools --studio

RAG in one command (with MCP parsing optional):

hector serve \
  --model gpt-4o \
  --docs-folder ./documents \
  --mcp-url http://localhost:8000/mcp \
  --mcp-parser-tool convert_document_into_docling_document

Using Config File

cat > config.yaml <<'EOF'
version: "2"
llms:
  default:
    provider: openai
    model: gpt-4o
    api_key: ${OPENAI_API_KEY}
agents:
  assistant:
    llm: default
    tools: [search]
server:
  port: 8080
EOF

hector serve --config config.yaml --studio

Highlights

  • Unified Configuration: CLI flags seed a YAML config file for repeatability. JSON Schema available via hector schema.
  • Programmatic API: Build agents in Go (pkg/api.go), including sub-agents and agent-as-tool patterns.
  • RAG: Folder-based document stores, embedded vector search (chromem), native PDF/DOCX/XLSX parsers, optional MCP parsing (Docling).
  • Vector DBs: Embedded chromem (default), or external (Qdrant, Pinecone, Weaviate, Milvus, Chroma).
  • Persistence: Tasks and sessions can use in-memory or SQL backends (sqlite/postgres/mysql via DSN).
  • Observability: Metrics endpoint and OTLP tracing options.
  • Checkpointing: Optional checkpoint/recovery strategies.
  • Auth: JWT/JWKS (OIDC) support or Shared Secret (Bearer token) at the server layer.
  • Guardrails: Input validation, prompt injection detection, PII redaction, and tool authorization.
  • A2A-native: Uses a2a-go types and JSON-RPC/gRPC endpoints.

Documentation

License

MIT (see LICENSE).

Documentation

Overview

Package hector provides a pure A2A-native declarative AI agent platform.

Hector allows you to build powerful AI agents using pure YAML configuration, without writing any code. It implements the A2A (Agent-to-Agent) protocol for interoperability and provides multi-agent orchestration capabilities.

Quick Start

Install Hector: 

go install github.com/verikod/hector/cmd/hector@latest

Create a simple agent configuration: 

yaml
agents:
  assistant:
    name: "My Assistant"
    llm: "gpt-4o"
    prompt:
      system_role: "You are a helpful assistant"

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

Start the server: 

hector serve --config my-agent.yaml

Using as Go Library

Import the main package for convenience: 

import "github.com/verikod/hector/pkg"

Or import specific packages: 

import (
    "github.com/verikod/hector/pkg/agent"
    "github.com/verikod/hector/pkg/a2a/pb"
    "github.com/verikod/hector/pkg/config"
)

Key Features

  • **Declarative YAML**: Define complete agents without code
  • **A2A Protocol**: Industry-standard agent communication
  • **Multi-Agent Orchestration**: LLM-driven delegation
  • **External Agent Integration**: Connect to remote A2A agents
  • **Built-in Tools**: Search, file ops, commands, todos
  • **RAG Support**: Semantic search with document stores
  • **Plugin System**: Extend with custom LLMs, databases, tools

Architecture

Hector follows a pure A2A architecture: 

User/Client → A2A Server → Agent Registry → Agents (Native/External)

All communication uses the A2A protocol, ensuring interoperability with other A2A-compliant systems.

Alpha Status

Hector is currently in alpha development. APIs may change, and some features are experimental. We welcome feedback and contributions!

Documentation

For complete documentation, see:

License

MIT - See LICENSE for details.

Package hector provides build-time version information. These variables are populated via ldflags during build.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Version is the semantic version (e.g., "v0.1.1").
	// Set via: -X 'github.com/verikod/hector.Version=$(VERSION)'
	Version = "1.16.2"

	// GitCommit is the short git commit hash.
	// Set via: -X 'github.com/verikod/hector.GitCommit=$(GIT_COMMIT)'
	GitCommit = "unknown"

	// BuildDate is the build timestamp in ISO 8601 format.
	// Set via: -X 'github.com/verikod/hector.BuildDate=$(BUILD_DATE)'
	BuildDate = "unknown"
)

Version information set at build time via ldflags. When building with make: make build (uses git describe) When installing via go install: populated from module version

Functions

This section is empty.

Types

This section is empty.

Source Files

View all Source files

Directories

Path Synopsis
cmd
hector command
Command hector is the CLI for Hector pkg.
 Command hector is the CLI for Hector pkg.
pkg
Package pkg provides a config-first AI agent platform with a clean programmatic API.
 Package pkg provides a config-first AI agent platform with a clean programmatic API.
agent
Package agent defines the core agent interfaces and types for Hector v2.
 Package agent defines the core agent interfaces and types for Hector v2.
agent/llmagent
Package llmagent provides an LLM-based agent implementation for Hector v2.
 Package llmagent provides an LLM-based agent implementation for Hector v2.
agent/remoteagent
Package remoteagent provides remote A2A agent support.
 Package remoteagent provides remote A2A agent support.
agent/runneragent
Package runneragent provides a deterministic tool execution agent.
 Package runneragent provides a deterministic tool execution agent.
agent/workflowagent
Package workflowagent provides workflow agents for orchestrating multi-agent flows.
 Package workflowagent provides workflow agents for orchestrating multi-agent flows.
auth
Package auth provides authentication and authorization for Hector v2.
 Package auth provides authentication and authorization for Hector v2.
builder
Package builder provides fluent builder APIs for programmatic agent construction.
 Package builder provides fluent builder APIs for programmatic agent construction.
checkpoint
Package checkpoint provides execution state capture and recovery.
 Package checkpoint provides execution state capture and recovery.
config
Package config provides configuration loading and management for Hector v2.
 Package config provides configuration loading and management for Hector v2.
config/provider
Package provider defines the config source abstraction.
 Package provider defines the config source abstraction.
embedder
Package embedder provides text embedding services for semantic search.
 Package embedder provides text embedding services for semantic search.
examples/programmatic command
Example programmatic demonstrates the comprehensive programmatic API of Hector.
 Example programmatic demonstrates the comprehensive programmatic API of Hector.
examples/weather command
Example weather demonstrates using Hector with MCP tools.
 Example weather demonstrates using Hector with MCP tools.
guardrails
Package guardrails provides composable safety controls for Hector agents.
 Package guardrails provides composable safety controls for Hector agents.
guardrails/input
guardrails/output
guardrails/tool
httpclient
Package httpclient provides an HTTP client with retry, backoff, and rate limit handling.
 Package httpclient provides an HTTP client with retry, backoff, and rate limit handling.
instruction
Package instruction provides instruction templating for Hector v2 agents.
 Package instruction provides instruction templating for Hector v2 agents.
logger
memory
model
Package model defines the LLM interface for Hector v2.
 Package model defines the LLM interface for Hector v2.
model/anthropic
Package anthropic provides an Anthropic Claude LLM implementation.
 Package anthropic provides an Anthropic Claude LLM implementation.
model/gemini
Package gemini implements the model.LLM interface for Google Gemini models.
 Package gemini implements the model.LLM interface for Google Gemini models.
model/ollama
Package ollama provides an Ollama LLM implementation.
 Package ollama provides an Ollama LLM implementation.
model/openai
Package openai provides an OpenAI LLM implementation using the Responses API.
 Package openai provides an OpenAI LLM implementation using the Responses API.
notification
Package notification provides outbound notification dispatching.
 Package notification provides outbound notification dispatching.
observability
Package observability provides OpenTelemetry tracing and Prometheus metrics.
 Package observability provides OpenTelemetry tracing and Prometheus metrics.
rag
Package rag provides Retrieval-Augmented Generation (RAG) capabilities.
 Package rag provides Retrieval-Augmented Generation (RAG) capabilities.
ratelimit
Package ratelimit provides a comprehensive rate limiting system for Hector v2.
 Package ratelimit provides a comprehensive rate limiting system for Hector v2.
runner
Package runner provides the orchestration layer for agent execution.
 Package runner provides the orchestration layer for agent execution.
runtime
Package runtime builds and manages Hector agents from configuration.
 Package runtime builds and manages Hector agents from configuration.
server
make build-release # Production build make install # Install to GOPATH/bin
 make build-release # Production build make install # Install to GOPATH/bin
session
Package session provides session management for Hector v2.
 Package session provides session management for Hector v2.
task
Package task provides task management for Hector v2.
 Package task provides task management for Hector v2.
tool
Package tool defines interfaces for tools that agents can invoke.
 Package tool defines interfaces for tools that agents can invoke.
tool/agenttool
Package agenttool provides a tool that allows an agent to call another agent.
 Package agenttool provides a tool that allows an agent to call another agent.
tool/approvaltool
Package approvaltool provides a Human-in-the-Loop (HITL) tool example.
 Package approvaltool provides a Human-in-the-Loop (HITL) tool example.
tool/commandtool
Package commandtool provides a secure, streaming command execution tool.
 Package commandtool provides a secure, streaming command execution tool.
tool/controltool
Package controltool provides control flow tools for agent reasoning loops.
 Package controltool provides control flow tools for agent reasoning loops.
tool/filetool
tool/functiontool
Package functiontool provides a convenient way to create tools from typed Go functions.
 Package functiontool provides a convenient way to create tools from typed Go functions.
tool/mcptoolset
Package mcptoolset provides a Toolset implementation for MCP servers.
 Package mcptoolset provides a Toolset implementation for MCP servers.
tool/memorytool
tool/searchtool
Package searchtool provides a search tool for agents to query document stores.
 Package searchtool provides a search tool for agents to query document stores.
tool/todotool
tool/webtool
trigger
Package trigger provides scheduled and event-driven agent invocation.
 Package trigger provides scheduled and event-driven agent invocation.
utils
Package utils provides utility functions for v2.
 Package utils provides utility functions for v2.
vector
Package vector provides a unified interface for vector database operations.
 Package vector provides a unified interface for vector database operations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.