Skip to content

armgit / ax

Public Imported from GitHub
0

Agent Executor (AX) is Google's open agentic orchestration runtime

Go

Simplify the loop - Remove EvaluateFunc - Remove the goal from Task - Use gemini 2.5 flash - Avoid agent metadata in tool selection

Jaana Dogane640b5e39eea
diff --git a/internal/controller/controller.go b/internal/controller/controller.go
index c1103e5..ac947cb 100644
--- a/internal/controller/controller.go
+++ b/internal/controller/controller.go
@@ -42,7 +42,6 @@ type Controller struct {
type Config struct {
EventLogFactory eventlog.EventLogFactory
PlanFunc PlanFunc
- EvaluateFunc EvaluateFunc
// TODO(jbd): Add CompactionFunc.
@@ -71,7 +70,6 @@ func New(ctx context.Context, config Config) (*Controller, error) {
SessionManager: sessionManager,
MaxSteps: config.MaxSteps,
PlanFunc: config.PlanFunc,
- EvaluateFunc: config.EvaluateFunc,
})
if err != nil {
return nil, fmt.Errorf("failed to create loop executor: %w", err)
@@ -117,8 +115,23 @@ func (d *Controller) TriggerSession(ctx context.Context, sessionID string, input
return fmt.Errorf("failed to create session: %w", err)
}
}
- if err := d.loopExecutor.Execute(ctx, sess, inputs); err != nil {
- return fmt.Errorf("execution failed: %w", err)
+
+ if sess.State() == proto.State_STATE_FAILED {
+ return fmt.Errorf("session has failed and cannot continue")
+ }
+
+ // Write input content to session
+ for _, content := range inputs {
+ if _, err := sess.WriteContentIn(ctx, content); err != nil {
+ return fmt.Errorf("failed to write input content: %w", err)
+ }
+ }
+
+ if err := d.loopExecutor.Execute(ctx, sess, handler); err != nil {
+ if err := sess.SetState(ctx, proto.State_STATE_FAILED); err != nil {
+ return fmt.Errorf("failed to set session state: %w", err)
+ }
+ return fmt.Errorf("loop execution failed: %w", err)
}
return nil
}
diff --git a/internal/controller/gemini.go b/internal/controller/gemini.go
index 9f0ec48..6bdf8c8 100644
--- a/internal/controller/gemini.go
+++ b/internal/controller/gemini.go
@@ -16,25 +16,23 @@ package controller
import (
"context"
- "encoding/json"
"fmt"
"os"
"time"
+ "github.com/google/gar/proto"
"google.golang.org/genai"
)
-const noActionAgentID = "no_action_agent"
+const noActionAgentID = "no-action-agent"
// GeminiPlannerConfig configures the Gemini-based planner.
type GeminiPlannerConfig struct {
- APIKey string // Google AI API key (for programmatic use only; if empty, uses GEMINI_API_KEY env var - recommended)
- Model string // Model name (default: "gemini-flash-latest", can override with GAR_GEMINI_MODEL env var)
- Temperature float32 // Temperature for generation (default: 0.7)
- MaxTokens int32 // Max output tokens (default: 8192)
- Timeout time.Duration // Request timeout (default: 60s)
- SystemPrompt string // Custom system prompt (optional)
- ContextWindow int // Number of recent messages to include (default: 30)
+ APIKey string // Google AI API key (for programmatic use only; if empty, uses GEMINI_API_KEY env var - recommended)
+ Model string // Model name (default: gemini-2.5-flash)
+ MaxTokens int32 // Max output tokens (default: 8192)
+ Timeout time.Duration // Request timeout (default: 60s)
+ SystemPrompt string // Custom system prompt (optional)
}
// NewGeminiPlanFunc creates a planning function that uses Gemini for intelligent agent selection.
@@ -48,7 +46,7 @@ func NewGeminiPlanFunc(ctx context.Context, registry *Registry, config GeminiPla
if config.Model == "" {
config.Model = os.Getenv("GAR_GEMINI_MODEL")
if config.Model == "" {
- config.Model = "gemini-flash-latest"
+ config.Model = "gemini-2.5-flash"
}
}
if config.APIKey == "" {
@@ -64,20 +62,17 @@ func NewGeminiPlanFunc(ctx context.Context, registry *Registry, config GeminiPla
Available agents have been provided to you as function tools. Each agent has:
- A unique ID
-- A name describing its purpose
- A description of its capabilities
-- Metadata with additional information
Your job is to:
1. Analyze the current conversation context and understand what needs to be done
2. Select the best agent for the task by calling the appropriate function
-3. Provide clear, relevant input to the selected agent
+3. If enough work is done, call the no-action-agent to indicate completion
Guidelines:
- Choose agents based on their capabilities and the user's needs
-- If no suitable agent exists, call no_action_agent to indicate completion
-- Keep the conversation context in mind when selecting agents
-- Provide concise but complete input to the selected agent`
+- If no suitable agent exists, call no-action-agent to indicate completion
+- Keep the conversation context in mind when selecting agents`
}
client, err := genai.NewClient(ctx, &genai.ClientConfig{
@@ -88,69 +83,58 @@ Guidelines:
}
// Return the plan function
- return func(ctx context.Context, session *Session) (*Task, error) {
+ return func(ctx context.Context, inputs []*proto.Content) (*Task, error) {
// Create a context with timeout
ctx, cancel := context.WithTimeout(ctx, config.Timeout)
defer cancel()
- // Get healthy agents
- healthyAgents := registry.ListHealthy()
- if len(healthyAgents) == 0 {
- return nil, fmt.Errorf("no healthy agents available")
- }
-
// Convert agents to Gemini function declarations
- tools, err := agentsToTools(registry, healthyAgents)
+ tools, err := agentsToTools(registry)
if err != nil {
return nil, fmt.Errorf("failed to convert agents to tools: %w", err)
}
-
tools = append(tools, &genai.Tool{
FunctionDeclarations: []*genai.FunctionDeclaration{
{
Name: noActionAgentID,
- Description: "Call this when no further action is needed and the task is complete",
+ Description: "Call this when no agents need to be invoked and the task is complete",
},
},
})
// Convert session to conversation history
- history := sessionToHistory(session, config.ContextWindow)
- contents := append(history, genai.Text("Based on the above conversation, determine the next best agent to handle the task.")...)
-
+ contents := protoToContents(inputs)
resp, err := client.Models.GenerateContent(ctx, config.Model, contents, &genai.GenerateContentConfig{
Tools: tools,
SystemInstruction: genai.Text(config.SystemPrompt)[0],
MaxOutputTokens: config.MaxTokens,
- Temperature: &config.Temperature,
+ CandidateCount: 1,
})
if err != nil {
- return nil, fmt.Errorf("failed to generate content: %w", err)
+ return nil, fmt.Errorf("failed to generate in planner: %w", err)
}
-
- // Parse function calls from response
- if len(resp.Candidates) == 0 || len(resp.Candidates[0].Content.Parts) == 0 {
- return nil, fmt.Errorf("no tool selection in response from Gemini")
+ if len(resp.Candidates) == 0 {
+ return nil, fmt.Errorf("no candidates from Gemini in planner")
+ }
+ candidate := resp.Candidates[0]
+ if candidate.Content == nil || candidate.Content.Parts == nil {
+ return nil, fmt.Errorf("no content in candidates from Gemini")
}
// Look for function calls in the response
- for _, part := range resp.Candidates[0].Content.Parts {
+ for _, part := range candidate.Content.Parts {
if part == nil {
continue
}
+
if fc := part.FunctionCall; fc != nil {
if fc.Name == noActionAgentID {
return nil, nil // No more tasks
}
-
- agentID := fc.Name
- // Get the input from function call args
return &Task{
- AgentID: agentID,
- Inputs: session.History(),
- Goal: &Goal{Description: "Process user request using model selected agent"},
- StepIndex: 0,
+ AgentID: fc.Name,
+ Inputs: inputs,
}, nil
}
}
@@ -159,10 +143,14 @@ Guidelines:
}
// agentsToTools converts registry agents to Gemini function declarations.
-func agentsToTools(registry *Registry, agentIDs []string) ([]*genai.Tool, error) {
- var tools []*genai.Tool
+func agentsToTools(registry *Registry) ([]*genai.Tool, error) {
+ healthyAgents := registry.ListHealthy()
+ if len(healthyAgents) == 0 {
+ return nil, fmt.Errorf("no healthy agents available")
+ }
- for _, id := range agentIDs {
+ var tools []*genai.Tool
+ for _, id := range healthyAgents {
info, err := registry.GetInfo(id)
if err != nil {
continue // Skip agents we can't get info for
@@ -171,45 +159,36 @@ func agentsToTools(registry *Registry, agentIDs []string) ([]*genai.Tool, error)
// Create a function declaration for this agent
funcDecl := &genai.FunctionDeclaration{
Name: id, // Use agent ID as function name
- Description: fmt.Sprintf("%s - %s", info.Name, info.Description),
- }
-
- // Add metadata as additional context in the description if available
- if len(info.Metadata) > 0 {
- metadataJSON, _ := json.Marshal(info.Metadata)
- funcDecl.Description += fmt.Sprintf(" (Metadata: %s)", string(metadataJSON))
+ Description: fmt.Sprintf("%s, %s", info.Name, info.Description),
}
tools = append(tools, &genai.Tool{
FunctionDeclarations: []*genai.FunctionDeclaration{funcDecl},
})
}
-
return tools, nil
}
-// sessionToHistory converts session message history to Gemini conversation format.
-func sessionToHistory(session *Session, contextWindow int) []*genai.Content {
- // TODO(jbd): Remove the dead code, and replace it with a compactor.
- var history []*genai.Content
-
- // Get recent messages within context window
- mHistory := session.History()
- startIdx := max(0, len(mHistory)-contextWindow)
- messages := mHistory[startIdx:]
+// protoToContents converts session message history to Gemini conversation format.
+func protoToContents(inputs []*proto.Content) []*genai.Content {
+ var contents []*genai.Content
// Convert each message to Gemini format
- for _, msg := range messages {
+ for _, msg := range inputs {
role := msg.Role
- history = append(history, &genai.Content{
+ if role == "assistant" {
+ role = "model"
+ }
+ contents = append(contents, &genai.Content{
Role: role,
Parts: []*genai.Part{
{
Text: msg.Data,
+ // TODO(jbd): Handle other content types (e.g., images, files)
},
},
})
}
- return history
+ return contents
}
diff --git a/internal/controller/loop.go b/internal/controller/loop.go
index 55a440f..08277ab 100644
--- a/internal/controller/loop.go
+++ b/internal/controller/loop.go
@@ -18,20 +18,14 @@ import (
"context"
"fmt"
+ "github.com/google/gar/agent"
"github.com/google/gar/proto"
)
-// Goal represents the objective of an agent task.
-type Goal struct {
- Description string
-}
-
// Task represents a task to be executed by an agent.
type Task struct {
- AgentID string
- Inputs []*proto.Content
- Goal *Goal
- StepIndex int
+ AgentID string
+ Inputs []*proto.Content
}
// LoopExecutor orchestrates the agentic loop workflow.
@@ -41,16 +35,11 @@ type LoopExecutor struct {
sessionManager *SessionManager
maxSteps int
planFunc PlanFunc
- evaluateFunc EvaluateFunc
}
// PlanFunc determines the next agent task to execute.
// It receives the current session state and returns the next task.
-type PlanFunc func(ctx context.Context, session *Session) (*Task, error)
-
-// EvaluateFunc evaluates the agent's response to determine if the goal is achieved.
-// Returns true if the goal is met and the loop should terminate.
-type EvaluateFunc func(ctx context.Context, session *Session, task *Task, output []*proto.Content) (bool, error)
+type PlanFunc func(ctx context.Context, inputs []*proto.Content) (*Task, error)
// LoopConfig configures the loop executor.
type LoopConfig struct {
@@ -58,7 +47,6 @@ type LoopConfig struct {
SessionManager *SessionManager
MaxSteps int
PlanFunc PlanFunc
- EvaluateFunc EvaluateFunc
}
// NewLoopExecutor creates a new loop executor.
@@ -83,41 +71,22 @@ func NewLoopExecutor(ctx context.Context, config LoopConfig) (*LoopExecutor, err
config.PlanFunc = geminiPlanFunc
}
- // Provide default evaluate function if not specified
- if config.EvaluateFunc == nil {
- config.EvaluateFunc = defaultEvaluateFunc
- }
-
return &LoopExecutor{
registry: config.Registry,
sessionManager: config.SessionManager,
maxSteps: config.MaxSteps,
planFunc: config.PlanFunc,
- evaluateFunc: config.EvaluateFunc,
}, nil
}
// Execute starts a new agentic loop execution for the given session.
-func (e *LoopExecutor) Execute(ctx context.Context, session *Session, inputs []*proto.Content) error {
- if session.State() == proto.State_STATE_FAILED {
- return fmt.Errorf("session has failed and cannot continue")
- }
- if err := session.SetState(ctx, proto.State_STATE_RUNNING); err != nil {
- return fmt.Errorf("failed to set session state: %w", err)
- }
-
- // Write input content to session
- for _, content := range inputs {
- if _, err := session.WriteContentIn(ctx, content); err != nil {
- return fmt.Errorf("failed to write input content: %w", err)
- }
- }
- return e.runLoop(ctx, session)
+func (e *LoopExecutor) Execute(ctx context.Context, session *Session, handler agent.OutputHandler) error {
+ return e.runLoop(ctx, session, handler)
}
// runLoop executes the main agentic loop.
// It runs up to maxSteps iterations per trigger/resume invocation.
-func (e *LoopExecutor) runLoop(ctx context.Context, session *Session) error {
+func (e *LoopExecutor) runLoop(ctx context.Context, session *Session, handler agent.OutputHandler) error {
steps := 0
for steps < e.maxSteps {
@@ -128,50 +97,31 @@ func (e *LoopExecutor) runLoop(ctx context.Context, session *Session) error {
default:
}
- // Phase 1: Plan - Determine next agent and action
- task, err := e.planFunc(ctx, session)
+ task, err := e.planFunc(ctx, session.History())
if err != nil {
- if err := session.SetState(ctx, proto.State_STATE_FAILED); err != nil {
- return fmt.Errorf("failed to set session state: %w", err)
- }
return fmt.Errorf("planning failed: %w", err)
}
if task == nil {
+ // No more tasks to execute; loop is complete.
return nil
}
- // Phase 2: Execute - Send content to agent and receive response
- outputs, err := e.executeTask(ctx, session, task)
+ outputs, err := e.executeTask(ctx, session.ID, task)
if err != nil {
- if err := session.SetState(ctx, proto.State_STATE_FAILED); err != nil {
- return fmt.Errorf("failed to set session state: %w", err)
- }
- return fmt.Errorf("execution failed: %w", err)
+ return fmt.Errorf("task execution failed: %w", err)
}
-
for _, output := range outputs {
if _, err := session.WriteContentOut(ctx, output); err != nil {
- return fmt.Errorf("failed to write task inputs: %w", err)
+ return fmt.Errorf("failed to write output content: %w", err)
}
- }
-
- // Phase 3: Evaluate - Check if goal achieved
- goalAchieved, err := e.evaluateFunc(ctx, session, task, outputs)
- if err != nil {
- if err := session.SetState(ctx, proto.State_STATE_FAILED); err != nil {
- return fmt.Errorf("failed to set session state: %w", err)
+ if err := handler(output); err != nil {
+ return fmt.Errorf("output handler error: %w", err)
}
- return fmt.Errorf("evaluation failed: %w", err)
}
// Phase 4: Advance step counters
steps++
-
- // If goal achieved, complete the session
- if goalAchieved {
- return nil
- }
}
// Can be resumed later with another trigger
@@ -179,7 +129,7 @@ func (e *LoopExecutor) runLoop(ctx context.Context, session *Session) error {
}
// executeTask sends input to an agent and collects output.
-func (e *LoopExecutor) executeTask(ctx context.Context, session *Session, task *Task) ([]*proto.Content, error) {
+func (e *LoopExecutor) executeTask(ctx context.Context, sessionID string, task *Task) ([]*proto.Content, error) {
// Get the agent from registry
ag, err := e.registry.Get(task.AgentID)
if err != nil {
@@ -195,16 +145,9 @@ func (e *LoopExecutor) executeTask(ctx context.Context, session *Session, task *
}
// Process inputs with the agent
- if err := ag.Process(ctx, session.ID, task.Inputs, outputHandler); err != nil {
+ if err := ag.Process(ctx, sessionID, task.Inputs, outputHandler); err != nil {
return nil, fmt.Errorf("agent process failed: %w", err)
}
return outputs, nil
}
-
-// defaultEvaluateFunc is a simple default evaluation function.
-// It considers the goal achieved after processing one step.
-func defaultEvaluateFunc(ctx context.Context, session *Session, task *Task, output []*proto.Content) (bool, error) {
- // Simple evaluation: goal achieved if we got any output
- return len(output) > 0, nil
-}