roles

package
v0.18.0 Latest Latest
Warning

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

 Go to latest Published: Aug 17, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package roles provides role support for omniagent.

Roles are high-level agent personas that combine skills, workflows, and system prompts into cohesive behaviors. They provide a way to configure agents for specific use cases like "Meeting PM" or "Investment Analyst".

Role Architecture

A role defines:

  • Required and optional skills it needs
  • System prompt modifications for the persona
  • Workflows for multi-step operations

Usage 

// Create a role with its configuration
pmRole := meetingpm.New(meetingpm.Config{
    DefaultConfluenceSpace: "TEAM",
})

// Create the skills the role needs
meetingSkill := meeting.NewSkill(...)
googleSkill := google.NewSkill(...)

// Register role with agent
agent, err := agent.New(config,
    agent.WithRole(pmRole, meetingSkill, googleSkill),
)

Index

Constants

This section is empty.

Variables

View Source 
var ErrBudgetExceeded = errors.New("delegation budget exceeded")

ErrBudgetExceeded is returned when the delegation budget is exceeded.

View Source 
var ErrDelegationDisabled = errors.New("delegation is not enabled for this role")

ErrDelegationDisabled is returned when delegation is not enabled.

View Source 
var ErrNoDelegationRule = errors.New("no delegation rule matches the task")

ErrNoDelegationRule is returned when no delegation rule matches.

View Source 
var ErrPolicyDenied = errors.New("operation denied by policy")

ErrPolicyDenied is returned when a policy blocks an operation.

Functions

func JSONInput added in v0.16.0 

func JSONInput(input map[string]any) (string, error)

JSONInput is a helper to marshal input to JSON for sub-agent processing.

Types

type ActionExecution 

type ActionExecution struct {
	ActionID  string
	Type      string
	Completed bool
	Result    map[string]any
	Error     error
}

ActionExecution represents the execution of a single action.

type BehaviorEngine 

type BehaviorEngine struct {
	// contains filtered or unexported fields
}

BehaviorEngine matches behaviors to the current context.

The engine evaluates behaviors defined in a role's RoleSpec and determines which behaviors are active based on the current context (meeting, chat, autonomous) and any triggered events.

func NewBehaviorEngine 

func NewBehaviorEngine(behaviors []role.Behavior) *BehaviorEngine

NewBehaviorEngine creates a new BehaviorEngine with the given behaviors.

func (*BehaviorEngine) Context 

func (e *BehaviorEngine) Context() role.BehaviorContext

Context returns the current behavior context.

func (*BehaviorEngine) ExecuteBehavior 

func (e *BehaviorEngine) ExecuteBehavior(ctx context.Context, behavior role.Behavior) *BehaviorExecution

ExecuteBehavior runs the actions defined in a behavior. This is a placeholder that returns the actions to be executed. The actual execution happens in the agent runtime.

func (*BehaviorEngine) GetActive 

func (e *BehaviorEngine) GetActive(ctx context.Context) []role.Behavior

GetActive returns all behaviors that are active in the current context. Behaviors are sorted by priority (highest first).

func (*BehaviorEngine) GetBehavior 

func (e *BehaviorEngine) GetBehavior(id string) *role.Behavior

GetBehavior returns a specific behavior by ID. Returns nil if the behavior is not found.

func (*BehaviorEngine) HasBehavior 

func (e *BehaviorEngine) HasBehavior(id string) bool

HasBehavior checks if a behavior with the given ID exists and is enabled.

func (*BehaviorEngine) MatchTrigger 

func (e *BehaviorEngine) MatchTrigger(ctx context.Context, event string) []role.Behavior

MatchTrigger returns behaviors that match a specific event trigger. Only returns behaviors that are both active in the current context and have a matching event trigger.

func (*BehaviorEngine) SetContext 

func (e *BehaviorEngine) SetContext(ctx role.BehaviorContext)

SetContext updates the current behavior context.

type BehaviorExecution 

type BehaviorExecution struct {
	BehaviorID string
	Actions    []ActionExecution
	Completed  bool
	Error      error
}

BehaviorExecution represents the execution of a behavior.

type DelegationExecutor added in v0.16.0 

type DelegationExecutor struct {
	// RoleFactory creates agents for target roles.
	RoleFactory RoleFactory

	// Logger for delegation events.
	Logger *slog.Logger

	// RetryPolicy for failed delegations.
	RetryPolicy *role.DelegationRetryPolicy
	// contains filtered or unexported fields
}

DelegationExecutor executes delegated tasks by spawning sub-agents.

The executor manages the lifecycle of delegated tasks, including:

  • Task queuing and scheduling
  • Sub-agent spawning
  • Result collection and timeout handling
  • Retry logic for failed delegations

func NewDelegationExecutor added in v0.16.0 

func NewDelegationExecutor(factory RoleFactory) *DelegationExecutor

NewDelegationExecutor creates a new executor.

func (*DelegationExecutor) ActiveTasks added in v0.16.0 

func (e *DelegationExecutor) ActiveTasks() int

ActiveTasks returns the number of currently executing tasks.

func (*DelegationExecutor) Cancel added in v0.16.0 

func (e *DelegationExecutor) Cancel(taskID string) error

Cancel cancels an executing task.

func (*DelegationExecutor) Execute added in v0.16.0 

func (e *DelegationExecutor) Execute(ctx context.Context, req *DelegationRequest) error

Execute runs a delegation request asynchronously. Returns immediately; use WaitFor to get the result.

func (*DelegationExecutor) ExecuteBatch added in v0.16.0 

func (e *DelegationExecutor) ExecuteBatch(ctx context.Context, requests []*DelegationRequest) ([]*role.DelegationResult, error)

ExecuteBatch executes multiple delegation requests in parallel. Returns results in the same order as requests.

func (*DelegationExecutor) ExecuteSync added in v0.16.0 

func (e *DelegationExecutor) ExecuteSync(ctx context.Context, req *DelegationRequest) (*role.DelegationResult, error)

ExecuteSync executes a delegation request synchronously. Blocks until the task completes or times out.

func (*DelegationExecutor) GetResult added in v0.16.0 

func (e *DelegationExecutor) GetResult(taskID string) (*role.DelegationResult, bool)

GetResult returns the result for a completed task.

func (*DelegationExecutor) Shutdown added in v0.16.0 

func (e *DelegationExecutor) Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the executor. Waits for active tasks to complete or cancels them after timeout.

func (*DelegationExecutor) Status added in v0.16.0 

func (e *DelegationExecutor) Status(taskID string) (role.DelegationStatus, bool)

Status returns the current status of a task, synchronized with the executor's internal state. Reading DelegationRequest.Status directly races with the background goroutine that updates it; callers that need a task's live status should use this instead.

func (*DelegationExecutor) WaitFor added in v0.16.0 

func (e *DelegationExecutor) WaitFor(ctx context.Context, taskID string) (*role.DelegationResult, error)

WaitFor waits for a task to complete and returns its result.

type DelegationRequest 

type DelegationRequest struct {
	TaskID     string
	TaskType   string
	TargetRole string
	Input      map[string]any
	Timeout    time.Duration
	CreatedAt  time.Time
	Status     role.DelegationStatus
	Result     *role.DelegationResult
}

DelegationRequest represents a request to delegate work to another role.

type Delegator 

type Delegator struct {
	// contains filtered or unexported fields
}

Delegator manages sub-agent delegation based on role rules.

The delegator evaluates delegation rules defined in a role's RoleSpec and determines whether tasks can be delegated to other roles.

func NewDelegator 

func NewDelegator(config *role.DelegationConfig) *Delegator

NewDelegator creates a new Delegator with the given configuration.

func (*Delegator) CanDelegate 

func (d *Delegator) CanDelegate(ctx context.Context, taskType string) (bool, []string)

CanDelegate determines if a task type can be delegated. Returns true and the list of target roles if delegation is possible.

func (*Delegator) Complete 

func (d *Delegator) Complete(req *DelegationRequest)

Complete marks a delegation as completed, freeing budget resources.

func (*Delegator) Delegate 

func (d *Delegator) Delegate(ctx context.Context, taskType, taskID string, input map[string]any) (*DelegationRequest, error)

Delegate prepares a delegation request for a task. Returns a DelegationRequest that can be used to track the delegation.

func (*Delegator) IsAutonomous 

func (d *Delegator) IsAutonomous(taskType string) bool

IsAutonomous checks if a task type can be delegated autonomously.

func (*Delegator) SelectTargetRole 

func (d *Delegator) SelectTargetRole(ctx context.Context, taskType string) (string, error)

SelectTargetRole finds the best role for a given task type. Returns the first matching target role based on rule priority.

type FuncSubAgent added in v0.16.0 

type FuncSubAgent struct {
	ProcessFunc func(ctx context.Context, input map[string]any) (map[string]any, error)
}

FuncSubAgent wraps a function as a SubAgent.

func (*FuncSubAgent) Close added in v0.16.0 

func (f *FuncSubAgent) Close() error

Close implements SubAgent.

func (*FuncSubAgent) Process added in v0.16.0 

func (f *FuncSubAgent) Process(ctx context.Context, input map[string]any) (map[string]any, error)

Process implements SubAgent.

type InMemoryMetricsStore 

type InMemoryMetricsStore struct {
	// contains filtered or unexported fields
}

InMemoryMetricsStore provides an in-memory implementation of MetricsStore. This is suitable for development and testing but not for production use where persistence and scalability are required.

func NewInMemoryMetricsStore 

func NewInMemoryMetricsStore() *InMemoryMetricsStore

NewInMemoryMetricsStore creates a new in-memory metrics store.

func (*InMemoryMetricsStore) Get 

func (s *InMemoryMetricsStore) Get(ctx context.Context, roleID, metricID string) ([]MetricPoint, error)

Get retrieves metric data points.

func (*InMemoryMetricsStore) GetWithLabels 

func (s *InMemoryMetricsStore) GetWithLabels(ctx context.Context, roleID, metricID string, labels map[string]string) ([]MetricPoint, error)

GetWithLabels retrieves metric data points filtered by labels.

func (*InMemoryMetricsStore) Record 

func (s *InMemoryMetricsStore) Record(ctx context.Context, roleID, metricID string, value float64) error

Record stores a metric value.

func (*InMemoryMetricsStore) RecordWithLabels 

func (s *InMemoryMetricsStore) RecordWithLabels(ctx context.Context, roleID, metricID string, value float64, labels map[string]string) error

RecordWithLabels stores a metric value with additional labels.

func (*InMemoryMetricsStore) Summary 

func (s *InMemoryMetricsStore) Summary(ctx context.Context, roleID, metricID string, period time.Duration) (*MetricSummary, error)

Summary returns aggregate statistics for a metric.

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager manages role lifecycle and skill injection.

The enhanced Manager integrates policy enforcement, behavior matching, metrics collection, and delegation capabilities from the role's spec.

func NewManager 

func NewManager(r role.Role, compiledSkills ...compiled.Skill) (*Manager, error)

NewManager creates a new role manager with the given role and skills.

func NewManagerWithMetrics 

func NewManagerWithMetrics(r role.Role, metricsStore MetricsStore, compiledSkills ...compiled.Skill) (*Manager, error)

NewManagerWithMetrics creates a Manager with a custom metrics store.

func (*Manager) CanDelegate 

func (m *Manager) CanDelegate(ctx context.Context, taskType string) (bool, []string)

CanDelegate checks if a task type can be delegated.

func (*Manager) CheckDataAccess 

func (m *Manager) CheckDataAccess(ctx context.Context, dataType string) error

CheckDataAccess validates that a data type can be accessed according to policies. Returns nil if allowed, an error if denied.

func (*Manager) CheckToolAccess 

func (m *Manager) CheckToolAccess(ctx context.Context, toolName string) error

CheckToolAccess validates that a tool can be used according to policies. Returns nil if allowed, an error if denied.

func (*Manager) Close 

func (m *Manager) Close() error

Close closes the role.

func (*Manager) Delegate 

func (m *Manager) Delegate(ctx context.Context, taskType, taskID string, input map[string]any) (*DelegationRequest, error)

Delegate creates a delegation request for a task.

func (*Manager) DelegateAndExecute added in v0.16.0 

func (m *Manager) DelegateAndExecute(ctx context.Context, taskType, taskID string, input map[string]any) (*DelegationRequest, error)

DelegateAndExecute is a convenience method that creates and executes a delegation. Combines Delegate() and ExecuteDelegation() into a single call.

func (*Manager) DelegateAndWait added in v0.16.0 

func (m *Manager) DelegateAndWait(ctx context.Context, taskType, taskID string, input map[string]any) (*role.DelegationResult, error)

DelegateAndWait is a convenience method that delegates, executes, and waits for completion.

func (*Manager) ExecuteDelegation added in v0.16.0 

func (m *Manager) ExecuteDelegation(ctx context.Context, req *DelegationRequest) error

ExecuteDelegation executes a delegation request using the configured executor. Returns an error if no executor is configured.

func (*Manager) ExecuteDelegationSync added in v0.16.0 

func (m *Manager) ExecuteDelegationSync(ctx context.Context, req *DelegationRequest) (*role.DelegationResult, error)

ExecuteDelegationSync executes a delegation request synchronously. Blocks until the task completes or times out.

func (*Manager) Executor added in v0.16.0 

func (m *Manager) Executor() *DelegationExecutor

Executor returns the delegation executor, or nil if not configured.

func (*Manager) GetActiveBehaviors 

func (m *Manager) GetActiveBehaviors(ctx context.Context) []role.Behavior

GetActiveBehaviors returns behaviors active in the current context.

func (*Manager) IncrementMetric 

func (m *Manager) IncrementMetric(ctx context.Context, metricID string) error

IncrementMetric increments a counter metric by 1.

func (*Manager) Init 

func (m *Manager) Init(ctx context.Context) error

Init initializes the role with its skills.

func (*Manager) IsAutonomousDelegation 

func (m *Manager) IsAutonomousDelegation(taskType string) bool

IsAutonomousDelegation checks if a task type can be delegated autonomously.

func (*Manager) MatchBehaviorTrigger 

func (m *Manager) MatchBehaviorTrigger(ctx context.Context, event string) []role.Behavior

MatchBehaviorTrigger returns behaviors matching a specific event.

func (*Manager) OptionalSkills 

func (m *Manager) OptionalSkills() []string

OptionalSkills returns the optional skills for the role, if defined.

func (*Manager) RecordMetric 

func (m *Manager) RecordMetric(ctx context.Context, metricID string, value float64) error

RecordMetric records a metric value.

func (*Manager) RequiresConfirmation 

func (m *Manager) RequiresConfirmation(ctx context.Context, operation string) bool

RequiresConfirmation checks if an operation requires user confirmation.

func (*Manager) Role 

func (m *Manager) Role() role.Role

Role returns the managed role.

func (*Manager) SetBehaviorContext 

func (m *Manager) SetBehaviorContext(ctx role.BehaviorContext)

SetBehaviorContext updates the current behavior context.

func (*Manager) SetExecutor added in v0.16.0 

func (m *Manager) SetExecutor(executor *DelegationExecutor)

SetExecutor sets the delegation executor for running sub-agents.

func (*Manager) Spec 

func (m *Manager) Spec() *role.RoleSpec

Spec returns the role's specification.

func (*Manager) SystemPrompt 

func (m *Manager) SystemPrompt(ctx context.Context) (string, error)

SystemPrompt returns the role's system prompt.

func (*Manager) Workflows 

func (m *Manager) Workflows() []role.Workflow

Workflows returns the role's workflows.

type MapRoleFactory added in v0.16.0 

type MapRoleFactory struct {
	// contains filtered or unexported fields
}

MapRoleFactory is a simple RoleFactory backed by a map of role creators.

func NewMapRoleFactory added in v0.16.0 

func NewMapRoleFactory(creators map[string]func(ctx context.Context) (SubAgent, error)) *MapRoleFactory

NewMapRoleFactory creates a factory from a map of role creators.

func (*MapRoleFactory) AvailableRoles added in v0.16.0 

func (f *MapRoleFactory) AvailableRoles() []string

AvailableRoles implements RoleFactory.

func (*MapRoleFactory) CreateAgent added in v0.16.0 

func (f *MapRoleFactory) CreateAgent(ctx context.Context, roleName string) (SubAgent, error)

CreateAgent implements RoleFactory.

type MetricPoint 

type MetricPoint struct {
	Timestamp time.Time
	Value     float64
	Labels    map[string]string
}

MetricPoint represents a single metric measurement.

type MetricSummary 

type MetricSummary struct {
	MetricID string
	Period   time.Duration
	Count    int64
	Sum      float64
	Min      float64
	Max      float64
	Avg      float64
	P50      float64
	P90      float64
	P99      float64
}

MetricSummary provides aggregate statistics for a metric.

type MetricsCollector 

type MetricsCollector struct {
	// contains filtered or unexported fields
}

MetricsCollector provides a convenient wrapper for recording metrics for a specific role.

func NewMetricsCollector 

func NewMetricsCollector(store MetricsStore, roleID string, metrics []role.MetricDefinition) *MetricsCollector

NewMetricsCollector creates a collector for a specific role.

func (*MetricsCollector) Duration 

func (c *MetricsCollector) Duration(ctx context.Context, metricID string, d time.Duration) error

Duration records a duration metric in seconds.

func (*MetricsCollector) Increment 

func (c *MetricsCollector) Increment(ctx context.Context, metricID string) error

Increment increases a counter metric by 1.

func (*MetricsCollector) Record 

func (c *MetricsCollector) Record(ctx context.Context, metricID string, value float64) error

Record stores a metric value.

type MetricsStore 

type MetricsStore interface {
	// Record stores a metric value.
	Record(ctx context.Context, roleID, metricID string, value float64) error

	// RecordWithLabels stores a metric value with additional labels.
	RecordWithLabels(ctx context.Context, roleID, metricID string, value float64, labels map[string]string) error

	// Get retrieves metric data points.
	Get(ctx context.Context, roleID, metricID string) ([]MetricPoint, error)

	// GetWithLabels retrieves metric data points filtered by labels.
	GetWithLabels(ctx context.Context, roleID, metricID string, labels map[string]string) ([]MetricPoint, error)

	// Summary returns aggregate statistics for a metric.
	Summary(ctx context.Context, roleID, metricID string, period time.Duration) (*MetricSummary, error)
}

MetricsStore collects and stores role metrics.

The store provides methods to record metric values and retrieve historical data for analysis and reporting.

type PolicyEngine 

type PolicyEngine struct {
	// contains filtered or unexported fields
}

PolicyEngine enforces policy rules at runtime.

The engine evaluates policies defined in a role's RoleSpec and determines whether specific operations should be allowed, warned, or blocked.

func NewPolicyEngine 

func NewPolicyEngine(policies []role.Policy) *PolicyEngine

NewPolicyEngine creates a new PolicyEngine with the given policies.

func (*PolicyEngine) CheckDataAccess 

func (e *PolicyEngine) CheckDataAccess(ctx context.Context, dataType string) error

CheckDataAccess determines if a data type can be accessed. Returns nil if allowed, ErrPolicyDenied if blocked.

func (*PolicyEngine) CheckRateLimit 

func (e *PolicyEngine) CheckRateLimit(ctx context.Context, operation string) error

CheckRateLimit determines if an operation is within rate limits. Returns nil if allowed, ErrPolicyDenied if rate limit exceeded.

func (*PolicyEngine) CheckToolAccess 

func (e *PolicyEngine) CheckToolAccess(ctx context.Context, toolName string) error

CheckToolAccess determines if a tool can be used. Returns nil if allowed, ErrPolicyDenied if blocked.

func (*PolicyEngine) RequiresConfirmation 

func (e *PolicyEngine) RequiresConfirmation(ctx context.Context, operation string) bool

RequiresConfirmation determines if an operation needs user confirmation.

type PolicyViolation 

type PolicyViolation struct {
	PolicyID   string
	PolicyName string
	RuleID     string
	TargetType string
	TargetName string
	Message    string
}

PolicyViolation provides details about a policy violation.

func (*PolicyViolation) Error 

func (v *PolicyViolation) Error() string

Error implements the error interface.

func (*PolicyViolation) Unwrap 

func (v *PolicyViolation) Unwrap() error

Unwrap returns the underlying error for errors.Is compatibility.

type RoleFactory added in v0.16.0 

type RoleFactory interface {
	// CreateAgent creates a sub-agent for the given role name.
	// Returns an error if the role is not available.
	CreateAgent(ctx context.Context, roleName string) (SubAgent, error)

	// AvailableRoles returns the list of roles that can be created.
	AvailableRoles() []string
}

RoleFactory creates sub-agents for target roles.

Implementations should return an agent capable of processing tasks for the specified role. The agent should be fully configured with the role's required skills.

type SubAgent added in v0.16.0 

type SubAgent interface {
	// Process executes a task and returns the result.
	Process(ctx context.Context, taskInput map[string]any) (map[string]any, error)

	// Close releases resources held by the sub-agent.
	Close() error
}

SubAgent is the interface for sub-agents that execute delegated tasks.

Source Files

View all Source files

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.