agnt5

package
v0.4.1 Latest Latest
Warning

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

 Go to latest Published: Aug 24, 2026 License: Apache-2.0 Imports: 44 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EventTypeOutputDelta = "output.delta"
	EventTypeLogDebug    = "log.debug"
	EventTypeLogInfo     = "log.info"
	EventTypeLogWarn     = "log.warn"
	EventTypeLogError    = "log.error"
)
View Source 
const (
	EvaluatorPresetVersion = "agnt5.evaluator_preset.v1"
)
View Source 
const EvaluatorSystemPrompt = `` /* 396-byte string literal not displayed */
View Source 
const TraceEvalContextSchema = "agnt5.eval.trace_eval_context.v1"

Variables

View Source 
var (
	ErrComponentNotFound        = errors.New("agnt5: component not found")
	ErrDuplicateComponent       = errors.New("agnt5: duplicate component")
	ErrInvalidComponentName     = errors.New("agnt5: invalid component name")
	ErrNilHandler               = errors.New("agnt5: nil handler")
	ErrNilWorker                = errors.New("agnt5: nil worker")
	ErrMissingRoutingMetadata   = errors.New("agnt5: missing project or deployment routing metadata")
	ErrInvalidStepName          = errors.New("agnt5: invalid step name")
	ErrRegistrationRejected     = errors.New("agnt5: worker registration rejected")
	ErrTransportNotImplemented  = errors.New("agnt5: worker transport not implemented")
	ErrUnexpectedRuntimeMessage = errors.New("agnt5: unexpected runtime message")
	ErrWorkerReplaced           = errors.New("agnt5: worker replaced")
	ErrCoordinatorDraining      = errors.New("agnt5: coordinator draining")
	ErrAgentModelRequired       = errors.New("agnt5: agent model is required")
	ErrAgentMaxTurnsExceeded    = errors.New("agnt5: agent max turns exceeded")
	ErrToolNotFound             = errors.New("agnt5: tool not found")
	ErrMCPTransportClosed       = errors.New("agnt5: MCP transport closed")
	ErrDurabilityUnavailable    = errors.New("agnt5: durable activation unavailable")
	ErrNondeterministicReplay   = errors.New("agnt5: non-deterministic replay")
	ErrStaleActivationAuthority = errors.New("agnt5: stale activation authority")
	ErrActivationCancelled      = errors.New("agnt5: activation cancelled")
	ErrActivationContended      = errors.New("agnt5: activation is already active")
	ErrActivationUnknownOutcome = errors.New("agnt5: activation outcome is unknown")
)
View Source 
var BuiltInDeterministicScorerNames = []string{
	"exact_match", "contains", "regex_match", "json_valid", "json_schema",
	"numeric_range", "levenshtein", "tool_called", "tool_not_called",
	"tool_sequence", "tool_sequence_in_order", "tool_sequence_exact",
	"tool_sequence_any_order", "tool_trajectory", "tool_params_match",
	"max_tool_calls", "max_llm_calls", "max_tokens", "duration_under",
	"no_errors", "tool_failure_recovered", "step_efficiency", "plan_quality",
	"plan_adherence", "state_equals",
}
View Source 
var BuiltInJudgeScorerNames = []string{
	"llm_judge", "correctness", "faithfulness", "goal_success", "agent_judge",
}
View Source 
var ErrStateNotFound = errors.New("agnt5: state not found")

ErrStateNotFound is returned when a state key does not exist.

View Source 
var EvaluatorOutputSchema = map[string]any{
	"type":     "object",
	"required": []any{"score", "passed", "label", "explanation"},
	"properties": map[string]any{
		"score":       map[string]any{"type": "number", "minimum": 0, "maximum": 1},
		"passed":      map[string]any{"type": "boolean"},
		"label":       map[string]any{"type": "string"},
		"explanation": map[string]any{"type": "string"},
		"metadata":    map[string]any{"type": "object"},
	},
	"additionalProperties": true,
}

Functions

func IsSSEOnlyEventType 

func IsSSEOnlyEventType(eventType string) bool

IsSSEOnlyEventType mirrors the SDK event-classification contract.

func IsWaitingForUserInput 

func IsWaitingForUserInput(err error) bool

IsWaitingForUserInput reports whether err carries a user-input request.

func RegisterAgent 

func RegisterAgent(w *Worker, agent *Agent, opts ...ComponentOption) error

RegisterAgent registers an Agent as a worker component.

func RegisterChatBot 

func RegisterChatBot(w *Worker, bot *ChatBot, opts ...ComponentOption) error

RegisterChatBot registers a ChatBot as an agent-routed component.

func RegisterFunction 

func RegisterFunction[In any, Out any](w *Worker, name string, handler func(*Context, In) (Out, error), opts ...ComponentOption) error

RegisterFunction registers a typed function component.

func RegisterRaw 

func RegisterRaw(w *Worker, name string, componentType ComponentType, handler func(*Context, []byte) ([]byte, error), opts ...ComponentOption) error

RegisterRaw registers an escape-hatch component that receives and returns raw JSON bytes.

func RegisterScorer 

func RegisterScorer(w *Worker, config ScorerConfig, opts ...ComponentOption) error

RegisterScorer registers a scorer as a worker component.

func RegisterTool 

func RegisterTool(w *Worker, tool Tool, opts ...ComponentOption) error

RegisterTool registers a Tool both in the global tool registry and on a worker.

func RegisterWorkflow 

func RegisterWorkflow[In any, Out any](w *Worker, name string, handler func(*Context, In) (Out, error), opts ...ComponentOption) error

RegisterWorkflow registers a typed workflow component.

func Step 

func Step[T any](ctx *Context, name string, fn func(context.Context) (T, error)) (T, error)

Step runs a named unit of work and memoizes successful output when the worker is connected to an AGNT5 engine. Without an engine checkpoint writer it keeps local behavior: execute the function and emit step lifecycle events.

func StepWithKey added in v0.4.0 

func StepWithKey[T any](ctx *Context, name, key string, fn func(*Context) (T, error)) (T, error)

StepWithKey runs a named durable step under an explicit stable key. Explicit keys are required for fan-out, parallel branches, reordered collections, and repeated same-name work where a sequential ordinal is not deterministic.

func Task added in v0.2.1 

func Task[TInput any, TOutput any](
	ctx *Context,
	name string,
	input TInput,
	fn func(*Context, TInput) (TOutput, error),
) (TOutput, error)

Task invokes a registered-style handler as a durable workflow step. In addition to workflow.step lifecycle events, it emits a function lifecycle child so Studio can show each nested component consistently across SDKs.

func ToolCallNames added in v0.3.0 

func ToolCallNames(calls []ToolCall) []string

func ToolTrajectoryMatches added in v0.3.0 

func ToolTrajectoryMatches(actual, expected []string, mode ToolTrajectoryMode) bool

func WithLLMJudgeModel added in v0.3.0 

func WithLLMJudgeModel(ctx context.Context, model LanguageModel) context.Context

WithLLMJudgeModel injects a deterministic or custom model for built-in judge scorers.

Types

type ActivationError added in v0.4.0 

type ActivationError struct {
	Code         ActivationErrorCode
	ActivationID string
	Attempt      uint32
	Message      string
	Cause        error
}

ActivationError preserves a stable correctness error and its durable identity.

func (*ActivationError) Error added in v0.4.0 

func (e *ActivationError) Error() string

func (*ActivationError) Is added in v0.4.0 

func (e *ActivationError) Is(target error) bool

func (*ActivationError) Unwrap added in v0.4.0 

func (e *ActivationError) Unwrap() error

type ActivationErrorCode added in v0.4.0 

type ActivationErrorCode string

ActivationErrorCode is stable across the Go SDK and runtime activation protocol. 

const (
	ActivationErrorDurabilityUnavailable   ActivationErrorCode = "DURABILITY_UNAVAILABLE"
	ActivationErrorNondeterministicReplay  ActivationErrorCode = "NON_DETERMINISTIC_REPLAY"
	ActivationErrorStaleAuthority          ActivationErrorCode = "STALE_AUTHORITY"
	ActivationErrorCancelled               ActivationErrorCode = "CANCELLED"
	ActivationErrorContended               ActivationErrorCode = "CONTENDED"
	ActivationErrorUnknownOutcome          ActivationErrorCode = "UNKNOWN_OUTCOME"
	ActivationErrorPayloadConflict         ActivationErrorCode = "PAYLOAD_CONFLICT"
	ActivationErrorIllegalTransition       ActivationErrorCode = "ILLEGAL_TRANSITION"
	ActivationErrorInvalidArgument         ActivationErrorCode = "INVALID_ARGUMENT"
	ActivationErrorReferenceRequired       ActivationErrorCode = "REFERENCE_REQUIRED"
	ActivationErrorStateVersionConflict    ActivationErrorCode = "STATE_VERSION_CONFLICT"
	ActivationErrorRequiredChildUnresolved ActivationErrorCode = "REQUIRED_CHILD_UNRESOLVED"
)

type ActivationExecution added in v0.4.0 

type ActivationExecution struct {
	ActivationID   string
	Attempt        uint32
	IdempotencyKey string
}

ActivationExecution is exposed while one durable unit is running.

func ActivationFromContext added in v0.4.0 

func ActivationFromContext(ctx context.Context) (ActivationExecution, bool)

ActivationFromContext returns the current durable activation and downstream key.

type Agent 

type Agent struct {
	Name         string
	Instructions string
	Model        LanguageModel
	Tools        []Tool
	Handoffs     []Handoff
	MaxTurns     int
	Cache        *PromptCache
	// Deprecated compatibility aliases. Prefer Cache.
	CacheControl bool
	CacheTTL     string
}

Agent is a small provider-neutral agent loop.

func NewAgent 

func NewAgent(name string, opts ...AgentOption) (*Agent, error)

NewAgent constructs an Agent.

func (*Agent) Run 

func (a *Agent) Run(ctx *Context, input AgentInput) (AgentResult, error)

Run executes the agent loop with the configured LanguageModel.

type AgentInput 

type AgentInput struct {
	Message  string    `json:"message"`
	Messages []Message `json:"messages,omitempty"`
}

AgentInput is the default dispatch input for an Agent component.

type AgentManager 

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

AgentManager provides a small orchestration facade over an AgentRegistry.

func NewAgentManager 

func NewAgentManager(registry *AgentRegistry) *AgentManager

func (*AgentManager) Get 

func (m *AgentManager) Get(name string) (*Agent, bool)

func (*AgentManager) List 

func (m *AgentManager) List() []*Agent

func (*AgentManager) Register 

func (m *AgentManager) Register(agent *Agent) error

func (*AgentManager) Run 

func (m *AgentManager) Run(ctx *Context, name string, input AgentInput) (AgentResult, error)

type AgentOption 

type AgentOption func(*Agent)

AgentOption mutates Agent construction.

func WithAgentCacheControl 

func WithAgentCacheControl(enabled bool, ttl string) AgentOption

func WithAgentHandoffs 

func WithAgentHandoffs(handoffs ...Handoff) AgentOption

func WithAgentInstructions 

func WithAgentInstructions(instructions string) AgentOption

func WithAgentMaxTurns 

func WithAgentMaxTurns(maxTurns int) AgentOption

func WithAgentModel 

func WithAgentModel(model LanguageModel) AgentOption

func WithAgentPromptCache 

func WithAgentPromptCache(cache *PromptCache) AgentOption

func WithAgentTools 

func WithAgentTools(tools ...Tool) AgentOption

type AgentRegistry 

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

AgentRegistry stores named agents for application-level orchestration.

func DefaultAgentRegistry 

func DefaultAgentRegistry() *AgentRegistry

func NewAgentRegistry 

func NewAgentRegistry() *AgentRegistry

func (*AgentRegistry) Clear 

func (r *AgentRegistry) Clear()

func (*AgentRegistry) Get 

func (r *AgentRegistry) Get(name string) (*Agent, bool)

func (*AgentRegistry) List 

func (r *AgentRegistry) List() []*Agent

func (*AgentRegistry) Register 

func (r *AgentRegistry) Register(agent *Agent) error

type AgentResult 

type AgentResult struct {
	AgentName       string          `json:"agent_name"`
	Response        string          `json:"response"`
	Messages        []Message       `json:"messages,omitempty"`
	ToolCalls       int             `json:"tool_calls,omitempty"`
	ToolCallDetails []AgentToolCall `json:"tool_call_details,omitempty"`
	HandoffTo       string          `json:"handoff_to,omitempty"`
	HandoffMetadata map[string]any  `json:"handoff_metadata,omitempty"`
	Metadata        map[string]any  `json:"metadata,omitempty"`
}

AgentResult is returned by Agent.Run.

type AgentToolCall 

type AgentToolCall struct {
	ID        string         `json:"id,omitempty"`
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments,omitempty"`
	Iteration int            `json:"iteration"`
	Result    any            `json:"result,omitempty"`
	Error     string         `json:"error,omitempty"`
	Handoff   string         `json:"handoff,omitempty"`
}

AgentToolCall records a tool execution requested by a model.

type AnthropicConfig 

type AnthropicConfig struct {
	BaseURL    string
	APIKey     string
	Model      string
	HTTPClient *http.Client
	Version    string
}

AnthropicConfig configures Anthropic Messages API access.

type AnthropicModel 

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

func NewAnthropicModel 

func NewAnthropicModel(config AnthropicConfig) *AnthropicModel

func (*AnthropicModel) Generate 

func (m *AnthropicModel) Generate(ctx context.Context, request GenerateRequest) (GenerateResponse, error)

type AssertionResult added in v0.3.0 

type AssertionResult struct {
	Name        string `json:"name"`
	Passed      bool   `json:"passed"`
	Explanation string `json:"explanation"`
}

AssertionResult is one trace assertion verdict.

type AzureOpenAIConfig 

type AzureOpenAIConfig struct {
	Endpoint   string
	APIKey     string
	Deployment string
	APIVersion string
	HTTPClient *http.Client
}

type BatchEvalItem added in v0.3.0 

type BatchEvalItem struct {
	Input    map[string]any `json:"input"`
	Expected any            `json:"expected,omitempty"`
	ItemID   string         `json:"item_id,omitempty"`
	Index    *int           `json:"index,omitempty"`
}

BatchEvalItem is one input/expected pair in a local concurrent batch eval.

func NormalizeBatchEvalItems added in v0.3.0 

func NormalizeBatchEvalItems(inputs []map[string]any, expected []any) []BatchEvalItem

NormalizeBatchEvalItems pairs plain input maps with optional expected values.

type BatchEvalItemResult added in v0.3.0 

type BatchEvalItemResult struct {
	Index      int             `json:"index"`
	RunID      string          `json:"run_id"`
	Output     json.RawMessage `json:"output,omitempty"`
	Scores     []EvalScore     `json:"scores"`
	Passed     bool            `json:"passed"`
	DurationMS int64           `json:"duration_ms"`
	ItemID     string          `json:"item_id,omitempty"`
	TraceID    string          `json:"trace_id,omitempty"`
	Error      string          `json:"error,omitempty"`
}

BatchEvalItemResult is the result of one batch item.

func (BatchEvalItemResult) GetScore added in v0.3.0 

func (r BatchEvalItemResult) GetScore(name string) (EvalScore, bool)

func (BatchEvalItemResult) IsFailed added in v0.3.0 

func (r BatchEvalItemResult) IsFailed() bool

func (BatchEvalItemResult) IsSuccess added in v0.3.0 

func (r BatchEvalItemResult) IsSuccess() bool

type BatchEvalOptions added in v0.3.0 

type BatchEvalOptions struct {
	Scorers        []EvalScorerSpec
	Expected       []any
	ComponentType  ComponentType
	DeploymentID   string
	MaxConcurrency int
	Timeout        time.Duration
}

BatchEvalOptions controls batch evaluation behavior.

type BatchEvalResult added in v0.3.0 

type BatchEvalResult struct {
	BatchID string                `json:"batch_id"`
	Status  string                `json:"status"`
	Results []BatchEvalItemResult `json:"results"`
	Stats   BatchEvalStats        `json:"stats"`
}

BatchEvalResult contains ordered item results and aggregate statistics.

func (BatchEvalResult) FailedItems added in v0.3.0 

func (r BatchEvalResult) FailedItems() []BatchEvalItemResult

func (BatchEvalResult) FailingItems added in v0.3.0 

func (r BatchEvalResult) FailingItems() []BatchEvalItemResult

func (BatchEvalResult) IsPartialFailure added in v0.3.0 

func (r BatchEvalResult) IsPartialFailure() bool

func (BatchEvalResult) IsSuccess added in v0.3.0 

func (r BatchEvalResult) IsSuccess() bool

func (BatchEvalResult) Outputs added in v0.3.0 

func (r BatchEvalResult) Outputs() []json.RawMessage

func (BatchEvalResult) PassRate added in v0.3.0 

func (r BatchEvalResult) PassRate() float64

func (BatchEvalResult) PassingItems added in v0.3.0 

func (r BatchEvalResult) PassingItems() []BatchEvalItemResult

type BatchEvalStats added in v0.3.0 

type BatchEvalStats struct {
	TotalItems     int   `json:"total_items"`
	CompletedItems int   `json:"completed_items"`
	FailedItems    int   `json:"failed_items"`
	PassedItems    int   `json:"passed_items"`
	AvgDurationMS  int64 `json:"avg_duration_ms"`
	DurationMS     int64 `json:"duration_ms"`
}

BatchEvalStats summarizes a batch evaluation.

type BatchItemError 

type BatchItemError struct {
	Code    string         `json:"code,omitempty"`
	Message string         `json:"message,omitempty"`
	Details map[string]any `json:"details,omitempty"`
}

BatchItemError is per-item failure information in a batch response.

type BatchItemInput 

type BatchItemInput struct {
	Input     any               `json:"input"`
	Index     *int              `json:"index,omitempty"`
	ItemID    string            `json:"item_id,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
	TimeoutMS int64             `json:"timeout_ms,omitempty"`
}

BatchItemInput describes one batch item with optional per-item metadata.

func NewBatchItem 

func NewBatchItem(input any, opts ...BatchItemOption) BatchItemInput

NewBatchItem constructs one Python-compatible batch item envelope.

type BatchItemOption 

type BatchItemOption func(*BatchItemInput)

BatchItemOption mutates a BatchItemInput.

func WithBatchItemID 

func WithBatchItemID(itemID string) BatchItemOption

WithBatchItemID sets the item identifier.

func WithBatchItemIndex 

func WithBatchItemIndex(index int) BatchItemOption

WithBatchItemIndex sets the item index.

func WithBatchItemMetadata 

func WithBatchItemMetadata(metadata map[string]string) BatchItemOption

WithBatchItemMetadata sets per-item metadata.

func WithBatchItemTimeoutMS 

func WithBatchItemTimeoutMS(timeoutMS int64) BatchItemOption

WithBatchItemTimeoutMS sets a per-item timeout.

type BatchItemResult 

type BatchItemResult struct {
	Index       int             `json:"index"`
	ItemID      string          `json:"item_id,omitempty"`
	RunID       string          `json:"run_id"`
	Status      RunStatus       `json:"status"`
	Output      json.RawMessage `json:"output,omitempty"`
	Error       *BatchItemError `json:"error,omitempty"`
	DurationMS  *int64          `json:"duration_ms,omitempty"`
	StartedAt   *time.Time      `json:"started_at,omitempty"`
	CompletedAt *time.Time      `json:"completed_at,omitempty"`
	Raw         map[string]any  `json:"-"`
}

BatchItemResult is one item result in a batch response.

func (BatchItemResult) DecodeOutput 

func (r BatchItemResult) DecodeOutput(target any) error

DecodeOutput unmarshals the item output into target.

func (BatchItemResult) IsFailed 

func (r BatchItemResult) IsFailed() bool

IsFailed reports whether this batch item failed.

func (BatchItemResult) IsSuccess 

func (r BatchItemResult) IsSuccess() bool

IsSuccess reports whether this batch item completed successfully.

type BatchOption 

type BatchOption func(*batchConfig)

BatchOption mutates Batch request configuration.

func WithBatchComponentType 

func WithBatchComponentType(componentType ComponentType) BatchOption

WithBatchComponentType sets the component kind for Batch.

func WithBatchContinueOnFailure 

func WithBatchContinueOnFailure(continueOnFailure bool) BatchOption

WithBatchContinueOnFailure controls whether the batch should continue after item failure.

func WithBatchDefaultItemTimeoutMS 

func WithBatchDefaultItemTimeoutMS(timeoutMS int64) BatchOption

WithBatchDefaultItemTimeoutMS sets the advertised default per-item timeout.

func WithBatchHTTPTimeout 

func WithBatchHTTPTimeout(timeout time.Duration) BatchOption

WithBatchHTTPTimeout sets a per-request HTTP timeout.

func WithBatchIdempotencyKey added in v0.4.0 

func WithBatchIdempotencyKey(key string) BatchOption

WithBatchIdempotencyKey sets the stable caller key used to deduplicate a Batch or BatchStream admission.

func WithBatchMaxConcurrency 

func WithBatchMaxConcurrency(maxConcurrency int) BatchOption

WithBatchMaxConcurrency sets the advertised batch concurrency.

func WithBatchMetadata 

func WithBatchMetadata(metadata map[string]string) BatchOption

WithBatchMetadata sets batch-level metadata.

func WithBatchRawItems 

func WithBatchRawItems() BatchOption

WithBatchRawItems sends each item as the component input directly. Without this option, plain inputs are wrapped in Python-compatible BatchItemInput envelopes containing input and index fields.

func WithBatchTenant 

func WithBatchTenant(tenantID string) BatchOption

WithBatchTenant overrides the default X-TENANT-ID for this request.

func WithBatchTimeoutMS 

func WithBatchTimeoutMS(timeoutMS int64) BatchOption

WithBatchTimeoutMS sets the advertised whole-batch timeout.

type BatchResult 

type BatchResult struct {
	BatchID    string            `json:"batch_id"`
	Status     BatchStatus       `json:"status"`
	RunIDs     []string          `json:"run_ids,omitempty"`
	TotalItems int               `json:"total_items,omitempty"`
	Results    []BatchItemResult `json:"results,omitempty"`
	Stats      *BatchStats       `json:"stats,omitempty"`
	TraceID    string            `json:"trace_id,omitempty"`
	CreatedAt  *time.Time        `json:"created_at,omitempty"`
	Raw        map[string]any    `json:"-"`
}

BatchResult is returned by Batch.

func (*BatchResult) FailedItems 

func (r *BatchResult) FailedItems() []BatchItemResult

FailedItems returns failed item results.

func (*BatchResult) IsPartialFailure 

func (r *BatchResult) IsPartialFailure() bool

IsPartialFailure reports whether some batch items failed and some succeeded.

func (*BatchResult) IsSuccess 

func (r *BatchResult) IsSuccess() bool

IsSuccess reports whether all batch items completed successfully.

func (*BatchResult) Outputs 

func (r *BatchResult) Outputs() []json.RawMessage

Outputs returns item outputs sorted by index. Failed items return nil.

func (*BatchResult) SuccessfulOutputs 

func (r *BatchResult) SuccessfulOutputs() []json.RawMessage

SuccessfulOutputs returns successful item outputs sorted by index.

type BatchStats 

type BatchStats struct {
	TotalItems        int   `json:"total_items"`
	CompletedItems    int   `json:"completed_items"`
	FailedItems       int   `json:"failed_items"`
	CancelledItems    int   `json:"cancelled_items"`
	PendingItems      int   `json:"pending_items"`
	DurationMS        int64 `json:"duration_ms"`
	AvgItemDurationMS int64 `json:"avg_item_duration_ms"`
}

BatchStats summarizes batch item states and duration.

type BatchStatus 

type BatchStatus string

BatchStatus is the gateway-visible lifecycle status for a batch. 

const (
	BatchStatusPending        BatchStatus = "pending"
	BatchStatusQueued         BatchStatus = "queued"
	BatchStatusStarted        BatchStatus = "started"
	BatchStatusRunning        BatchStatus = "running"
	BatchStatusCompleted      BatchStatus = "completed"
	BatchStatusPartialFailure BatchStatus = "partial_failure"
	BatchStatusFailed         BatchStatus = "failed"
	BatchStatusCancelled      BatchStatus = "cancelled"
	BatchStatusUnknown        BatchStatus = "unknown"
)

type BatchStatusResponse 

type BatchStatusResponse struct {
	BatchID     string            `json:"batch_id"`
	Found       bool              `json:"found,omitempty"`
	Status      BatchStatus       `json:"status"`
	Results     []BatchItemResult `json:"results,omitempty"`
	Stats       *BatchStats       `json:"stats,omitempty"`
	TraceID     string            `json:"trace_id,omitempty"`
	SubmittedAt *time.Time        `json:"submitted_at,omitempty"`
	StartedAt   *time.Time        `json:"started_at,omitempty"`
	CompletedAt *time.Time        `json:"completed_at,omitempty"`
	Raw         map[string]any    `json:"-"`
}

BatchStatusResponse is returned by GetBatchStatus.

func (*BatchStatusResponse) IsCompleted 

func (r *BatchStatusResponse) IsCompleted() bool

IsCompleted reports whether the batch reached a terminal status.

func (*BatchStatusResponse) IsRunning 

func (r *BatchStatusResponse) IsRunning() bool

IsRunning reports whether the batch is still running.

type BatchStreamEvent 

type BatchStreamEvent struct {
	EventType string          `json:"event_type"`
	BatchID   string          `json:"batch_id,omitempty"`
	RunID     string          `json:"run_id,omitempty"`
	Data      json.RawMessage `json:"data,omitempty"`
	Metadata  map[string]any  `json:"metadata,omitempty"`
	Raw       map[string]any  `json:"-"`
}

BatchStreamEvent is one SSE event from BatchStream.

type CancelBatchResponse 

type CancelBatchResponse struct {
	BatchID        string         `json:"batch_id"`
	Status         BatchStatus    `json:"status"`
	CancelledItems int            `json:"cancelled_items,omitempty"`
	CompletedItems int            `json:"completed_items,omitempty"`
	Raw            map[string]any `json:"-"`
}

CancelBatchResponse is returned by CancelBatch.

type CancelRunResponse 

type CancelRunResponse struct {
	RunID  string         `json:"run_id"`
	Status string         `json:"status"`
	Offset int64          `json:"offset,omitempty"`
	Raw    map[string]any `json:"-"`
}

CancelRunResponse is returned after asking the gateway to cancel a run.

type ChatBot 

type ChatBot struct {
	Name  string
	Agent *Agent
}

ChatBot wraps an Agent with conversation memory.

func NewChatBot 

func NewChatBot(name string, agent *Agent) (*ChatBot, error)

func (*ChatBot) Handle 

func (b *ChatBot) Handle(ctx *Context, message ChatMessage) (ChatResponse, error)

type ChatMessage 

type ChatMessage struct {
	SessionID string         `json:"session_id,omitempty"`
	UserID    string         `json:"user_id,omitempty"`
	Role      MessageRole    `json:"role"`
	Content   string         `json:"content"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

ChatMessage is a user-facing chat message.

type ChatResponse 

type ChatResponse struct {
	SessionID string      `json:"session_id,omitempty"`
	Message   ChatMessage `json:"message"`
}

ChatResponse is returned by ChatBot.

type ChildJoinPolicy added in v0.4.0 

type ChildJoinPolicy string

ChildJoinPolicy controls whether a delegated child blocks parent success. 

const (
	ChildJoinPolicyRequired ChildJoinPolicy = "required"
	ChildJoinPolicyDetached ChildJoinPolicy = "detached"
)

type Client 

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

Client invokes deployed AGNT5 components through the runtime gateway.

func NewClient 

func NewClient(gatewayURL string, opts ...ClientOption) (*Client, error)

NewClient constructs a gateway client. Empty gatewayURL falls back to AGNT5_GATEWAY_URL, then https://gw.agnt5.com.

func (*Client) Batch 

func (c *Client) Batch(ctx context.Context, component string, items any, opts ...BatchOption) (*BatchResult, error)

Batch submits a batch of component invocations through /v1/{type}/{component}/batch.

func (*Client) BatchEval added in v0.3.0 

func (c *Client) BatchEval(ctx context.Context, component string, items []BatchEvalItem, options BatchEvalOptions, runOpts ...RunOption) *BatchEvalResult

BatchEval runs Client.Eval for each item with a bounded concurrency limit.

func (*Client) BatchStream 

func (c *Client) BatchStream(ctx context.Context, component string, items any, handle func(BatchStreamEvent) error, opts ...BatchOption) error

BatchStream submits a batch and streams batch/run events until a terminal batch event is delivered.

func (*Client) CancelBatch 

func (c *Client) CancelBatch(ctx context.Context, batchID, reason string, timeout time.Duration) (*CancelBatchResponse, error)

CancelBatch cancels a running batch.

func (*Client) CancelRun 

func (c *Client) CancelRun(ctx context.Context, runID string, reason string, opts ...RunOption) (*CancelRunResponse, error)

CancelRun requests cancellation of an in-flight run.

func (*Client) Chat 

func (c *Client) Chat(ctx context.Context, agent string, message ChatMessage, opts ...RunOption) (*ChatResponse, error)

Chat sends a chat message to an agent chat endpoint.

func (*Client) Eval 

func (c *Client) Eval(ctx context.Context, request EvalRequest, opts ...RunOption) (*EvalResponse, error)

Eval evaluates a component output using gateway scorers.

func (*Client) GetBatchStatus 

func (c *Client) GetBatchStatus(ctx context.Context, batchID string, includeResults bool, timeout time.Duration) (*BatchStatusResponse, error)

GetBatchStatus returns current batch status.

func (*Client) GetEvents 

func (c *Client) GetEvents(ctx context.Context, runID string) (*EventsResponse, error)

GetEvents returns all journal events for a run as JSON.

func (*Client) GetResult 

func (c *Client) GetResult(ctx context.Context, runID string) (*RunResponse, error)

GetResult returns the terminal result for a run.

func (*Client) GetStatus 

func (c *Client) GetStatus(ctx context.Context, runID string) (*StatusResponse, error)

GetStatus returns the current status for a run.

func (*Client) ResumeWorkflow 

func (c *Client) ResumeWorkflow(ctx context.Context, runID string, userResponse any, opts ...RunOption) (*ResumeWorkflowResponse, error)

ResumeWorkflow resumes a workflow paused by Context.AskUser or RequestApproval.

func (*Client) Run 

func (c *Client) Run(ctx context.Context, component string, input any, opts ...RunOption) (*RunResponse, error)

Run executes a component synchronously through /v1/{type}/{component}/run.

func (*Client) Session 

func (c *Client) Session(sessionID string) *SessionProxy

Session returns a proxy that sends X-Session-ID.

func (*Client) Stream 

func (c *Client) Stream(ctx context.Context, component string, input any, handle func(string) error, opts ...RunOption) error

Stream consumes output.delta chunks from a streaming component run.

func (*Client) StreamEvents 

func (c *Client) StreamEvents(ctx context.Context, component string, input any, handle func(ReceivedEvent) error, opts ...RunOption) error

StreamEvents consumes typed SSE events from /v1/{type}/{component}/stream.

func (*Client) Submit 

func (c *Client) Submit(ctx context.Context, component string, input any, opts ...SubmitOption) (*SubmitResponse, error)

Submit enqueues a component asynchronously through /v1/{type}/{component}/submit.

func (*Client) WaitForResult 

func (c *Client) WaitForResult(ctx context.Context, runID string, timeout, pollInterval time.Duration) (*RunResponse, error)

WaitForResult polls status until a run reaches a terminal status or timeout expires.

func (*Client) Workflow 

func (c *Client) Workflow(name string) *WorkflowProxy

Workflow returns a proxy for invoking one workflow.

type ClientError 

type ClientError struct {
	Method     string
	URL        string
	StatusCode int
	Body       string
}

ClientError describes a non-run HTTP failure from the gateway.

func (*ClientError) Error 

func (e *ClientError) Error() string

type ClientOption 

type ClientOption func(*clientConfig)

ClientOption mutates Client configuration during construction.

func WithAPIKey 

func WithAPIKey(apiKey string) ClientOption

WithAPIKey sets the service key sent as X-API-KEY.

func WithClientDeploymentID 

func WithClientDeploymentID(deploymentID string) ClientOption

WithClientDeploymentID sets the deployment routing key sent as X-DEPLOYMENT-ID.

func WithClientTimeout 

func WithClientTimeout(timeout time.Duration) ClientOption

WithClientTimeout sets the default HTTP request timeout.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) ClientOption

WithHTTPClient sets the HTTP client used for gateway requests.

func WithTenantID 

func WithTenantID(tenantID string) ClientOption

WithTenantID sets the default sub-tenant sent as X-TENANT-ID.

type Coherence added in v0.3.0 

type Coherence struct{ EvaluatorPresetConfig }

func (Coherence) ToEvalScorerSpec added in v0.3.0 

func (p Coherence) ToEvalScorerSpec() EvalScorerSpec

type Component 

type Component struct {
	Name         string
	Type         ComponentType
	InputSchema  map[string]any
	OutputSchema map[string]any
	Config       map[string]string
	Metadata     map[string]string
	Triggers     []TriggerSpec
	// contains filtered or unexported fields
}

Component describes a registered Go handler.

func (Component) Info 

func (c Component) Info() ComponentInfo

Info returns the registration descriptor for this component.

type ComponentInfo 

type ComponentInfo struct {
	Name         string
	Type         ComponentType
	InputSchema  map[string]any
	OutputSchema map[string]any
	Config       map[string]string
	Metadata     map[string]string
	Triggers     []TriggerSpec
}

ComponentInfo is the SDK-local registration descriptor. Transport adapters convert this shape to the runtime protobuf ComponentInfo.

type ComponentOption 

type ComponentOption func(*Component)

ComponentOption mutates component registration metadata.

func WithBackoff 

func WithBackoff(backoffType string, multiplier float64) ComponentOption

WithBackoff configures component backoff metadata.

func WithComponentConfig 

func WithComponentConfig(config map[string]string) ComponentOption

WithComponentConfig adds config values to a component registration.

func WithComponentMetadata 

func WithComponentMetadata(metadata map[string]string) ComponentOption

WithComponentMetadata adds metadata to a component registration.

func WithCron 

func WithCron(expression string) ComponentOption

WithCron marks a workflow as scheduled with a cron expression.

func WithInputSchema added in v0.2.1 

func WithInputSchema(schema map[string]any) ComponentOption

WithInputSchema overrides the JSON Schema derived for a typed component. Use it to add descriptions, formats, or constraints that Go reflection cannot infer from the handler signature alone.

func WithOutputSchema added in v0.2.1 

func WithOutputSchema(schema map[string]any) ComponentOption

WithOutputSchema overrides the JSON Schema derived for a typed component.

func WithRetry 

func WithRetry(maxAttempts, initialIntervalMS, maxIntervalMS int) ComponentOption

WithRetry configures component retry metadata.

func WithTriggers 

func WithTriggers(triggers ...TriggerSpec) ComponentOption

WithTriggers attaches runtime trigger declarations to a component.

type ComponentType 

type ComponentType string

ComponentType identifies the kind of component registered with a worker. 

const (
	ComponentTypeRun      ComponentType = "run"
	ComponentTypeFunction ComponentType = "function"
	ComponentTypeWorkflow ComponentType = "workflow"
	ComponentTypeAgent    ComponentType = "agent"
	ComponentTypeTool     ComponentType = "tool"
	ComponentTypeMCP      ComponentType = "mcp"
	ComponentTypeEntity   ComponentType = "entity"
	ComponentTypeScorer   ComponentType = "scorer"
	ComponentTypeChat     ComponentType = "chat"
)

type Conciseness added in v0.3.0 

type Conciseness struct{ EvaluatorPresetConfig }

func (Conciseness) ToEvalScorerSpec added in v0.3.0 

func (p Conciseness) ToEvalScorerSpec() EvalScorerSpec

type Context 

type Context struct {
	context.Context
	// contains filtered or unexported fields
}

Context is passed to Go component handlers.

func (*Context) Activation added in v0.4.0 

func (c *Context) Activation() (ActivationExecution, bool)

Activation returns the current durable activation for this component context.

func (*Context) AskUser 

func (c *Context) AskUser(request UserInputRequest) (string, error)

AskUser returns a replayed response on workflow resume, otherwise emits approval.requested and workflow.paused before returning WaitingForUserInputError.

func (*Context) Attempt 

func (c *Context) Attempt() int

Attempt returns the zero-based retry attempt number.

func (*Context) ComponentName 

func (c *Context) ComponentName() string

ComponentName returns the component being executed.

func (*Context) ComponentType 

func (c *Context) ComponentType() ComponentType

ComponentType returns the component type being executed.

func (*Context) Emit 

func (c *Context) Emit(event Event) error

Emit delivers streaming events immediately when transport emitters are available; otherwise it buffers the event for the invocation flush.

func (*Context) Events 

func (c *Context) Events() []Event

Events returns a defensive copy of events emitted during invocation.

func (*Context) Generate 

func (c *Context) Generate(model LanguageModel, request GenerateRequest) (GenerateResponse, error)

Generate runs a model and emits LLM lifecycle events.

func (*Context) InvocationID 

func (c *Context) InvocationID() string

InvocationID returns the runtime invocation ID.

func (*Context) IsStreaming 

func (c *Context) IsStreaming() bool

IsStreaming reports whether this run has an active streaming listener.

func (*Context) LeaseID 

func (c *Context) LeaseID() string

LeaseID returns the current dispatch lease ID, if any.

func (*Context) Logger 

func (c *Context) Logger() *Logger

Logger returns the run-scoped logger.

func (*Context) Memory 

func (c *Context) Memory() *MemoryAccessor

Memory returns a session/user-aware memory accessor backed by State.

func (*Context) Metadata 

func (c *Context) Metadata(key string) string

Metadata returns a single metadata value.

func (*Context) MetadataMap 

func (c *Context) MetadataMap() map[string]string

MetadataMap returns a defensive copy of invocation metadata.

func (*Context) Output 

func (c *Context) Output(delta string)

Output emits an output.delta event.

func (*Context) RequestApproval 

func (c *Context) RequestApproval(prompt string, metadata map[string]any) (bool, error)

RequestApproval asks for a yes/no approval.

func (*Context) RunID 

func (c *Context) RunID() string

RunID returns the run ID associated with this invocation.

func (*Context) Sandbox 

func (c *Context) Sandbox() SandboxRunner

Sandbox returns the context sandbox runner, if one was attached.

func (*Context) SetSandbox 

func (c *Context) SetSandbox(sandbox SandboxRunner)

SetSandbox attaches a sandbox runner to the context.

func (*Context) Sleep added in v0.4.0 

func (c *Context) Sleep(duration time.Duration, opts ...SleepOption) error

Sleep waits locally outside a negotiated runtime context and yields a typed durable suspension when durable_suspension_v1 is available.

func (*Context) State 

func (c *Context) State() *StateManager

State returns a run-scoped state accessor. The default implementation is an in-memory adapter so handlers can use the API before a runtime-backed adapter is configured.

func (*Context) Value added in v0.2.1 

func (c *Context) Value(key any) any

Value preserves the embedded context chain while making active dispatch authority available to runtime-backed state stores, including through context.WithCancel/WithTimeout wrappers derived from this Context.

type ConversationMemory 

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

ConversationMemory stores append-only chat messages.

func (*ConversationMemory) Append 

func (m *ConversationMemory) Append(ctx context.Context, message MemoryMessage) error

func (*ConversationMemory) Messages 

func (m *ConversationMemory) Messages(ctx context.Context) ([]MemoryMessage, error)

type Correctness added in v0.3.0 

type Correctness struct{ EvaluatorPresetConfig }

func (Correctness) ToEvalScorerSpec added in v0.3.0 

func (p Correctness) ToEvalScorerSpec() EvalScorerSpec

type CorrectnessConfig added in v0.3.0 

type CorrectnessConfig = EvaluatorPresetConfig

type DurableActivationMode added in v0.4.0 

type DurableActivationMode string

DurableActivationMode controls worker startup against mixed runtime versions. 

const (
	DurableActivationDisabled  DurableActivationMode = "disabled"
	DurableActivationPreferred DurableActivationMode = "preferred"
	DurableActivationRequired  DurableActivationMode = "required"
)

type DurableActivationStatus added in v0.4.0 

type DurableActivationStatus struct {
	Mode     DurableActivationMode
	Enabled  bool
	Degraded bool
	Reason   string
}

DurableActivationStatus reports the negotiated durability state.

type EvalContext added in v0.3.0 

type EvalContext struct {
	Input    any
	Output   any
	Expected any
	RunID    string
	TraceID  string
	Events   []TraceEvent
}

EvalContext contains the input/output pair and trace evidence for custom eval logic.

func (EvalContext) EventsByType added in v0.3.0 

func (c EvalContext) EventsByType(eventType string) []TraceEvent

func (EvalContext) LMCalls added in v0.3.0 

func (c EvalContext) LMCalls() []TraceEvent

func (EvalContext) StepEvents added in v0.3.0 

func (c EvalContext) StepEvents(stepName string) []TraceEvent

func (EvalContext) ToolCallNames added in v0.3.0 

func (c EvalContext) ToolCallNames() []string

func (EvalContext) ToolCalls added in v0.3.0 

func (c EvalContext) ToolCalls() []ToolCall

func (EvalContext) ToolTrajectoryMatches added in v0.3.0 

func (c EvalContext) ToolTrajectoryMatches(expected []string, mode ToolTrajectoryMode) bool

func (EvalContext) TotalTokens added in v0.3.0 

func (c EvalContext) TotalTokens() int64

type EvalError added in v0.3.0 

type EvalError struct {
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Details map[string]any `json:"details,omitempty"`
}

EvalError describes a component or scorer failure embedded in an eval response.

type EvalRequest 

type EvalRequest struct {
	Component     string           `json:"component"`
	ComponentType ComponentType    `json:"component_type,omitempty"`
	Input         any              `json:"input"`
	Expected      any              `json:"expected,omitempty"`
	Scorers       []EvalScorerSpec `json:"scorers,omitempty"`
	Metadata      map[string]any   `json:"metadata,omitempty"`
}

EvalRequest is the gateway eval request shape.

type EvalResponse 

type EvalResponse struct {
	Output     json.RawMessage `json:"output,omitempty"`
	Scores     []EvalScore     `json:"scores,omitempty"`
	Passed     bool            `json:"passed"`
	RunID      string          `json:"run_id,omitempty"`
	TraceID    string          `json:"trace_id,omitempty"`
	DurationMS int64           `json:"duration_ms,omitempty"`
	Error      *EvalError      `json:"error,omitempty"`
	Raw        map[string]any  `json:"-"`
}

EvalResponse is returned by Client.Eval.

func (*EvalResponse) DecodeOutput added in v0.3.0 

func (r *EvalResponse) DecodeOutput(target any) error

DecodeOutput unmarshals the component output into target.

func (*EvalResponse) GetScore added in v0.3.0 

func (r *EvalResponse) GetScore(name string) (EvalScore, bool)

func (*EvalResponse) IsError added in v0.3.0 

func (r *EvalResponse) IsError() bool

func (*EvalResponse) IsSuccess added in v0.3.0 

func (r *EvalResponse) IsSuccess() bool

func (*EvalResponse) RaiseForStatus added in v0.3.0 

func (r *EvalResponse) RaiseForStatus() error

RaiseForStatus returns a typed error when the eval response embeds a failure.

type EvalScore 

type EvalScore struct {
	Scorer      string         `json:"scorer"`
	Score       float64        `json:"score"`
	Passed      bool           `json:"passed"`
	Explanation string         `json:"explanation,omitempty"`
	Label       string         `json:"label,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

EvalScore is one scorer result returned by the gateway.

type EvalScorer added in v0.3.0 

type EvalScorer interface {
	ToEvalScorerSpec() EvalScorerSpec
}

EvalScorer converts a typed scorer helper to the gateway scorer spec.

type EvalScorerSpec 

type EvalScorerSpec struct {
	Name   string         `json:"name"`
	Config map[string]any `json:"config,omitempty"`
}

EvalScorerSpec is one scorer requested for a gateway eval.

func NamedScorer added in v0.3.0 

func NamedScorer(name string) EvalScorerSpec

NamedScorer returns a scorer spec with no configuration.

func NormalizeEvalScorers added in v0.3.0 

func NormalizeEvalScorers(scorers ...any) []EvalScorerSpec

NormalizeEvalScorers converts names, raw specs, and typed presets to API specs.

func (EvalScorerSpec) ToEvalScorerSpec added in v0.3.0 

func (s EvalScorerSpec) ToEvalScorerSpec() EvalScorerSpec

type EvaluatorPresetConfig added in v0.3.0 

type EvaluatorPresetConfig struct {
	Model              string
	IncludeInput       *bool
	Temperature        float64
	Threshold          *float64
	AnswerField        string
	ReferenceField     string
	OutputField        string
	ExpectedField      string
	InputField         string
	ContextFields      []string
	SessionFields      []string
	JournalEventFields []string
	Metadata           map[string]any
}

EvaluatorPresetConfig controls versioned managed judge presets.

type Event 

type Event struct {
	RunID               string
	Type                string
	Data                any
	Metadata            map[string]string
	CorrelationID       string
	ParentCorrelationID string
	ContentIndex        int
	Sequence            int64
	SourceTimestampNS   int64
}

Event is the language-level event representation used before transport delivery.

type EventsResponse 

type EventsResponse struct {
	Items []RunEvent     `json:"items"`
	Count int            `json:"count"`
	Raw   map[string]any `json:"-"`
}

EventsResponse is returned by GetEvents.

type ExecuteCodeResult 

type ExecuteCodeResult struct {
	Stdout   string `json:"stdout,omitempty"`
	Stderr   string `json:"stderr,omitempty"`
	ExitCode int    `json:"exit_code"`
}

type Faithfulness added in v0.3.0 

type Faithfulness struct{ EvaluatorPresetConfig }

func (Faithfulness) ToEvalScorerSpec added in v0.3.0 

func (p Faithfulness) ToEvalScorerSpec() EvalScorerSpec

type FaithfulnessConfig added in v0.3.0 

type FaithfulnessConfig = EvaluatorPresetConfig

type FileInfo 

type FileInfo struct {
	Path  string `json:"path"`
	IsDir bool   `json:"is_dir"`
	Size  int64  `json:"size,omitempty"`
}

type GenerateRequest 

type GenerateRequest struct {
	Model       string       `json:"model,omitempty"`
	Messages    []Message    `json:"messages"`
	Tools       []Tool       `json:"tools,omitempty"`
	Temperature *float64     `json:"temperature,omitempty"`
	MaxTokens   *int         `json:"max_tokens,omitempty"`
	Cache       *PromptCache `json:"cache,omitempty"`
	// Deprecated compatibility aliases. Prefer Cache.
	CacheControl        bool           `json:"cache_control,omitempty"`
	CacheTTL            string         `json:"cache_ttl,omitempty"`
	GoogleCachedContent string         `json:"google_cached_content,omitempty"`
	Metadata            map[string]any `json:"metadata,omitempty"`
	// RecoveryPolicy controls how an interrupted model call is settled.
	// The default is unknown_outcome.
	RecoveryPolicy RecoveryPolicy `json:"recovery_policy,omitempty"`
}

GenerateRequest is a provider-neutral model request.

type GenerateResponse 

type GenerateResponse struct {
	ID           string         `json:"id,omitempty"`
	Model        string         `json:"model,omitempty"`
	Content      string         `json:"content"`
	Usage        TokenUsage     `json:"usage,omitempty"`
	FinishReason string         `json:"finish_reason,omitempty"`
	ToolCalls    []ToolCall     `json:"tool_calls,omitempty"`
	Metadata     map[string]any `json:"metadata,omitempty"`
}

GenerateResponse is a provider-neutral model response.

type GoalSuccess added in v0.3.0 

type GoalSuccess struct{ EvaluatorPresetConfig }

func (GoalSuccess) ToEvalScorerSpec added in v0.3.0 

func (p GoalSuccess) ToEvalScorerSpec() EvalScorerSpec

type GoogleConfig 

type GoogleConfig struct {
	BaseURL    string
	APIKey     string
	Model      string
	Version    string
	HTTPClient *http.Client
}

GoogleConfig configures Google Gemini API access.

type GoogleModel 

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

GoogleModel is a minimal Gemini LanguageModel.

func NewGeminiModel 

func NewGeminiModel(config GoogleConfig) *GoogleModel

func NewGoogleModel 

func NewGoogleModel(config GoogleConfig) *GoogleModel

func (*GoogleModel) CreateCachedContent 

func (m *GoogleModel) CreateCachedContent(ctx context.Context, model string, system string, contents []string, ttlSeconds int) (string, error)

func (*GoogleModel) DeleteCachedContent 

func (m *GoogleModel) DeleteCachedContent(ctx context.Context, name string) error

func (*GoogleModel) Generate 

func (m *GoogleModel) Generate(ctx context.Context, request GenerateRequest) (GenerateResponse, error)

type HITLInputType 

type HITLInputType string

HITLInputType describes the requested user input shape. 

const (
	HITLText        HITLInputType = "text"
	HITLSelect      HITLInputType = "select"
	HITLMultiSelect HITLInputType = "multiselect"
	HITLApproval    HITLInputType = "approval"
)

type HITLOption 

type HITLOption struct {
	Label string `json:"label"`
	Value string `json:"value"`
}

HITLOption is one selectable user input option.

type HTTPSandbox 

type HTTPSandbox struct {
	Endpoint   string
	APIKey     string
	HTTPClient *http.Client
}

HTTPSandbox talks to an AGNT5-compatible sandbox HTTP endpoint.

func NewHTTPSandbox 

func NewHTTPSandbox(endpoint string, apiKey string) *HTTPSandbox

func (*HTTPSandbox) ExecuteCode 

func (s *HTTPSandbox) ExecuteCode(ctx context.Context, language, code string) (ExecuteCodeResult, error)

func (*HTTPSandbox) ListFiles 

func (s *HTTPSandbox) ListFiles(ctx context.Context, path string) (ListFilesResult, error)

func (*HTTPSandbox) ReadFile 

func (s *HTTPSandbox) ReadFile(ctx context.Context, path string) (ReadFileResult, error)

func (*HTTPSandbox) RunCommand 

func (s *HTTPSandbox) RunCommand(ctx context.Context, command []string) (RunCommandResult, error)

func (*HTTPSandbox) WriteFile 

func (s *HTTPSandbox) WriteFile(ctx context.Context, path string, content []byte) (WriteFileResult, error)

type Handoff 

type Handoff struct {
	Agent           *Agent          `json:"-"`
	Description     string          `json:"description,omitempty"`
	ToolName        string          `json:"tool_name,omitempty"`
	PassFullHistory bool            `json:"pass_full_history,omitempty"`
	Metadata        map[string]any  `json:"metadata,omitempty"`
	JoinPolicy      ChildJoinPolicy `json:"join_policy,omitempty"`
}

Handoff exposes another agent as a callable transfer target.

func NewHandoff 

func NewHandoff(agent *Agent, opts ...HandoffOption) (Handoff, error)

NewHandoff exposes an agent as a transfer target for another agent.

type HandoffOption 

type HandoffOption func(*Handoff)

HandoffOption mutates handoff construction.

func WithHandoffDescription 

func WithHandoffDescription(description string) HandoffOption

func WithHandoffFullHistory 

func WithHandoffFullHistory(pass bool) HandoffOption

func WithHandoffJoinPolicy added in v0.4.0 

func WithHandoffJoinPolicy(policy ChildJoinPolicy) HandoffOption

WithHandoffJoinPolicy selects required or detached child terminal behavior.

func WithHandoffMetadata 

func WithHandoffMetadata(metadata map[string]any) HandoffOption

func WithHandoffToolName 

func WithHandoffToolName(toolName string) HandoffOption

type Harmfulness added in v0.3.0 

type Harmfulness struct{ EvaluatorPresetConfig }

func (Harmfulness) ToEvalScorerSpec added in v0.3.0 

func (p Harmfulness) ToEvalScorerSpec() EvalScorerSpec

type Helpfulness added in v0.3.0 

type Helpfulness struct{ EvaluatorPresetConfig }

func (Helpfulness) ToEvalScorerSpec added in v0.3.0 

func (p Helpfulness) ToEvalScorerSpec() EvalScorerSpec

type InMemorySandbox 

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

InMemorySandbox is a deterministic sandbox for tests and local examples.

func NewInMemorySandbox 

func NewInMemorySandbox() *InMemorySandbox

func (*InMemorySandbox) ExecuteCode 

func (s *InMemorySandbox) ExecuteCode(ctx context.Context, language, code string) (ExecuteCodeResult, error)

func (*InMemorySandbox) ListFiles 

func (s *InMemorySandbox) ListFiles(ctx context.Context, path string) (ListFilesResult, error)

func (*InMemorySandbox) ReadFile 

func (s *InMemorySandbox) ReadFile(ctx context.Context, path string) (ReadFileResult, error)

func (*InMemorySandbox) RunCommand 

func (s *InMemorySandbox) RunCommand(ctx context.Context, command []string) (RunCommandResult, error)

func (*InMemorySandbox) WriteFile 

func (s *InMemorySandbox) WriteFile(ctx context.Context, path string, content []byte) (WriteFileResult, error)

type InMemoryStateStore 

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

InMemoryStateStore is a process-local StateStore implementation.

func NewInMemoryStateStore 

func NewInMemoryStateStore() *InMemoryStateStore

NewInMemoryStateStore creates an empty in-memory state store.

func (*InMemoryStateStore) Delete 

func (s *InMemoryStateStore) Delete(_ context.Context, scope StateScope, namespace, key string) error

func (*InMemoryStateStore) Get 

func (s *InMemoryStateStore) Get(_ context.Context, scope StateScope, namespace, key string) (any, bool, error)

func (*InMemoryStateStore) List 

func (s *InMemoryStateStore) List(_ context.Context, scope StateScope, namespace string) (map[string]any, error)

func (*InMemoryStateStore) Set 

func (s *InMemoryStateStore) Set(_ context.Context, scope StateScope, namespace, key string, value any) error

type InstructionFollowing added in v0.3.0 

type InstructionFollowing struct{ EvaluatorPresetConfig }

func (InstructionFollowing) ToEvalScorerSpec added in v0.3.0 

func (p InstructionFollowing) ToEvalScorerSpec() EvalScorerSpec

type Invocation 

type Invocation struct {
	ID             string
	RunID          string
	ComponentName  string
	ComponentType  ComponentType
	Input          []byte
	Attempt        int
	Metadata       map[string]string
	LeaseID        string
	IsStreaming    bool
	StreamFallback bool
}

Invocation contains the runtime data needed to execute one component.

type InvocationResult 

type InvocationResult struct {
	Output   []byte
	Metadata map[string]string
	LeaseID  string
	Events   []Event
}

InvocationResult is the language-local result of executing a component.

type KVMemory 

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

KVMemory stores arbitrary values by key.

func (*KVMemory) Delete 

func (m *KVMemory) Delete(ctx context.Context, key string) error

func (*KVMemory) Get 

func (m *KVMemory) Get(ctx context.Context, key string) (any, error)

func (*KVMemory) List 

func (m *KVMemory) List(ctx context.Context) (map[string]any, error)

func (*KVMemory) Set 

func (m *KVMemory) Set(ctx context.Context, key string, value any) error

type LLMJudge added in v0.3.0 

type LLMJudge struct {
	LLMJudgeConfig
}

LLMJudge is a typed scorer spec for the platform API.

func NewLLMJudge added in v0.3.0 

func NewLLMJudge(config LLMJudgeConfig) LLMJudge

func (LLMJudge) ToEvalScorerSpec added in v0.3.0 

func (j LLMJudge) ToEvalScorerSpec() EvalScorerSpec

type LLMJudgeConfig added in v0.3.0 

type LLMJudgeConfig struct {
	Criteria       string
	Model          string
	SystemPrompt   string
	Temperature    float64
	IncludeInput   bool
	PromptTemplate string
	ChoiceScores   map[string]float64
}

LLMJudgeConfig configures a generic LLM-as-judge scorer.

type LanguageModel 

type LanguageModel interface {
	Generate(ctx context.Context, request GenerateRequest) (GenerateResponse, error)
}

LanguageModel is the provider boundary used by Agent and direct LLM helpers.

type ListFilesResult 

type ListFilesResult struct {
	Path  string     `json:"path"`
	Files []FileInfo `json:"files"`
}

type Logger 

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

Logger emits log events tied to a run context.

func (*Logger) Debug 

func (l *Logger) Debug(message string, keyvals ...any)

Debug emits a debug log event.

func (*Logger) Error 

func (l *Logger) Error(message string, keyvals ...any)

Error emits an error log event.

func (*Logger) Info 

func (l *Logger) Info(message string, keyvals ...any)

Info emits an info log event.

func (*Logger) Warn 

func (l *Logger) Warn(message string, keyvals ...any)

Warn emits a warning log event.

type MCPCallToolResult 

type MCPCallToolResult struct {
	Content []map[string]any `json:"content,omitempty"`
	IsError bool             `json:"isError,omitempty"`
	Raw     map[string]any   `json:"-"`
}

MCPCallToolResult is returned from tools/call.

type MCPClient 

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

MCPClient is a small MCP JSON-RPC client.

func NewMCPClient 

func NewMCPClient(transport MCPTransport) (*MCPClient, error)

func (*MCPClient) CallTool 

func (c *MCPClient) CallTool(ctx context.Context, name string, arguments map[string]any) (MCPCallToolResult, error)

func (*MCPClient) Close 

func (c *MCPClient) Close() error

func (*MCPClient) Initialize added in v0.4.0 

func (c *MCPClient) Initialize(ctx context.Context) error

Initialize performs the MCP initialize/initialized handshake. It is idempotent and safe for concurrent callers. Legacy transports that do not implement MCPNotificationTransport retain their request-only behavior.

func (*MCPClient) ListTools 

func (c *MCPClient) ListTools(ctx context.Context) ([]MCPTool, error)

type MCPNotificationTransport added in v0.4.0 

type MCPNotificationTransport interface {
	Notify(ctx context.Context, method string, params any) error
}

MCPNotificationTransport is optionally implemented by transports that can send JSON-RPC notifications. MCPClient uses it for the initialize lifecycle.

type MCPRequestError added in v0.4.0 

type MCPRequestError struct {
	Code    int
	Message string
	Data    any
}

MCPRequestError is a JSON-RPC error returned by an MCP server.

func (*MCPRequestError) Error added in v0.4.0 

func (e *MCPRequestError) Error() string

type MCPResource 

type MCPResource struct {
	URI         string `json:"uri"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	MimeType    string `json:"mimeType,omitempty"`
}

MCPResource describes an MCP resource.

type MCPTool 

type MCPTool struct {
	Name        string         `json:"name"`
	Description string         `json:"description,omitempty"`
	InputSchema map[string]any `json:"inputSchema,omitempty"`
}

MCPTool describes an MCP tool.

type MCPTransport 

type MCPTransport interface {
	Request(ctx context.Context, method string, params any) (map[string]any, error)
	Close() error
}

MCPTransport is the JSON-RPC boundary for MCP.

type MemoryAccessor 

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

MemoryAccessor provides scoped memory helpers.

func NewMemoryAccessor 

func NewMemoryAccessor(store StateStore, ctx MemoryContext) *MemoryAccessor

NewMemoryAccessor constructs a memory accessor.

func (*MemoryAccessor) Conversation 

func (m *MemoryAccessor) Conversation() *ConversationMemory

Conversation returns session-scoped conversation memory.

func (*MemoryAccessor) KV 

func (m *MemoryAccessor) KV(scope MemoryScope) *KVMemory

KV returns key/value memory for a scope.

func (*MemoryAccessor) Working 

func (m *MemoryAccessor) Working() *WorkingMemory

Working returns session-scoped working memory.

type MemoryContext 

type MemoryContext struct {
	RunID     string
	SessionID string
	UserID    string
}

MemoryContext carries scope identifiers for memory access.

type MemoryMessage 

type MemoryMessage struct {
	Role      string         `json:"role"`
	Content   string         `json:"content"`
	Metadata  map[string]any `json:"metadata,omitempty"`
	CreatedAt time.Time      `json:"created_at"`
}

MemoryMessage is one conversation memory message.

type MemoryResult 

type MemoryResult struct {
	Key      string         `json:"key"`
	Value    any            `json:"value"`
	Score    float64        `json:"score,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

MemoryResult is returned from memory search APIs.

type MemoryScope 

type MemoryScope string

MemoryScope identifies a memory namespace. 

const (
	MemoryScopeRun     MemoryScope = "run"
	MemoryScopeSession MemoryScope = "session"
	MemoryScopeUser    MemoryScope = "user"
	MemoryScopeGlobal  MemoryScope = "global"
)

type Message 

type Message struct {
	Role       MessageRole `json:"role"`
	Content    string      `json:"content"`
	Name       string      `json:"name,omitempty"`
	ToolCallID string      `json:"tool_call_id,omitempty"`
	ToolCalls  []ToolCall  `json:"tool_calls,omitempty"`
}

Message is one LLM or agent conversation message.

type MessageRole 

type MessageRole string

MessageRole identifies a chat message role. 

const (
	MessageRoleSystem    MessageRole = "system"
	MessageRoleUser      MessageRole = "user"
	MessageRoleAssistant MessageRole = "assistant"
	MessageRoleTool      MessageRole = "tool"
)

type ModelStreamChunk 

type ModelStreamChunk struct {
	Type           ModelStreamChunkType
	Content        string
	Index          int
	ToolCallID     string
	ToolName       string
	ArgumentsDelta string
	Arguments      map[string]any
}

ModelStreamChunk is emitted while a StreamingLanguageModel is generating. Tool-call arguments use their provider-neutral JSON representation so agents can expose partial arguments without executing an incomplete call.

type ModelStreamChunkType 

type ModelStreamChunkType string

ModelStreamChunkType identifies one provider-neutral model stream event. 

const (
	ModelStreamMessageStart  ModelStreamChunkType = "message_start"
	ModelStreamMessageDelta  ModelStreamChunkType = "message_delta"
	ModelStreamMessageStop   ModelStreamChunkType = "message_stop"
	ModelStreamThinkingStart ModelStreamChunkType = "thinking_start"
	ModelStreamThinkingDelta ModelStreamChunkType = "thinking_delta"
	ModelStreamThinkingStop  ModelStreamChunkType = "thinking_stop"
	ModelStreamToolCallStart ModelStreamChunkType = "tool_call_start"
	ModelStreamToolCallDelta ModelStreamChunkType = "tool_call_delta"
	ModelStreamToolCallStop  ModelStreamChunkType = "tool_call_stop"
)

type OpenAIConfig 

type OpenAIConfig struct {
	BaseURL      string
	APIKey       string
	APIKeyHeader string
	AuthScheme   string
	Model        string
	Organization string
	HTTPClient   *http.Client
	Headers      map[string]string
	Path         string
}

OpenAIConfig configures an OpenAI-compatible chat-completions provider.

type OpenAIModel 

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

OpenAIModel is a minimal OpenAI-compatible LanguageModel.

func NewAzureOpenAIModel 

func NewAzureOpenAIModel(config AzureOpenAIConfig) *OpenAIModel

NewAzureOpenAIModel constructs an Azure OpenAI chat-completions adapter.

func NewDeepSeekModel 

func NewDeepSeekModel(config OpenAIConfig) *OpenAIModel

func NewGroqModel 

func NewGroqModel(config OpenAIConfig) *OpenAIModel

func NewMistralModel 

func NewMistralModel(config OpenAIConfig) *OpenAIModel

func NewMoonshotModel 

func NewMoonshotModel(config OpenAIConfig) *OpenAIModel

NewMoonshotModel constructs an OpenAI-compatible Moonshot AI (Kimi) adapter.

func NewOllamaModel 

func NewOllamaModel(config OpenAIConfig) *OpenAIModel

func NewOpenAIModel 

func NewOpenAIModel(config OpenAIConfig) *OpenAIModel

NewOpenAIModel constructs an OpenAI-compatible model.

func NewOpenRouterModel 

func NewOpenRouterModel(config OpenAIConfig) *OpenAIModel

func NewTogetherModel 

func NewTogetherModel(config OpenAIConfig) *OpenAIModel

func NewXAIModel 

func NewXAIModel(config OpenAIConfig) *OpenAIModel

func (*OpenAIModel) Generate 

func (m *OpenAIModel) Generate(ctx context.Context, request GenerateRequest) (GenerateResponse, error)

type PromptCache 

type PromptCache struct {
	Enabled   bool   `json:"enabled,omitempty"`
	TTL       string `json:"ttl,omitempty"`
	Key       string `json:"key,omitempty"`
	Retention string `json:"retention,omitempty"`
	Resource  string `json:"resource,omitempty"`
}

PromptCache is a provider-neutral prompt-cache policy.

func EnablePromptCache 

func EnablePromptCache() *PromptCache

func PromptCacheResource 

func PromptCacheResource(name string) *PromptCache

func PromptCacheWithTTL 

func PromptCacheWithTTL(ttl string) *PromptCache

type ReadFileResult 

type ReadFileResult struct {
	Path    string `json:"path"`
	Content []byte `json:"content"`
}

type ReceivedEvent 

type ReceivedEvent struct {
	EventType    string         `json:"event_type"`
	Data         map[string]any `json:"data"`
	ContentIndex int            `json:"content_index"`
	Sequence     int            `json:"sequence"`
	RunID        string         `json:"run_id,omitempty"`
}

ReceivedEvent is one event decoded from a streaming SSE response.

type RecoveryPolicy added in v0.4.0 

type RecoveryPolicy string

RecoveryPolicy controls how interrupted durable work is settled. 

const (
	RecoveryPolicyIdempotentRetry RecoveryPolicy = "idempotent_retry"
	RecoveryPolicyDurableSteps    RecoveryPolicy = "durable_steps"
	RecoveryPolicyUnknownOutcome  RecoveryPolicy = "unknown_outcome"
	RecoveryPolicyCompensate      RecoveryPolicy = "compensate"
	RecoveryPolicyFail            RecoveryPolicy = "fail"
)

type Refusal added in v0.3.0 

type Refusal struct{ EvaluatorPresetConfig }

func (Refusal) ToEvalScorerSpec added in v0.3.0 

func (p Refusal) ToEvalScorerSpec() EvalScorerSpec

type Registry 

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

Registry stores registered components by name.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates an empty component registry.

func (*Registry) ComponentInfos 

func (r *Registry) ComponentInfos() []ComponentInfo

ComponentInfos returns deterministic component registration descriptors.

func (*Registry) Get 

func (r *Registry) Get(name string) (Component, bool)

Get returns a component by name.

func (*Registry) List 

func (r *Registry) List() []Component

List returns all registered components.

func (*Registry) Register 

func (r *Registry) Register(component Component) error

Register stores a component by name.

type ResponseRelevance added in v0.3.0 

type ResponseRelevance struct{ EvaluatorPresetConfig }

func (ResponseRelevance) ToEvalScorerSpec added in v0.3.0 

func (p ResponseRelevance) ToEvalScorerSpec() EvalScorerSpec

type ResumeWorkflowResponse 

type ResumeWorkflowResponse struct {
	RunID  string         `json:"run_id"`
	Status string         `json:"status"`
	Offset int64          `json:"offset,omitempty"`
	Raw    map[string]any `json:"-"`
}

ResumeWorkflowResponse is returned after asking the gateway to resume a paused workflow.

type RunCommandResult 

type RunCommandResult struct {
	Stdout   string `json:"stdout,omitempty"`
	Stderr   string `json:"stderr,omitempty"`
	ExitCode int    `json:"exit_code"`
}

type RunError 

type RunError struct {
	Message     string
	RunID       string
	ErrorCode   string
	Attempts    int
	MaxAttempts int
	Metadata    map[string]any
}

RunError is returned when a run or stream reaches an error state.

func (*RunError) Error 

func (e *RunError) Error() string

func (*RunError) ExhaustedRetries 

func (e *RunError) ExhaustedRetries() bool

ExhaustedRetries reports whether all configured attempts were used.

func (*RunError) WasRetried 

func (e *RunError) WasRetried() bool

WasRetried reports whether the run made more than one attempt.

type RunErrorDetail 

type RunErrorDetail struct {
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Details map[string]any `json:"details,omitempty"`
}

RunErrorDetail is structured error information returned by the gateway.

type RunEvent 

type RunEvent struct {
	ID                  string          `json:"id,omitempty"`
	EventType           string          `json:"event_type"`
	RunID               string          `json:"run_id"`
	Data                json.RawMessage `json:"data,omitempty"`
	InputData           json.RawMessage `json:"input_data,omitempty"`
	OutputData          json.RawMessage `json:"output_data,omitempty"`
	StepKey             string          `json:"step_key,omitempty"`
	ParentEventID       string          `json:"parent_event_id,omitempty"`
	CorrelationID       string          `json:"correlation_id,omitempty"`
	ParentCorrelationID string          `json:"parent_correlation_id,omitempty"`
	Metadata            map[string]any  `json:"metadata,omitempty"`
	TraceID             string          `json:"trace_id,omitempty"`
	TimestampNS         int64           `json:"timestamp_ns,omitempty"`
	CreatedAt           *time.Time      `json:"created_at,omitempty"`
	Raw                 map[string]any  `json:"-"`
}

RunEvent is one journal event returned by GetEvents.

type RunOption 

type RunOption func(*runConfig)

RunOption mutates Run and streaming request configuration.

func WithIdempotencyKey added in v0.4.0 

func WithIdempotencyKey(key string) RunOption

WithIdempotencyKey sets the stable caller key used to deduplicate a Run or streaming admission. It overrides an Idempotency-Key supplied through raw headers regardless of option order.

func WithRunComponentType 

func WithRunComponentType(componentType ComponentType) RunOption

WithRunComponentType sets the component kind for Run or StreamEvents.

func WithRunHeader 

func WithRunHeader(key, value string) RunOption

WithRunHeader sets one additional HTTP header for this request.

func WithRunHeaders 

func WithRunHeaders(headers map[string]string) RunOption

WithRunHeaders adds HTTP headers for this request.

func WithRunIdempotencyKey added in v0.4.0 

func WithRunIdempotencyKey(key string) RunOption

WithRunIdempotencyKey is the scope-explicit alias for WithIdempotencyKey.

func WithRunSessionID 

func WithRunSessionID(sessionID string) RunOption

WithRunSessionID sets X-Session-ID.

func WithRunTenant 

func WithRunTenant(tenantID string) RunOption

WithRunTenant overrides the default X-TENANT-ID for this request.

func WithRunTimeout 

func WithRunTimeout(timeout time.Duration) RunOption

WithRunTimeout sets a per-request context timeout.

func WithRunUserID 

func WithRunUserID(userID string) RunOption

WithRunUserID sets X-User-ID.

type RunResponse 

type RunResponse struct {
	RunID       string          `json:"run_id"`
	StatusCode  int             `json:"status_code"`
	Status      RunStatus       `json:"status"`
	Output      json.RawMessage `json:"output,omitempty"`
	Error       *RunErrorDetail `json:"error,omitempty"`
	DurationMS  *int64          `json:"duration_ms,omitempty"`
	TraceID     string          `json:"trace_id,omitempty"`
	Component   string          `json:"component,omitempty"`
	CreatedAt   *time.Time      `json:"created_at,omitempty"`
	StartedAt   *time.Time      `json:"started_at,omitempty"`
	CompletedAt *time.Time      `json:"completed_at,omitempty"`
	FailedAt    *time.Time      `json:"failed_at,omitempty"`
	SessionID   string          `json:"session_id,omitempty"`
	Metadata    map[string]any  `json:"metadata,omitempty"`
	Raw         map[string]any  `json:"-"`
}

RunResponse is returned by Run, GetResult, and WaitForResult.

func (*RunResponse) DecodeOutput 

func (r *RunResponse) DecodeOutput(target any) error

DecodeOutput unmarshals the run output into target.

func (*RunResponse) IsError 

func (r *RunResponse) IsError() bool

IsError reports whether the run reached an error terminal state.

func (*RunResponse) IsPending 

func (r *RunResponse) IsPending() bool

IsPending reports whether the run is queued or still executing.

func (*RunResponse) IsSuccess 

func (r *RunResponse) IsSuccess() bool

IsSuccess reports whether the run completed successfully.

func (*RunResponse) RaiseForStatus 

func (r *RunResponse) RaiseForStatus() error

RaiseForStatus returns a RunError when the response is an error state.

type RunStatus 

type RunStatus string

RunStatus is the gateway-visible lifecycle status for a run. 

const (
	RunStatusEnqueued          RunStatus = "enqueued"
	RunStatusQueued            RunStatus = "queued"
	RunStatusStarted           RunStatus = "started"
	RunStatusRunning           RunStatus = "running"
	RunStatusCompleted         RunStatus = "completed"
	RunStatusFailed            RunStatus = "failed"
	RunStatusCancelled         RunStatus = "cancelled"
	RunStatusPaused            RunStatus = "paused"
	RunStatusAwaitingInput     RunStatus = "awaiting_input"
	RunStatusAwaitingUserInput RunStatus = "awaiting_user_input"
	RunStatusTimeout           RunStatus = "timeout"
	RunStatusUnknown           RunStatus = "unknown"
)

type SSEMCPTransport 

type SSEMCPTransport struct {
	Endpoint   string
	Headers    map[string]string
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

SSEMCPTransport sends MCP JSON-RPC requests to an HTTP/SSE MCP endpoint. It accepts both plain JSON responses and text/event-stream responses with JSON payloads in data: lines.

func NewSSEMCPTransport 

func NewSSEMCPTransport(endpoint string, headers map[string]string) *SSEMCPTransport

func (*SSEMCPTransport) Close 

func (t *SSEMCPTransport) Close() error

func (*SSEMCPTransport) Notify added in v0.4.0 

func (t *SSEMCPTransport) Notify(ctx context.Context, method string, params any) error

func (*SSEMCPTransport) Request 

func (t *SSEMCPTransport) Request(ctx context.Context, method string, params any) (map[string]any, error)

type SandboxRunner 

type SandboxRunner interface {
	ExecuteCode(ctx context.Context, language, code string) (ExecuteCodeResult, error)
	RunCommand(ctx context.Context, command []string) (RunCommandResult, error)
	WriteFile(ctx context.Context, path string, content []byte) (WriteFileResult, error)
	ReadFile(ctx context.Context, path string) (ReadFileResult, error)
	ListFiles(ctx context.Context, path string) (ListFilesResult, error)
}

SandboxRunner is the common sandbox operation boundary.

type ScorerConfig 

type ScorerConfig struct {
	Name        string
	Description string
	Handler     ScorerHandler
	Metadata    map[string]any
	Scope       ScorerScope
	IsAsync     bool
	DependsOn   []string
	InputSchema map[string]any
}

ScorerConfig describes a registered scorer.

func ContainsScorer 

func ContainsScorer() ScorerConfig

ContainsScorer returns a string containment scorer.

func ExactMatchScorer 

func ExactMatchScorer() ScorerConfig

ExactMatchScorer returns a deterministic exact-match scorer.

type ScorerContext added in v0.3.0 

type ScorerContext = Context

ScorerContext is the run-scoped context passed to worker scorer handlers.

type ScorerError added in v0.3.0 

type ScorerError struct {
	Code    string         `json:"code"`
	Message string         `json:"message"`
	Scorer  string         `json:"scorer,omitempty"`
	Details map[string]any `json:"details,omitempty"`
}

ScorerError is a typed scorer execution error returned by the eval runtime.

func (*ScorerError) Error added in v0.3.0 

func (e *ScorerError) Error() string

type ScorerHandler 

type ScorerHandler func(context.Context, ScorerRequest) (ScorerResult, error)

ScorerHandler executes a scorer.

type ScorerNameCollisionError added in v0.3.0 

type ScorerNameCollisionError struct {
	Name    string
	BuiltIn bool
}

ScorerNameCollisionError reports duplicate or reserved scorer names.

func (*ScorerNameCollisionError) Error added in v0.3.0 

func (e *ScorerNameCollisionError) Error() string

func (*ScorerNameCollisionError) Unwrap added in v0.3.0 

func (e *ScorerNameCollisionError) Unwrap() error

type ScorerNotFoundError added in v0.3.0 

type ScorerNotFoundError struct {
	Name string
}

ScorerNotFoundError reports an unknown custom scorer name.

func (*ScorerNotFoundError) Error added in v0.3.0 

func (e *ScorerNotFoundError) Error() string

type ScorerRegistry 

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

ScorerRegistry stores scorers by name.

func DefaultScorerRegistry 

func DefaultScorerRegistry() *ScorerRegistry

func NewScorerRegistry 

func NewScorerRegistry() *ScorerRegistry

func (*ScorerRegistry) Clear 

func (r *ScorerRegistry) Clear()

func (*ScorerRegistry) Get 

func (r *ScorerRegistry) Get(name string) (ScorerConfig, bool)

func (*ScorerRegistry) List 

func (r *ScorerRegistry) List() []ScorerConfig

func (*ScorerRegistry) Register 

func (r *ScorerRegistry) Register(config ScorerConfig) error

func (*ScorerRegistry) Run 

func (r *ScorerRegistry) Run(ctx context.Context, name string, request ScorerRequest) (ScorerResult, error)

type ScorerRequest 

type ScorerRequest struct {
	Input            any              `json:"input,omitempty"`
	Output           any              `json:"output,omitempty"`
	Expected         any              `json:"expected,omitempty"`
	Trace            []TraceEvent     `json:"trace,omitempty"`
	Config           map[string]any   `json:"config,omitempty"`
	PeerScores       []map[string]any `json:"peer_scores,omitempty"`
	TraceEvalContext any              `json:"trace_eval_context,omitempty"`
	State            map[string]any   `json:"state,omitempty"`
	States           map[string]any   `json:"states,omitempty"`
	StateSnapshots   map[string]any   `json:"state_snapshots,omitempty"`
	Metadata         map[string]any   `json:"metadata,omitempty"`
	// Events is retained for compatibility with early Go SDK scorer handlers.
	// New code should use Trace, which matches the cross-SDK scorer contract.
	Events []RunEvent `json:"events,omitempty"`
}

ScorerRequest is passed to scorer handlers.

type ScorerResult 

type ScorerResult struct {
	Score       float64        `json:"score"`
	Passed      bool           `json:"passed"`
	Explanation string         `json:"explanation,omitempty"`
	Label       string         `json:"label,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

ScorerResult is returned by scorer handlers.

func FailingScorerResult added in v0.3.0 

func FailingScorerResult(explanation string) ScorerResult

FailingScorerResult creates a fully failing scorer result.

func NewScorerResult added in v0.3.0 

func NewScorerResult(score float64, explanation string) ScorerResult

NewScorerResult creates a clamped scorer result and infers Passed at 0.5.

func PassingScorerResult added in v0.3.0 

func PassingScorerResult(explanation string) ScorerResult

PassingScorerResult creates a fully passing scorer result.

func TraceScorer added in v0.3.0 

func TraceScorer(trace []TraceEvent, assertions []TraceAssertion) ScorerResult

TraceScorer applies multiple assertions and returns their aggregate score.

type ScorerResultSummary added in v0.3.0 

type ScorerResultSummary = EvalScore

type ScorerScope added in v0.3.0 

type ScorerScope string

ScorerScope identifies the artifact a scorer evaluates. 

const (
	ScorerScopeItem     ScorerScope = "item"
	ScorerScopeRun      ScorerScope = "run"
	ScorerScopeTrace    ScorerScope = "trace"
	ScorerScopeSpan     ScorerScope = "span"
	ScorerScopeSession  ScorerScope = "session"
	ScorerScopeFleetRun ScorerScope = "fleet_run"
)

type ScriptedModel 

type ScriptedModel struct {
	Responses []GenerateResponse
	// contains filtered or unexported fields
}

ScriptedModel returns a deterministic sequence of responses.

func (*ScriptedModel) Generate 

func (m *ScriptedModel) Generate(_ context.Context, request GenerateRequest) (GenerateResponse, error)

type ServerConfig 

type ServerConfig struct {
	Name      string            `json:"name,omitempty"`
	Transport TransportType     `json:"transport"`
	Command   string            `json:"command,omitempty"`
	Args      []string          `json:"args,omitempty"`
	URL       string            `json:"url,omitempty"`
	Env       map[string]string `json:"env,omitempty"`
}

ServerConfig describes an MCP server connection.

type SessionProxy 

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

SessionProxy adds a default session ID to client calls.

func (*SessionProxy) Run 

func (p *SessionProxy) Run(ctx context.Context, component string, input any, opts ...RunOption) (*RunResponse, error)

func (*SessionProxy) WithUser 

func (p *SessionProxy) WithUser(userID string) *SessionProxy

WithUser returns a copy of the proxy that also sends X-User-ID.

func (*SessionProxy) Workflow 

func (p *SessionProxy) Workflow(name string) *SessionWorkflowProxy

type SessionWorkflowProxy 

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

SessionWorkflowProxy combines workflow and session defaults.

func (*SessionWorkflowProxy) Run 

func (p *SessionWorkflowProxy) Run(ctx context.Context, input any, opts ...RunOption) (*RunResponse, error)

type SleepOption added in v0.4.0 

type SleepOption func(*sleepOptions)

SleepOption configures one workflow sleep.

func WithSleepKey added in v0.4.0 

func WithSleepKey(key string) SleepOption

WithSleepKey assigns a stable key to a durable sleep. Use explicit keys in branches, loops, and fan-out where source-order ordinals are not stable.

type StateManager 

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

StateManager provides scoped key/value state access.

func NewStateManager 

func NewStateManager(store StateStore, scope StateScope, namespace string) *StateManager

NewStateManager constructs a scoped state manager.

func (*StateManager) Delete 

func (s *StateManager) Delete(ctx context.Context, key string) error

Delete removes a state value.

func (*StateManager) Get 

func (s *StateManager) Get(ctx context.Context, key string) (any, error)

Get returns a state value by key.

func (*StateManager) GetString 

func (s *StateManager) GetString(ctx context.Context, key string) (string, error)

GetString returns a string state value by key.

func (*StateManager) List 

func (s *StateManager) List(ctx context.Context) (map[string]any, error)

List returns all values in this scope.

func (*StateManager) Scope 

func (s *StateManager) Scope(scope StateScope, namespace string) *StateManager

Scope returns a manager for another scope and namespace.

func (*StateManager) Set 

func (s *StateManager) Set(ctx context.Context, key string, value any) error

Set stores a state value.

type StateScope 

type StateScope string

StateScope identifies the namespace for a state value. 

const (
	StateScopeRun     StateScope = "run"
	StateScopeSession StateScope = "session"
	StateScopeUser    StateScope = "user"
	StateScopeGlobal  StateScope = "global"
)

type StateStore 

type StateStore interface {
	Get(ctx context.Context, scope StateScope, namespace, key string) (any, bool, error)
	Set(ctx context.Context, scope StateScope, namespace, key string, value any) error
	Delete(ctx context.Context, scope StateScope, namespace, key string) error
	List(ctx context.Context, scope StateScope, namespace string) (map[string]any, error)
}

StateStore is the pluggable storage boundary for StateManager.

type StaticMCPTransport 

type StaticMCPTransport struct {
	Responses map[string]map[string]any
}

StaticMCPTransport is a deterministic in-memory transport for tests.

func (StaticMCPTransport) Close 

func (t StaticMCPTransport) Close() error

func (StaticMCPTransport) Request 

func (t StaticMCPTransport) Request(_ context.Context, method string, _ any) (map[string]any, error)

type StaticModel 

type StaticModel struct {
	Model     string
	Content   string
	ToolCalls []ToolCall
}

StaticModel is a deterministic model useful for tests and examples.

func (StaticModel) Generate 

func (m StaticModel) Generate(_ context.Context, request GenerateRequest) (GenerateResponse, error)

type StatusResponse 

type StatusResponse struct {
	RunID       string         `json:"run_id"`
	StatusCode  int            `json:"status_code"`
	Status      RunStatus      `json:"status"`
	TraceID     string         `json:"trace_id,omitempty"`
	Component   string         `json:"component,omitempty"`
	CreatedAt   *time.Time     `json:"created_at,omitempty"`
	StartedAt   *time.Time     `json:"started_at,omitempty"`
	CompletedAt *time.Time     `json:"completed_at,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
	Raw         map[string]any `json:"-"`
}

StatusResponse is returned by GetStatus.

func (*StatusResponse) IsComplete 

func (r *StatusResponse) IsComplete() bool

IsComplete reports whether the run is in a terminal status.

func (*StatusResponse) IsRunning 

func (r *StatusResponse) IsRunning() bool

IsRunning reports whether the run is actively executing.

type StdioMCPTransport 

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

StdioMCPTransport manages an MCP server process over newline-delimited JSON-RPC.

func NewStdioMCPTransport 

func NewStdioMCPTransport(ctx context.Context, command string, args ...string) (*StdioMCPTransport, error)

func NewStdioMCPTransportConfig 

func NewStdioMCPTransportConfig(ctx context.Context, config ServerConfig) (*StdioMCPTransport, error)

func (*StdioMCPTransport) Close 

func (t *StdioMCPTransport) Close() error

func (*StdioMCPTransport) Notify added in v0.4.0 

func (t *StdioMCPTransport) Notify(ctx context.Context, method string, params any) error

func (*StdioMCPTransport) Request 

func (t *StdioMCPTransport) Request(ctx context.Context, method string, params any) (map[string]any, error)

type Stereotyping added in v0.3.0 

type Stereotyping struct{ EvaluatorPresetConfig }

func (Stereotyping) ToEvalScorerSpec added in v0.3.0 

func (p Stereotyping) ToEvalScorerSpec() EvalScorerSpec

type StreamMCPTransport 

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

StreamMCPTransport sends newline-delimited JSON-RPC messages over an io pair.

func NewStreamMCPTransport 

func NewStreamMCPTransport(rw io.ReadWriter) *StreamMCPTransport

func (*StreamMCPTransport) Close 

func (t *StreamMCPTransport) Close() error

func (*StreamMCPTransport) Notify added in v0.4.0 

func (t *StreamMCPTransport) Notify(ctx context.Context, method string, params any) error

func (*StreamMCPTransport) Request 

func (t *StreamMCPTransport) Request(ctx context.Context, method string, params any) (map[string]any, error)

type StreamingLanguageModel 

type StreamingLanguageModel interface {
	LanguageModel
	Stream(
		ctx context.Context,
		request GenerateRequest,
		emit func(ModelStreamChunk) error,
	) (GenerateResponse, error)
}

StreamingLanguageModel is the optional streaming extension implemented by models that can return incremental text and tool-call chunks. LanguageModel remains the required compatibility surface, so existing models are unchanged. 

type SubmitLinks struct {
	SelfURL string `json:"self"`
}

SubmitLinks contains links returned for async submissions.

type SubmitOption 

type SubmitOption func(*submitConfig)

SubmitOption mutates Submit request configuration.

func WithSubmitComponentType 

func WithSubmitComponentType(componentType ComponentType) SubmitOption

WithSubmitComponentType sets the component kind for Submit.

func WithSubmitIdempotencyKey added in v0.4.0 

func WithSubmitIdempotencyKey(key string) SubmitOption

WithSubmitIdempotencyKey sets the stable caller key used to deduplicate a Submit admission.

func WithSubmitMetadata 

func WithSubmitMetadata(metadata map[string]string) SubmitOption

WithSubmitMetadata passes metadata through the async job queue.

func WithSubmitTenant 

func WithSubmitTenant(tenantID string) SubmitOption

WithSubmitTenant overrides the default X-TENANT-ID for this request.

type SubmitResponse 

type SubmitResponse struct {
	RunID      string       `json:"run_id"`
	StatusCode int          `json:"status_code"`
	Status     RunStatus    `json:"status"`
	TraceID    string       `json:"trace_id,omitempty"`
	Component  string       `json:"component,omitempty"`
	CreatedAt  *time.Time   `json:"created_at,omitempty"`
	Links      *SubmitLinks `json:"links,omitempty"`
	Raw        map[string]any
}

SubmitResponse is returned by Submit.

func (*SubmitResponse) StatusURL 

func (r *SubmitResponse) StatusURL() string

StatusURL returns the status link when the gateway supplied one.

type TokenUsage 

type TokenUsage struct {
	InputTokens         int `json:"input_tokens,omitempty"`
	OutputTokens        int `json:"output_tokens,omitempty"`
	TotalTokens         int `json:"total_tokens,omitempty"`
	CachedTokens        int `json:"cached_tokens,omitempty"`
	CacheCreationTokens int `json:"cache_creation_tokens,omitempty"`
}

TokenUsage captures provider token accounting.

type Tool 

type Tool struct {
	Name                     string         `json:"name"`
	Description              string         `json:"description,omitempty"`
	Schema                   map[string]any `json:"schema,omitempty"`
	Metadata                 map[string]any `json:"metadata,omitempty"`
	RecoveryPolicy           RecoveryPolicy `json:"recovery_policy,omitempty"`
	DisableDurableActivation bool           `json:"-"`
	Handler                  ToolHandler    `json:"-"`
}

Tool describes a callable tool.

func NewTool 

func NewTool(name string, handler ToolHandler, opts ...ToolOption) (Tool, error)

NewTool creates a Tool.

type ToolCall 

type ToolCall struct {
	ID          string         `json:"id,omitempty"`
	Name        string         `json:"name"`
	Arguments   map[string]any `json:"arguments,omitempty"`
	Raw         map[string]any `json:"raw,omitempty"`
	CallID      string         `json:"call_id,omitempty"`
	SpanID      string         `json:"span_id,omitempty"`
	TimestampNS int64          `json:"timestamp_ns,omitempty"`
	StartedAt   int64          `json:"started_at,omitempty"`
	EndedAt     int64          `json:"ended_at,omitempty"`
	Status      string         `json:"status,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

ToolCall is a provider-neutral request to execute a tool.

func ExtractToolCallsFromEvents added in v0.3.0 

func ExtractToolCallsFromEvents(events []TraceEvent) []ToolCall

ExtractToolCallsFromEvents normalizes tool calls from journal event payloads.

type ToolHandler 

type ToolHandler func(context.Context, map[string]any) (any, error)

ToolHandler executes a tool call.

type ToolOption 

type ToolOption func(*Tool)

ToolOption mutates Tool construction.

func WithToolDescription 

func WithToolDescription(description string) ToolOption

func WithToolMetadata 

func WithToolMetadata(metadata map[string]any) ToolOption

func WithToolRecoveryPolicy added in v0.4.0 

func WithToolRecoveryPolicy(policy RecoveryPolicy) ToolOption

WithToolRecoveryPolicy selects how interrupted calls are recovered.

func WithToolSchema 

func WithToolSchema(schema map[string]any) ToolOption

func WithoutDurableToolActivation added in v0.4.0 

func WithoutDurableToolActivation() ToolOption

WithoutDurableToolActivation preserves suspension-native or legacy tool behavior.

type ToolRegistry 

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

ToolRegistry stores tools by name.

func DefaultToolRegistry 

func DefaultToolRegistry() *ToolRegistry

DefaultToolRegistry returns the process-global tool registry.

func NewToolRegistry 

func NewToolRegistry() *ToolRegistry

NewToolRegistry creates an empty tool registry.

func (*ToolRegistry) CallTool 

func (r *ToolRegistry) CallTool(ctx context.Context, name string, input map[string]any) (any, error)

CallTool executes a tool from this registry.

func (*ToolRegistry) Clear 

func (r *ToolRegistry) Clear()

func (*ToolRegistry) Get 

func (r *ToolRegistry) Get(name string) (Tool, bool)

func (*ToolRegistry) List 

func (r *ToolRegistry) List() []Tool

func (*ToolRegistry) Register 

func (r *ToolRegistry) Register(tool Tool) error

type ToolTrajectoryMode added in v0.3.0 

type ToolTrajectoryMode string

ToolTrajectoryMode controls tool-call order matching. 

const (
	ToolTrajectoryExact    ToolTrajectoryMode = "exact"
	ToolTrajectoryInOrder  ToolTrajectoryMode = "in_order"
	ToolTrajectoryAnyOrder ToolTrajectoryMode = "any_order"
)

type TraceAssertion added in v0.3.0 

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

TraceAssertion checks journal events.

func DurationUnder added in v0.3.0 

func DurationUnder(max time.Duration) TraceAssertion

func EventCount added in v0.3.0 

func EventCount(eventType string, min int) TraceAssertion

func EventSequence added in v0.3.0 

func EventSequence(expected []string) TraceAssertion

func MaxLMCalls added in v0.3.0 

func MaxLMCalls(max int) TraceAssertion

func MaxTokens added in v0.3.0 

func MaxTokens(max int64) TraceAssertion

func NoErrors added in v0.3.0 

func NoErrors() TraceAssertion

func StepMemoized added in v0.3.0 

func StepMemoized(stepName string) TraceAssertion

func (TraceAssertion) Check added in v0.3.0 

func (a TraceAssertion) Check(trace []TraceEvent) AssertionResult

type TraceEvalContext added in v0.3.0 

type TraceEvalContext struct {
	SchemaVersion           string                   `json:"schema_version"`
	SessionID               string                   `json:"session_id"`
	ProjectID               string                   `json:"project_id"`
	DeploymentID            string                   `json:"deployment_id,omitempty"`
	RootRunID               string                   `json:"root_run_id"`
	TraceID                 string                   `json:"trace_id,omitempty"`
	Task                    *TraceEvalTask           `json:"task,omitempty"`
	Session                 TraceEvalSession         `json:"session,omitempty"`
	Plan                    TraceEvalPlan            `json:"plan,omitempty"`
	ExecutionSteps          []TraceEvalExecutionStep `json:"execution_steps,omitempty"`
	Features                TraceEvalFeatures        `json:"features,omitempty"`
	EvidenceRefs            any                      `json:"evidence_refs,omitempty"`
	RedactionPolicySnapshot any                      `json:"redaction_policy_snapshot,omitempty"`
}

TraceEvalContext is the redacted, normalized artifact used by trace scorers.

type TraceEvalExecutionStep added in v0.3.0 

type TraceEvalExecutionStep struct {
	Index           int64    `json:"index"`
	Kind            string   `json:"kind"`
	SpanID          string   `json:"span_id,omitempty"`
	RunID           string   `json:"run_id,omitempty"`
	Name            string   `json:"name,omitempty"`
	Role            string   `json:"role,omitempty"`
	Status          string   `json:"status,omitempty"`
	StartedAt       int64    `json:"started_at,omitempty"`
	EndedAt         int64    `json:"ended_at,omitempty"`
	DurationMS      int64    `json:"duration_ms,omitempty"`
	SummarySafe     string   `json:"summary_safe,omitempty"`
	ToolName        string   `json:"tool_name,omitempty"`
	Provider        string   `json:"provider,omitempty"`
	Model           string   `json:"model,omitempty"`
	Tokens          int64    `json:"tokens,omitempty"`
	InputRef        string   `json:"input_ref,omitempty"`
	InputHash       string   `json:"input_hash,omitempty"`
	OutputRef       string   `json:"output_ref,omitempty"`
	OutputHash      string   `json:"output_hash,omitempty"`
	ArgumentsRef    string   `json:"arguments_ref,omitempty"`
	ArgumentsHash   string   `json:"arguments_hash,omitempty"`
	ResultRef       string   `json:"result_ref,omitempty"`
	ResultHash      string   `json:"result_hash,omitempty"`
	PromptRef       string   `json:"prompt_ref,omitempty"`
	PromptHash      string   `json:"prompt_hash,omitempty"`
	ResponseRef     string   `json:"response_ref,omitempty"`
	ResponseHash    string   `json:"response_hash,omitempty"`
	ErrorCode       string   `json:"error_code,omitempty"`
	ErrorClass      string   `json:"error_class,omitempty"`
	ErrorSafe       string   `json:"error_safe,omitempty"`
	MatchesPlanStep *int64   `json:"matches_plan_step,omitempty"`
	Flags           []string `json:"flags,omitempty"`
}

type TraceEvalFeatures added in v0.3.0 

type TraceEvalFeatures struct {
	ExecutionStepCount  int64                      `json:"execution_step_count,omitempty"`
	ToolCallCount       int64                      `json:"tool_call_count,omitempty"`
	UniqueToolCallCount int64                      `json:"unique_tool_call_count,omitempty"`
	TurnCount           int64                      `json:"turn_count,omitempty"`
	LMCallCount         int64                      `json:"llm_call_count,omitempty"`
	TotalTokens         int64                      `json:"total_tokens,omitempty"`
	ErrorCount          int64                      `json:"error_count,omitempty"`
	DuplicateToolCalls  []TraceEvalStepGroup       `json:"duplicate_tool_calls,omitempty"`
	PlanStepsTotal      int64                      `json:"plan_steps_total,omitempty"`
	PlanStepsMatched    int64                      `json:"plan_steps_matched,omitempty"`
	PlanStepsMissing    []TraceEvalMissingPlanStep `json:"plan_steps_missing,omitempty"`
	OffPathSteps        []int64                    `json:"off_path_steps,omitempty"`
	RetryGroups         []TraceEvalRetryGroup      `json:"retry_groups,omitempty"`
}

type TraceEvalMissingPlanStep added in v0.3.0 

type TraceEvalMissingPlanStep struct {
	PlanStepIndex int64  `json:"plan_step_index,omitempty"`
	TextSafe      string `json:"text_safe,omitempty"`
}

type TraceEvalPlan added in v0.3.0 

type TraceEvalPlan struct {
	Detected bool                `json:"detected"`
	Steps    []TraceEvalPlanStep `json:"steps,omitempty"`
}

type TraceEvalPlanStep added in v0.3.0 

type TraceEvalPlanStep struct {
	Index          int64  `json:"index,omitempty"`
	TextSafe       string `json:"text_safe,omitempty"`
	ExpectedAction string `json:"expected_action,omitempty"`
	ExpectedTool   string `json:"expected_tool,omitempty"`
}

type TraceEvalRetryGroup added in v0.3.0 

type TraceEvalRetryGroup struct {
	StepIDs []int64 `json:"step_ids,omitempty"`
	Reason  string  `json:"reason,omitempty"`
}

type TraceEvalSession added in v0.3.0 

type TraceEvalSession struct {
	TurnCount int64           `json:"turn_count,omitempty"`
	Turns     []TraceEvalTurn `json:"turns,omitempty"`
}

type TraceEvalStepGroup added in v0.3.0 

type TraceEvalStepGroup struct {
	ToolName string  `json:"tool_name,omitempty"`
	StepIDs  []int64 `json:"step_ids,omitempty"`
	Reason   string  `json:"reason,omitempty"`
}

type TraceEvalTask added in v0.3.0 

type TraceEvalTask struct {
	TextSafe string `json:"text_safe,omitempty"`
}

type TraceEvalTurn added in v0.3.0 

type TraceEvalTurn struct {
	TurnIndex   int64  `json:"turn_index,omitempty"`
	Role        string `json:"role,omitempty"`
	StartedAt   int64  `json:"started_at,omitempty"`
	EndedAt     int64  `json:"ended_at,omitempty"`
	MessageRef  string `json:"message_ref,omitempty"`
	MessageHash string `json:"message_hash,omitempty"`
	SummarySafe string `json:"summary_safe,omitempty"`
}

type TraceEvent added in v0.3.0 

type TraceEvent struct {
	EventType           string         `json:"event_type"`
	EventID             string         `json:"event_id,omitempty"`
	CorrelationID       string         `json:"correlation_id,omitempty"`
	ParentCorrelationID string         `json:"parent_correlation_id,omitempty"`
	TimestampNS         int64          `json:"timestamp_ns,omitempty"`
	Data                map[string]any `json:"data,omitempty"`
	Name                string         `json:"name,omitempty"`
}

TraceEvent is the cross-SDK journal event shape used by eval helpers.

func (*TraceEvent) UnmarshalJSON added in v0.3.0 

func (e *TraceEvent) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts both runtime snake_case and SDK camelCase event fields.

type TraceScorerResult added in v0.3.0 

type TraceScorerResult = ScorerResult

type TransportType 

type TransportType string

TransportType identifies an MCP transport. 

const (
	TransportTypeStdio TransportType = "stdio"
	TransportTypeSSE   TransportType = "sse"
)

type TriggerSpec 

type TriggerSpec struct {
	TriggerID        string `json:"trigger_id,omitempty"`
	TriggerType      string `json:"trigger_type"`
	EventName        string `json:"event_name,omitempty"`
	FilterExpression string `json:"filter_expression,omitempty"`
	InputMapping     string `json:"input_mapping,omitempty"`
	BatchWindowMS    int64  `json:"batch_window_ms,omitempty"`
	DelayExpression  string `json:"delay_expression,omitempty"`
}

TriggerSpec declares a runtime trigger attached to a component registration.

func EventTrigger 

func EventTrigger(name string) TriggerSpec

EventTrigger declares an event trigger for a workflow.

func WebhookTrigger 

func WebhookTrigger(source, event string) TriggerSpec

WebhookTrigger declares a webhook event trigger. Runtime webhooks dispatch as "{source}.{event}", matching Python and TypeScript SDK helpers.

type UserInputRequest 

type UserInputRequest struct {
	ID          string         `json:"id"`
	Prompt      string         `json:"prompt"`
	Type        HITLInputType  `json:"type"`
	Options     []HITLOption   `json:"options,omitempty"`
	AllowCustom bool           `json:"allow_custom,omitempty"`
	Skippable   bool           `json:"skippable,omitempty"`
	Metadata    map[string]any `json:"metadata,omitempty"`
}

UserInputRequest is emitted when a workflow pauses for user input.

type WaitingForUserInputError 

type WaitingForUserInputError struct {
	Request UserInputRequest
}

WaitingForUserInputError marks an invocation as waiting for user input.

func (*WaitingForUserInputError) Error 

func (e *WaitingForUserInputError) Error() string

type Worker 

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

Worker owns component registration and, once transport is wired, runtime connectivity for a Go service.

func NewWorker 

func NewWorker(serviceName string, opts ...WorkerOption) *Worker

NewWorker constructs a Go worker with environment-compatible defaults.

func (*Worker) Components 

func (w *Worker) Components() []ComponentInfo

Components returns deterministic registration descriptors for this worker.

func (*Worker) CoordinatorEndpoint 

func (w *Worker) CoordinatorEndpoint() string

CoordinatorEndpoint returns the coordinator endpoint the worker will dial.

func (*Worker) DeploymentID 

func (w *Worker) DeploymentID() string

DeploymentID returns the configured deployment routing key.

func (*Worker) DurableActivationStatus added in v0.4.0 

func (w *Worker) DurableActivationStatus() DurableActivationStatus

DurableActivationStatus returns the latest negotiated runtime capability state.

func (*Worker) EngineEndpoint 

func (w *Worker) EngineEndpoint() string

EngineEndpoint returns the optional direct engine endpoint used for journal writes.

func (*Worker) MaxConcurrency 

func (w *Worker) MaxConcurrency() uint32

MaxConcurrency returns the configured in-flight invocation budget.

func (*Worker) Metadata 

func (w *Worker) Metadata() map[string]string

Metadata returns a defensive copy of service metadata.

func (*Worker) ProjectID 

func (w *Worker) ProjectID() string

ProjectID returns the configured project routing key.

func (*Worker) Registry 

func (w *Worker) Registry() *Registry

Registry returns the component registry owned by the worker.

func (*Worker) Run 

func (w *Worker) Run(ctx context.Context) error

Run connects this worker to AGNT5 and starts the push-mode worker stream.

func (*Worker) ServiceName 

func (w *Worker) ServiceName() string

ServiceName returns the service name advertised by the worker.

func (*Worker) ServiceType 

func (w *Worker) ServiceType() string

ServiceType returns the service type advertised by the worker.

func (*Worker) ServiceVersion 

func (w *Worker) ServiceVersion() string

ServiceVersion returns the service version advertised by the worker.

func (*Worker) WorkerID 

func (w *Worker) WorkerID() string

WorkerID returns the runtime stream identity advertised by this process.

func (*Worker) WorkerMode 

func (w *Worker) WorkerMode() WorkerMode

WorkerMode returns the configured assignment mode.

type WorkerMode 

type WorkerMode string

WorkerMode controls how the worker receives assignments from the runtime. 

const (
	WorkerModePush WorkerMode = "push"
	WorkerModePull WorkerMode = "pull"
)

type WorkerOption 

type WorkerOption func(*Worker)

WorkerOption mutates Worker configuration during construction.

func WithCoordinatorEndpoint 

func WithCoordinatorEndpoint(endpoint string) WorkerOption

WithCoordinatorEndpoint sets the runtime coordinator endpoint.

func WithDeploymentID 

func WithDeploymentID(deploymentID string) WorkerOption

WithDeploymentID sets the deployment routing key for worker metadata.

func WithDurableActivationArtifact added in v0.4.0 

func WithDurableActivationArtifact(sha256 string) WorkerOption

WithDurableActivationArtifact supplies the immutable deployed artifact SHA-256 used in activation definition identity. Managed runtimes normally inject this value; local E2E workers may set it explicitly.

func WithDurableActivationMode added in v0.4.0 

func WithDurableActivationMode(mode DurableActivationMode) WorkerOption

WithDurableActivationMode selects disabled, preferred, or required startup behavior for durable_activation_v1 protocol negotiation.

func WithEngineEndpoint 

func WithEngineEndpoint(endpoint string) WorkerOption

WithEngineEndpoint sets the direct engine endpoint for durable journal writes. Leave empty to rely on coordinator terminal-response fallback behavior.

func WithMaxConcurrency 

func WithMaxConcurrency(maxConcurrency uint32) WorkerOption

WithMaxConcurrency sets the max in-flight invocation budget.

func WithMaxReconnects 

func WithMaxReconnects(maxReconnects uint32) WorkerOption

WithMaxReconnects sets the retry budget after transient coordinator failures.

func WithMetadata 

func WithMetadata(metadata map[string]string) WorkerOption

WithMetadata adds service-level metadata advertised during registration.

func WithProjectID 

func WithProjectID(projectID string) WorkerOption

WithProjectID sets the project routing key for worker metadata.

func WithReconnectBackoff 

func WithReconnectBackoff(initial, max time.Duration) WorkerOption

WithReconnectBackoff sets the initial and maximum reconnect delay.

func WithServiceType 

func WithServiceType(serviceType string) WorkerOption

WithServiceType sets the service type advertised during worker registration.

func WithServiceVersion 

func WithServiceVersion(version string) WorkerOption

WithServiceVersion sets the version advertised during worker registration.

func WithStateStore 

func WithStateStore(store StateStore) WorkerOption

WithStateStore overrides the default run/session/user state backend.

func WithWorkerID 

func WithWorkerID(workerID string) WorkerOption

WithWorkerID sets the runtime stream identity advertised by the worker.

func WithWorkerMode 

func WithWorkerMode(mode WorkerMode) WorkerOption

WithWorkerMode sets push or pull assignment mode.

type WorkflowProxy 

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

WorkflowProxy is a fluent client wrapper for one workflow component.

func (*WorkflowProxy) Run 

func (p *WorkflowProxy) Run(ctx context.Context, input any, opts ...RunOption) (*RunResponse, error)

func (*WorkflowProxy) Submit 

func (p *WorkflowProxy) Submit(ctx context.Context, input any, opts ...SubmitOption) (*SubmitResponse, error)

type WorkingMemory 

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

WorkingMemory stores a single session working-memory document.

func (*WorkingMemory) Get 

func (m *WorkingMemory) Get(ctx context.Context) (string, error)

func (*WorkingMemory) Set 

func (m *WorkingMemory) Set(ctx context.Context, value string) error

type WriteFileResult 

type WriteFileResult struct {
	Path  string `json:"path"`
	Bytes int    `json:"bytes"`
}

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.