Skip to content

armgit / ax

Public Imported from GitHub
0

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

Go

impl: fix subagent execution flow and add unit tests (#339)

anj-s6eaba7c1e8e8
diff --git a/examples/docker_agent/run_e2e.sh b/examples/docker_agent/run_e2e.sh
index 4cb4222..3c4f134 100755
--- a/examples/docker_agent/run_e2e.sh
+++ b/examples/docker_agent/run_e2e.sh
@@ -31,7 +31,8 @@ go run examples/docker_agent/main.go &
AGENT_PID=$!
echo "Starting AX Server in background..."
-ax serve --config examples/docker_agent/ax.yaml &
+/opt/homebrew/bin/go build -o bin/ax ./cmd/ax
+./bin/ax serve --config examples/docker_agent/ax.yaml &
SERVER_PID=$!
# Give servers a few seconds to start up
@@ -46,7 +47,7 @@ for i in {1..30}; do
done
echo "Executing task..."
-ax exec --server localhost:8494 --input "Write a Dockerfile for a Python flask app that says hello world."
+./bin/ax exec --server localhost:8494 --input "Write a Dockerfile for a Python flask app that says hello world."
# Wait for the exec command to finish
# The trap will kill the background servers when the script exits
diff --git a/internal/gemini/gemini.go b/internal/gemini/gemini.go
index 341a3c8..d117fa7 100644
--- a/internal/gemini/gemini.go
+++ b/internal/gemini/gemini.go
@@ -189,6 +189,9 @@ func (t *BashTool) FuncDecl() []*genai.Tool {
}
func (t *BashTool) HandleCall(ctx context.Context, fc *genai.FunctionCall, o agent.OutputHandler) error {
+ if disallow, _ := ctx.Value(disallowConfirmationsKey).(bool); disallow {
+ return t.HandleExecute(ctx, fc, true, o)
+ }
command, _ := fc.Args["command"].(string)
argsStruct, err := structpb.NewStruct(fc.Args)
if err != nil {
@@ -348,6 +351,9 @@ func (t *SkillsTool) FuncDecl() []*genai.Tool {
}
func (t *SkillsTool) HandleCall(ctx context.Context, fc *genai.FunctionCall, o agent.OutputHandler) error {
+ if disallow, _ := ctx.Value(disallowConfirmationsKey).(bool); disallow {
+ return t.HandleExecute(ctx, fc, true, o)
+ }
argsStruct, err := structpb.NewStruct(fc.Args)
if err != nil {
return err
diff --git a/internal/gemini/gemini_planner.go b/internal/gemini/gemini_planner.go
index 270990e..45027d7 100644
--- a/internal/gemini/gemini_planner.go
+++ b/internal/gemini/gemini_planner.go
@@ -18,6 +18,7 @@ import (
"context"
"fmt"
"os"
+ "runtime/debug"
"strings"
"time"
@@ -26,14 +27,32 @@ import (
"github.com/google/ax/proto"
"github.com/google/uuid"
"google.golang.org/genai"
+ "google.golang.org/protobuf/types/known/structpb"
)
+type contextKey string
+const disallowConfirmationsKey contextKey = "disallowConfirmations"
+
// AgentRegistry defines the interface needed by the planner to discover agents.
type AgentRegistry interface {
List() []string
GetInfo(id string) (*agent.AgentInfo, error)
}
+// ContentGenerator abstracts Gemini content generation for testing.
+type ContentGenerator interface {
+ GenerateContent(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) (*genai.GenerateContentResponse, error)
+}
+
+// realContentGenerator implements ContentGenerator using the real genai.Client.
+type realContentGenerator struct {
+ client *genai.Client
+}
+
+func (g *realContentGenerator) GenerateContent(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) (*genai.GenerateContentResponse, error) {
+ return g.client.Models.GenerateContent(ctx, model, contents, config)
+}
+
// GeminiPlannerConfig configures the Gemini-based planner.
type GeminiPlannerConfig struct {
GeminiConfig *config.GeminiConfig
@@ -43,7 +62,7 @@ type GeminiPlannerConfig struct {
// geminiPlannerAgent implements task.Agent using Gemini.
type geminiPlannerAgent struct {
config GeminiPlannerConfig
- client *genai.Client
+ client ContentGenerator
bashTool Tool
skillsTool Tool
registry AgentRegistry
@@ -110,7 +129,7 @@ When introducing yourself, simply reply: "I am AX, how can I help you?"
}
p := &geminiPlannerAgent{
- client: client,
+ client: &realContentGenerator{client: client},
bashTool: &BashTool{},
skillsTool: skillsTool,
registry: registry,
@@ -139,7 +158,7 @@ func (p *geminiPlannerAgent) loop(ctx context.Context, conversationID string, st
}
for {
- nextAgentID, keepLooping, err := p.process(ctx, start, outputCapturer)
+ nextAgentID, keepLooping, err := p.process(ctx, conversationID, start, e, outputCapturer)
if err != nil {
return err
}
@@ -170,23 +189,11 @@ func (p *geminiPlannerAgent) loop(ctx context.Context, conversationID string, st
if state == proto.State_STATE_PENDING {
return nil
}
-
- // TODO(anjalisridhar): Replace it with function response
- // for the model to be able to pick up that agent is executed.
- start.Messages = append(start.Messages, &proto.Message{
- Role: "assistant",
- Content: &proto.Content{
- Type: &proto.Content_Text{
- Text: &proto.TextContent{
- Text: fmt.Sprintf("This step is done by the agent %q, figure out the next step if there is one.", nextAgentID),
- },
- },
- },
- })
+
}
}
-func (p *geminiPlannerAgent) process(ctx context.Context, start *proto.AgentStart, handler agent.OutputHandler) (agentID string, keepLooping bool, err error) {
+func (p *geminiPlannerAgent) process(ctx context.Context, conversationID string, start *proto.AgentStart, e agent.Executor, handler agent.OutputHandler) (agentID string, keepLooping bool, err error) {
tools, err := agentsToTools(p.registry)
if err != nil {
return "", false, fmt.Errorf("failed to convert agents to tools: %w", err)
@@ -223,7 +230,7 @@ func (p *geminiPlannerAgent) process(ctx context.Context, start *proto.AgentStar
genCfg.Temperature = &t
}
- resp, err := p.client.Models.GenerateContent(ctx, p.config.GeminiConfig.Model, contents, genCfg)
+ resp, err := p.client.GenerateContent(ctx, p.config.GeminiConfig.Model, contents, genCfg)
if err != nil {
return "", false, fmt.Errorf("failed to generate in planner: %w", err)
@@ -276,6 +283,9 @@ func (p *geminiPlannerAgent) process(ctx context.Context, start *proto.AgentStar
case "activate_skill":
return "", true, p.skillsTool.HandleCall(ctx, fc, handler)
default:
+ if p.isAgent(fc.Name) {
+ return "", true, p.handleSubagentCall(ctx, conversationID, fc, part.ThoughtSignature, start.Messages, e, handler)
+ }
return strings.ReplaceAll(fc.Name, "_", "-"), false, nil
}
}
@@ -283,6 +293,169 @@ func (p *geminiPlannerAgent) process(ctx context.Context, start *proto.AgentStar
return "", false, nil
}
+func (p *geminiPlannerAgent) isAgent(name string) bool {
+ mappedName := strings.ReplaceAll(name, "_", "-")
+ for _, a := range p.registry.List() {
+ if a == mappedName {
+ return true
+ }
+ }
+ return false
+}
+
+func (p *geminiPlannerAgent) handleSubagentCall(ctx context.Context, conversationID string, fc *genai.FunctionCall, signature []byte, history []*proto.Message, e agent.Executor, handler agent.OutputHandler) error {
+
+ prompt, ok := fc.Args["prompt"].(string)
+ if !ok {
+ return fmt.Errorf("missing or invalid 'prompt' argument")
+ }
+
+ // Record the function call in the history.
+ argsStruct, err := structpb.NewStruct(fc.Args)
+ if err != nil {
+ return err
+ }
+ if err := handler(&proto.AgentOutputs{
+ Messages: []*proto.Message{
+ {
+ Role: "model",
+ Content: &proto.Content{
+ Type: &proto.Content_ToolCall{
+ ToolCall: &proto.ToolCallContent{
+ Id: fc.ID,
+ Signature: signature,
+ Type: &proto.ToolCallContent_FunctionCall{
+ FunctionCall: &proto.FunctionCallContent{
+ Name: fc.Name,
+ Arguments: argsStruct,
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ }); err != nil {
+ return err
+ }
+
+ mappedName := strings.ReplaceAll(fc.Name, "_", "-")
+ var historyStr strings.Builder
+ for _, msg := range history {
+ historyStr.WriteString(fmt.Sprintf("%s: ", msg.Role))
+ if msg.Content != nil {
+ if txt := msg.Content.GetText(); txt != nil {
+ historyStr.WriteString(txt.Text)
+ }
+ }
+ historyStr.WriteString("\n")
+ }
+
+ subagentStart := &proto.AgentStart{
+ AgentId: mappedName,
+ Messages: []*proto.Message{
+ {
+ Role: "user",
+ Content: &proto.Content{
+ Type: &proto.Content_Text{
+ Text: &proto.TextContent{Text: fmt.Sprintf("History Summary:\n%s\n\nPrompt:\n%s", historyStr.String(), prompt)},
+ },
+ },
+ },
+ },
+ }
+
+ var subagentOutputs []*proto.Message
+ capturer := func(outgoing *proto.AgentOutputs) error {
+ subagentOutputs = append(subagentOutputs, outgoing.Messages...)
+ return nil
+ }
+
+ var execErr error
+ func() {
+ defer func() {
+ if r := recover(); r != nil {
+ execErr = fmt.Errorf("panic: %v\n%s", r, string(debug.Stack()))
+ }
+ }()
+ // Disallow tool confirmations for subagents.
+ // NOTE: We use context here for simplicity, but for robust resumption support
+ // across process restarts, this might need to be persisted in AgentConfig
+ // in the future if the controller does not preserve context on resume.
+ subCtx := context.WithValue(ctx, disallowConfirmationsKey, true)
+ _, execErr = e.Exec(subCtx, conversationID, mappedName, subagentStart, capturer)
+ }()
+
+ if execErr != nil {
+ respStruct, _ := structpb.NewStruct(map[string]any{
+ "result": "sub agent failed",
+ "error": execErr.Error(),
+ })
+ return handler(&proto.AgentOutputs{
+ Messages: []*proto.Message{
+ {
+ Role: "user",
+ Content: &proto.Content{
+ Type: &proto.Content_ToolResult{
+ ToolResult: &proto.ToolResultContent{
+ CallId: fc.ID,
+ Type: &proto.ToolResultContent_FunctionResult{
+ FunctionResult: &proto.FunctionResultContent{
+ Name: fc.Name,
+ Result: &proto.FunctionResultContent_Response{
+ Response: respStruct,
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ })
+ }
+
+
+ var resultText strings.Builder
+ for _, msg := range subagentOutputs {
+ if msg.Content != nil {
+ if txt := msg.Content.GetText(); txt != nil {
+ resultText.WriteString(txt.Text)
+ resultText.WriteString("\n")
+ }
+ }
+ }
+
+ respStruct, err := structpb.NewStruct(map[string]any{"result": resultText.String()})
+ if err != nil {
+ return err
+ }
+
+ return handler(&proto.AgentOutputs{
+ Messages: []*proto.Message{
+ {
+ Role: "user",
+ Content: &proto.Content{
+ Type: &proto.Content_ToolResult{
+ ToolResult: &proto.ToolResultContent{
+ CallId: fc.ID,
+ Type: &proto.ToolResultContent_FunctionResult{
+ FunctionResult: &proto.FunctionResultContent{
+ Name: fc.Name,
+ Result: &proto.FunctionResultContent_Response{
+ Response: respStruct,
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ },
+ })
+}
+
+
func (p *geminiPlannerAgent) handleConfirmationAnswer(inputs []*proto.Message) (*genai.FunctionCall, bool) {
var conf *proto.ConfirmationContent
var approved bool
@@ -359,11 +532,16 @@ func agentsToTools(registry AgentRegistry, nativeTools ...Tool) ([]*genai.Tool,
Parameters: &genai.Schema{
Type: genai.TypeObject,
Properties: map[string]*genai.Schema{
- "request_instructions": {
+ "history": {
+ Type: genai.TypeString,
+ Description: "Summary of the conversation history so far.",
+ },
+ "prompt": {
Type: genai.TypeString,
- Description: "Any custom instructions or directives to provide directly to the target execution sequence.",
+ Description: "The last user prompt verbatim.",
},
},
+ Required: []string{"history", "prompt"},
},
}
tools = append(tools, &genai.Tool{
diff --git a/internal/gemini/gemini_planner_test.go b/internal/gemini/gemini_planner_test.go
index aa530ca..4154ce2 100644
--- a/internal/gemini/gemini_planner_test.go
+++ b/internal/gemini/gemini_planner_test.go
@@ -15,9 +15,15 @@
package gemini
import (
+ "context"
+ "fmt"
+ "strings"
"testing"
+ "github.com/google/ax/internal/agent"
+ "github.com/google/ax/internal/config"
"github.com/google/ax/proto"
+ "google.golang.org/genai"
"google.golang.org/protobuf/types/known/structpb"
)
@@ -129,3 +135,304 @@ func TestHandleConfirmationAnswer(t *testing.T) {
t.Error("expected approved to be true")
}
}
+
+type mockContentGenerator struct {
+ generateContentFunc func(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) (*genai.GenerateContentResponse, error)
+}
+
+func (m *mockContentGenerator) GenerateContent(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) (*genai.GenerateContentResponse, error) {
+ if m.generateContentFunc != nil {
+ return m.generateContentFunc(ctx, model, contents, config)
+ }
+ return nil, nil
+}
+
+type mockExecutor struct {
+ execFunc func(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error)
+}
+
+func (m *mockExecutor) Exec(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error) {
+ if m.execFunc != nil {
+ return m.execFunc(ctx, conversationID, execID, start, o)
+ }
+ return proto.State_STATE_COMPLETED, nil
+}
+
+type mockAgentRegistry struct {
+ listFunc func() []string
+ getInfoFunc func(id string) (*agent.AgentInfo, error)
+}
+
+func (m *mockAgentRegistry) List() []string {
+ if m.listFunc != nil {
+ return m.listFunc()
+ }
+ return nil
+}
+
+func (m *mockAgentRegistry) GetInfo(id string) (*agent.AgentInfo, error) {
+ if m.getInfoFunc != nil {
+ return m.getInfoFunc(id)
+ }
+ return nil, nil
+}
+
+func TestAgentsToTools_Parameters(t *testing.T) {
+ registry := &mockAgentRegistry{
+ listFunc: func() []string {
+ return []string{"test-agent"}
+ },
+ getInfoFunc: func(id string) (*agent.AgentInfo, error) {
+ return &agent.AgentInfo{
+ ID: "test-agent",
+ Name: "Test Agent",
+ Description: "A test agent",
+ }, nil
+ },
+ }
+
+ tools, err := agentsToTools(registry)
+ if err != nil {
+ t.Fatalf("agentsToTools failed: %v", err)
+ }
+
+ if len(tools) != 1 {
+ t.Fatalf("expected 1 tool, got %d", len(tools))
+ }
+
+ decl := tools[0].FunctionDeclarations[0]
+ if decl.Name != "test_agent" {
+ t.Errorf("expected name test_agent, got %s", decl.Name)
+ }
+
+ params := decl.Parameters
+ if params == nil {
+ t.Fatal("expected parameters")
+ }
+
+ if params.Type != genai.TypeObject {
+ t.Errorf("expected type object, got %v", params.Type)
+ }
+
+ if _, ok := params.Properties["history"]; !ok {
+ t.Error("expected 'history' property")
+ }
+ if _, ok := params.Properties["prompt"]; !ok {
+ t.Error("expected 'prompt' property")
+ }
+
+ required := params.Required
+ if len(required) != 2 {
+ t.Errorf("expected 2 required properties, got %d", len(required))
+ }
+
+ foundHistory := false
+ foundPrompt := false
+ for _, r := range required {
+ if r == "history" {
+ foundHistory = true
+ }
+ if r == "prompt" {
+ foundPrompt = true
+ }
+ }
+ if !foundHistory {
+ t.Error("expected 'history' to be required")
+ }
+ if !foundPrompt {
+ t.Error("expected 'prompt' to be required")
+ }
+}
+
+func TestHandleSubagentCall_Success(t *testing.T) {
+ mockGen := &mockContentGenerator{
+ generateContentFunc: func(ctx context.Context, model string, contents []*genai.Content, config *genai.GenerateContentConfig) (*genai.GenerateContentResponse, error) {
+ return &genai.GenerateContentResponse{
+ Candidates: []*genai.Candidate{
+ {
+ Content: &genai.Content{
+ Parts: []*genai.Part{
+ {Text: "Subagent work summary."},
+ },
+ },
+ },
+ },
+ }, nil
+ },
+ }
+
+ mockExec := &mockExecutor{
+ execFunc: func(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error) {
+ o(&proto.AgentOutputs{
+ Messages: []*proto.Message{
+ {
+ Role: "model",
+ Content: &proto.Content{
+ Type: &proto.Content_Text{
+ Text: &proto.TextContent{Text: "Subagent output step 1"},
+ },
+ },
+ },
+ },
+ })
+ return proto.State_STATE_COMPLETED, nil
+ },
+ }
+
+ p := &geminiPlannerAgent{
+ client: mockGen,
+ config: GeminiPlannerConfig{
+ GeminiConfig: &config.GeminiConfig{Model: "test-model"},
+ },
+ }
+
+ fc := &genai.FunctionCall{
+ Name: "test-subagent",
+ Args: map[string]any{
+ "history": "Previous history summary",
+ "prompt": "Current user prompt",
+ },
+ }
+
+ var handlerCalled bool
+ var handlerOutput *proto.AgentOutputs
+ handler := func(outgoing *proto.AgentOutputs) error {
+ handlerCalled = true
+ handlerOutput = outgoing
+ return nil
+ }
+
+ err := p.handleSubagentCall(context.Background(), "test-conv", fc, nil, nil, mockExec, handler)
+ if err != nil {
+ t.Fatalf("handleSubagentCall failed: %v", err)
+ }
+
+ if !handlerCalled {
+ t.Fatal("expected handler to be called")
+ }
+
+ if len(handlerOutput.Messages) != 1 {
+ t.Fatalf("expected 1 message, got %d", len(handlerOutput.Messages))
+ }
+ msg := handlerOutput.Messages[0]
+ tr := msg.Content.GetToolResult()
+ if tr == nil {
+ t.Fatal("expected tool result")
+ }
+ fr := tr.GetFunctionResult()
+ if fr == nil {
+ t.Fatal("expected function result")
+ }
+ if fr.Name != "test-subagent" {
+ t.Errorf("expected name test-subagent, got %s", fr.Name)
+ }
+ resp := fr.GetResponse()
+ if resp == nil {
+ t.Fatal("expected response")
+ }
+ resultVal := resp.Fields["result"].GetStringValue()
+ if resultVal != "Subagent output step 1\n" {
+ t.Errorf("expected 'Subagent output step 1\\n', got %s", resultVal)
+ }
+}
+
+func TestHandleSubagentCall_MissingArgs(t *testing.T) {
+ p := &geminiPlannerAgent{}
+ fc := &genai.FunctionCall{
+ Name: "test-subagent",
+ Args: map[string]any{},
+ }
+
+ err := p.handleSubagentCall(context.Background(), "test-conv", fc, nil, nil, nil, nil)
+ if err == nil {
+ t.Fatal("expected error due to missing arguments")
+ }
+ if !strings.Contains(err.Error(), "missing or invalid 'prompt' argument") {
+ t.Errorf("unexpected error: %v", err)
+ }
+}
+
+func TestHandleSubagentCall_Failure(t *testing.T) {
+ mockExec := &mockExecutor{
+ execFunc: func(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error) {
+ return proto.State_STATE_UNSPECIFIED, fmt.Errorf("subagent execution failed")
+ },
+ }
+
+ p := &geminiPlannerAgent{}
+ fc := &genai.FunctionCall{
+ Name: "test-subagent",
+ Args: map[string]any{
+ "history": "Previous history summary",
+ "prompt": "Current user prompt",
+ },
+ }
+
+ var handlerOutput *proto.AgentOutputs
+ handler := func(outgoing *proto.AgentOutputs) error {
+ handlerOutput = outgoing
+ return nil
+ }
+
+ err := p.handleSubagentCall(context.Background(), "test-conv", fc, nil, nil, mockExec, handler)
+ if err != nil {
+ t.Fatalf("handleSubagentCall failed: %v", err)
+ }
+
+ msg := handlerOutput.Messages[0]
+ tr := msg.Content.GetToolResult()
+ fr := tr.GetFunctionResult()
+ resp := fr.GetResponse()
+ resultVal := resp.Fields["result"].GetStringValue()
+ if resultVal != "sub agent failed" {
+ t.Errorf("expected 'sub agent failed', got %s", resultVal)
+ }
+ errVal := resp.Fields["error"].GetStringValue()
+ if !strings.Contains(errVal, "subagent execution failed") {
+ t.Errorf("expected error to contain 'subagent execution failed', got %s", errVal)
+ }
+}
+
+func TestHandleSubagentCall_Panic(t *testing.T) {
+ mockExec := &mockExecutor{
+ execFunc: func(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error) {
+ panic("something went wrong")
+ },
+ }
+
+ p := &geminiPlannerAgent{}
+ fc := &genai.FunctionCall{
+ Name: "test-subagent",
+ Args: map[string]any{
+ "history": "Previous history summary",
+ "prompt": "Current user prompt",
+ },
+ }
+
+ var handlerOutput *proto.AgentOutputs
+ handler := func(outgoing *proto.AgentOutputs) error {
+ handlerOutput = outgoing
+ return nil
+ }
+
+ err := p.handleSubagentCall(context.Background(), "test-conv", fc, nil, nil, mockExec, handler)
+ if err != nil {
+ t.Fatalf("handleSubagentCall failed: %v", err)
+ }
+
+ msg := handlerOutput.Messages[0]
+ tr := msg.Content.GetToolResult()
+ fr := tr.GetFunctionResult()
+ resp := fr.GetResponse()
+ resultVal := resp.Fields["result"].GetStringValue()
+ if resultVal != "sub agent failed" {
+ t.Errorf("expected 'sub agent failed', got %s", resultVal)
+ }
+ errVal := resp.Fields["error"].GetStringValue()
+ if !strings.Contains(errVal, "panic: something went wrong") {
+ t.Errorf("expected error to contain 'panic: something went wrong', got %s", errVal)
+ }
+ if !strings.Contains(errVal, "goroutine") {
+ t.Errorf("expected stack trace in error, got %s", errVal)
+ }
+}