restate

package
v0.3.3 Latest Latest
Warning

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

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

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrAgentEventLogCleared = errors.New(errAgentEventLogClearedMsg)

ErrAgentEventLogCleared is returned (as a Restate terminal error) when Pull targets a log that has been Cleared past the reader's offset.

View Source
var ErrNotApprovalCustomEvent = errors.New("restate: custom event is not a recognized approval kind")

ErrNotApprovalCustomEvent means the CUSTOM event name is not tool or delegation approval.

Functions

This section is empty.

Types

type AgentEventLog

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

AgentEventLog is a Restate Virtual Object implementing a per-run durable event log (publish / pull / subscribe / clear). Bound beside AgentLoop so Stream can publish events and [streamHandle.Events] can pull them from any process.

Protocol mirrors https://github.com/restatedev/pubsub (TypeScript @restatedev/pubsub), with Clear (full wipe) instead of partial Truncate — matching this product's use case.

func (AgentEventLog) Clear

Clear removes all messages from this run's event log (full wipe after EventLog.TTL).

func (AgentEventLog) Publish

Publish appends a message and notifies waiting subscribers.

func (AgentEventLog) Pull

Pull returns messages from offset (catch-up). When PullRequest.Wait is false (SDK default), an empty topic returns immediately with no awakeable — safe for short-lived clients. When Wait is true, long-polls up to pubsubPullTimeout and returns HTTP 408 on timeout.

func (AgentEventLog) ServiceName

func (s AgentEventLog) ServiceName() string

ServiceName returns the Restate service name for this Virtual Object.

func (AgentEventLog) Subscribe

func (AgentEventLog) Subscribe(ctx restatesdk.ObjectContext, sub pubsubSubscription) error

Subscribe registers an awakeable for future publishes, or resolves immediately when messages are already available at/after offset. Exclusive (mutates subscription state).

type AgentLoop

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

AgentLoop is the Restate service that runs the durable agent loop. Bound via restatesdk.Reflect(AgentLoop{rt: r}) in NewRestateRuntime. Value receivers are required for Reflect to discover handlers.

func (AgentLoop) Cancel

func (AgentLoop) Cancel(ctx restatesdk.Context, req CancelRequest) error

Cancel cancels an in-flight agent loop invocation via Restate's native CancelInvocation. Stateless: does not need the runtime pointer.

func (AgentLoop) Run

Run is the durable non-streaming agent loop entry point.

func (AgentLoop) ServiceName

func (s AgentLoop) ServiceName() string

ServiceName returns the Restate service name (AgentLoop_<agentName>).

func (AgentLoop) Stream

Stream is the durable streaming agent loop entry point.

type AgentLoopInput

type AgentLoopInput struct {

	// StreamingEnabled requests token-level LLM streaming.
	// Only active when IsStreamHandler is also true (the Stream handler enables both).
	StreamingEnabled bool
	// IsStreamHandler is true when this input is for the Stream handler path.
	// Stream runs publish events to AgentEventLog; Run runs publish only approval events.
	IsStreamHandler bool
	// Tools is the resolved tool list for this run (not on the Restate wire payload).
	Tools []interfaces.Tool
	// contains filtered or unexported fields
}

AgentLoopInput holds per-run execution inputs for one durable Restate agent run. Shares [agentLoopCore] with AgentLoopRequest; adds resolved tools and stream flags. Mirrors AgentLoopInput (local) / AgentWorkflowInput (Temporal) field semantics.

type AgentLoopRequest

type AgentLoopRequest struct {
	AgentName        string `json:"agent_name,omitempty"`
	LLMStreamEnabled bool   `json:"llm_stream_enabled"`
	StreamHandler    bool   `json:"stream_handler"`
	// contains filtered or unexported fields
}

AgentLoopRequest is the JSON ingress payload for AgentLoop.Run and .Stream. Non-serializable per-run state (tools, eventTypes) is stashed in rt.tools.stash.

type AgentLoopResponse

type AgentLoopResponse struct {
	Result *types.AgentRunResult `json:"result,omitempty"`
}

AgentLoopResponse is the durable result serialised by Restate when the handler completes.

type AgentLoopResult

type AgentLoopResult struct {
	Content   string
	LLMUsage  *interfaces.LLMUsage
	Telemetry *types.AgentTelemetry
}

AgentLoopResult is the outcome of a completed durable agent run. Mirrors AgentLoopResult (local) and AgentWorkflowResult (Temporal) — same fields, same semantics.

type CancelRequest

type CancelRequest struct {
	RunID        string `json:"run_id,omitempty"`
	InvocationID string `json:"invocation_id"`
}

CancelRequest requests cancellation of an in-flight agent loop invocation.

type EndpointConfig

type EndpointConfig struct {
	// ListenAddress is the bind address for the SDK endpoint (e.g. ":9080").
	// Empty defaults to ":9080".
	ListenAddress string
	// IdentityPublicKeys are optional Restate request-identity public keys
	// used to verify inbound requests from Restate.
	IdentityPublicKeys []string
	// AdminURL is the Restate admin API base URL (e.g. "http://localhost:9070").
	// When set, NewRestateRuntime registers this endpoint automatically after startup.
	AdminURL string
	// DeploymentURL is the URL Restate uses to call back into this process.
	// Empty defaults to http://127.0.0.1 + ListenAddress port. Override when Restate
	// runs in a container with a different network (e.g. "http://host.docker.internal:9080").
	DeploymentURL string
}

EndpointConfig specifies where this process serves AgentLoop for Restate to invoke.

type EventLogConfig

type EventLogConfig struct {
	// DisableClear skips scheduling AgentEventLog/Clear after a root run.
	// Default false means cleanup is on.
	DisableClear bool
	// TTL is how long to wait after a root Run/Stream completes before Clear.
	// Used only when DisableClear is false. Zero defaults to 90 seconds.
	TTL time.Duration
}

EventLogConfig configures when AgentEventLog state is Cleared after a root Run/Stream.

By default (zero value), cleanup is enabled and Clear is scheduled EventLog.TTL after the run completes (90s). Set DisableClear for short-lived examples so Restate does not retry Clear against a process that has already exited.

type IngressConfig

type IngressConfig struct {
	// URL is the Restate ingress base URL (e.g. "http://localhost:8080").
	URL string
	// AuthKey is an optional bearer token for authenticated ingress (e.g. Restate Cloud).
	AuthKey string
	// HTTPTimeout is the per-attempt timeout for short ingress RPCs.
	// Zero defaults to 30s. Long-running Attach is not bounded by this field.
	HTTPTimeout time.Duration
	// HTTPMaxAttempts is the retry budget for transient failures (network, 429/5xx).
	// Zero defaults to 3.
	HTTPMaxAttempts int
}

IngressConfig specifies how this runtime contacts Restate to submit and manage runs.

type Option

type Option func(*RestateRuntime)

Option configures a RestateRuntime at construction time.

func WithAgentConfig

func WithAgentConfig(cfg runtime.AgentConfig) Option

WithAgentConfig sets static agent wiring (LLM client, limits, memory, retrievers, hooks).

func WithAgentSpec

func WithAgentSpec(spec runtime.AgentSpec) Option

WithAgentSpec sets the agent identity (name, description, system prompt).

func WithApprovalHandler

func WithApprovalHandler(fn types.ApprovalHandler) Option

WithApprovalHandler sets the Run-path approval callback. The handler is called synchronously for each tool that requires human approval. Stream runs use CUSTOM events + [StreamHandle.Approve] instead.

func WithLogger

func WithLogger(l logger.Logger) Option

WithLogger sets the logger used by the runtime and its Restate endpoint.

func WithMetrics

func WithMetrics(metrics interfaces.Metrics) Option

WithMetrics sets the metrics sink.

func WithRestateConfig

func WithRestateConfig(config *RestateConfig) Option

WithRestateConfig sets the Restate connection and endpoint configuration.

func WithToolExecutionMode

func WithToolExecutionMode(mode types.AgentToolExecutionMode) Option

WithToolExecutionMode controls whether tools run sequentially or in parallel per iteration.

func WithToolsResolver

func WithToolsResolver(fn ToolsResolver) Option

WithToolsResolver sets the fallback tool resolver for multi-pod deployments. In single-pod mode, tools passed via [RunRequest.Tools] are stashed in-process and loaded at handler entry. WithToolsResolver provides a registry-based fallback for pods that receive a Restate invocation without a stash entry (different pod).

func WithTracer

func WithTracer(tracer interfaces.Tracer) Option

WithTracer sets the OpenTelemetry tracer for distributed tracing.

type PullRequest

type PullRequest struct {
	// Offset is the next message index to read. Nil means wait for new messages at tail
	// (no catch-up). Zero is a valid start-of-stream offset.
	Offset *int64 `json:"offset,omitempty"`
	// Wait, when true, long-polls up to pubsubPullTimeout (Restate PubSub convention).
	// SDK stream/approval listeners use Wait=false so Pull always completes quickly and
	// is never left suspended when the process exits.
	Wait bool `json:"wait,omitempty"`
}

PullRequest is the body for AgentEventLog.Pull.

type PullResponse

type PullResponse struct {
	Messages   []json.RawMessage `json:"messages"`
	NextOffset int64             `json:"nextOffset"`
}

PullResponse is returned by AgentEventLog.Pull.

type RestateConfig

type RestateConfig struct {
	Ingress  IngressConfig
	Endpoint EndpointConfig
	// EventLog controls post-run cleanup of the per-run [AgentEventLog] virtual object.
	EventLog EventLogConfig
}

RestateConfig holds Restate ingress and endpoint settings for a RestateRuntime.

type RestateRuntime

type RestateRuntime struct {
	base.Runtime
	// contains filtered or unexported fields
}

RestateRuntime executes the agent loop via Restate, embedding base.Runtime for shared core methods (LLM, tools, memory, retrievers). The Restate SDK endpoint serves AgentLoop and AgentEventLog for this agent. Sub-agents are independent Restate agents (own listen port / deployment); the parent invokes their AgentLoop service by name.

func NewRestateRuntime

func NewRestateRuntime(opts ...Option) (*RestateRuntime, error)

NewRestateRuntime constructs a RestateRuntime, binds AgentLoop and AgentEventLog, starts the SDK endpoint, and optionally registers the deployment with the Restate admin API.

func (*RestateRuntime) Close

func (rt *RestateRuntime) Close()

Close stops the Restate SDK endpoint and releases runtime resources.

func (*RestateRuntime) GetRunHandle

func (rt *RestateRuntime) GetRunHandle(ctx context.Context, runID string) (sdkruntime.RunHandle, error)

GetRunHandle reconnects to an existing non-streaming run identified by runID. Returns ErrRunNotFound when Restate has no record and ErrRunAlreadyCompleted when finished.

func (*RestateRuntime) GetStreamHandle

func (rt *RestateRuntime) GetStreamHandle(ctx context.Context, runID string) (sdkruntime.StreamHandle, error)

GetStreamHandle reconnects to an existing streaming run identified by runID. Returns ErrStreamNotFound when Restate has no record and ErrRunAlreadyCompleted when finished.

func (*RestateRuntime) OnApproval

func (rt *RestateRuntime) OnApproval(ctx context.Context, approvalToken string, status types.ApprovalStatus) error

OnApproval is a deprecated Runtime-interface wrapper around approve. Prefer StreamHandle.Approve on the handle returned by Stream or GetStreamHandle.

func (*RestateRuntime) Run

Run starts a durable non-streaming agent loop via Restate ingress and returns a RunHandle. The run executes asynchronously; use RunHandle.Get or RunHandle.Done to wait for completion. When an approvalHandler is configured, a background goroutine drives approvals for this run.

func (*RestateRuntime) Stream

Stream starts a durable streaming agent loop via Restate ingress and returns a StreamHandle. Call StreamHandle.Events to subscribe to the event stream.

type RuntimeFactory

type RuntimeFactory struct {
	Config *RestateConfig
}

RuntimeFactory implements agentruntime.RuntimeFactory for the Restate backend. It is the single place that turns agent-level wiring (agentruntime.RuntimeParams) into RestateRuntime options. Callers construct it from the opt-in github.com/agenticenv/agent-sdk-go/pkg/agent/runtime/restate package so local-only apps do not link the Restate SDK (and wazero).

Config must be set; see RuntimeFactory.Validate.

func (*RuntimeFactory) Build

func (f *RuntimeFactory) Build(params *agentruntime.RuntimeParams, remoteWorker bool) (sdkruntime.Runtime, error)

Build constructs a RestateRuntime from params. Restate embeds its SDK endpoint in-process, so remoteWorker (used by [NewAgentWorker] for Temporal) is rejected.

func (*RuntimeFactory) Name

func (f *RuntimeFactory) Name() string

Name identifies this factory as the "restate" runtime.

func (*RuntimeFactory) Validate

func (f *RuntimeFactory) Validate() error

Validate checks that Config is set. Ingress/endpoint field validation runs in NewRestateRuntime via [validateConfig].

type SubAgentRoute

type SubAgentRoute struct {
	Name        string                   `json:"name"`
	ToolName    string                   `json:"tool_name"`
	ServiceName string                   `json:"service_name,omitempty"`
	ChildRoutes map[string]SubAgentRoute `json:"child_routes,omitempty"`
}

SubAgentRoute is the JSON-safe delegation metadata passed in AgentLoopRequest. ServiceName is the child's Restate AgentLoop service (AgentLoop_<name>), analogous to Temporal's child task queue — each sub-agent is an independent Restate agent.

type ToolsResolver

type ToolsResolver func(ctx context.Context) ([]interfaces.Tool, error)

ToolsResolver resolves per-run tools at handler entry (same process as the Restate endpoint). Used as the multi-pod fallback when tools are not stashed in-process.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL