Documentation
¶
Overview ¶
Package declarative provides YAML/JSON-based declarative Agent definition and loading.
It allows users to define Agents in configuration files instead of Go code, then load and convert those definitions into runtime configurations compatible with agent.NewAgentBuilder.
The package intentionally avoids importing the agent package to prevent circular dependencies. Instead, it produces a config map that callers use to wire up the AgentBuilder themselves.
Usage:
loader := declarative.NewYAMLLoader()
def, err := loader.LoadFile("my-agent.yaml")
factory := declarative.NewAgentFactory(logger)
if err := factory.Validate(def); err != nil { ... }
configMap := factory.ToAgentConfig(def)
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentDefinition ¶
type AgentDefinition struct {
// Identity
ID string `yaml:"id" json:"id"`
Name string `yaml:"name" json:"name"`
Type string `yaml:"type,omitempty" json:"type,omitempty"` // "react", "plan_execute", "rewoo", etc.
Description string `yaml:"description,omitempty" json:"description,omitempty"`
Version string `yaml:"version,omitempty" json:"version,omitempty"`
// LLM configuration
Model string `yaml:"model" json:"model"`
Provider string `yaml:"provider,omitempty" json:"provider,omitempty"`
Temperature float64 `yaml:"temperature,omitempty" json:"temperature,omitempty"`
MaxTokens int `yaml:"max_tokens,omitempty" json:"max_tokens,omitempty"`
// Prompt
SystemPrompt string `yaml:"system_prompt,omitempty" json:"system_prompt,omitempty"`
// Tools (string names for simple references, or ToolDefinition for richer config)
Tools []string `yaml:"tools,omitempty" json:"tools,omitempty"`
ToolDefinitions []ToolDefinition `yaml:"tool_definitions,omitempty" json:"tool_definitions,omitempty"`
// Memory configuration
Memory *MemoryConfig `yaml:"memory,omitempty" json:"memory,omitempty"`
// Guardrails configuration
Guardrails *GuardrailsConfig `yaml:"guardrails,omitempty" json:"guardrails,omitempty"`
// Optional feature toggles
Features AgentFeatures `yaml:"features,omitempty" json:"features,omitempty"`
// Metadata
Metadata map[string]string `yaml:"metadata,omitempty" json:"metadata,omitempty"`
}
AgentDefinition is a declarative Agent specification. It extends workflow/dsl.AgentDef with identity, versioning, memory, guardrails, and feature toggles. This struct is designed to be deserialized from YAML or JSON files.
type AgentFactory ¶
type AgentFactory struct {
// contains filtered or unexported fields
}
AgentFactory converts AgentDefinition into a runtime config map compatible with agent.NewAgentBuilder.
It does not import the agent package directly to avoid circular dependencies. Callers use the returned map to construct an Agent via the builder:
configMap := factory.ToAgentConfig(def)
builder := agent.NewAgentBuilder(agent.Config{
ID: configMap["id"].(string),
Name: configMap["name"].(string),
Model: configMap["model"].(string),
// ...
})
func NewAgentFactory ¶
func NewAgentFactory(logger *zap.Logger) *AgentFactory
NewAgentFactory creates a new AgentFactory.
func (*AgentFactory) ToAgentConfig ¶
func (f *AgentFactory) ToAgentConfig(def *AgentDefinition) map[string]interface{}
ToAgentConfig converts an AgentDefinition into a map[string]interface{} that mirrors the fields of agent.Config. Callers use these values to populate agent.Config and call agent.NewAgentBuilder.
Keys match the JSON tags of agent.Config:
"id", "name", "type", "description", "model", "provider", "max_tokens", "temperature", "system_prompt", "tools", "tool_definitions", "memory", "guardrails", "metadata", "enable_reflection", "enable_tool_selection", "enable_prompt_enhancer", "enable_skills", "enable_mcp", "enable_observability", "max_react_iterations"
func (*AgentFactory) Validate ¶
func (f *AgentFactory) Validate(def *AgentDefinition) error
Validate checks that required fields are present and constraints are met.
type AgentFeatures ¶
type AgentFeatures struct {
EnableReflection bool `yaml:"enable_reflection,omitempty" json:"enable_reflection,omitempty"`
EnableToolSelection bool `yaml:"enable_tool_selection,omitempty" json:"enable_tool_selection,omitempty"`
EnablePromptEnhancer bool `yaml:"enable_prompt_enhancer,omitempty" json:"enable_prompt_enhancer,omitempty"`
EnableSkills bool `yaml:"enable_skills,omitempty" json:"enable_skills,omitempty"`
EnableMCP bool `yaml:"enable_mcp,omitempty" json:"enable_mcp,omitempty"`
EnableObservability bool `yaml:"enable_observability,omitempty" json:"enable_observability,omitempty"`
MaxReActIterations int `yaml:"max_react_iterations,omitempty" json:"max_react_iterations,omitempty"`
}
AgentFeatures controls optional Agent capabilities.
type AgentLoader ¶
type AgentLoader interface {
// LoadFile reads a file and parses it into an AgentDefinition.
// Format is auto-detected from the file extension (.yaml, .yml, .json).
LoadFile(path string) (*AgentDefinition, error)
// LoadBytes parses raw bytes into an AgentDefinition.
// format must be "yaml" or "json".
LoadBytes(data []byte, format string) (*AgentDefinition, error)
}
AgentLoader loads AgentDefinition from files or raw bytes.
type GuardrailsConfig ¶
type GuardrailsConfig struct {
MaxRetries int `yaml:"max_retries,omitempty" json:"max_retries,omitempty"`
OnInputFailure string `yaml:"on_input_failure,omitempty" json:"on_input_failure,omitempty"` // "reject", "warn", "ignore"
OnOutputFailure string `yaml:"on_output_failure,omitempty" json:"on_output_failure,omitempty"` // "reject", "warn", "ignore"
}
GuardrailsConfig configures input/output validation guardrails.
type MemoryConfig ¶
type MemoryConfig struct {
Type string `yaml:"type" json:"type"` // "short_term", "long_term", "both"
Capacity int `yaml:"capacity" json:"capacity"` // max number of memory entries
}
MemoryConfig configures the Agent's memory subsystem.
type ToolDefinition ¶
type ToolDefinition struct {
Name string `yaml:"name" json:"name"`
Description string `yaml:"description,omitempty" json:"description,omitempty"`
}
ToolDefinition describes a tool with name and description. Use this when you need richer tool metadata than a plain string name.
type YAMLLoader ¶
type YAMLLoader struct{}
YAMLLoader implements AgentLoader for YAML and JSON formats.
func (*YAMLLoader) LoadBytes ¶
func (l *YAMLLoader) LoadBytes(data []byte, format string) (*AgentDefinition, error)
LoadBytes parses raw bytes in the given format ("yaml" or "json").
func (*YAMLLoader) LoadFile ¶
func (l *YAMLLoader) LoadFile(path string) (*AgentDefinition, error)
LoadFile reads a file and parses it based on extension.
Source Files