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) 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) 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