Documentation
¶
Overview ¶
Package server provides the HTTP and gRPC server implementation for Hector.
The server exposes REST and gRPC APIs for agent management and execution. Use the --studio flag to enable Studio Mode API endpoints for remote UI connections.
To build the server:
go build ./cmd/hector
Or use the Makefile targets:
make build # Development build make build-release # Production build make install # Install to GOPATH/bin
Package server provides A2A protocol server implementation for Hector v2.
The server package implements the a2asrv.AgentExecutor interface to expose Hector agents via the A2A protocol (JSON-RPC, gRPC, HTTP).
Usage ¶
executor := server.NewExecutor(server.ExecutorConfig{
RunnerConfig: runner.Config{
AppName: "my-app",
Agent: myAgent,
SessionService: session.InMemoryService(),
},
})
handler := a2asrv.NewHandler(executor)
http.Handle("/a2a", a2asrv.NewJSONRPCHandler(handler))
Index ¶
- type ApprovalResponse
- type Executor
- type ExecutorConfig
- type HTTPServer
- func (s *HTTPServer) Address() string
- func (s *HTTPServer) GRPCAddress() string
- func (s *HTTPServer) SetReloadFunc(fn func() error)
- func (s *HTTPServer) SetStudioMode(configPath string)
- func (s *HTTPServer) Shutdown(ctx context.Context) error
- func (s *HTTPServer) Start(ctx context.Context) error
- func (s *HTTPServer) UpdateExecutors(cfg *config.Config, executors map[string]*Executor)
- type HTTPServerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ApprovalResponse ¶
type ApprovalResponse struct {
// Decision is "approve" or "deny"
Decision string
// ToolCallID is the ID of the tool call being approved/denied
ToolCallID string
// TaskID is the task this approval is for
TaskID string
}
ApprovalResponse represents an approval decision from the user.
func ExtractApprovalResponse ¶
func ExtractApprovalResponse(msg *a2a.Message) *ApprovalResponse
ExtractApprovalResponse checks if a message contains an approval response. Returns nil if the message is not an approval response.
Approval responses can be: 1. A DataPart with type: "tool_approval" 2. A TextPart with "approve" or "deny" (for simple approvals)
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor implements a2asrv.AgentExecutor to bridge Hector agents to A2A.
Event translation follows these rules:
- New task: emit TaskStatusUpdateEvent with TaskStateSubmitted
- Before runner invocation: emit TaskStatusUpdateEvent with TaskStateWorking
- For each agent.Event: emit TaskArtifactUpdateEvent with translated parts
- After last event: emit TaskArtifactUpdateEvent with LastChunk=true
- On LLM error: emit TaskStatusUpdateEvent with TaskStateFailed
- On long-running tool: emit TaskStatusUpdateEvent with TaskStateInputRequired
- On success: emit TaskStatusUpdateEvent with TaskStateCompleted
func NewExecutor ¶
func NewExecutor(config ExecutorConfig) *Executor
NewExecutor creates a new A2A executor.
func (*Executor) Cancel ¶
func (e *Executor) Cancel(ctx context.Context, reqCtx *a2asrv.RequestContext, queue eventqueue.Queue) error
Cancel implements a2asrv.AgentExecutor.
func (*Executor) Execute ¶
func (e *Executor) Execute(ctx context.Context, reqCtx *a2asrv.RequestContext, queue eventqueue.Queue) error
Execute implements a2asrv.AgentExecutor.
type ExecutorConfig ¶
type ExecutorConfig struct {
// RunnerConfig is used to create a runner for each execution.
RunnerConfig runner.Config
// RunConfig contains runtime configuration for agent execution.
RunConfig agent.RunConfig
// TaskService provides task management for cascade cancellation.
// If nil, cascade cancellation will not work.
TaskService task.Service
}
ExecutorConfig contains the configuration for the A2A executor.
type HTTPServer ¶
type HTTPServer struct {
// contains filtered or unexported fields
}
HTTPServer is the Hector HTTP server. Uses a2a-go native handlers for A2A protocol compliance.
func NewHTTPServer ¶
func NewHTTPServer(appCfg *config.Config, executors map[string]*Executor, opts ...HTTPServerOption) *HTTPServer
NewHTTPServer creates a new HTTP server from config. executors is a map of agent name to its executor (one per agent).
func (*HTTPServer) Address ¶
func (s *HTTPServer) Address() string
Address returns the HTTP server address.
func (*HTTPServer) GRPCAddress ¶
func (s *HTTPServer) GRPCAddress() string
GRPCAddress returns the gRPC server address (if enabled).
func (*HTTPServer) SetReloadFunc ¶ added in v1.13.1
func (s *HTTPServer) SetReloadFunc(fn func() error)
SetReloadFunc sets the function to call for synchronous config reload. This should trigger the same reload logic as the file watcher, returning nil on success or an error if reload fails.
func (*HTTPServer) SetStudioMode ¶
func (s *HTTPServer) SetStudioMode(configPath string)
SetStudioMode enables studio mode with config file path.
func (*HTTPServer) Shutdown ¶
func (s *HTTPServer) Shutdown(ctx context.Context) error
Shutdown gracefully shuts down the server(s).
func (*HTTPServer) Start ¶
func (s *HTTPServer) Start(ctx context.Context) error
Start starts the HTTP server.
func (*HTTPServer) UpdateExecutors ¶
func (s *HTTPServer) UpdateExecutors(cfg *config.Config, executors map[string]*Executor)
UpdateExecutors atomically updates configuration and agent executors (for hot-reload).
type HTTPServerOption ¶
type HTTPServerOption func(*HTTPServer)
HTTPServerOption configures the HTTP server.
func WithAuthValidator ¶
func WithAuthValidator(validator auth.TokenValidator) HTTPServerOption
WithAuthValidator sets the JWT validator for authentication. When set, HTTP requests will be validated and claims passed to agents.
func WithObservability ¶
func WithObservability(obs *observability.Manager) HTTPServerOption
WithObservability sets the observability manager for tracing and metrics.
func WithTaskService ¶
func WithTaskService(ts task.Service) HTTPServerOption
WithTaskService sets the task service for task-scoped cancellation.
func WithTaskStore ¶
func WithTaskStore(store a2asrv.TaskStore) HTTPServerOption
WithTaskStore sets the task store for persistent task storage. If not set, a2a-go uses its internal in-memory store.
Source Files