Documentation
¶
Overview ¶
Package poolagent provides ordered failover across multiple agent backends.
A PoolExecutor lazily creates the first healthy member from a configured list and reuses it until a run fails. NewPoolAgent wraps that behavior in an ADK agent so callers can expose failover pools through the same interface as any other runtime agent.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentCreator ¶
type AgentCreator interface {
CreateAgent(ctx context.Context, name string, req AgentRequest) (agent.Agent, error)
}
AgentCreator constructs one pool member agent on demand.
type AgentRequest ¶
type AgentRequest struct {
// Name is the per-member runtime agent name.
Name string
// Description is the per-member runtime agent description.
Description string
// SystemInstructions are forwarded to the selected member agent.
SystemInstructions string
// WorkingDirectory is the session working directory for the selected member.
WorkingDirectory string
}
AgentRequest contains the normalized request passed to each pool member.
type AllPoolMembersFailedError ¶
type AllPoolMembersFailedError struct {
// PoolName is the logical pool identifier.
PoolName string
// MemberNames is a comma-separated list of configured member IDs.
MemberNames string
// Errors contains the individual member failures in evaluation order.
Errors []AttemptError
// Err is the underlying summary error for errors.Is and errors.Unwrap.
Err error
}
AllPoolMembersFailedError reports that every member failed to initialize.
func (*AllPoolMembersFailedError) Error ¶
func (e *AllPoolMembersFailedError) Error() string
Error formats the full failover failure report.
func (*AllPoolMembersFailedError) Unwrap ¶
func (e *AllPoolMembersFailedError) Unwrap() error
Unwrap returns the summary error for the failover failure.
type AttemptError ¶
type AttemptError struct {
// Member is the member provider ID.
Member string
// Index is the zero-based member position in the configured failover order.
Index int
// Err is the member-specific failure text.
Err string
}
AttemptError describes one failed member creation attempt.
type MemberConfig ¶
type MemberConfig struct {
// Name is the provider ID used when creating the member agent.
Name string
// Cfg is the validated provider configuration for the member.
Cfg agentconfig.Config
}
MemberConfig identifies one provider that can satisfy a pool request.
type PoolAgent ¶
PoolAgent exposes pool failover through the ADK agent interface.
func NewPoolAgent ¶
func NewPoolAgent(ctx context.Context, poolName string, members []MemberConfig, req AgentRequest, agentCreator AgentCreator) (*PoolAgent, error)
NewPoolAgent creates an ADK agent that runs through a failover pool.
type PoolExecutor ¶
type PoolExecutor struct {
// contains filtered or unexported fields
}
PoolExecutor lazily selects and caches the first healthy pool member.
func NewPoolExecutor ¶
func NewPoolExecutor(poolName string, members []MemberConfig, agentCreator AgentCreator, req AgentRequest) *PoolExecutor
NewPoolExecutor creates a pool executor for ordered failover across members.
Example ¶
package main
import (
"context"
"fmt"
"iter"
"github.com/normahq/norma/pkg/runtime/agentconfig"
"google.golang.org/adk/agent"
"google.golang.org/adk/session"
)
type exampleCreator struct{}
func (exampleCreator) CreateAgent(ctx context.Context, name string, _ AgentRequest) (agent.Agent, error) {
if name == "primary" {
return nil, fmt.Errorf("backend unavailable")
}
return agent.New(agent.Config{
Name: name,
Description: "example",
Run: func(agent.InvocationContext) iter.Seq2[*session.Event, error] {
return func(func(*session.Event, error) bool) {}
},
})
}
func main() {
executor := NewPoolExecutor("writers", []MemberConfig{
{Name: "primary", Cfg: agentconfig.Config{Type: agentconfig.AgentTypeOpenAI}},
{Name: "secondary", Cfg: agentconfig.Config{Type: agentconfig.AgentTypeOpenAI}},
}, exampleCreator{}, AgentRequest{})
selected, err := executor.Agent(context.Background())
if err != nil {
fmt.Println(err)
return
}
fmt.Println(selected.Name())
}
Output: secondary
func (*PoolExecutor) Agent ¶
Agent returns the cached healthy agent or creates the first successful pool member in configured order.
func (*PoolExecutor) Close ¶
func (p *PoolExecutor) Close() error
Close closes the cached member agent when it exposes Close.
Source Files