agent

package
v1.4.0 Latest Latest
Warning

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

 Go to latest Published: Oct 20, 2026 License: Apache-2.0 Imports: 14 Imported by: 0

Documentation

Overview

Package agent defines the provider-neutral Agent Runtime Interface used by native SDKs and framework adapters. It intentionally depends only on the Go standard library so third-party Agents do not import Kernel implementation packages.

Index

Constants

View Source 
const (
	ProtocolVersion       = "fenced.runtime.interface/v1"
	LegacyProtocolVersion = "fenced.runtime.interface/v1alpha1"

	StatusAccepted  = "ACCEPTED"
	StatusRunning   = "RUNNING"
	StatusSucceeded = "SUCCEEDED"
	StatusFailed    = "FAILED"
	StatusCancelled = "CANCELLED"
)

Variables

View Source 
var (
	ErrExecutionNotFound = errors.New("agent execution not found")
	ErrExecutionConflict = errors.New("agent execution id conflicts with another request")
	ErrCapacityExhausted = errors.New("agent runtime capacity exhausted")
)
View Source 
var ErrStreamingUnsupported = errors.New("runtime interface does not support event streaming")

ErrStreamingUnsupported reports a runtime that implements only the frozen v1 polling endpoints. Callers fall back to Events/Result polling.

Functions

func ValidateBaseURL 

func ValidateBaseURL(baseURL string) error

ValidateBaseURL checks one Runtime Interface endpoint against the wire contract every client and binding loader shares: an absolute http(s) URL with a host and no userinfo, query, fragment, or path components. It is the single validator so configuration fails fast at load time instead of at the first request.

Types

type CapabilityGrant 

type CapabilityGrant struct {
	Tools               []string `json:"tools"`
	Models              []string `json:"models"`
	Memory              []string `json:"memory"`
	MemorySensitivities []string `json:"memorySensitivities,omitempty"`
	Secrets             []string `json:"secrets"`
	SpawnTasks          bool     `json:"spawnTasks,omitempty"`
	ChildAgents         []string `json:"childAgents,omitempty"`
	// Peers lists the AgentVersion references this agent may send IPC messages
	// to. An absent or empty list denies every peer.
	Peers []string `json:"peers,omitempty"`
}

CapabilityGrant contains symbolic grants already admitted by the Kernel. Adapters use these identifiers to select a Gateway; they are never network endpoints, credentials, or raw secret values.

type Checkpoint 

type Checkpoint struct {
	SchemaVersion string          `json:"schemaVersion"`
	State         json.RawMessage `json:"state"`
	CreatedAt     time.Time       `json:"createdAt"`
}

type CheckpointResponse 

type CheckpointResponse struct {
	ExecutionID string     `json:"executionId"`
	Checkpoint  Checkpoint `json:"checkpoint"`
}

type Client 

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

func NewClient 

func NewClient(baseURL string, client *http.Client) (*Client, error)

func NewLegacyClient 

func NewLegacyClient(baseURL string, client *http.Client) (*Client, error)

NewLegacyClient creates an explicit N-1 client for the deprecated alpha endpoint. New integrations must use NewClient, which negotiates stable v1.

func (*Client) Checkpoint 

func (c *Client) Checkpoint(ctx context.Context, executionID string) (CheckpointResponse, error)

func (*Client) Events 

func (c *Client) Events(ctx context.Context, executionID string, after int64) (EventList, error)

func (*Client) Health 

func (c *Client) Health(ctx context.Context) (HealthResponse, error)

func (*Client) Restore 

func (c *Client) Restore(ctx context.Context, request RestoreRequest) (RestoreResponse, error)

func (*Client) Result 

func (c *Client) Result(ctx context.Context, executionID string) (Result, bool, error)

func (*Client) Start 

func (c *Client) Start(ctx context.Context, request StartRequest) (StartResponse, error)

func (*Client) Stop 

func (c *Client) Stop(ctx context.Context, executionID string) (StopResponse, error)

func (*Client) StreamEvents 

func (c *Client) StreamEvents(ctx context.Context, executionID string, after int64, onEvent func(Event) error) (Result, error)

StreamEvents consumes one execution's event stream over a single long-lived connection. Events after the cursor are delivered to onEvent; the terminal frame carries the final Result so no separate Result poll is needed. The connection lifetime is bound to ctx.

func (*Client) WaitResult 

func (c *Client) WaitResult(ctx context.Context, executionID string, interval time.Duration) (Result, error)

type Emitter 

type Emitter func(eventType string, payload json.RawMessage) error

Emitter appends a bounded execution event. Payload must be valid JSON.

type Event 

type Event struct {
	Sequence   int64           `json:"sequence"`
	Type       string          `json:"type"`
	Payload    json.RawMessage `json:"payload"`
	OccurredAt time.Time       `json:"occurredAt"`
}

type EventList 

type EventList struct {
	ExecutionID string  `json:"executionId"`
	Events      []Event `json:"events"`
	NextAfter   int64   `json:"nextAfter"`
	Truncated   bool    `json:"truncated,omitempty"`
}

type HTTPError 

type HTTPError struct {
	Status int
	Body   []byte
}

func (*HTTPError) Error 

func (e *HTTPError) Error() string

type HealthResponse 

type HealthResponse struct {
	Status           string   `json:"status"`
	ProtocolVersions []string `json:"protocolVersions"`
	Adapter          string   `json:"adapter"`
	MaxConcurrent    int      `json:"maxConcurrent"`
	ActiveExecutions int      `json:"activeExecutions"`
}

type Host 

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

Host exposes one Runtime through the stable HTTP+JSON Runtime Interface. It supplies idempotent start, bounded event history, cancellation, logical checkpoint/restore, and terminal result semantics for every adapter.

func NewHost 

func NewHost(runtime Runtime, options HostOptions) (*Host, error)

func (*Host) ServeHTTP 

func (h *Host) ServeHTTP(writer http.ResponseWriter, request *http.Request)

type HostOptions 

type HostOptions struct {
	Adapter          string
	MaxConcurrent    int
	EventLimit       int
	ExecutionLimit   int
	ExecutionTimeout time.Duration
	Now              func() time.Time
	TerminationGrace time.Duration
	// ForceTerminate must kill the isolated execution boundary (subprocess,
	// container or microVM) after cooperative cancellation fails. Production
	// adapters should configure it; embedded dev adapters may leave it nil.
	ForceTerminate func(executionID string) error
}

type RestoreRequest 

type RestoreRequest struct {
	ExecutionID string     `json:"executionId"`
	Checkpoint  Checkpoint `json:"checkpoint"`
}

type RestoreResponse 

type RestoreResponse struct {
	ExecutionID string `json:"executionId"`
	Restored    bool   `json:"restored"`
}

type Result 

type Result struct {
	ExecutionID string          `json:"executionId"`
	Status      string          `json:"status"`
	Output      json.RawMessage `json:"output,omitempty"`
	ErrorCode   string          `json:"errorCode,omitempty"`
	Error       string          `json:"error,omitempty"`
	CompletedAt *time.Time      `json:"completedAt,omitempty"`
}

type Runtime 

type Runtime interface {
	Run(ctx context.Context, request StartRequest, emit Emitter) (json.RawMessage, error)
	Checkpoint(ctx context.Context, executionID string) (Checkpoint, error)
	Restore(ctx context.Context, request RestoreRequest) error
}

Runtime is implemented by Native SDKs and framework adapters. Run owns one execution until a terminal output or error. Stop is represented by context cancellation. Checkpoint and Restore must use versioned logical state.

type StartRequest 

type StartRequest struct {
	ExecutionID     string          `json:"executionId"`
	AgentVersionRef string          `json:"agentVersionRef"`
	Goal            string          `json:"goal"`
	Input           json.RawMessage `json:"input"`
	Capabilities    CapabilityGrant `json:"capabilities"`
}

type StartResponse 

type StartResponse struct {
	ExecutionID string `json:"executionId"`
	Status      string `json:"status"`
	Replayed    bool   `json:"replayed"`
}

type StopResponse 

type StopResponse struct {
	ExecutionID string `json:"executionId"`
	Status      string `json:"status"`
}

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.