agentops

package
v0.5.1 Latest Latest
Warning

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

 Go to latest Published: Jan 19, 2026 License: MIT Imports: 6 Imported by: 0

Documentation

Overview

Package agentops provides observability for multi-agent systems. It tracks agent lifecycle, workflows, handoffs, and tool invocations, complementing llmops (LLM-specific) and observops (infrastructure).

Architecture

AgentOps operates at a higher level than LLMOps: 

┌─────────────────────────────────────────────────────┐
│                     AgentOps                        │
│  (Workflows, Tasks, Handoffs, Tool Invocations)     │
│                                                     │
│  ┌─────────────────────────────────────────────┐    │
│  │                  LLMOps                     │    │
│  │  (LLM calls, prompts, tokens, completions)  │    │
│  └─────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────┘

Quick Start 

import (
	"github.com/agentplexus/omniobserve/agentops"
	_ "github.com/agentplexus/omniobserve/agentops/postgres"
)

store, err := agentops.Open("postgres",
	agentops.WithDSN("postgres://user:pass@localhost/db"),
)
defer store.Close()

// Start a workflow
workflow, err := store.StartWorkflow(ctx, "statistics-extraction",
	agentops.WithWorkflowInput(map[string]any{"topic": "GDP"}),
)

// Record a task
task, err := store.StartTask(ctx, workflow.ID, "synthesis-agent", "extract",
	agentops.WithTaskType("extraction"),
)

// Complete the task
err = store.CompleteTask(ctx, task.ID,
	agentops.WithTaskOutput(map[string]any{"stats": results}),
)

Event Types

AgentOps tracks several types of events:

  • Workflows: End-to-end processing sessions
  • Tasks: Individual agent tasks within a workflow
  • Handoffs: Agent-to-agent communication
  • Tool Invocations: External tool/API calls
  • Events: Generic extensible events

Index

Constants

View Source 
const (
	StatusPending   = "pending"
	StatusRunning   = "running"
	StatusCompleted = "completed"
	StatusFailed    = "failed"
	StatusCancelled = "cancelled"
)

Status constants

View Source 
const (
	HandoffTypeRequest   = "request"
	HandoffTypeResponse  = "response"
	HandoffTypeBroadcast = "broadcast"
	HandoffTypeDelegate  = "delegate"
)

Handoff type constants

View Source 
const (
	EventCategoryAgent    = "agent"
	EventCategoryWorkflow = "workflow"
	EventCategoryTool     = "tool"
	EventCategoryDomain   = "domain"
	EventCategorySystem   = "system"
)

Event category constants

View Source 
const (
	SeverityDebug = "debug"
	SeverityInfo  = "info"
	SeverityWarn  = "warn"
	SeverityError = "error"
)

Severity constants

View Source 
const (
	EventTypeTaskStarted       = "gen_ai.agent.task.started"
	EventTypeTaskCompleted     = "gen_ai.agent.task.completed"
	EventTypeTaskFailed        = "gen_ai.agent.task.failed"
	EventTypeHandoffInitiated  = "gen_ai.agent.handoff.initiated"
	EventTypeHandoffCompleted  = "gen_ai.agent.handoff.completed"
	EventTypeToolCallInvoked   = "gen_ai.agent.tool_call.invoked"
	EventTypeToolCallCompleted = "gen_ai.agent.tool_call.completed"
	EventTypeWorkflowStarted   = "gen_ai.agent.workflow.started"
	EventTypeWorkflowCompleted = "gen_ai.agent.workflow.completed"
	EventTypeRetryAttempted    = "gen_ai.agent.retry.attempted"
)

Common event types

Variables

View Source 
var (
	// ErrNotFound indicates the requested entity was not found.
	ErrNotFound = errors.New("agentops: not found")

	// ErrMissingDSN indicates a DSN is required but not provided.
	ErrMissingDSN = errors.New("agentops: DSN is required")

	// ErrInvalidStatus indicates an invalid status transition.
	ErrInvalidStatus = errors.New("agentops: invalid status transition")

	// ErrAlreadyCompleted indicates the entity is already completed.
	ErrAlreadyCompleted = errors.New("agentops: already completed")

	// ErrStoreClosed indicates the store has been closed.
	ErrStoreClosed = errors.New("agentops: store is closed")

	// ErrConnectionFailed indicates a connection failure.
	ErrConnectionFailed = errors.New("agentops: connection failed")
)

Sentinel errors for common failure cases.

Functions

func IsAlreadyCompleted 

func IsAlreadyCompleted(err error) bool

IsAlreadyCompleted returns true if the error indicates already completed.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the error indicates a not found condition.

func Providers 

func Providers() []string

Providers returns a sorted list of the names of the registered providers.

func Register 

func Register(name string, factory StoreFactory)

Register makes a store provider available by the provided name. If Register is called twice with the same name or if factory is nil, it panics.

func RegisterInfo 

func RegisterInfo(info ProviderInfo)

RegisterInfo registers metadata about a provider.

func Unregister 

func Unregister(name string)

Unregister removes a provider from the registry. This is primarily useful for testing.

func WrapError 

func WrapError(store, op string, err error) error

WrapError wraps an error with store context.

Types

type ClientConfig 

type ClientConfig struct {
	DSN          string
	MaxOpenConns int
	MaxIdleConns int
	ConnMaxLife  time.Duration
	Debug        bool
	AutoMigrate  bool
}

ClientConfig holds client configuration.

func ApplyClientOptions 

func ApplyClientOptions(opts ...ClientOption) *ClientConfig

ApplyClientOptions applies options to a config.

type ClientOption 

type ClientOption func(*ClientConfig)

ClientOption configures a store client.

func WithAutoMigrate 

func WithAutoMigrate() ClientOption

WithAutoMigrate enables automatic schema migration.

func WithConnMaxLifetime 

func WithConnMaxLifetime(d time.Duration) ClientOption

WithConnMaxLifetime sets the maximum connection lifetime.

func WithDSN 

func WithDSN(dsn string) ClientOption

WithDSN sets the database connection string.

func WithDebug 

func WithDebug() ClientOption

WithDebug enables debug logging.

func WithMaxIdleConns 

func WithMaxIdleConns(n int) ClientOption

WithMaxIdleConns sets the maximum number of idle connections.

func WithMaxOpenConns 

func WithMaxOpenConns(n int) ClientOption

WithMaxOpenConns sets the maximum number of open connections.

type Event 

type Event struct {
	ID            string         `json:"gen_ai.agent.event.id"`
	EventType     string         `json:"gen_ai.agent.event.name"`
	EventCategory string         `json:"gen_ai.agent.event.category"`
	WorkflowID    string         `json:"gen_ai.agent.workflow.id,omitempty"`
	TaskID        string         `json:"gen_ai.agent.task.id,omitempty"`
	AgentID       string         `json:"gen_ai.agent.id,omitempty"`
	TraceID       string         `json:"trace_id,omitempty"`
	SpanID        string         `json:"span_id,omitempty"`
	Severity      string         `json:"gen_ai.agent.event.severity"`
	Data          map[string]any `json:"data,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
	Tags          []string       `json:"tags,omitempty"`
	Source        string         `json:"gen_ai.agent.event.source,omitempty"`
	Version       string         `json:"event.version"`
	Timestamp     time.Time      `json:"timestamp"`
	CreatedAt     time.Time      `json:"created_at"`
}

Event represents a generic event. JSON field names follow OpenTelemetry Semantic Conventions for Agentic AI.

type EventConfig 

type EventConfig struct {
	Category   string
	WorkflowID string
	TaskID     string
	AgentID    string
	TraceID    string
	SpanID     string
	Severity   string
	Data       map[string]any
	Metadata   map[string]any
	Tags       []string
	Source     string
}

EventConfig holds event creation configuration.

func ApplyEventOptions 

func ApplyEventOptions(opts ...EventOption) *EventConfig

ApplyEventOptions applies options to a config.

type EventOption 

type EventOption func(*EventConfig)

EventOption configures event creation.

func WithEventAgent 

func WithEventAgent(agentID string) EventOption

WithEventAgent sets the agent ID.

func WithEventCategory 

func WithEventCategory(category string) EventOption

WithEventCategory sets the event category.

func WithEventData 

func WithEventData(data map[string]any) EventOption

WithEventData sets the event data.

func WithEventMetadata 

func WithEventMetadata(metadata map[string]any) EventOption

WithEventMetadata sets event metadata.

func WithEventSeverity 

func WithEventSeverity(severity string) EventOption

WithEventSeverity sets the severity.

func WithEventSource 

func WithEventSource(source string) EventOption

WithEventSource sets the event source.

func WithEventSpanID 

func WithEventSpanID(spanID string) EventOption

WithEventSpanID sets the span ID.

func WithEventTags 

func WithEventTags(tags ...string) EventOption

WithEventTags sets event tags.

func WithEventTask 

func WithEventTask(taskID string) EventOption

WithEventTask sets the task ID.

func WithEventTraceID 

func WithEventTraceID(traceID string) EventOption

WithEventTraceID sets the trace ID.

func WithEventWorkflow 

func WithEventWorkflow(workflowID string) EventOption

WithEventWorkflow sets the workflow ID.

type EventStore 

type EventStore interface {
	// EmitEvent emits a generic event.
	EmitEvent(ctx context.Context, eventType string, opts ...EventOption) (*Event, error)

	// GetEvent retrieves an event by ID.
	GetEvent(ctx context.Context, id string) (*Event, error)

	// ListEvents lists events with optional filters.
	ListEvents(ctx context.Context, opts ...ListOption) ([]*Event, error)
}

EventStore handles generic event operations.

type Handoff 

type Handoff struct {
	ID               string         `json:"gen_ai.agent.handoff.id"`
	WorkflowID       string         `json:"gen_ai.agent.workflow.id,omitempty"`
	FromAgentID      string         `json:"gen_ai.agent.handoff.from.agent.id"`
	FromAgentType    string         `json:"gen_ai.agent.handoff.from.agent.type,omitempty"`
	ToAgentID        string         `json:"gen_ai.agent.handoff.to.agent.id"`
	ToAgentType      string         `json:"gen_ai.agent.handoff.to.agent.type,omitempty"`
	HandoffType      string         `json:"gen_ai.agent.handoff.type"`
	Status           string         `json:"gen_ai.agent.handoff.status"`
	TraceID          string         `json:"trace_id,omitempty"`
	FromTaskID       string         `json:"gen_ai.agent.handoff.from.task.id,omitempty"`
	ToTaskID         string         `json:"gen_ai.agent.handoff.to.task.id,omitempty"`
	Payload          map[string]any `json:"payload,omitempty"`
	Metadata         map[string]any `json:"metadata,omitempty"`
	PayloadSizeBytes int            `json:"gen_ai.agent.handoff.payload.size"`
	LatencyMs        int64          `json:"gen_ai.agent.handoff.latency,omitempty"`
	ErrorMessage     string         `json:"gen_ai.agent.handoff.error.message,omitempty"`
	InitiatedAt      time.Time      `json:"initiated_at"`
	AcceptedAt       *time.Time     `json:"accepted_at,omitempty"`
	CompletedAt      *time.Time     `json:"completed_at,omitempty"`
	CreatedAt        time.Time      `json:"created_at"`
	UpdatedAt        time.Time      `json:"updated_at"`
}

Handoff represents an agent-to-agent handoff. JSON field names follow OpenTelemetry Semantic Conventions for Agentic AI.

type HandoffConfig 

type HandoffConfig struct {
	WorkflowID    string
	FromAgentType string
	ToAgentType   string
	HandoffType   string
	TraceID       string
	FromTaskID    string
	ToTaskID      string
	Payload       map[string]any
	Metadata      map[string]any
	PayloadSize   int
}

HandoffConfig holds handoff creation configuration.

func ApplyHandoffOptions 

func ApplyHandoffOptions(opts ...HandoffOption) *HandoffConfig

ApplyHandoffOptions applies options to a config.

type HandoffOption 

type HandoffOption func(*HandoffConfig)

HandoffOption configures handoff creation.

func WithFromAgentType 

func WithFromAgentType(agentType string) HandoffOption

WithFromAgentType sets the source agent type.

func WithFromTaskID 

func WithFromTaskID(taskID string) HandoffOption

WithFromTaskID sets the source task ID.

func WithHandoffMetadata 

func WithHandoffMetadata(metadata map[string]any) HandoffOption

WithHandoffMetadata sets metadata.

func WithHandoffPayload 

func WithHandoffPayload(payload map[string]any) HandoffOption

WithHandoffPayload sets the payload.

func WithHandoffPayloadSize 

func WithHandoffPayloadSize(size int) HandoffOption

WithHandoffPayloadSize sets the payload size in bytes.

func WithHandoffTraceID 

func WithHandoffTraceID(traceID string) HandoffOption

WithHandoffTraceID sets the trace ID.

func WithHandoffType 

func WithHandoffType(handoffType string) HandoffOption

WithHandoffType sets the handoff type.

func WithHandoffWorkflow 

func WithHandoffWorkflow(workflowID string) HandoffOption

WithHandoffWorkflow sets the workflow ID.

func WithHandoffWorkflowID 

func WithHandoffWorkflowID(workflowID string) HandoffOption

WithHandoffWorkflowID is an alias for WithHandoffWorkflow.

func WithToAgentType 

func WithToAgentType(agentType string) HandoffOption

WithToAgentType sets the target agent type.

type HandoffStore 

type HandoffStore interface {
	// RecordHandoff records a handoff between agents.
	RecordHandoff(ctx context.Context, fromAgentID, toAgentID string, opts ...HandoffOption) (*Handoff, error)

	// GetHandoff retrieves a handoff by ID.
	GetHandoff(ctx context.Context, id string) (*Handoff, error)

	// UpdateHandoff updates handoff status.
	UpdateHandoff(ctx context.Context, id string, opts ...HandoffUpdateOption) error

	// ListHandoffs lists handoffs with optional filters.
	ListHandoffs(ctx context.Context, opts ...ListOption) ([]*Handoff, error)
}

HandoffStore handles agent handoff operations.

type HandoffUpdateConfig 

type HandoffUpdateConfig struct {
	Status       string
	ToTaskID     string
	ErrorMessage string
	Latency      int64
}

HandoffUpdateConfig holds handoff update configuration.

func ApplyHandoffUpdateOptions 

func ApplyHandoffUpdateOptions(opts ...HandoffUpdateOption) *HandoffUpdateConfig

ApplyHandoffUpdateOptions applies options to a config.

type HandoffUpdateOption 

type HandoffUpdateOption func(*HandoffUpdateConfig)

HandoffUpdateOption configures handoff updates.

func WithHandoffError 

func WithHandoffError(msg string) HandoffUpdateOption

WithHandoffError sets the error message.

func WithHandoffStatus 

func WithHandoffStatus(status string) HandoffUpdateOption

WithHandoffStatus sets the status.

func WithHandoffToTaskID 

func WithHandoffToTaskID(taskID string) HandoffUpdateOption

WithHandoffToTaskID sets the target task ID.

func WithHandoffUpdateError 

func WithHandoffUpdateError(msg string) HandoffUpdateOption

WithHandoffUpdateError sets the error message.

func WithHandoffUpdateLatency 

func WithHandoffUpdateLatency(latency int64) HandoffUpdateOption

WithHandoffUpdateLatency sets the handoff latency.

func WithHandoffUpdateStatus 

func WithHandoffUpdateStatus(status string) HandoffUpdateOption

WithHandoffUpdateStatus is an alias for WithHandoffStatus.

type ListConfig 

type ListConfig struct {
	Limit      int
	Offset     int
	WorkflowID string
	TaskID     string
	AgentID    string
	Status     string
	EventType  string
	StartTime  *time.Time
	EndTime    *time.Time
	OrderBy    string
	OrderDesc  bool
}

ListConfig holds list query configuration.

func ApplyListOptions 

func ApplyListOptions(opts ...ListOption) *ListConfig

ApplyListOptions applies options to a config.

type ListOption 

type ListOption func(*ListConfig)

ListOption configures list queries.

func WithFilterAgent 

func WithFilterAgent(agentID string) ListOption

WithFilterAgent filters by agent ID.

func WithFilterEventType 

func WithFilterEventType(eventType string) ListOption

WithFilterEventType filters by event type.

func WithFilterStatus 

func WithFilterStatus(status string) ListOption

WithFilterStatus filters by status.

func WithFilterTask 

func WithFilterTask(taskID string) ListOption

WithFilterTask filters by task ID.

func WithFilterTimeRange 

func WithFilterTimeRange(start, end time.Time) ListOption

WithFilterTimeRange filters by time range.

func WithFilterWorkflow 

func WithFilterWorkflow(workflowID string) ListOption

WithFilterWorkflow filters by workflow ID.

func WithLimit 

func WithLimit(limit int) ListOption

WithLimit sets the result limit.

func WithOffset 

func WithOffset(offset int) ListOption

WithOffset sets the pagination offset.

func WithOrderBy 

func WithOrderBy(field string, desc bool) ListOption

WithOrderBy sets the ordering field.

type ProviderInfo 

type ProviderInfo struct {
	Name        string
	Description string
	Features    []string
}

ProviderInfo contains metadata about a registered provider.

func AllProviderInfo 

func AllProviderInfo() []ProviderInfo

AllProviderInfo returns metadata for all registered providers.

func GetProviderInfo 

func GetProviderInfo(name string) (ProviderInfo, bool)

GetProviderInfo returns metadata about a registered provider.

type Store 

type Store interface {
	WorkflowStore
	TaskStore
	HandoffStore
	ToolInvocationStore
	EventStore

	// Close closes the store connection.
	Close() error

	// Ping checks the connection to the store.
	Ping(ctx context.Context) error
}

Store is the main interface for AgentOps storage backends.

func MustOpen 

func MustOpen(name string, opts ...ClientOption) Store

MustOpen is like Open but panics on error.

func Open 

func Open(name string, opts ...ClientOption) (Store, error)

Open opens a store specified by its provider name.

Most users will use a specific provider package import like: 

import _ "github.com/agentplexus/omniobserve/agentops/postgres"

And then open it with: 

store, err := agentops.Open("postgres",
	agentops.WithDSN("postgres://user:pass@localhost/db"),
)

type StoreError 

type StoreError struct {
	Store string
	Op    string
	Err   error
}

StoreError wraps errors from a specific store.

func (*StoreError) Error 

func (e *StoreError) Error() string

func (*StoreError) Unwrap 

func (e *StoreError) Unwrap() error

type StoreFactory 

type StoreFactory func(opts ...ClientOption) (Store, error)

StoreFactory creates a new Store instance with the given options.

type Task 

type Task struct {
	ID               string         `json:"gen_ai.agent.task.id"`
	WorkflowID       string         `json:"gen_ai.agent.workflow.id,omitempty"`
	AgentID          string         `json:"gen_ai.agent.id"`
	AgentType        string         `json:"gen_ai.agent.type,omitempty"`
	TaskType         string         `json:"gen_ai.agent.task.type"`
	Name             string         `json:"gen_ai.agent.task.name"`
	Status           string         `json:"gen_ai.agent.task.status"`
	TraceID          string         `json:"trace_id,omitempty"`
	SpanID           string         `json:"span_id,omitempty"`
	ParentSpanID     string         `json:"gen_ai.agent.task.parent_id,omitempty"`
	Input            map[string]any `json:"input,omitempty"`
	Output           map[string]any `json:"output,omitempty"`
	Metadata         map[string]any `json:"metadata,omitempty"`
	LLMCallCount     int            `json:"gen_ai.agent.task.llm.call_count"`
	ToolCallCount    int            `json:"gen_ai.agent.task.tool_call.count"`
	RetryCount       int            `json:"gen_ai.agent.task.retry_count"`
	TokensPrompt     int            `json:"gen_ai.usage.input_tokens"`
	TokensCompletion int            `json:"gen_ai.usage.output_tokens"`
	TokensTotal      int            `json:"gen_ai.usage.total_tokens"`
	CostUSD          float64        `json:"gen_ai.usage.cost"`
	DurationMs       int64          `json:"gen_ai.agent.task.duration,omitempty"`
	ErrorType        string         `json:"gen_ai.agent.task.error.type,omitempty"`
	ErrorMessage     string         `json:"gen_ai.agent.task.error.message,omitempty"`
	StartedAt        time.Time      `json:"started_at"`
	EndedAt          *time.Time     `json:"ended_at,omitempty"`
	CreatedAt        time.Time      `json:"created_at"`
	UpdatedAt        time.Time      `json:"updated_at"`
}

Task represents an agent task. JSON field names follow OpenTelemetry Semantic Conventions for Agentic AI.

type TaskCompleteConfig 

type TaskCompleteConfig struct {
	Output   map[string]any
	Metadata map[string]any
	Duration int64
}

TaskCompleteConfig holds task completion configuration.

func ApplyTaskCompleteOptions 

func ApplyTaskCompleteOptions(opts ...TaskCompleteOption) *TaskCompleteConfig

ApplyTaskCompleteOptions applies options to a config.

type TaskCompleteOption 

type TaskCompleteOption func(*TaskCompleteConfig)

TaskCompleteOption configures task completion.

func WithTaskCompleteDuration 

func WithTaskCompleteDuration(duration int64) TaskCompleteOption

WithTaskCompleteDuration sets the task duration on completion.

func WithTaskCompleteMetadata 

func WithTaskCompleteMetadata(metadata map[string]any) TaskCompleteOption

WithTaskCompleteMetadata sets metadata on completion.

func WithTaskOutput 

func WithTaskOutput(output map[string]any) TaskCompleteOption

WithTaskOutput sets the task output.

type TaskConfig 

type TaskConfig struct {
	AgentType    string
	TaskType     string
	TraceID      string
	SpanID       string
	ParentSpanID string
	Input        map[string]any
	Metadata     map[string]any
}

TaskConfig holds task creation configuration.

func ApplyTaskOptions 

func ApplyTaskOptions(opts ...TaskOption) *TaskConfig

ApplyTaskOptions applies options to a config.

type TaskFailConfig 

type TaskFailConfig struct {
	ErrorType string
	Duration  int64
}

TaskFailConfig holds task failure configuration.

func ApplyTaskFailOptions 

func ApplyTaskFailOptions(opts ...TaskFailOption) *TaskFailConfig

ApplyTaskFailOptions applies options to a config.

type TaskFailOption 

type TaskFailOption func(*TaskFailConfig)

TaskFailOption configures task failure.

func WithTaskErrorType 

func WithTaskErrorType(errorType string) TaskFailOption

WithTaskErrorType sets the error type.

func WithTaskFailDuration 

func WithTaskFailDuration(duration int64) TaskFailOption

WithTaskFailDuration sets the task duration on failure.

type TaskOption 

type TaskOption func(*TaskConfig)

TaskOption configures task creation.

func WithAgentType 

func WithAgentType(agentType string) TaskOption

WithAgentType sets the agent type.

func WithTaskInput 

func WithTaskInput(input map[string]any) TaskOption

WithTaskInput sets the task input.

func WithTaskMetadata 

func WithTaskMetadata(metadata map[string]any) TaskOption

WithTaskMetadata sets task metadata.

func WithTaskParentSpanID 

func WithTaskParentSpanID(parentSpanID string) TaskOption

WithTaskParentSpanID sets the parent span ID.

func WithTaskSpanID 

func WithTaskSpanID(spanID string) TaskOption

WithTaskSpanID sets the span ID.

func WithTaskTraceID 

func WithTaskTraceID(traceID string) TaskOption

WithTaskTraceID sets the trace ID.

func WithTaskType 

func WithTaskType(taskType string) TaskOption

WithTaskType sets the task type.

type TaskStore 

type TaskStore interface {
	// StartTask creates a new task.
	StartTask(ctx context.Context, workflowID, agentID, name string, opts ...TaskOption) (*Task, error)

	// GetTask retrieves a task by ID.
	GetTask(ctx context.Context, id string) (*Task, error)

	// UpdateTask updates task fields.
	UpdateTask(ctx context.Context, id string, opts ...TaskUpdateOption) error

	// CompleteTask marks a task as completed.
	CompleteTask(ctx context.Context, id string, opts ...TaskCompleteOption) error

	// FailTask marks a task as failed.
	FailTask(ctx context.Context, id string, err error, opts ...TaskFailOption) error

	// ListTasks lists tasks with optional filters.
	ListTasks(ctx context.Context, opts ...ListOption) ([]*Task, error)
}

TaskStore handles agent task operations.

type TaskUpdateConfig 

type TaskUpdateConfig struct {
	AddLLMCalls  int
	AddToolCalls int
	AddRetries   int
	AddTokens    TokenUsage
	AddCost      float64
	Metadata     map[string]any
}

TaskUpdateConfig holds task update configuration.

func ApplyTaskUpdateOptions 

func ApplyTaskUpdateOptions(opts ...TaskUpdateOption) *TaskUpdateConfig

ApplyTaskUpdateOptions applies options to a config.

type TaskUpdateOption 

type TaskUpdateOption func(*TaskUpdateConfig)

TaskUpdateOption configures task updates.

func WithTaskAddCost 

func WithTaskAddCost(cost float64) TaskUpdateOption

WithTaskAddCost adds to the cost.

func WithTaskAddLLMCall 

func WithTaskAddLLMCall() TaskUpdateOption

WithTaskAddLLMCall increments LLM call count.

func WithTaskAddRetry 

func WithTaskAddRetry() TaskUpdateOption

WithTaskAddRetry increments retry count.

func WithTaskAddTokens 

func WithTaskAddTokens(prompt, completion int) TaskUpdateOption

WithTaskAddTokens adds token usage.

func WithTaskAddToolCall 

func WithTaskAddToolCall() TaskUpdateOption

WithTaskAddToolCall increments tool call count.

type TokenUsage 

type TokenUsage struct {
	Prompt     int
	Completion int
}

TokenUsage holds token counts.

type ToolInvocation 

type ToolInvocation struct {
	ID                string         `json:"gen_ai.agent.tool_call.id"`
	TaskID            string         `json:"gen_ai.agent.task.id,omitempty"`
	AgentID           string         `json:"gen_ai.agent.id"`
	ToolName          string         `json:"gen_ai.agent.tool_call.name"`
	ToolType          string         `json:"gen_ai.agent.tool_call.type,omitempty"`
	Status            string         `json:"gen_ai.agent.tool_call.status"`
	TraceID           string         `json:"trace_id,omitempty"`
	SpanID            string         `json:"span_id,omitempty"`
	Input             map[string]any `json:"input,omitempty"`
	Output            map[string]any `json:"output,omitempty"`
	Metadata          map[string]any `json:"metadata,omitempty"`
	HTTPMethod        string         `json:"gen_ai.agent.tool_call.http.method,omitempty"`
	HTTPURL           string         `json:"gen_ai.agent.tool_call.http.url,omitempty"`
	HTTPStatusCode    int            `json:"gen_ai.agent.tool_call.http.status_code,omitempty"`
	DurationMs        int64          `json:"gen_ai.agent.tool_call.duration,omitempty"`
	RequestSizeBytes  int            `json:"gen_ai.agent.tool_call.request.size"`
	ResponseSizeBytes int            `json:"gen_ai.agent.tool_call.response.size"`
	RetryCount        int            `json:"gen_ai.agent.tool_call.retry_count"`
	ErrorType         string         `json:"gen_ai.agent.tool_call.error.type,omitempty"`
	ErrorMessage      string         `json:"gen_ai.agent.tool_call.error.message,omitempty"`
	StartedAt         time.Time      `json:"started_at"`
	EndedAt           *time.Time     `json:"ended_at,omitempty"`
	CreatedAt         time.Time      `json:"created_at"`
	UpdatedAt         time.Time      `json:"updated_at"`
}

ToolInvocation represents a tool/function call. JSON field names follow OpenTelemetry Semantic Conventions for Agentic AI. Uses gen_ai.agent.tool_call.* to avoid collision with OTel's gen_ai.tool.* (definitions).

type ToolInvocationCompleteConfig 

type ToolInvocationCompleteConfig struct {
	Output            map[string]any
	HTTPStatusCode    int
	ResponseSizeBytes int
	Duration          int64
}

ToolInvocationCompleteConfig holds tool invocation completion configuration.

func ApplyToolInvocationCompleteOptions 

func ApplyToolInvocationCompleteOptions(opts ...ToolInvocationCompleteOption) *ToolInvocationCompleteConfig

ApplyToolInvocationCompleteOptions applies options to a config.

type ToolInvocationCompleteOption 

type ToolInvocationCompleteOption func(*ToolInvocationCompleteConfig)

ToolInvocationCompleteOption configures tool invocation completion.

func WithToolCompleteDuration 

func WithToolCompleteDuration(duration int64) ToolInvocationCompleteOption

WithToolCompleteDuration sets the duration on completion.

func WithToolCompleteResponseSize 

func WithToolCompleteResponseSize(size int) ToolInvocationCompleteOption

WithToolCompleteResponseSize is an alias for WithToolResponseSize.

func WithToolHTTPStatus 

func WithToolHTTPStatus(code int) ToolInvocationCompleteOption

WithToolHTTPStatus sets the HTTP status code.

func WithToolOutput 

func WithToolOutput(output map[string]any) ToolInvocationCompleteOption

WithToolOutput sets the output.

func WithToolResponseSize 

func WithToolResponseSize(size int) ToolInvocationCompleteOption

WithToolResponseSize sets the response size.

type ToolInvocationConfig 

type ToolInvocationConfig struct {
	ToolType    string
	TraceID     string
	SpanID      string
	Input       map[string]any
	Metadata    map[string]any
	HTTPMethod  string
	HTTPURL     string
	RequestSize int
}

ToolInvocationConfig holds tool invocation creation configuration.

func ApplyToolInvocationOptions 

func ApplyToolInvocationOptions(opts ...ToolInvocationOption) *ToolInvocationConfig

ApplyToolInvocationOptions applies options to a config.

type ToolInvocationOption 

type ToolInvocationOption func(*ToolInvocationConfig)

ToolInvocationOption configures tool invocation creation.

func WithToolHTTP 

func WithToolHTTP(method, url string) ToolInvocationOption

WithToolHTTP sets HTTP details.

func WithToolHTTPMethod 

func WithToolHTTPMethod(method string) ToolInvocationOption

WithToolHTTPMethod sets the HTTP method.

func WithToolHTTPURL 

func WithToolHTTPURL(url string) ToolInvocationOption

WithToolHTTPURL sets the HTTP URL.

func WithToolInput 

func WithToolInput(input map[string]any) ToolInvocationOption

WithToolInput sets the input.

func WithToolMetadata 

func WithToolMetadata(metadata map[string]any) ToolInvocationOption

WithToolMetadata sets metadata.

func WithToolRequestSize 

func WithToolRequestSize(size int) ToolInvocationOption

WithToolRequestSize sets the request size in bytes.

func WithToolSpanID 

func WithToolSpanID(spanID string) ToolInvocationOption

WithToolSpanID sets the span ID.

func WithToolTraceID 

func WithToolTraceID(traceID string) ToolInvocationOption

WithToolTraceID sets the trace ID.

func WithToolType 

func WithToolType(toolType string) ToolInvocationOption

WithToolType sets the tool type.

type ToolInvocationStore 

type ToolInvocationStore interface {
	// RecordToolInvocation records a tool invocation.
	RecordToolInvocation(ctx context.Context, taskID, agentID, toolName string, opts ...ToolInvocationOption) (*ToolInvocation, error)

	// GetToolInvocation retrieves a tool invocation by ID.
	GetToolInvocation(ctx context.Context, id string) (*ToolInvocation, error)

	// UpdateToolInvocation updates a tool invocation.
	UpdateToolInvocation(ctx context.Context, id string, opts ...ToolInvocationUpdateOption) error

	// CompleteToolInvocation marks a tool invocation as completed.
	CompleteToolInvocation(ctx context.Context, id string, opts ...ToolInvocationCompleteOption) error

	// ListToolInvocations lists tool invocations with optional filters.
	ListToolInvocations(ctx context.Context, opts ...ListOption) ([]*ToolInvocation, error)
}

ToolInvocationStore handles tool invocation operations.

type ToolInvocationUpdateConfig 

type ToolInvocationUpdateConfig struct {
	RetryCount   int
	Status       string
	Duration     int64
	ErrorType    string
	ErrorMessage string
}

ToolInvocationUpdateConfig holds tool invocation update configuration.

func ApplyToolInvocationUpdateOptions 

func ApplyToolInvocationUpdateOptions(opts ...ToolInvocationUpdateOption) *ToolInvocationUpdateConfig

ApplyToolInvocationUpdateOptions applies options to a config.

type ToolInvocationUpdateOption 

type ToolInvocationUpdateOption func(*ToolInvocationUpdateConfig)

ToolInvocationUpdateOption configures tool invocation updates.

func WithToolRetry 

func WithToolRetry() ToolInvocationUpdateOption

WithToolRetry increments retry count.

func WithToolUpdateDuration 

func WithToolUpdateDuration(duration int64) ToolInvocationUpdateOption

WithToolUpdateDuration sets the tool invocation duration.

func WithToolUpdateError 

func WithToolUpdateError(errorType, errorMessage string) ToolInvocationUpdateOption

WithToolUpdateError sets the error type and message.

func WithToolUpdateStatus 

func WithToolUpdateStatus(status string) ToolInvocationUpdateOption

WithToolUpdateStatus sets the tool invocation status.

type Workflow 

type Workflow struct {
	ID                 string         `json:"gen_ai.agent.workflow.id"`
	Name               string         `json:"gen_ai.agent.workflow.name"`
	Status             string         `json:"gen_ai.agent.workflow.status"`
	TraceID            string         `json:"trace_id,omitempty"`
	ParentWorkflowID   string         `json:"gen_ai.agent.workflow.parent_id,omitempty"`
	Initiator          string         `json:"gen_ai.agent.workflow.initiator,omitempty"`
	Input              map[string]any `json:"input,omitempty"`
	Output             map[string]any `json:"output,omitempty"`
	Metadata           map[string]any `json:"metadata,omitempty"`
	TaskCount          int            `json:"gen_ai.agent.workflow.task.count"`
	CompletedTaskCount int            `json:"gen_ai.agent.workflow.task.completed_count"`
	FailedTaskCount    int            `json:"gen_ai.agent.workflow.task.failed_count"`
	TotalCostUSD       float64        `json:"gen_ai.usage.cost"`
	TotalTokens        int            `json:"gen_ai.usage.total_tokens"`
	DurationMs         int64          `json:"gen_ai.agent.workflow.duration,omitempty"`
	ErrorMessage       string         `json:"error.message,omitempty"`
	StartedAt          time.Time      `json:"started_at"`
	EndedAt            *time.Time     `json:"ended_at,omitempty"`
	CreatedAt          time.Time      `json:"created_at"`
	UpdatedAt          time.Time      `json:"updated_at"`
}

Workflow represents an end-to-end workflow/session. JSON field names follow OpenTelemetry Semantic Conventions for Agentic AI.

type WorkflowCompleteConfig 

type WorkflowCompleteConfig struct {
	Output   map[string]any
	Metadata map[string]any
}

WorkflowCompleteConfig holds workflow completion configuration.

func ApplyWorkflowCompleteOptions 

func ApplyWorkflowCompleteOptions(opts ...WorkflowCompleteOption) *WorkflowCompleteConfig

ApplyWorkflowCompleteOptions applies options to a config.

type WorkflowCompleteOption 

type WorkflowCompleteOption func(*WorkflowCompleteConfig)

WorkflowCompleteOption configures workflow completion.

func WithWorkflowCompleteOutput 

func WithWorkflowCompleteOutput(output map[string]any) WorkflowCompleteOption

WithWorkflowCompleteOutput sets the output on completion.

type WorkflowConfig 

type WorkflowConfig struct {
	TraceID          string
	ParentWorkflowID string
	Initiator        string
	Input            map[string]any
	Metadata         map[string]any
}

WorkflowConfig holds workflow creation configuration.

func ApplyWorkflowOptions 

func ApplyWorkflowOptions(opts ...WorkflowOption) *WorkflowConfig

ApplyWorkflowOptions applies options to a config.

type WorkflowOption 

type WorkflowOption func(*WorkflowConfig)

WorkflowOption configures workflow creation.

func WithParentWorkflow 

func WithParentWorkflow(id string) WorkflowOption

WithParentWorkflow sets the parent workflow ID.

func WithParentWorkflowID 

func WithParentWorkflowID(id string) WorkflowOption

WithParentWorkflowID is an alias for WithParentWorkflow.

func WithWorkflowInitiator 

func WithWorkflowInitiator(initiator string) WorkflowOption

WithWorkflowInitiator sets who initiated the workflow.

func WithWorkflowInput 

func WithWorkflowInput(input map[string]any) WorkflowOption

WithWorkflowInput sets the workflow input.

func WithWorkflowMetadata 

func WithWorkflowMetadata(metadata map[string]any) WorkflowOption

WithWorkflowMetadata sets workflow metadata.

func WithWorkflowTraceID 

func WithWorkflowTraceID(traceID string) WorkflowOption

WithWorkflowTraceID sets the trace ID.

type WorkflowStore 

type WorkflowStore interface {
	// StartWorkflow creates a new workflow.
	StartWorkflow(ctx context.Context, name string, opts ...WorkflowOption) (*Workflow, error)

	// GetWorkflow retrieves a workflow by ID.
	GetWorkflow(ctx context.Context, id string) (*Workflow, error)

	// UpdateWorkflow updates workflow fields.
	UpdateWorkflow(ctx context.Context, id string, opts ...WorkflowUpdateOption) error

	// CompleteWorkflow marks a workflow as completed.
	CompleteWorkflow(ctx context.Context, id string, opts ...WorkflowCompleteOption) error

	// FailWorkflow marks a workflow as failed.
	FailWorkflow(ctx context.Context, id string, err error) error

	// ListWorkflows lists workflows with optional filters.
	ListWorkflows(ctx context.Context, opts ...ListOption) ([]*Workflow, error)
}

WorkflowStore handles workflow operations.

type WorkflowUpdateConfig 

type WorkflowUpdateConfig struct {
	Output    map[string]any
	Metadata  map[string]any
	AddCost   float64
	AddTokens int
	Duration  int64
}

WorkflowUpdateConfig holds workflow update configuration.

func ApplyWorkflowUpdateOptions 

func ApplyWorkflowUpdateOptions(opts ...WorkflowUpdateOption) *WorkflowUpdateConfig

ApplyWorkflowUpdateOptions applies options to a config.

type WorkflowUpdateOption 

type WorkflowUpdateOption func(*WorkflowUpdateConfig)

WorkflowUpdateOption configures workflow updates.

func WithWorkflowAddCost 

func WithWorkflowAddCost(cost float64) WorkflowUpdateOption

WithWorkflowAddCost adds to the total cost.

func WithWorkflowAddTokens 

func WithWorkflowAddTokens(tokens int) WorkflowUpdateOption

WithWorkflowAddTokens adds to the total tokens.

func WithWorkflowOutput 

func WithWorkflowOutput(output map[string]any) WorkflowUpdateOption

WithWorkflowOutput sets the workflow output.

func WithWorkflowUpdateDuration 

func WithWorkflowUpdateDuration(duration int64) WorkflowUpdateOption

WithWorkflowUpdateDuration sets the workflow duration.

Source Files

View all Source files

Directories

Path Synopsis
ent
agentevent
agenthandoff
agenttask
enttest
hook
migrate
predicate
runtime
schema
toolinvocation
workflow
Package middleware provides reusable instrumentation helpers for multi-agent systems.
 Package middleware provides reusable instrumentation helpers for multi-agent systems.
Package postgres provides a PostgreSQL backend for agentops using Ent.
 Package postgres provides a PostgreSQL backend for agentops using Ent.

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.