Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Wire up controller2 and harness by a build tag. (#33)
Junjie Wangb8d190f32c17
diff --git a/Makefile b/Makefileindex d4ba6bd..f638a9a 100644--- a/Makefile+++ b/Makefile@@ -1,4 +1,4 @@-.PHONY: all build proto test clean install install-ate images+.PHONY: all build build-harness proto test clean install install-harness install-ate images# Default container registry for dockerexport KO_DOCKER_REPO ?= gcr.io/ax-container-images@@ -15,6 +15,13 @@ build:@go build -o bin/remote_agent ./examples/remote_agent@echo "Build complete!"+# (Dev-only) Build ax with the `harness` build tag.+build-harness:+ @echo "Building ax (harness path)..."+ @mkdir -p bin+ @go build -tags harness -o bin/ax ./cmd/ax+ @echo "Build complete!"+# Generate protobuf codeproto:@echo "Generating protobuf code..."@@ -42,6 +49,12 @@ install:@go install ./cmd/ax@echo "Install complete!"+# Install ax with the `harness` build tag.+install-harness:+ @echo "Installing ax (harness path)..."+ @go install -tags harness ./cmd/ax+ @echo "Install complete!"+# Install ax with ATE support to GOPATH/bininstall-ate:@echo "Installing ax with ATE support..."@@ -70,6 +83,10 @@ ax-image:@echo "Building container image with ko..."GOFLAGS="-tags=ate" ko build --base-import-paths ./cmd/ax+ax-server-image:+ @echo "Building ax-server (harness path) container image with ko..."+ GOFLAGS="-tags=harness" ko build --base-import-paths ./cmd/ax+axepp-image:@echo "Building axepp container image with ko..."GOFLAGS="-tags=ate" ko build --base-import-paths ./cmd/axeppdiff --git a/cmd/ax/exec.go b/cmd/ax/exec.goindex 9d7fbc9..93ece37 100644--- a/cmd/ax/exec.go+++ b/cmd/ax/exec.go@@ -29,7 +29,6 @@ import ("github.com/google/ax/cmd/ax/internal""github.com/google/ax/cmd/ax/internal/cliutil"- "github.com/google/ax/internal/controller""github.com/google/ax/proto""github.com/google/uuid""github.com/spf13/cobra"@@ -68,14 +67,17 @@ func init() {// TODO(jbd): Add multimodal input flags, e.g. --input-image.var (- execController *controller.Controller+ // The concrete type depends on the build tag:+ // - Default: *controller.Controller+ // - With -tags harness: *controller2.Controller+ execController cliutil.Controller// interruptCount tracks consecutive Ctrl+C events to support exiting on double Ctrl+C.interruptCount int32// activeCancel stores the cancellation function for the currently in-flight request,// allowing a single Ctrl+C to cancel the active execution request rather than exiting the process.- activeCancel context.CancelFunc+ activeCancel context.CancelFunc// cancelMu protects activeCancel from concurrent access across goroutines.- cancelMu sync.Mutex+ cancelMu sync.Mutex)func runExec(cmd *cobra.Command, args []string) error {@@ -315,7 +317,7 @@ func runAutoExec(ctx context.Context, d *internal.Display, req *proto.ExecRequesfunc runExecHeadless(ctx context.Context, d *internal.Display, req *proto.ExecRequest) (*proto.ConfirmationContent, error) {var confirmation *proto.ConfirmationContentvar lastSeq int32- outputHandler := controller.ExecHandler(func(resp *proto.ExecResponse) error {+ outputHandler := cliutil.ExecHandler(func(resp *proto.ExecResponse) error {for _, m := range resp.Outputs {if conf := m.GetContent().GetConfirmation(); conf != nil {confirmation = confdiff --git a/cmd/ax/internal/cliutil/cliutil.go b/cmd/ax/internal/cliutil/cliutil.goindex 2183376..3f4cb99 100644--- a/cmd/ax/internal/cliutil/cliutil.go+++ b/cmd/ax/internal/cliutil/cliutil.go@@ -1,3 +1,5 @@+//go:build !harness+// Copyright 2026 Google LLC//// Licensed under the Apache License, Version 2.0 (the "License");@@ -26,6 +28,12 @@ import ("github.com/google/ax/internal/gemini")+// Controller is the active controller type for this build.+type Controller = *controller.Controller++// ExecHandler is the handler type accepted by Controller.Exec.+type ExecHandler = controller.ExecHandler+// NewControllerFromConfig creates a new Controller instance based on the provided configuration.func NewControllerFromConfig(ctx context.Context, cfg *config.Config) (*controller.Controller, error) {// Validate planner type earlydiff --git a/cmd/ax/internal/cliutil/cliutil_harness.go b/cmd/ax/internal/cliutil/cliutil_harness.gonew file mode 100644index 0000000..c1e5e19--- /dev/null+++ b/cmd/ax/internal/cliutil/cliutil_harness.go@@ -0,0 +1,40 @@+//go:build harness++// 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 cliutil++import (+ "context"++ "github.com/google/ax/internal/config"+ "github.com/google/ax/internal/controller/executor"+ "github.com/google/ax/internal/controller2"+)++// Controller is the active controller type for this build.+type Controller = *controller2.Controller++// ExecHandler is the handler type accepted by Controller.Exec.+type ExecHandler = controller2.ExecHandler++// NewControllerFromConfig creates a controller2.Controller.+func NewControllerFromConfig(ctx context.Context, cfg *config.Config) (*controller2.Controller, error) {+ return controller2.New(ctx, controller2.Config{+ EventLogBuilder: func() (executor.EventLog, error) {+ return executor.OpenSQLiteEventLog(cfg.EventLog.SQLiteConfig.Filename)+ },+ })+}diff --git a/cmd/ax/internal/cliutil/cliutil_test.go b/cmd/ax/internal/cliutil/cliutil_test.goindex 577e612..2b493f7 100644--- a/cmd/ax/internal/cliutil/cliutil_test.go+++ b/cmd/ax/internal/cliutil/cliutil_test.go@@ -1,3 +1,5 @@+//go:build !harness+// Copyright 2026 Google LLC//// Licensed under the Apache License, Version 2.0 (the "License");diff --git a/internal/server/server.go b/internal/server/server.goindex 57b7cd3..8a3bd4c 100644--- a/internal/server/server.go+++ b/internal/server/server.go@@ -1,3 +1,5 @@+//go:build !harness+// Copyright 2026 Google LLC//// Licensed under the Apache License, Version 2.0 (the "License");diff --git a/internal/server/server_ate.go b/internal/server/server_ate.goindex 6a7d003..c3b2c57 100644--- a/internal/server/server_ate.go+++ b/internal/server/server_ate.go@@ -1,4 +1,4 @@-//go:build ate+//go:build !harness && ate// Copyright 2026 Google LLC//diff --git a/internal/server/server_harness.go b/internal/server/server_harness.gonew file mode 100644index 0000000..2f43bab--- /dev/null+++ b/internal/server/server_harness.go@@ -0,0 +1,174 @@+//go:build harness++// 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 server implements the gRPC server for AXService,+// exposing execution management and agent registration APIs.++package server++import (+ "context"+ "fmt"+ "log/slog"+ "net"+ "sync"++ "google.golang.org/grpc"+ "google.golang.org/grpc/codes"+ "google.golang.org/grpc/health"+ "google.golang.org/grpc/health/grpc_health_v1"+ "google.golang.org/grpc/status"++ "github.com/google/ax/internal/controller2"+ "github.com/google/ax/proto"+)++// Server implements the AXService gRPC service.+type Server struct {+ proto.UnimplementedControllerServiceServer+ proto.UnimplementedConversationServiceServer++ controller *controller2.Controller+ grpcServer *grpc.Server+ inFlight map[string]struct{}+ inFlightMu sync.Mutex+}++// New creates a new controller server.+func New(c *controller2.Controller) *Server {+ return &Server{+ controller: c,+ inFlight: make(map[string]struct{}),+ }+}++// Exec executes a new agentic task with streaming responses.+func (s *Server) Exec(req *proto.ExecRequest, stream grpc.ServerStreamingServer[proto.ExecResponse]) error {+ ctx := stream.Context()+ slog.InfoContext(ctx, "Executing...",+ slog.String("conversation_id", req.ConversationId))++ inFlight, cleanup := s.markInFlight(req.ConversationId)+ if inFlight {+ return status.Errorf(codes.FailedPrecondition, "conversation %q is already in flight", req.ConversationId)+ }+ defer cleanup()++ outputHandler := controller2.ExecHandler(func(resp *proto.ExecResponse) error {+ return stream.Send(resp)+ })+ return s.controller.Exec(ctx, req, outputHandler)+}++func (s *Server) ForkConversation(ctx context.Context, req *proto.ForkConversationRequest) (*proto.ForkConversationResponse, error) {+ slog.InfoContext(ctx, "Forking conversation...",+ slog.String("src_conversation_id", req.SrcConversationId),+ slog.Int("src_seq", int(req.SrcSeq)),+ slog.String("dest_conversation_id", req.DestConversationId))++ if req.SrcConversationId == "" {+ return nil, status.Errorf(codes.InvalidArgument, "src_conversation_id is required")+ }+ // dest_conversation_id must be supplied by the caller: the substrate+ // router uses it to bring up the actor for the new conversation+ // before the request reaches this handler, so an empty value here+ // would mean no actor was provisioned.+ // TODO: consider relaxing this requirement.+ if req.DestConversationId == "" {+ return nil, status.Errorf(codes.InvalidArgument, "dest_conversation_id is required")+ }++ inFlight, cleanup := s.markInFlight(req.DestConversationId)+ if inFlight {+ return nil, status.Errorf(codes.FailedPrecondition, "conversation %q is already in flight", req.DestConversationId)+ }+ defer cleanup()++ destID, err := s.controller.Fork(ctx, req.SrcConversationId, req.SrcSeq, req.DestConversationId)+ if err != nil {+ return nil, status.Errorf(codes.Internal, "failed to fork conversation: %v", err)+ }+ return &proto.ForkConversationResponse{ConversationId: destID}, nil+}++func (s *Server) DeleteConversation(ctx context.Context, req *proto.DeleteConversationRequest) (*proto.DeleteConversationResponse, error) {+ slog.InfoContext(ctx, "Deleting conversation...",+ slog.String("conversation_id", req.ConversationId))++ if req.ConversationId == "" {+ return nil, status.Errorf(codes.InvalidArgument, "conversation_id is required")+ }+ inFlight, cleanup := s.markInFlight(req.ConversationId)+ if inFlight {+ return nil, status.Errorf(codes.FailedPrecondition, "conversation %q is already in flight", req.ConversationId)+ }+ defer cleanup()++ if err := s.controller.Delete(ctx, req.ConversationId); err != nil {+ return nil, status.Errorf(codes.Internal, "failed to delete conversation: %v", err)+ }+ return &proto.DeleteConversationResponse{}, nil+}++// Serve starts the gRPC server on the specified address.+func (s *Server) Serve(address string, opts ...grpc.ServerOption) error {+ lis, err := net.Listen("tcp", address)+ if err != nil {+ return fmt.Errorf("failed to listen: %w", err)+ }++ s.grpcServer = grpc.NewServer(opts...)+ proto.RegisterControllerServiceServer(s.grpcServer, s)+ proto.RegisterConversationServiceServer(s.grpcServer, s)++ // Register standard gRPC Health Check server.+ hs := health.NewServer()+ hs.SetServingStatus("AX", grpc_health_v1.HealthCheckResponse_SERVING)+ grpc_health_v1.RegisterHealthServer(s.grpcServer, hs)++ if err := s.grpcServer.Serve(lis); err != nil {+ return fmt.Errorf("failed to serve: %w", err)+ }+ return nil+}++// GracefulStop stops the gRPC server gracefully.+func (s *Server) GracefulStop() {+ slog.Info("Stopping server gracefully...")+ if s.controller != nil {+ s.controller.Close()+ }+ if s.grpcServer != nil {+ s.grpcServer.GracefulStop()+ }+}++func (s *Server) markInFlight(id string) (exists bool, cleanup func()) {+ s.inFlightMu.Lock()+ defer s.inFlightMu.Unlock()++ _, ok := s.inFlight[id]+ if ok {+ return true, func() {}+ }+ s.inFlight[id] = struct{}{}++ return false, func() {+ s.inFlightMu.Lock()+ delete(s.inFlight, id)+ s.inFlightMu.Unlock()+ }+}diff --git a/internal/server/server_harness_test.go b/internal/server/server_harness_test.gonew file mode 100644index 0000000..8bb71a1--- /dev/null+++ b/internal/server/server_harness_test.go@@ -0,0 +1,117 @@+//go:build harness++// 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 server++import (+ "context"+ "testing"++ "github.com/google/ax/internal/controller/executor"+ "github.com/google/ax/internal/controller/executor/executortest"+ "github.com/google/ax/internal/controller2"+ "github.com/google/ax/proto"+)++func TestServer_Fork(t *testing.T) {+ ctx := context.Background()+ srcCID := "src-conv"+ destCID := "dest-conv"++ log := &executortest.MemoryEventLog{}+ log.AllEvents = []*proto.ConversationEvent{+ {+ ConversationId: srcCID,+ Seq: 1,+ Messages: []*proto.Message{+ {Role: "user", Content: &proto.Content{Type: &proto.Content_Text{Text: &proto.TextContent{Text: "msg 1"}}}},+ },+ State: proto.State_STATE_COMPLETED,+ },+ }++ c, err := controller2.New(ctx, controller2.Config{+ EventLogBuilder: func() (executor.EventLog, error) {+ return log, nil+ },+ })+ if err != nil {+ t.Fatal(err)+ }+ defer c.Close()++ s := New(c)++ resp, err := s.ForkConversation(ctx, &proto.ForkConversationRequest{+ SrcConversationId: srcCID,+ DestConversationId: destCID,+ })+ if err != nil {+ t.Fatal(err)+ }++ if resp.ConversationId != destCID {+ t.Fatalf("expected destCID %s, got %s", destCID, resp.ConversationId)+ }++ events, err := log.Events(ctx, destCID)+ if err != nil {+ t.Fatal(err)+ }+ if len(events) != 1 {+ t.Fatalf("expected 1 event, got %d", len(events))+ }+}++// TestServer_Fork_RequiresDestID verifies that ForkConversation rejects+// a request without DestConversationId. The substrate router relies on+// the dest ID to bring up the conversation's actor before the handler+// runs, so we can't accept empty IDs at this layer.+func TestServer_Fork_RequiresDestID(t *testing.T) {+ ctx := context.Background()+ srcCID := "src-conv"++ log := &executortest.MemoryEventLog{}+ log.AllEvents = []*proto.ConversationEvent{+ {+ ConversationId: srcCID,+ Seq: 1,+ Messages: []*proto.Message{+ {Role: "user", Content: &proto.Content{Type: &proto.Content_Text{Text: &proto.TextContent{Text: "msg 1"}}}},+ },+ State: proto.State_STATE_COMPLETED,+ },+ }++ c, err := controller2.New(ctx, controller2.Config{+ EventLogBuilder: func() (executor.EventLog, error) {+ return log, nil+ },+ })+ if err != nil {+ t.Fatal(err)+ }+ defer c.Close()++ s := New(c)++ if _, err := s.ForkConversation(ctx, &proto.ForkConversationRequest{+ SrcConversationId: srcCID,+ // DestConversationId intentionally left empty.+ }); err == nil {+ t.Fatal("expected InvalidArgument when DestConversationId is empty, got nil")+ }+}diff --git a/internal/server/server_no_ate.go b/internal/server/server_no_ate.goindex 8885291..e239110 100644--- a/internal/server/server_no_ate.go+++ b/internal/server/server_no_ate.go@@ -1,4 +1,4 @@-//go:build !ate+//go:build !harness && !ate// Copyright 2026 Google LLC//diff --git a/internal/server/server_test.go b/internal/server/server_test.goindex db99fb7..09b3d28 100644--- a/internal/server/server_test.go+++ b/internal/server/server_test.go@@ -1,3 +1,5 @@+//go:build !harness+// Copyright 2026 Google LLC//// Licensed under the Apache License, Version 2.0 (the "License");