Documentation
¶
Overview ¶
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 DocumentStoreProvider
- type DynamicRouter
- type Executor
- func (e *Executor) Cancel(ctx context.Context, reqCtx *a2asrv.RequestContext, queue eventqueue.Queue) error
- func (e *Executor) Execute(ctx context.Context, reqCtx *a2asrv.RequestContext, queue eventqueue.Queue) error
- func (e *Executor) ResumeFromCheckpoint(ctx context.Context, state *checkpoint.State) error
- type ExecutorConfig
- type HTTPServer
- func (s *HTTPServer) Address() string
- func (s *HTTPServer) CreateA2AWebhookHandlers() map[string]*trigger.WebhookHandler
- func (s *HTTPServer) GRPCAddress() string
- func (s *HTTPServer) GetAgentA2AInvoker() trigger.AgentInvoker
- func (s *HTTPServer) GetTaskResultProvider() func(ctx context.Context, taskID string) (string, error)
- func (s *HTTPServer) SetDocumentStoreProvider(p DocumentStoreProvider)
- 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, webhookHandlers map[string]*trigger.WebhookHandler) error
- func (s *HTTPServer) UpdateState(cfg *config.Config, executors map[string]*Executor, ...)
- type HTTPServerOption
- func WithAuthValidator(validator auth.TokenValidator) HTTPServerOption
- func WithDocumentStoreProvider(p DocumentStoreProvider) HTTPServerOption
- func WithObservability(obs *observability.Manager) HTTPServerOption
- func WithTaskService(ts task.Service) HTTPServerOption
- func WithTaskStore(store a2asrv.TaskStore) 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 DocumentStoreProvider ¶ added in v1.15.2
type DocumentStoreProvider interface {
DocumentStores() map[string]*rag.DocumentStore
}
DocumentStoreProvider provides access to document stores for status reporting. This interface avoids importing the runtime package directly.
type DynamicRouter ¶ added in v1.15.1
type DynamicRouter struct {
// contains filtered or unexported fields
}
DynamicRouter is a thread-safe HTTP handler that supports atomic route table swaps. This enables hot-reload of routes (e.g., webhooks) without restarting the HTTP server. Implements http.Handler.
func NewDynamicRouter ¶ added in v1.15.1
func NewDynamicRouter(h http.Handler) *DynamicRouter
NewDynamicRouter creates a new DynamicRouter with the given initial handler.
func (*DynamicRouter) ServeHTTP ¶ added in v1.15.1
func (r *DynamicRouter) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP delegates to the current handler atomically.
func (*DynamicRouter) Swap ¶ added in v1.15.1
func (r *DynamicRouter) Swap(h http.Handler)
Swap atomically replaces the current handler with a new one.
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.
func (*Executor) ResumeFromCheckpoint ¶ added in v1.16.1
ResumeFromCheckpoint resumes agent execution from a checkpoint. This is called by the checkpoint recovery manager on startup.
The session already contains the conversation history from before the crash/shutdown. We re-invoke the agent with the original query, and it will continue from where it left off.
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
// Notifier dispatches outbound notifications on task events.
// If nil, notifications are disabled.
Notifier *notification.Notifier
}
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) CreateA2AWebhookHandlers ¶ added in v1.15.1
func (s *HTTPServer) CreateA2AWebhookHandlers() map[string]*trigger.WebhookHandler
CreateA2AWebhookHandlers creates webhook handlers that use A2A protocol for invocation. This enables automatic task registration in TaskStore, making tasks queryable via tasks/get. Call this after NewHTTPServer to get A2A-integrated webhook handlers.
func (*HTTPServer) GRPCAddress ¶
func (s *HTTPServer) GRPCAddress() string
GRPCAddress returns the gRPC server address (if enabled).
func (*HTTPServer) GetAgentA2AInvoker ¶ added in v1.15.1
func (s *HTTPServer) GetAgentA2AInvoker() trigger.AgentInvoker
GetAgentA2AInvoker returns an AgentInvoker that uses A2A handlers for invocation. This enables webhooks to invoke agents through A2A protocol with automatic TaskStore registration.
func (*HTTPServer) GetTaskResultProvider ¶ added in v1.15.1
func (s *HTTPServer) GetTaskResultProvider() func(ctx context.Context, taskID string) (string, error)
GetTaskResultProvider returns a function that fetches task result from TaskStore.
func (*HTTPServer) SetDocumentStoreProvider ¶ added in v1.15.2
func (s *HTTPServer) SetDocumentStoreProvider(p DocumentStoreProvider)
SetDocumentStoreProvider updates the provider for RAG indexing status (for hot-reload).
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, webhookHandlers map[string]*trigger.WebhookHandler) error
Start starts the HTTP server. webhookHandlers are passed for initial route registration.
func (*HTTPServer) UpdateState ¶ added in v1.14.0
func (s *HTTPServer) UpdateState(cfg *config.Config, executors map[string]*Executor, webhookHandlers map[string]*trigger.WebhookHandler, taskStore a2asrv.TaskStore, taskService task.Service, validator auth.TokenValidator)
UpdateState atomically updates configuration, agent executors, webhook handlers, and task store (for hot-reload). It rebuilds all HTTP handlers and atomically swaps the route table via DynamicRouter. If webhookHandlers is nil, A2A-integrated webhook handlers are created automatically.
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 WithDocumentStoreProvider ¶ added in v1.15.2
func WithDocumentStoreProvider(p DocumentStoreProvider) HTTPServerOption
WithDocumentStoreProvider sets the provider for document store status.
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