Documentation
¶
Index ¶
- Variables
- type AgentEventLog
- func (AgentEventLog) Clear(ctx restatesdk.ObjectContext) error
- func (AgentEventLog) Publish(ctx restatesdk.ObjectContext, message json.RawMessage) error
- func (s AgentEventLog) Pull(ctx restatesdk.ObjectSharedContext, req PullRequest) (PullResponse, error)
- func (s AgentEventLog) ServiceName() string
- func (AgentEventLog) Subscribe(ctx restatesdk.ObjectContext, sub pubsubSubscription) error
- type AgentLoop
- func (AgentLoop) Cancel(ctx restatesdk.Context, req CancelRequest) error
- func (s AgentLoop) Run(ctx restatesdk.Context, req AgentLoopRequest) (*AgentLoopResponse, error)
- func (s AgentLoop) ServiceName() string
- func (s AgentLoop) Stream(ctx restatesdk.Context, req AgentLoopRequest) (*AgentLoopResponse, error)
- type AgentLoopInput
- type AgentLoopRequest
- type AgentLoopResponse
- type AgentLoopResult
- type CancelRequest
- type EndpointConfig
- type EventLogConfig
- type IngressConfig
- type Option
- func WithAgentConfig(cfg runtime.AgentConfig) Option
- func WithAgentSpec(spec runtime.AgentSpec) Option
- func WithApprovalHandler(fn types.ApprovalHandler) Option
- func WithLogger(l logger.Logger) Option
- func WithMetrics(metrics interfaces.Metrics) Option
- func WithRestateConfig(config *RestateConfig) Option
- func WithToolExecutionMode(mode types.AgentToolExecutionMode) Option
- func WithToolsResolver(fn ToolsResolver) Option
- func WithTracer(tracer interfaces.Tracer) Option
- type PullRequest
- type PullResponse
- type RestateConfig
- type RestateRuntime
- func (rt *RestateRuntime) Close()
- func (rt *RestateRuntime) GetRunHandle(ctx context.Context, runID string) (sdkruntime.RunHandle, error)
- func (rt *RestateRuntime) GetStreamHandle(ctx context.Context, runID string) (sdkruntime.StreamHandle, error)
- func (rt *RestateRuntime) OnApproval(ctx context.Context, approvalToken string, status types.ApprovalStatus) error
- func (rt *RestateRuntime) Run(ctx context.Context, req *sdkruntime.RunRequest) (sdkruntime.RunHandle, error)
- func (rt *RestateRuntime) Stream(ctx context.Context, req *sdkruntime.RunRequest) (sdkruntime.StreamHandle, error)
- type RuntimeFactory
- type SubAgentRoute
- type ToolsResolver
Constants ¶
This section is empty.
Variables ¶
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.
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 ¶
func (AgentEventLog) Clear(ctx restatesdk.ObjectContext) error
Clear removes all messages from this run's event log (full wipe after EventLog.TTL).
func (AgentEventLog) Publish ¶
func (AgentEventLog) Publish(ctx restatesdk.ObjectContext, message json.RawMessage) error
Publish appends a message and notifies waiting subscribers.
func (AgentEventLog) Pull ¶
func (s AgentEventLog) Pull(ctx restatesdk.ObjectSharedContext, req PullRequest) (PullResponse, error)
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 ¶
func (s AgentLoop) Run(ctx restatesdk.Context, req AgentLoopRequest) (*AgentLoopResponse, error)
Run is the durable non-streaming agent loop entry point.
func (AgentLoop) ServiceName ¶
ServiceName returns the Restate service name (AgentLoop_<agentName>).
func (AgentLoop) Stream ¶
func (s AgentLoop) Stream(ctx restatesdk.Context, req AgentLoopRequest) (*AgentLoopResponse, error)
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 ¶
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 ¶
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 ¶
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 ¶
func (rt *RestateRuntime) Run(ctx context.Context, req *sdkruntime.RunRequest) (sdkruntime.RunHandle, error)
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 ¶
func (rt *RestateRuntime) Stream(ctx context.Context, req *sdkruntime.RunRequest) (sdkruntime.StreamHandle, error)
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.