agents

type AIConfig ¶

type AIConfig struct {
	TaskQueue string
	Durable   bool
	Realtime  bool
	Public    bool

	Model        string
	Inference    string
	MaxSteps     int
	Tools        map[string]ai.Tool
	Provider     ai.Provider
	Instructions string
	Revision     string

	// LiveModel is the Gemini Live (or equivalent) model id used for voice.
	// Required when the agent declares a voice channel. Reuse Inference for
	// Live credentials — do not add a separate LiveInference field.
	LiveModel string
	// ToolModel is the text/tool-loop model used alongside LiveModel. Required
	// whenever LiveModel is set; it is never defaulted from Model.
	ToolModel string
	// VoiceName is the default prebuilt voice for Live sessions.
	VoiceName string

	DurableUpdates             DurableUpdateStore
	OnReviewPublicationFailure func(context.Context, updates.UpdateEvent, error)
}

AIConfig declares a framework-owned model/tool loop. Model is an OpenRouter catalog id (for example openai/gpt-4o-mini or google/gemini-2.5-flash). Known first-segment providers stay {openrouter, anthropic, bedrock, vertex}; do not author openai/, google/, x-ai/, or grok/ as built-in providers.

Inference selects a process-local BYOK provider (openrouter, google, vertex, anthropic, or bedrock) and is an unmetered hosted bypass. It is not copied into the agents manifest or Temporal workflow input. Provider may be supplied for a custom provider; credentials stay runtime-only.

type AIDefinition ¶

type AIDefinition struct {
	Config Config
	AI     AIConfig
	Slots  Slots
}

AIDefinition is the fixed conversational agent definition produced by DefineAI. The compiler fills Instructions and Revision from instructions.md and the compiled filesystem definition.

func DefineAI(config AIConfig, slots ...Slots) AIDefinition

func (definition AIDefinition) Invoke(ctx context.Context, actor Actor, input AIInput) (AIOutput, error)

func (definition AIDefinition) LanguageModel() (ai.LanguageModel, error)

func (definition AIDefinition) ProbeLiveModel() error

func (definition AIDefinition) RuntimeProvider() ai.Provider

func (definition AIDefinition) Stream(ctx context.Context, actor Actor, input AIInput) (*ai.StreamTextResult, error)

func (definition AIDefinition) ValidateRegistration() error

type AIInput ¶

type AIInput struct {
	Prompt   string      `json:"prompt,omitempty"`
	Message  string      `json:"message,omitempty"`
	Text     string      `json:"text,omitempty"`
	Messages []AIMessage `json:"messages,omitempty"`
}

AIInput accepts both prompt-oriented callers and AI SDK chat transports. Prompt wins over the Message/Text convenience aliases when more than one is provided.

func (input AIInput) PromptText() string

func (input AIInput) ToAIMessages() ([]ai.Message, error)

type AIMessage ¶

type AIMessage struct {
	Role    string          `json:"role"`
	Content string          `json:"content,omitempty"`
	Parts   []AIMessagePart `json:"parts,omitempty"`
}

AIMessage is the text-message subset shared by the native HTTP client and AI SDK chat transports. Content supports simple clients; Parts supports AI SDK UIMessage text parts.

type AIMessagePart ¶

type AIMessagePart struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

type AIOutput ¶

type AIOutput struct {
	Text            string `json:"text"`
	FinishReason    string `json:"finishReason,omitempty"`
	RawFinishReason string `json:"rawFinishReason,omitempty"`
	Model           string `json:"model,omitempty"`
}

AIOutput is the stable native agent.output payload for both direct and durable AI agents.

type AITool ¶

type AITool = ai.Tool

AITool is the Go AI SDK tool definition used by a filesystem agent. Keeping the alias here lets authored agents define tools without importing framework runtime packages.

func DefineTool[Input any, Output any](config ToolConfig, handler ToolHandler[Input, Output]) AITool

func DefineToolWithCall[Input any, Output any](config ToolConfig, handler ToolCallHandler[Input, Output]) AITool

type Actor ¶

type Actor struct {
	ID       string            `json:"id"`
	Kind     string            `json:"kind"`
	Metadata map[string]string `json:"metadata,omitempty"`
}

Actor is the authenticated principal that invoked an agent. Identity is explicit so direct and durable invocations have the same author-facing type.

func DevLoopbackActor() Actor

func LoopbackDevActor() Actor

func (actor Actor) Validate() error

type Channel ¶

type Channel struct {
	ID        string
	Connector string
}

type Config ¶

type Config struct {
	TaskQueue string
	Durable   bool
	// Realtime keeps the agent durable while selecting a compiler-owned,
	// agent-unique task queue and local model/tool activity boundaries. It is
	// intentionally an execution hint rather than a persistence mode.
	Realtime bool
	Public   bool
}

Config is compiler-visible agent metadata. TaskQueue is a logical queue name; generated durable workers append the active environment suffix.

func (config Config) Mode() Mode

type Definition ¶

type Definition[Input any, Output any] struct {
	Config  Config
	Handler Handler[Input, Output]
	Slots   Slots
}

Definition associates compiler-visible metadata with a typed handler.

func Define[Input any, Output any](config Config, handler Handler[Input, Output], slots ...Slots) Definition[Input, Output]

func (definition Definition[Input, Output]) Invoke(ctx context.Context, actor Actor, input Input) (Output, error)

type DurableRunInput ¶

type DurableRunInput struct {
	Session Session         `json:"session"`
	Run     Run             `json:"run"`
	Actor   Actor           `json:"actor"`
	Input   json.RawMessage `json:"input"`
}

DurableRunInput is the serialization contract shared by the HTTP Temporal dispatcher and compiler-generated durable agent workflows. Generated workflows pass Input to the typed agent activity after decoding it there.

type DurableRunOutput ¶

type DurableRunOutput struct {
	Output json.RawMessage `json:"output"`
}

DurableRunOutput is returned by compiler-generated durable agent workflows. Output must contain one complete JSON value so the transport can publish the same agent.output event shape used by direct agents.

type DurableUpdateStore ¶

type DurableUpdateStore interface {
	updates.PreviewStore
	updates.RecordStore
}

DurableUpdateStore is the customer-owned durable half of a hosted agent conversation connector. GoBeyond never receives its credentials. Hosted workers compose it with the slot-private host review publisher; local workers keep using the durable store without requiring platform services.

type Handler ¶

type Handler[Input any, Output any] func(context.Context, Actor, Input) (Output, error)

Handler is the type-safe authoring signature for an agent run.

type HostedWebSearchRequest ¶

type HostedWebSearchRequest struct {
	NetworkID  string `json:"network_id,omitempty"`
	SessionID  string `json:"session_id,omitempty"`
	ToolCallID string `json:"tool_call_id,omitempty"`
	Query      string `json:"query"`
}

HostedWebSearchRequest is the provider-neutral Google grounding request. NetworkID is context/attribution only; the host-report socket identity is authoritative for the tenant.

type HostedWebSearchResponse ¶

type HostedWebSearchResponse struct {
	Answer      string   `json:"answer,omitempty"`
	Sources     []string `json:"sources,omitempty"`
	Searched    bool     `json:"searched"`
	Stub        bool     `json:"stub"`
	ReasonCode  string   `json:"reason_code,omitempty"`
	SearchModel string   `json:"search_model,omitempty"`
	Provider    string   `json:"provider,omitempty"`
}

HostedWebSearchResponse is deliberately explicit about grounding state so a failed provider call cannot be mistaken for a successful search.

func HostedWebSearch(ctx context.Context, request HostedWebSearchRequest) (HostedWebSearchResponse, error)

type Mode ¶

type Mode string

Mode describes how a run is executed.

const (
	// DirectMode executes in the request/runtime process. It is the default.
	DirectMode Mode = "direct"
	// DurableMode executes through the generated durable workflow runtime.
	DurableMode Mode = "durable"
)

type ModelMetadata ¶

type ModelMetadata struct {
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
}

ModelMetadata identifies the model selected for a run without leaking provider credentials or mutable runtime configuration into authored code.

type Run ¶

type Run struct {
	ID        string        `json:"id"`
	SessionID string        `json:"sessionId"`
	AgentID   string        `json:"agentId"`
	Mode      Mode          `json:"mode"`
	TaskQueue string        `json:"taskQueue,omitempty"`
	Model     ModelMetadata `json:"model,omitempty"`
	Status    string        `json:"status"`
	CreatedAt time.Time     `json:"createdAt"`
	UpdatedAt time.Time     `json:"updatedAt"`
}

Run is one execution attempt in a session. TaskQueue is empty for direct runs unless the host records a selected logical queue for observability.

type Schedule ¶

type Schedule struct {
	ID   string
	Cron string
}

type Session ¶

type Session struct {
	ID        string            `json:"id"`
	AgentID   string            `json:"agentId"`
	Actor     Actor             `json:"actor"`
	Model     ModelMetadata     `json:"model,omitempty"`
	CreatedAt time.Time         `json:"createdAt"`
	UpdatedAt time.Time         `json:"updatedAt"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

Session is the durable conversation identity shared by one or more runs.

type Skill ¶

type Skill struct {
	ID string
}

type Slots ¶

type Slots struct {
	Tools     []Tool
	Skills    []Skill
	Subagents []Subagent
	Schedules []Schedule
	Channels  []Channel
}

Slots declares every extensibility slot on an agent in one compiler-visible literal. Empty slots are valid and do not change the direct default.

type Subagent ¶

type Subagent struct {
	ID string
}

type Tool ¶

type Tool struct {
	ID string
}

Tool, Skill, Subagent, Schedule, and Channel are compiler-visible slots. IDs are stable authored references; their provider-specific implementations are deliberately kept outside this initial package boundary.

type ToolCallHandler ¶

type ToolCallHandler[Input any, Output any] func(context.Context, Actor, ai.ToolCall, Input) (Output, error)

ToolCallHandler is the call-aware form of ToolHandler. The call metadata is supplied by the provider and is preserved across hosted/durable tool dispatch. Existing tools should continue to use ToolHandler unless they need to correlate work with a provider tool-call ID.

type ToolConfig ¶

type ToolConfig struct {
	Name        string
	Title       string
	Description string
	// TaskQueue is a logical Temporal queue. Durable agents inherit their own
	// resolved queue when this is empty. Realtime agents reject explicit tool
	// queues because their tools execute as local activities.
	TaskQueue        string
	InputSchema      any
	OutputSchema     any
	RequiresApproval bool
}

ToolConfig is the provider-neutral authoring surface for a model-callable function. Schemas use ordinary JSON Schema values (usually map[string]any).

type ToolHandler ¶

type ToolHandler[Input any, Output any] func(context.Context, Actor, Input) (Output, error)