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.shindex 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}; dodoneecho "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 exitsdiff --git a/internal/gemini/gemini.go b/internal/gemini/gemini.goindex 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 errdiff --git a/internal/gemini/gemini_planner.go b/internal/gemini/gemini_planner.goindex 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() []stringGetInfo(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 ContentGeneratorbashTool ToolskillsTool Toolregistry 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, stif 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.AgentStargenCfg.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.AgentStarcase "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.AgentStarreturn "", 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.ConfirmationContentvar 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.goindex aa530ca..4154ce2 100644--- a/internal/gemini/gemini_planner_test.go+++ b/internal/gemini/gemini_planner_test.go@@ -15,9 +15,15 @@package geminiimport (+ "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)+ }+}