server

package
v0.3.1 Latest Latest
Warning

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

Go to latest
Published: Aug 27, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Index

Constants

View Source
const DefaultMaxRequestBytes int64 = 4 << 20 // 4 MiB

DefaultMaxRequestBytes bounds request bodies so a single client cannot exhaust server memory with an oversized payload.

Variables

This section is empty.

Functions

func BuildAgentPipeline

func BuildAgentPipeline(def AgentPipelineDefinition, agents *AgentManager) (*core.Graph, error)

BuildAgentPipeline compiles a data-only Studio definition into a core graph. It intentionally supports a sequential topology only. Conditional routing and arbitrary custom nodes require application code, where their behavior can be reviewed and tested, instead of being faked by the visual editor.

Types

type APIKeyCredential

type APIKeyCredential struct {
	Name string     `json:"name" yaml:"name"`
	Key  string     `json:"key" yaml:"key"` // pragma: allowlist secret
	Role APIKeyRole `json:"role" yaml:"role"`
}

APIKeyCredential is deliberately named so audit records never need to log the secret value in order to identify who changed a deployment. // pragma: allowlist secret

type APIKeyRole

type APIKeyRole string

APIKeyRole is an ordered permission level for the public control plane. Viewer can inspect; executor can invoke and interrupt runs; author can also create or modify agents and pipelines; admin is reserved for legacy keys and future administrative APIs. // pragma: allowlist secret

const (
	RoleViewer   APIKeyRole = "viewer"   // pragma: allowlist secret
	RoleExecutor APIKeyRole = "executor" // pragma: allowlist secret
	RoleAuthor   APIKeyRole = "author"   // pragma: allowlist secret
	RoleAdmin    APIKeyRole = "admin"    // pragma: allowlist secret
)

type AgentManager

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

AgentManager manages multiple agents

func NewAgentManager

func NewAgentManager(llmManager *llm.ProviderManager, toolRegistry *tools.ToolRegistry) *AgentManager

NewAgentManager creates a new agent manager

func (*AgentManager) CreateAgent

func (am *AgentManager) CreateAgent(config *agent.AgentConfig) (agent.Agent, error)

CreateAgent creates a new agent

func (*AgentManager) DeleteAgent

func (am *AgentManager) DeleteAgent(id string)

DeleteAgent removes an agent

func (*AgentManager) GetAgent

func (am *AgentManager) GetAgent(id string) (agent.Agent, bool)

GetAgent retrieves an agent by ID

func (*AgentManager) ListAgents

func (am *AgentManager) ListAgents() []string

ListAgents returns all agent IDs

func (*AgentManager) ReplaceAgents

func (am *AgentManager) ReplaceAgents(configs []*agent.AgentConfig) error

ReplaceAgents atomically replaces the agents managed by am. The replacement is built and validated before the live map is swapped, so a malformed reload leaves the currently serving agents available.

type AgentPipelineDefinition

type AgentPipelineDefinition struct {
	ID           string              `json:"id"`
	Name         string              `json:"name"`
	Nodes        []AgentPipelineNode `json:"nodes"`
	InputSchema  PipelineSchema      `json:"input_schema,omitempty"`
	OutputSchema PipelineSchema      `json:"output_schema,omitempty"`
}

AgentPipelineDefinition is the Studio authoring contract for an executable sequential multi-agent pipeline. The output of each step becomes the input of the next one and the full output remains available in graph state.

type AgentPipelineNode

type AgentPipelineNode struct {
	ID      string `json:"id"`
	AgentID string `json:"agent_id"`
	Name    string `json:"name,omitempty"`
}

AgentPipelineNode is a safe, declarative pipeline step. It refers to an already-registered agent rather than accepting a function or source code, making it suitable for authoring from Studio without turning the API into a remote-code-execution surface.

type AutoServer

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

AutoServer automatically generates REST endpoints for agents

func NewAutoServer

func NewAutoServer(config *AutoServerConfig) *AutoServer

NewAutoServer creates a new auto-server instance backed by the process-wide agent registry.

Note that the registry is shared: two AutoServer instances in one process see each other's agents, so an agent registered for one is served by the other. That is rarely what you want when the two servers have different exposure or credentials. Use NewAutoServerWithRegistry to give a server its own registry.

func NewAutoServerWithRegistry

func NewAutoServerWithRegistry(config *AutoServerConfig, registry *agent.AgentRegistry) *AutoServer

NewAutoServerWithRegistry creates an auto-server with its own agent registry, isolated from the process-wide one and from any other server.

func (*AutoServer) Address

func (as *AutoServer) Address() string

Address returns the address the server is listening on, or an empty string before Start. With port 0 configured this reports the port actually chosen.

func (*AutoServer) GenerateEndpoints

func (as *AutoServer) GenerateEndpoints() error

GenerateEndpoints automatically generates REST endpoints for all registered agents

func (*AutoServer) LoadAgentsFromConfig

func (as *AutoServer) LoadAgentsFromConfig(configPath string) error

LoadAgentsFromConfig loads agents from a multi-agent config file

func (*AutoServer) LoadAgentsFromDirectory

func (as *AutoServer) LoadAgentsFromDirectory(directory string) error

LoadAgentsFromDirectory loads agent definitions from a directory LoadAgentsFromDirectory loads every agent configuration file in a directory.

This previously scanned nothing: it listed whatever was already registered and logged that count as "Loaded agent definitions", so a caller pointing at a directory of configs got silence and no agents.

func (*AutoServer) RegisterAgent

func (as *AutoServer) RegisterAgent(id string, definition agent.AgentDefinition) error

RegisterAgent registers a single agent programmatically

func (*AutoServer) Registry

func (as *AutoServer) Registry() *agent.AgentRegistry

Registry returns the agent registry this server serves from.

func (*AutoServer) Start

func (as *AutoServer) Start(ctx context.Context) error

Start starts the auto-server

type AutoServerConfig

type AutoServerConfig struct {
	Host             string                 `yaml:"host" json:"host"`
	Port             int                    `yaml:"port" json:"port"`
	BasePath         string                 `yaml:"base_path" json:"base_path"`
	EnableWebUI      bool                   `yaml:"enable_web_ui" json:"enable_web_ui"`
	EnablePlayground bool                   `yaml:"enable_playground" json:"enable_playground"`
	EnableSchemaAPI  bool                   `yaml:"enable_schema_api" json:"enable_schema_api"`
	EnableMetricsAPI bool                   `yaml:"enable_metrics_api" json:"enable_metrics_api"`
	EnableCORS       bool                   `yaml:"enable_cors" json:"enable_cors"`
	SchemaValidation bool                   `yaml:"schema_validation" json:"schema_validation"`
	OllamaEndpoint   string                 `yaml:"ollama_endpoint" json:"ollama_endpoint"`
	LLMProviders     map[string]interface{} `yaml:"llm_providers" json:"llm_providers"`
	ServerTimeout    time.Duration          `yaml:"server_timeout" json:"server_timeout"`
	MaxRequestSize   int64                  `yaml:"max_request_size" json:"max_request_size"`
	Middleware       []string               `yaml:"middleware" json:"middleware"`
	// LogLevel controls the auto-server logger (for example, debug, info or
	// warn). An empty value defaults to info for backwards compatibility.
	LogLevel string `yaml:"log_level" json:"log_level"`

	// Security controls authentication, allowed origins and request limits,
	// using the same configuration type as Server. Nil falls back to
	// DefaultSecurityConfig.
	Security *SecurityConfig `yaml:"security" json:"security"`
}

AutoServerConfig configures the auto-generated server

func DefaultAutoServerConfig

func DefaultAutoServerConfig() *AutoServerConfig

DefaultAutoServerConfig returns default configuration

type ExecutionStepView

type ExecutionStepView struct {
	NodeID    string                     `json:"node_id"`
	Step      int                        `json:"step"`
	Success   bool                       `json:"success"`
	Error     string                     `json:"error,omitempty"`
	DurationM float64                    `json:"duration_ms"`
	Attempts  int                        `json:"attempts"`
	State     map[string]core.StateValue `json:"state,omitempty"`
}

ExecutionStepView is a single node execution, as sent to clients.

type GraphEdgeView

type GraphEdgeView struct {
	From        string `json:"from"`
	To          string `json:"to"`
	Conditional bool   `json:"conditional"`
	// RouteKey is set for conditional edges and names the routing key that
	// selects this destination.
	RouteKey string `json:"route_key,omitempty"`
}

GraphEdgeView describes an edge for API clients.

type GraphManager

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

GraphManager holds the graphs a server exposes over the API. Registering a graph makes it listable, inspectable, executable and streamable, which is what GoLangGraph Studio needs to debug a workflow.

func NewGraphManager

func NewGraphManager() *GraphManager

NewGraphManager creates an empty graph manager.

func (*GraphManager) Get

func (gm *GraphManager) Get(id string) (*core.Graph, bool)

Get returns a graph by ID.

func (*GraphManager) List

func (gm *GraphManager) List() []string

List returns registered graph IDs in registration order.

func (*GraphManager) Register

func (gm *GraphManager) Register(id string, g *core.Graph)

Register adds a graph under an ID. Re-registering an ID replaces the graph.

func (*GraphManager) Unregister

func (gm *GraphManager) Unregister(id string)

Unregister removes a graph.

type GraphNodeView

type GraphNodeView struct {
	ID       string                 `json:"id"`
	Name     string                 `json:"name"`
	Type     string                 `json:"type"`
	IsStart  bool                   `json:"is_start"`
	IsEnd    bool                   `json:"is_end"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

GraphNodeView describes a node for API clients.

type GraphSummaryView

type GraphSummaryView struct {
	ID        string   `json:"id"`
	Name      string   `json:"name"`
	StartNode string   `json:"start_node"`
	EndNodes  []string `json:"end_nodes"`
	NodeCount int      `json:"node_count"`
	EdgeCount int      `json:"edge_count"`
	Running   bool     `json:"running"`
}

GraphSummaryView describes a graph without its topology.

type GraphTopologyView

type GraphTopologyView struct {
	Nodes []GraphNodeView `json:"nodes"`
	Edges []GraphEdgeView `json:"edges"`
}

GraphTopologyView is the serialisable topology of a graph. Studio renders this directly, so both nodes and edges are always present (never null).

type PipelineField

type PipelineField struct {
	Type        string `json:"type"`
	Required    bool   `json:"required,omitempty"`
	Description string `json:"description,omitempty"`
}

PipelineField describes one top-level runtime field. Keeping contracts small and declarative makes them inspectable in Studio and prevents a UI-supplied schema from changing graph behavior beyond validation.

type PipelineSchema

type PipelineSchema map[string]PipelineField

PipelineSchema validates named top-level values flowing into or out of a Studio pipeline. Supported types are string, number, boolean, object, array and any. The engine retains arbitrary additional state for composability.

func (PipelineSchema) ValidateDefinition

func (schema PipelineSchema) ValidateDefinition(label string) error

func (PipelineSchema) ValidateValues

func (schema PipelineSchema) ValidateValues(label string, values map[string]core.StateValue) error

type Principal

type Principal struct {
	Name string     `json:"name"`
	Role APIKeyRole `json:"role"`
}

Principal is the authenticated identity carried through a request context and returned by /api/v1/whoami. It never includes a credential.

type SecurityConfig

type SecurityConfig struct {
	// RequireAuth rejects requests without a valid X-API-Key.
	RequireAuth bool `json:"require_auth" yaml:"require_auth"`
	// APIKeys are the accepted values for the X-API-Key header.
	// Deprecated for production use: legacy keys are granted the admin role.
	// Use APIKeyCredentials to issue named, least-privilege keys instead.
	APIKeys []string `json:"api_keys" yaml:"api_keys"`
	// APIKeyCredentials contains named keys and their least-privilege role.
	// Store Key values in a secret manager or mounted secret, never in source.
	APIKeyCredentials []APIKeyCredential `json:"api_key_credentials" yaml:"api_key_credentials"`
	// AllowedOrigins restricts CORS and WebSocket origins. Empty means any
	// origin is accepted, which is only appropriate for local development.
	AllowedOrigins []string `json:"allowed_origins" yaml:"allowed_origins"`
	// MaxRequestBytes caps request bodies. Zero applies DefaultMaxRequestBytes.
	MaxRequestBytes int64 `json:"max_request_bytes" yaml:"max_request_bytes"`
	// PublicPaths bypass authentication (health checks, readiness probes).
	PublicPaths []string `json:"public_paths" yaml:"public_paths"`
}

SecurityConfig controls authentication, cross-origin access and request limits. The zero value is permissive so existing embedded uses keep working; production deployments should set RequireAuth and AllowedOrigins.

func DefaultSecurityConfig

func DefaultSecurityConfig() *SecurityConfig

DefaultSecurityConfig returns a development-friendly configuration: no auth, any origin, but with a request size limit already in place.

type Server

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

Server represents the HTTP server

func NewServer

func NewServer(config *ServerConfig) *Server

NewServer creates a new server

func (*Server) GraphManager

func (s *Server) GraphManager() *GraphManager

GraphManager returns the server's graph manager, used to register graphs that should be listable, inspectable and executable over the API.

func (*Server) SetAgentManager

func (s *Server) SetAgentManager(manager *AgentManager)

SetAgentManager sets the agent manager

func (*Server) SetCheckpointer

func (s *Server) SetCheckpointer(cp persistence.Checkpointer)

SetCheckpointer attaches the checkpointer used to serve thread history.

func (*Server) SetGraphManager

func (s *Server) SetGraphManager(manager *GraphManager)

SetGraphManager replaces the graph manager.

func (*Server) SetLLMManager

func (s *Server) SetLLMManager(manager *llm.ProviderManager)

SetLLMManager sets the LLM provider manager

func (*Server) SetSessionManager

func (s *Server) SetSessionManager(manager *persistence.SessionManager)

SetSessionManager sets the session manager

func (*Server) SetToolRegistry

func (s *Server) SetToolRegistry(registry *tools.ToolRegistry)

SetToolRegistry sets the tool registry

func (*Server) Start

func (s *Server) Start() error

Start starts the server

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop stops the server

type ServerConfig

type ServerConfig struct {
	Host           string        `json:"host"`
	Port           int           `json:"port"`
	ReadTimeout    time.Duration `json:"read_timeout"`
	WriteTimeout   time.Duration `json:"write_timeout"`
	MaxHeaderBytes int           `json:"max_header_bytes"`
	EnableCORS     bool          `json:"enable_cors"`
	StaticDir      string        `json:"static_dir"`
	DevMode        bool          `json:"dev_mode"`
	LogLevel       string        `json:"log_level"`

	// Security controls authentication, allowed origins and request limits.
	// Nil falls back to DefaultSecurityConfig.
	Security *SecurityConfig `json:"security"`
}

ServerConfig represents server configuration

func DefaultServerConfig

func DefaultServerConfig() *ServerConfig

DefaultServerConfig returns default server configuration

Jump to

Keyboard shortcuts

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