Documentation
¶
Index ¶
- Constants
- func BuildAgentPipeline(def AgentPipelineDefinition, agents *AgentManager) (*core.Graph, error)
- type APIKeyCredential
- type APIKeyRole
- type AgentManager
- func (am *AgentManager) CreateAgent(config *agent.AgentConfig) (agent.Agent, error)
- func (am *AgentManager) DeleteAgent(id string)
- func (am *AgentManager) GetAgent(id string) (agent.Agent, bool)
- func (am *AgentManager) ListAgents() []string
- func (am *AgentManager) ReplaceAgents(configs []*agent.AgentConfig) error
- type AgentPipelineDefinition
- type AgentPipelineNode
- type AutoServer
- func (as *AutoServer) Address() string
- func (as *AutoServer) GenerateEndpoints() error
- func (as *AutoServer) LoadAgentsFromConfig(configPath string) error
- func (as *AutoServer) LoadAgentsFromDirectory(directory string) error
- func (as *AutoServer) RegisterAgent(id string, definition agent.AgentDefinition) error
- func (as *AutoServer) Registry() *agent.AgentRegistry
- func (as *AutoServer) Start(ctx context.Context) error
- type AutoServerConfig
- type ExecutionStepView
- type GraphEdgeView
- type GraphManager
- type GraphNodeView
- type GraphSummaryView
- type GraphTopologyView
- type PipelineField
- type PipelineSchema
- type Principal
- type SecurityConfig
- type Server
- func (s *Server) GraphManager() *GraphManager
- func (s *Server) SetAgentManager(manager *AgentManager)
- func (s *Server) SetCheckpointer(cp persistence.Checkpointer)
- func (s *Server) SetGraphManager(manager *GraphManager)
- func (s *Server) SetLLMManager(manager *llm.ProviderManager)
- func (s *Server) SetSessionManager(manager *persistence.SessionManager)
- func (s *Server) SetToolRegistry(registry *tools.ToolRegistry)
- func (s *Server) Start() error
- func (s *Server) Stop(ctx context.Context) error
- type ServerConfig
Constants ¶
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.
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 (*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
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