Skip to content

armgit / ax

Public Imported from GitHub
0

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

Go

fix: agentExecutor for sub-agent invocation (#329)

JoyceLiu9821d06efdab
diff --git a/.gitignore b/.gitignore
index 0552b47..5cf5ade 100644
--- a/.gitignore
+++ b/.gitignore
@@ -13,4 +13,5 @@ examples/sandbox_agent/cloudbuild.yaml
tasklog/*
python/__pycache__
python/proto/__pycache__
-axepp
\ No newline at end of file
+axepp
+__pycache__/
diff --git a/internal/controller/executor/agent_executor.go b/internal/controller/executor/agent_executor.go
new file mode 100644
index 0000000..82f6cc4
--- /dev/null
+++ b/internal/controller/executor/agent_executor.go
@@ -0,0 +1,111 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package executor
+
+import (
+ "context"
+ "errors"
+
+ "github.com/google/ax/internal/agent"
+ "github.com/google/ax/internal/historyutil"
+ "github.com/google/ax/proto"
+ "google.golang.org/protobuf/types/known/timestamppb"
+)
+
+// AgentExecutor returns an Executor suitable for invoking sub-agents from
+// within a planner or another agent's Connect method.
+//
+// Unlike DefaultExecutor (which is the controller's top-level conversation
+// runner), AgentExecutor:
+// - Does NOT load conversation history from the event log; the caller
+// passes the relevant messages in start.Messages.
+// - Does NOT short-circuit on WaitsForConfirmation or COMPLETED cache.
+// - DOES write execution-level logs (pending, outputs, completed) for
+// observability, but omits the WaitsForConfirmation/COMPLETED guards
+// that DefaultExecutor uses.
+// - Returns STATE_PENDING when the sub-agent's last output is an
+// unanswered confirmation question.
+func AgentExecutor(eventLog EventLog, registry map[string]agent.Agent) agent.Executor {
+ return &agentExecutor{
+ eventLog: eventLog,
+ registry: registry,
+ }
+}
+
+type agentExecutor struct {
+ execID string
+ eventLog EventLog
+ registry map[string]agent.Agent
+}
+
+func (ae *agentExecutor) Exec(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error) {
+ execID = newExecID(ae.execID, execID)
+ a, ok := ae.registry[start.AgentId]
+ if !ok {
+ return proto.State_STATE_UNSPECIFIED, errors.New("no agent found: " + start.AgentId)
+ }
+
+ // Log pending execution event with inputs for debuggability.
+ if err := ae.eventLog.AppendExec(ctx, &proto.ExecutionEvent{
+ Timestamp: timestamppb.Now(),
+ ExecId: execID,
+ AgentId: start.AgentId,
+ Inputs: start.Messages,
+ State: proto.State_STATE_PENDING,
+ }); err != nil {
+ return proto.State_STATE_UNSPECIFIED, err
+ }
+
+ var allOutputs []*proto.Message
+ outputBuffer := func(outgoing *proto.AgentOutputs) error {
+ allOutputs = append(allOutputs, outgoing.Messages...)
+ if o != nil {
+ return o(outgoing)
+ }
+ return nil
+ }
+
+ if err := a.Connect(ctx, conversationID, execID, start, &agentExecutor{execID: execID, eventLog: ae.eventLog, registry: ae.registry}, outputBuffer); err != nil {
+ return proto.State_STATE_UNSPECIFIED, err
+ }
+
+ // Log outputs.
+ if len(allOutputs) > 0 {
+ if err := ae.eventLog.AppendExec(ctx, &proto.ExecutionEvent{
+ Timestamp: timestamppb.Now(),
+ ExecId: execID,
+ AgentId: start.AgentId,
+ Outputs: allOutputs,
+ State: proto.State_STATE_PENDING,
+ }); err != nil {
+ return proto.State_STATE_UNSPECIFIED, err
+ }
+
+ if historyutil.WaitsForConfirmation(allOutputs) != nil {
+ return proto.State_STATE_PENDING, nil
+ }
+ }
+
+ // Log completed.
+ if err := ae.eventLog.AppendExec(ctx, &proto.ExecutionEvent{
+ Timestamp: timestamppb.Now(),
+ ExecId: execID,
+ AgentId: start.AgentId,
+ State: proto.State_STATE_COMPLETED,
+ }); err != nil {
+ return proto.State_STATE_UNSPECIFIED, err
+ }
+ return proto.State_STATE_COMPLETED, nil
+}
diff --git a/internal/controller/executor/agent_executor_test.go b/internal/controller/executor/agent_executor_test.go
new file mode 100644
index 0000000..ed9aa82
--- /dev/null
+++ b/internal/controller/executor/agent_executor_test.go
@@ -0,0 +1,349 @@
+// Copyright 2026 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package executor
+
+import (
+ "context"
+ "sync/atomic"
+ "testing"
+
+ "github.com/google/ax/internal/agent"
+ "github.com/google/ax/internal/controller/executor/executortest"
+ "github.com/google/ax/proto"
+)
+
+func TestAgentExecutor_BasicExec(t *testing.T) {
+ ctx := context.Background()
+ eventLog := &executortest.MemoryEventLog{}
+
+ registry := map[string]agent.Agent{
+ "echo": AgentFunc(func(inputs []*proto.Message, tm agent.Executor, o agent.OutputHandler) {
+ if o != nil {
+ o(&proto.AgentOutputs{
+ Messages: []*proto.Message{text("assistant", "hello from echo")},
+ })
+ }
+ }),
+ }
+
+ ae := AgentExecutor(eventLog, registry)
+ var received []*proto.Message
+ handler := func(outgoing *proto.AgentOutputs) error {
+ received = append(received, outgoing.Messages...)
+ return nil
+ }
+
+ state, err := ae.Exec(ctx, "conv-1", "exec-1", &proto.AgentStart{
+ AgentId: "echo",
+ Messages: []*proto.Message{text("user", "hi")},
+ }, handler)
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if state != proto.State_STATE_COMPLETED {
+ t.Fatalf("expected STATE_COMPLETED, got %v", state)
+ }
+ if len(received) != 1 {
+ t.Fatalf("expected 1 output message, got %d", len(received))
+ }
+ if received[0].GetContent().GetText().GetText() != "hello from echo" {
+ t.Fatalf("expected 'hello from echo', got %v", received[0].GetContent().GetText().GetText())
+ }
+
+ // Verify event log entries: pending, outputs, completed.
+ if len(eventLog.AllExecEvents) != 3 {
+ t.Fatalf("expected 3 exec events (pending, outputs, completed), got %d", len(eventLog.AllExecEvents))
+ }
+ if eventLog.AllExecEvents[0].State != proto.State_STATE_PENDING {
+ t.Fatalf("expected first event STATE_PENDING, got %v", eventLog.AllExecEvents[0].State)
+ }
+ if len(eventLog.AllExecEvents[1].Outputs) != 1 {
+ t.Fatalf("expected 1 output in second event, got %d", len(eventLog.AllExecEvents[1].Outputs))
+ }
+ if eventLog.AllExecEvents[2].State != proto.State_STATE_COMPLETED {
+ t.Fatalf("expected last event STATE_COMPLETED, got %v", eventLog.AllExecEvents[2].State)
+ }
+}
+
+func TestAgentExecutor_ConfirmationReturnsPending(t *testing.T) {
+ ctx := context.Background()
+ eventLog := &executortest.MemoryEventLog{}
+
+ confID := "conf-42"
+
+ var callCount atomic.Int32
+ registry := map[string]agent.Agent{
+ "confirmer": AgentFunc(func(inputs []*proto.Message, tm agent.Executor, o agent.OutputHandler) {
+ callCount.Add(1)
+ run := callCount.Load()
+
+ if run == 1 {
+ // First invocation: emit a confirmation question.
+ if o != nil {
+ o(&proto.AgentOutputs{
+ Messages: []*proto.Message{{
+ Role: "model",
+ Content: &proto.Content{
+ Type: &proto.Content_Confirmation{
+ Confirmation: &proto.ConfirmationContent{
+ Id: confID,
+ Question: "proceed?",
+ },
+ },
+ },
+ }},
+ })
+ }
+ return
+ }
+
+ // Second invocation: emit completion text.
+ if o != nil {
+ o(&proto.AgentOutputs{
+ Messages: []*proto.Message{text("assistant", "confirmed and done")},
+ })
+ }
+ }),
+ }
+
+ ae := AgentExecutor(eventLog, registry)
+
+ // --- First call: should return STATE_PENDING ---
+ var firstOutputs []*proto.Message
+ state, err := ae.Exec(ctx, "conv-1", "exec-conf", &proto.AgentStart{
+ AgentId: "confirmer",
+ Messages: []*proto.Message{text("user", "do something risky")},
+ }, func(outgoing *proto.AgentOutputs) error {
+ firstOutputs = append(firstOutputs, outgoing.Messages...)
+ return nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if state != proto.State_STATE_PENDING {
+ t.Fatalf("expected STATE_PENDING, got %v", state)
+ }
+ if len(firstOutputs) != 1 {
+ t.Fatalf("expected 1 output, got %d", len(firstOutputs))
+ }
+ if firstOutputs[0].GetContent().GetConfirmation().GetQuestion() != "proceed?" {
+ t.Fatalf("expected confirmation question 'proceed?', got %v",
+ firstOutputs[0].GetContent().GetConfirmation().GetQuestion())
+ }
+
+ // --- Second call: provide approval, should return STATE_COMPLETED ---
+ // agentExecutor does NOT check history/cache, so re-invoking with new
+ // start.Messages should call the agent again (callCount goes to 2).
+ approval := &proto.Message{
+ Role: "user",
+ Content: &proto.Content{
+ Type: &proto.Content_Confirmation{
+ Confirmation: &proto.ConfirmationContent{
+ Id: confID,
+ Decision: &proto.ConfirmationContent_Approval{
+ Approval: &proto.ApprovalDecision{Approved: true},
+ },
+ },
+ },
+ },
+ }
+
+ var secondOutputs []*proto.Message
+ state, err = ae.Exec(ctx, "conv-1", "exec-conf", &proto.AgentStart{
+ AgentId: "confirmer",
+ Messages: []*proto.Message{approval},
+ }, func(outgoing *proto.AgentOutputs) error {
+ secondOutputs = append(secondOutputs, outgoing.Messages...)
+ return nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ if state != proto.State_STATE_COMPLETED {
+ t.Fatalf("expected STATE_COMPLETED on second call, got %v", state)
+ }
+ if callCount.Load() != 2 {
+ t.Fatalf("expected agent called 2 times, got %d", callCount.Load())
+ }
+ if len(secondOutputs) != 1 {
+ t.Fatalf("expected 1 output on second call, got %d", len(secondOutputs))
+ }
+ if secondOutputs[0].GetContent().GetText().GetText() != "confirmed and done" {
+ t.Fatalf("expected 'confirmed and done', got %v",
+ secondOutputs[0].GetContent().GetText().GetText())
+ }
+}
+
+func TestAgentExecutor_NoHistoryLoading(t *testing.T) {
+ ctx := context.Background()
+ eventLog := &executortest.MemoryEventLog{}
+
+ execID := "exec-completed"
+ agentID := "worker"
+
+ // Pre-populate event log with a COMPLETED execution for the same execID.
+ // defaultExecutor would short-circuit at executor.go:78 and return
+ // STATE_COMPLETED without calling the agent. agentExecutor must NOT
+ // do this — it should always invoke the agent.
+ eventLog.AllExecEvents = []*proto.ExecutionEvent{
+ {
+ ExecId: execID,
+ AgentId: agentID,
+ State: proto.State_STATE_PENDING,
+ Inputs: []*proto.Message{text("user", "old input")},
+ },
+ {
+ ExecId: execID,
+ AgentId: agentID,
+ Outputs: []*proto.Message{text("assistant", "old output")},
+ State: proto.State_STATE_PENDING,
+ },
+ {
+ ExecId: execID,
+ AgentId: agentID,
+ State: proto.State_STATE_COMPLETED,
+ },
+ }
+
+ var agentCalled atomic.Bool
+ registry := map[string]agent.Agent{
+ agentID: AgentFunc(func(inputs []*proto.Message, tm agent.Executor, o agent.OutputHandler) {
+ agentCalled.Store(true)
+ if o != nil {
+ o(&proto.AgentOutputs{
+ Messages: []*proto.Message{text("assistant", "fresh output")},
+ })
+ }
+ }),
+ }
+
+ ae := AgentExecutor(eventLog, registry)
+
+ var outputs []*proto.Message
+ state, err := ae.Exec(ctx, "conv-1", execID, &proto.AgentStart{
+ AgentId: agentID,
+ Messages: []*proto.Message{text("user", "new input")},
+ }, func(outgoing *proto.AgentOutputs) error {
+ outputs = append(outputs, outgoing.Messages...)
+ return nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+
+ if !agentCalled.Load() {
+ t.Fatal("agent was NOT called — agentExecutor must not short-circuit on COMPLETED history")
+ }
+ if state != proto.State_STATE_COMPLETED {
+ t.Fatalf("expected STATE_COMPLETED, got %v", state)
+ }
+ if len(outputs) != 1 {
+ t.Fatalf("expected 1 output, got %d", len(outputs))
+ }
+ if outputs[0].GetContent().GetText().GetText() != "fresh output" {
+ t.Fatalf("expected 'fresh output', got %v", outputs[0].GetContent().GetText().GetText())
+ }
+
+ // Also verify that defaultExecutor WOULD short-circuit for the same setup,
+ // confirming agentExecutor's behavior is intentionally different.
+ agentCalled.Store(false)
+ de := DefaultExecutor(eventLog, registry)
+ deState, err := de.Exec(ctx, "conv-1", execID, &proto.AgentStart{
+ AgentId: agentID,
+ Messages: []*proto.Message{text("user", "new input")},
+ }, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if deState != proto.State_STATE_COMPLETED {
+ t.Fatalf("defaultExecutor: expected STATE_COMPLETED, got %v", deState)
+ }
+ if agentCalled.Load() {
+ t.Fatal("defaultExecutor should have short-circuited but called the agent")
+ }
+}
+
+func TestAgentExecutor_AgentNotFound(t *testing.T) {
+ ctx := context.Background()
+ eventLog := &executortest.MemoryEventLog{}
+
+ ae := AgentExecutor(eventLog, map[string]agent.Agent{})
+ _, err := ae.Exec(ctx, "conv-1", "exec-1", &proto.AgentStart{
+ AgentId: "nonexistent",
+ Messages: []*proto.Message{text("user", "hi")},
+ }, nil)
+ if err == nil {
+ t.Fatal("expected error for missing agent, got nil")
+ }
+ if err.Error() != "no agent found: nonexistent" {
+ t.Fatalf("expected 'no agent found: nonexistent', got: %v", err)
+ }
+}
+
+func TestAgentExecutor_NilHandler(t *testing.T) {
+ ctx := context.Background()
+ eventLog := &executortest.MemoryEventLog{}
+
+ registry := map[string]agent.Agent{
+ "silent": AgentFunc(func(inputs []*proto.Message, tm agent.Executor, o agent.OutputHandler) {
+ if o != nil {
+ o(&proto.AgentOutputs{
+ Messages: []*proto.Message{text("assistant", "output")},
+ })
+ }
+ }),
+ }
+
+ ae := AgentExecutor(eventLog, registry)
+ state, err := ae.Exec(ctx, "conv-1", "exec-nil", &proto.AgentStart{
+ AgentId: "silent",
+ Messages: []*proto.Message{text("user", "hi")},
+ }, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if state != proto.State_STATE_COMPLETED {
+ t.Fatalf("expected STATE_COMPLETED with nil handler, got %v", state)
+ }
+}
+
+func TestAgentExecutor_NoOutputs(t *testing.T) {
+ ctx := context.Background()
+ eventLog := &executortest.MemoryEventLog{}
+
+ registry := map[string]agent.Agent{
+ "noop": AgentFunc(func(inputs []*proto.Message, tm agent.Executor, o agent.OutputHandler) {
+ // Agent does nothing, emits no outputs.
+ }),
+ }
+
+ ae := AgentExecutor(eventLog, registry)
+ state, err := ae.Exec(ctx, "conv-1", "exec-noop", &proto.AgentStart{
+ AgentId: "noop",
+ Messages: []*proto.Message{text("user", "hi")},
+ }, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ if state != proto.State_STATE_COMPLETED {
+ t.Fatalf("expected STATE_COMPLETED for no-output agent, got %v", state)
+ }
+
+ // Should have pending + completed events (no outputs event).
+ if len(eventLog.AllExecEvents) != 2 {
+ t.Fatalf("expected 2 exec events (pending, completed), got %d", len(eventLog.AllExecEvents))
+ }
+}
diff --git a/internal/controller/executor/executor.go b/internal/controller/executor/executor.go
index 6844725..b911ffb 100644
--- a/internal/controller/executor/executor.go
+++ b/internal/controller/executor/executor.go
@@ -48,14 +48,14 @@ func DefaultExecutor(eventLog EventLog, registry map[string]agent.Agent) agent.E
}
}
-func (tm *defaultExecutor) Exec(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error) {
- execID = newExecID(tm.execID, execID)
- a, ok := tm.registry[start.AgentId]
+func (de *defaultExecutor) Exec(ctx context.Context, conversationID string, execID string, start *proto.AgentStart, o agent.OutputHandler) (proto.State, error) {
+ execID = newExecID(de.execID, execID)
+ a, ok := de.registry[start.AgentId]
if !ok {
return proto.State_STATE_UNSPECIFIED, errors.New("no agent found")
}
- allInputs, state, earlierAgentID, err := history(ctx, tm.eventLog, execID)
+ allInputs, state, earlierAgentID, err := history(ctx, de.eventLog, execID)
if err != nil {
return proto.State_STATE_UNSPECIFIED, err
}
@@ -78,10 +78,10 @@ func (tm *defaultExecutor) Exec(ctx context.Context, conversationID string, exec
if state == proto.State_STATE_COMPLETED {
return proto.State_STATE_COMPLETED, nil
}
- return tm.exec(ctx, conversationID, execID, start, tm.eventLog, a, allInputs, o)
+ return de.exec(ctx, conversationID, execID, start, de.eventLog, a, allInputs, o)
}
-func (tm *defaultExecutor) exec(
+func (de *defaultExecutor) exec(
ctx context.Context,
conversationID string,
execID string,
@@ -90,10 +90,10 @@ func (tm *defaultExecutor) exec(
a agent.Agent,
history []*proto.Message,
o agent.OutputHandler) (proto.State, error) {
- child := &defaultExecutor{
+ child := &agentExecutor{
execID: execID,
- eventLog: tm.eventLog,
- registry: tm.registry,
+ eventLog: de.eventLog,
+ registry: de.registry,
}
var allOutputs []*proto.Message
diff --git a/internal/gemini/gemini_planner.go b/internal/gemini/gemini_planner.go
index 6c7b570..a9f9fcc 100644
--- a/internal/gemini/gemini_planner.go
+++ b/internal/gemini/gemini_planner.go
@@ -158,9 +158,15 @@ func (p *geminiPlannerAgent) loop(ctx context.Context, conversationID string, st
Messages: append(start.Messages, outputs...),
}
outputs = nil
- if _, err := e.Exec(ctx, conversationID, nextAgentID, start, outputCapturer); err != nil {
+ state, err := e.Exec(ctx, conversationID, nextAgentID, start, outputCapturer)
+ if err != nil {
return err
}
+ start.Messages = append(start.Messages, outputs...)
+ outputs = nil
+ if state == proto.State_STATE_PENDING {
+ return nil
+ }
}
}
@@ -214,7 +220,7 @@ func (p *geminiPlannerAgent) process(ctx context.Context, start *proto.AgentStar
if candidate.FinishReason == genai.FinishReasonStop {
return "", false, nil // No more tasks
}
- return "", false, fmt.Errorf("no content in candidates from Gemini")
+ return "", false, fmt.Errorf("no content in candidates from Gemini (reason: %v)", candidate.FinishReason)
}
// Look for function calls in the response