Skip to content

Programmatic API Reference

Complete reference for building agents programmatically in Go.


Package: github.com/kadirpekel/hector/pkg/hector

All programmatic API builders are in the hector package.


Agent Builder

NewAgent(id string) *AgentBuilder

Creates a new agent builder.

Parameters: - id (string): Unique agent identifier (required)

Returns: *AgentBuilder

Example:

builder := hector.NewAgent("my-agent")

AgentBuilder Methods

Identity

WithName(name string) *AgentBuilder
WithDescription(desc string) *AgentBuilder

Core Components

WithLLMProvider(provider llms.LLMProvider) *AgentBuilder
WithReasoningStrategy(strategy reasoning.ReasoningStrategy) *AgentBuilder
WithWorkingMemory(strategy memory.WorkingMemoryStrategy) *AgentBuilder
WithLongTermMemory(strategy memory.LongTermMemoryStrategy, config memory.LongTermConfig) *AgentBuilder

Services

WithContext(service reasoning.ContextService) *AgentBuilder
WithTask(service reasoning.TaskService) *AgentBuilder
WithSession(service reasoning.SessionService) *AgentBuilder

Prompts

WithSystemPrompt(prompt string) *AgentBuilder
WithPromptSlots(slots *reasoning.PromptSlots) *AgentBuilder

Tools

WithTool(tool tools.Tool) *AgentBuilder
WithTools(tools ...tools.Tool) *AgentBuilder

A2A Configuration

WithA2ACard(card *config.A2ACardConfig) *AgentBuilder
WithPreferredTransport(transport string) *AgentBuilder

Security

WithSecurity(security *config.SecurityConfig) *AgentBuilder

Other

WithRegistry(registry *agent.AgentRegistry) *AgentBuilder
WithBaseURL(url string) *AgentBuilder
WithStructuredOutput(cfg *config.StructuredOutputConfig) *AgentBuilder
WithDocsFolder(folder string) *AgentBuilder
EnableTools(enabled bool) *AgentBuilder

Build

Build() (*agent.Agent, error)

Builds the agent from the builder configuration.


LLM Provider Builder

NewLLMProvider(providerType string) *LLMProviderBuilder

Creates a new LLM provider builder.

Supported Types: - "openai" - OpenAI API - "anthropic" - Anthropic Claude API - "gemini" - Google Gemini API - "ollama" - Local Ollama instance

Example:

builder := hector.NewLLMProvider("openai")

LLMProviderBuilder Methods

Model(model string) *LLMProviderBuilder
APIKey(key string) *LLMProviderBuilder
APIKeyFromEnv(envVar string) *LLMProviderBuilder
Host(host string) *LLMProviderBuilder
Temperature(temp float64) *LLMProviderBuilder  // 0.0-2.0
MaxTokens(max int) *LLMProviderBuilder
Timeout(seconds int) *LLMProviderBuilder
MaxRetries(max int) *LLMProviderBuilder
RetryDelay(seconds int) *LLMProviderBuilder
StructuredOutput(cfg *config.StructuredOutputConfig) *LLMProviderBuilder
WithStructuredOutput(builder *StructuredOutputBuilder) *LLMProviderBuilder
Build() (llms.LLMProvider, error)

Reasoning Builder

NewReasoning(strategyType string) *ReasoningBuilder

Creates a new reasoning strategy builder.

Supported Types: - "chain-of-thought" - Single-agent iterative reasoning - "supervisor" - Multi-agent orchestration

Example:

builder := hector.NewReasoning("chain-of-thought")

ReasoningBuilder Methods

MaxIterations(max int) *ReasoningBuilder
EnableStreaming(enable bool) *ReasoningBuilder
ShowTools(show bool) *ReasoningBuilder
ShowThinking(show bool) *ReasoningBuilder
Build() (reasoning.ReasoningStrategy, error)
GetConfig() ReasoningConfig

Working Memory Builder

NewWorkingMemory(strategy string) *WorkingMemoryBuilder

Creates a new working memory builder.

Supported Strategies: - "buffer" - Fixed-size buffer - "buffer_window" - Fixed message count window - "sliding_window" - Token-based sliding window - "summary_buffer" - Automatic summarization

Example:

builder := hector.NewWorkingMemory("summary_buffer")

WorkingMemoryBuilder Methods

WindowSize(size int) *WorkingMemoryBuilder
Budget(tokens int) *WorkingMemoryBuilder
Threshold(threshold float64) *WorkingMemoryBuilder
Target(target float64) *WorkingMemoryBuilder
WithLLMProvider(provider llms.LLMProvider) *WorkingMemoryBuilder
Build() (memory.WorkingMemoryStrategy, error)

Long-Term Memory Builder

NewLongTermMemory() *LongTermMemoryBuilder

Creates a new long-term memory builder.

Example:

builder := hector.NewLongTermMemory()

LongTermMemoryBuilder Methods

Enabled(enabled bool) *LongTermMemoryBuilder
Collection(name string) *LongTermMemoryBuilder
StorageScope(scope memory.StorageScope) *LongTermMemoryBuilder
BatchSize(size int) *LongTermMemoryBuilder
AutoRecall(enabled bool) *LongTermMemoryBuilder
RecallLimit(limit int) *LongTermMemoryBuilder
WithDatabase(db databases.DatabaseProvider) *LongTermMemoryBuilder
WithEmbedder(embedder embedders.EmbedderProvider) *LongTermMemoryBuilder
Build() (memory.LongTermMemoryStrategy, memory.LongTermConfig, error)

Context Service Builder (RAG)

NewContextService() *ContextServiceBuilder

Creates a new context service builder for RAG.

Example:

builder := hector.NewContextService()

ContextServiceBuilder Methods

WithDatabase(db databases.DatabaseProvider) *ContextServiceBuilder
WithEmbedder(embedder embedders.EmbedderProvider) *ContextServiceBuilder
WithSearchModel(model string) *ContextServiceBuilder
TopK(k int) *ContextServiceBuilder
Threshold(threshold float64) *ContextServiceBuilder
PreserveCase(preserve bool) *ContextServiceBuilder
WithDocumentStores(stores ...*config.DocumentStoreConfig) *ContextServiceBuilder
IncludeContext(include bool) *ContextServiceBuilder
Build() (reasoning.ContextService, error)
GetIncludeContext() bool

Task Service Builder

NewTaskService() *TaskServiceBuilder

Creates a new task service builder.

Example:

builder := hector.NewTaskService()

TaskServiceBuilder Methods

Core Configuration

Backend(backend string) *TaskServiceBuilder  // "memory" or "sql"
WorkerPool(size int) *TaskServiceBuilder
WithSQLConfig(cfg *config.TaskSQLConfig) *TaskServiceBuilder
InputTimeout(seconds int) *TaskServiceBuilder  // Timeout for INPUT_REQUIRED state
Timeout(seconds int) *TaskServiceBuilder      // Timeout for async task execution
Build() (reasoning.TaskService, error)

Human-in-the-Loop (HITL) Configuration

WithHITL(cfg *config.HITLConfig) *TaskServiceBuilder
HITL() *HITLConfigBuilder

HITLConfigBuilder Methods:

Mode(mode string) *HITLConfigBuilder  // "auto", "blocking", or "async"
Build() *config.HITLConfig

Example:

taskBuilder := hector.NewTaskService().
    Backend("sql").
    WorkerPool(10).
    HITL().
        Mode("async").  // Enable async HITL (requires session_store)
        Build()

Checkpoint Configuration

WithCheckpoint(cfg *config.CheckpointConfig) *TaskServiceBuilder
Checkpoint() *CheckpointConfigBuilder

CheckpointConfigBuilder Methods:

Enabled(enabled bool) *CheckpointConfigBuilder
Strategy(strategy string) *CheckpointConfigBuilder  // "event", "interval", or "hybrid"
Interval() *CheckpointIntervalConfigBuilder
Recovery() *CheckpointRecoveryConfigBuilder
Build() *config.CheckpointConfig

CheckpointIntervalConfigBuilder Methods:

EveryNIterations(n int) *CheckpointIntervalConfigBuilder
AfterToolCalls(enabled bool) *CheckpointIntervalConfigBuilder
BeforeLLMCalls(enabled bool) *CheckpointIntervalConfigBuilder
Build() *config.CheckpointIntervalConfig

CheckpointRecoveryConfigBuilder Methods:

AutoResume(enabled bool) *CheckpointRecoveryConfigBuilder
AutoResumeHITL(enabled bool) *CheckpointRecoveryConfigBuilder
ResumeTimeout(seconds int) *CheckpointRecoveryConfigBuilder
Build() *config.CheckpointRecoveryConfig

Example:

taskBuilder := hector.NewTaskService().
    Backend("sql").
    WorkerPool(10).
    Checkpoint().
        Enabled(true).
        Strategy("hybrid").
        Interval().
            EveryNIterations(5).
            AfterToolCalls(true).
            Build().
        Recovery().
            AutoResume(true).
            AutoResumeHITL(false).
            ResumeTimeout(3600).
            Build().
        Build()

Complete Example with HITL and Checkpoint:

// Build session service (required for async HITL)
sessionService := hector.NewSessionService("my-agent").
    Backend("sql").
    SQLConfig().
        Driver("sqlite").
        Database("./sessions.db").
        Build().
    Build()

// Build task service with HITL and checkpoint
taskService := hector.NewTaskService().
    Backend("sql").
    WorkerPool(10).
    InputTimeout(600).
    Timeout(3600).
    SQLConfig().
        Driver("sqlite").
        Database("./tasks.db").
        Build().
    HITL().
        Mode("async").
        Build().
    Checkpoint().
        Enabled(true).
        Strategy("hybrid").
        Interval().
            EveryNIterations(5).
            Build().
        Recovery().
            AutoResume(true).
            ResumeTimeout(3600).
            Build().
        Build().
    Build()

// Build agent with task service
agent, err := hector.NewAgent("assistant").
    WithLLMProvider(llm).
    WithReasoningStrategy(reasoning).
    WithWorkingMemory(workingMemory).
    WithSession(sessionService).
    WithTask(taskService).
    Build()


Session Service Builder

NewSessionService() *SessionServiceBuilder

Creates a new session service builder.

Example:

builder := hector.NewSessionService()

SessionServiceBuilder Methods

Backend(backend string) *SessionServiceBuilder  // "memory" or "sql"
WithSQLConfig(cfg *config.SQLConfig) *SessionServiceBuilder
WithRateLimit(config *config.RateLimitConfig) *SessionServiceBuilder
Build() (reasoning.SessionService, error)

Database Builder

NewDatabase(dbType string) *DatabaseBuilder

Creates a new database provider builder.

Supported Types: - "qdrant" - Qdrant vector database

Example:

builder := hector.NewDatabase("qdrant")

DatabaseBuilder Methods

Host(host string) *DatabaseBuilder
Port(port int) *DatabaseBuilder
APIKey(key string) *DatabaseBuilder
UseTLS(use bool) *DatabaseBuilder
Build() (databases.DatabaseProvider, error)

Embedder Builder

NewEmbedder(embedderType string) *EmbedderBuilder

Creates a new embedder provider builder.

Supported Types: - "openai" - OpenAI embeddings - "ollama" - Local Ollama embeddings

Example:

builder := hector.NewEmbedder("openai")

EmbedderBuilder Methods

Model(model string) *EmbedderBuilder
APIKey(key string) *EmbedderBuilder
APIKeyFromEnv(envVar string) *EmbedderBuilder
Host(host string) *EmbedderBuilder
Build() (embedders.EmbedderProvider, error)

Structured Output Builder

NewStructuredOutput() *StructuredOutputBuilder

Creates a new structured output builder.

Example:

builder := hector.NewStructuredOutput()

StructuredOutputBuilder Methods

Format(format string) *StructuredOutputBuilder  // "json", "yaml", etc.
Schema(schema map[string]interface{}) *StructuredOutputBuilder
Enum(values []string) *StructuredOutputBuilder
Prefill(value string) *StructuredOutputBuilder
PropertyOrdering(order []string) *StructuredOutputBuilder
Build() *config.StructuredOutputConfig

Security Builder

NewSecurityBuilder(cfg *config.SecurityConfig) *SecurityBuilder

Creates a new security configuration builder.

Example:

builder := hector.NewSecurityBuilder(nil)

SecurityBuilder Methods

JWKSURL(url string) *SecurityBuilder
Issuer(issuer string) *SecurityBuilder
Audience(audience string) *SecurityBuilder
WithScheme(name string, scheme *config.SecurityScheme) *SecurityBuilder
Scheme(name string) *SecuritySchemeBuilder
Require(requirement map[string][]string) *SecurityBuilder
Build() *config.SecurityConfig

A2A Card Builder

NewA2ACardBuilder(cfg *config.A2ACardConfig) *A2ACardBuilder

Creates a new A2A card builder.

Example:

builder := hector.NewA2ACardBuilder(nil)

A2ACardBuilder Methods

Version(version string) *A2ACardBuilder
InputModes(modes []string) *A2ACardBuilder
AddInputMode(mode string) *A2ACardBuilder
OutputModes(modes []string) *A2ACardBuilder
AddOutputMode(mode string) *A2ACardBuilder
Skills(skills []config.A2ASkillConfig) *A2ACardBuilder
AddSkill(skill config.A2ASkillConfig) *A2ACardBuilder
Skill() *A2ASkillBuilder
Provider(provider *config.A2AProviderConfig) *A2ACardBuilder
PreferredTransport(transport string) *A2ACardBuilder
DocumentationURL(url string) *A2ACardBuilder
Build() *config.A2ACardConfig

Document Store Builder

NewDocumentStore(name, source string) *DocumentStoreBuilder

Creates a new document store builder. source must be one of: "directory", "sql", or "api".

Example:

// Directory source
builder := hector.NewDocumentStore("docs", "directory").
    Path("./docs").
    ChunkSize(800).
    ChunkOverlap(100).
    IncludePatterns([]string{"*.md", "*.txt"}).
    WatchChanges(true)

// SQL source
sqlBuilder := hector.NewDocumentStoreSQL("mydb").
    Driver("postgres").
    Host("localhost").
    Port(5432).
    Username("user").
    Password("pass")

tableBuilder := hector.NewDocumentStoreSQLTable("articles", []string{"title", "content"}, "id").
    UpdatedColumn("updated_at").
    MetadataColumns([]string{"author", "category"})

builder := hector.NewDocumentStore("articles", "sql").
    WithSQLBuilder(sqlBuilder).
    WithSQLTableBuilder(tableBuilder)

// API source
authBuilder := hector.NewDocumentStoreAPIAuth("bearer").
    Token("my-token")

endpointBuilder := hector.NewDocumentStoreAPIEndpoint("/api/articles").
    ContentField("content").
    IDField("id").
    WithAuthBuilder(authBuilder)

apiBuilder := hector.NewDocumentStoreAPI("https://api.example.com").
    WithAuthBuilder(authBuilder).
    WithEndpointBuilder(endpointBuilder)

builder := hector.NewDocumentStore("api-docs", "api").
    WithAPIBuilder(apiBuilder)

DocumentStoreBuilder Methods

Core Configuration

Path(path string) *DocumentStoreBuilder                    // Required for directory source
IncludePatterns(patterns []string) *DocumentStoreBuilder
ExcludePatterns(patterns []string) *DocumentStoreBuilder
AdditionalExcludes(patterns []string) *DocumentStoreBuilder
WatchChanges(watch bool) *DocumentStoreBuilder             // Directory source only
MaxFileSize(size int64) *DocumentStoreBuilder              // Directory source only
IncrementalIndexing(enabled bool) *DocumentStoreBuilder

Chunking Configuration

ChunkSize(size int) *DocumentStoreBuilder
ChunkOverlap(overlap int) *DocumentStoreBuilder
ChunkStrategy(strategy string) *DocumentStoreBuilder       // "simple", "overlapping", "semantic"

Metadata Configuration

ExtractMetadata(enabled bool) *DocumentStoreBuilder
MetadataLanguages(languages []string) *DocumentStoreBuilder

Performance Configuration

MaxConcurrentFiles(max int) *DocumentStoreBuilder
ShowProgress(show bool) *DocumentStoreBuilder
VerboseProgress(verbose bool) *DocumentStoreBuilder
EnableCheckpoints(enabled bool) *DocumentStoreBuilder
QuietMode(quiet bool) *DocumentStoreBuilder

SQL Configuration

WithSQLConfig(sqlConfig *config.DocumentStoreSQLConfig) *DocumentStoreBuilder
WithSQLBuilder(sqlBuilder *DocumentStoreSQLBuilder) *DocumentStoreBuilder
SQLMaxRows(maxRows int) *DocumentStoreBuilder
WithSQLTable(tableConfig *config.DocumentStoreSQLTableConfig) *DocumentStoreBuilder
WithSQLTableBuilder(tableBuilder *DocumentStoreSQLTableBuilder) *DocumentStoreBuilder

API Configuration

WithAPIConfig(apiConfig *config.DocumentStoreAPIConfig) *DocumentStoreBuilder
WithAPIBuilder(apiBuilder *DocumentStoreAPIBuilder) *DocumentStoreBuilder

Build

Build() (*config.DocumentStoreConfig, error)

DocumentStoreSQLBuilder Methods

NewDocumentStoreSQL(database string) *DocumentStoreSQLBuilder
Driver(driver string) *DocumentStoreSQLBuilder              // "postgres", "mysql", "sqlite3"
Host(host string) *DocumentStoreSQLBuilder
Port(port int) *DocumentStoreSQLBuilder
Username(username string) *DocumentStoreSQLBuilder
Password(password string) *DocumentStoreSQLBuilder
SSLMode(mode string) *DocumentStoreSQLBuilder
Build() (*config.DocumentStoreSQLConfig, error)

DocumentStoreSQLTableBuilder Methods

NewDocumentStoreSQLTable(table string, columns []string, idColumn string) *DocumentStoreSQLTableBuilder
UpdatedColumn(column string) *DocumentStoreSQLTableBuilder
WhereClause(clause string) *DocumentStoreSQLTableBuilder
MetadataColumns(columns []string) *DocumentStoreSQLTableBuilder
Build() (*config.DocumentStoreSQLTableConfig, error)

DocumentStoreAPIBuilder Methods

NewDocumentStoreAPI(baseURL string) *DocumentStoreAPIBuilder
WithAuth(authConfig *config.DocumentStoreAPIAuthConfig) *DocumentStoreAPIBuilder
WithAuthBuilder(authBuilder *DocumentStoreAPIAuthBuilder) *DocumentStoreAPIBuilder
WithEndpoint(endpointConfig *config.DocumentStoreAPIEndpointConfig) *DocumentStoreAPIBuilder
WithEndpointBuilder(endpointBuilder *DocumentStoreAPIEndpointBuilder) *DocumentStoreAPIBuilder
Build() (*config.DocumentStoreAPIConfig, error)

DocumentStoreAPIAuthBuilder Methods

NewDocumentStoreAPIAuth(authType string) *DocumentStoreAPIAuthBuilder  // "bearer", "basic", "apikey"
Token(token string) *DocumentStoreAPIAuthBuilder                      // For bearer auth
Username(username string) *DocumentStoreAPIAuthBuilder                // For basic auth
Password(password string) *DocumentStoreAPIAuthBuilder                 // For basic auth
Header(header string) *DocumentStoreAPIAuthBuilder                    // For apikey auth
Extra(extra map[string]string) *DocumentStoreAPIAuthBuilder
Build() (*config.DocumentStoreAPIAuthConfig, error)

DocumentStoreAPIEndpointBuilder Methods

NewDocumentStoreAPIEndpoint(path string) *DocumentStoreAPIEndpointBuilder
Method(method string) *DocumentStoreAPIEndpointBuilder
Params(params map[string]string) *DocumentStoreAPIEndpointBuilder
Headers(headers map[string]string) *DocumentStoreAPIEndpointBuilder
Body(body string) *DocumentStoreAPIEndpointBuilder
WithAuth(authConfig *config.DocumentStoreAPIAuthConfig) *DocumentStoreAPIEndpointBuilder
WithAuthBuilder(authBuilder *DocumentStoreAPIAuthBuilder) *DocumentStoreAPIEndpointBuilder
IDField(field string) *DocumentStoreAPIEndpointBuilder
ContentField(field string) *DocumentStoreAPIEndpointBuilder
MetadataFields(fields []string) *DocumentStoreAPIEndpointBuilder
UpdatedField(field string) *DocumentStoreAPIEndpointBuilder
WithPagination(paginationConfig *config.DocumentStoreAPIPaginationConfig) *DocumentStoreAPIEndpointBuilder
WithPaginationBuilder(paginationBuilder *DocumentStoreAPIPaginationBuilder) *DocumentStoreAPIEndpointBuilder
Build() (*config.DocumentStoreAPIEndpointConfig, error)

DocumentStoreAPIPaginationBuilder Methods

NewDocumentStoreAPIPagination(paginationType string) *DocumentStoreAPIPaginationBuilder  // "offset", "cursor", "page", "link"
PageParam(param string) *DocumentStoreAPIPaginationBuilder
SizeParam(param string) *DocumentStoreAPIPaginationBuilder
MaxPages(maxPages int) *DocumentStoreAPIPaginationBuilder
PageSize(size int) *DocumentStoreAPIPaginationBuilder
NextField(field string) *DocumentStoreAPIPaginationBuilder
DataField(field string) *DocumentStoreAPIPaginationBuilder
Build() (*config.DocumentStoreAPIPaginationConfig, error)

Observability Builder

NewObservability() *ObservabilityBuilder

Creates a new observability builder for configuring tracing and metrics.

Example:

obsConfig, _ := hector.NewObservability().
    EnableMetrics(true).
    WithTracing(hector.NewTracing().
        Enable(true).
        EndpointURL("http://jaeger:4317").
        SamplingRate(0.1).
        ServiceName("my-app")).
    Build()

// Initialize observability manager
obsMgr := observability.NewManager(obsConfig)
if err := obsMgr.Initialize(context.Background()); err != nil {
    log.Fatal(err)
}

ObservabilityBuilder Methods

EnableMetrics(enabled bool) *ObservabilityBuilder
WithTracing(tracingBuilder *TracingBuilder) *ObservabilityBuilder
Build() (observability.Config, error)

TracingBuilder Methods

NewTracing() *TracingBuilder
Enable(enabled bool) *TracingBuilder
ExporterType(exporterType string) *TracingBuilder
EndpointURL(url string) *TracingBuilder
SamplingRate(rate float64) *TracingBuilder                  // 0.0 to 1.0
ServiceName(name string) *TracingBuilder
Build() (observability.TracerConfig, error)

Config Agent Builder

NewConfigAgentBuilder(cfg *config.Config) (*ConfigAgentBuilder, error)

Creates a builder that converts configuration to agents using the programmatic API.

Example:

cfg, _ := config.LoadConfig(config.LoaderOptions{Path: "agents.yaml"})
builder, _ := hector.NewConfigAgentBuilder(cfg)

ConfigAgentBuilder Methods

BuildAgent(agentID string) (*agent.Agent, error)
BuildAllAgents() (map[string]*agent.Agent, error)
AgentRegistry() *agent.AgentRegistry
ComponentManager() *component.ComponentManager
Config() *config.Config

Runtime Builder

runtime.NewRuntimeBuilder() *RuntimeBuilder

Creates a new runtime builder (from pkg/runtime package).

Example:

builder := runtime.NewRuntimeBuilder()

RuntimeBuilder Methods

WithAgent(agent *agent.Agent) *RuntimeBuilder
WithAgents(agents map[string]*agent.Agent) *RuntimeBuilder
Start() (*Runtime, error)

Helper Functions

boolPtr(b bool) *bool

Returns a pointer to the bool value.

boolValue(b *bool, defaultValue bool) bool

Returns the bool value or default if nil.


Type Definitions

ReasoningConfig

type ReasoningConfig struct {
    Engine          string
    MaxIterations   int
    EnableStreaming *bool
    ShowTools       *bool
    ShowThinking    *bool
}

Examples

See Programmatic API Guide for complete examples.