Skip to content

armgit / ax

Public Imported from GitHub
0

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/Makefile
index 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 docker
export 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 code
proto:
@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/bin
install-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/axepp
diff --git a/cmd/ax/exec.go b/cmd/ax/exec.go
index 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.ExecReques
func runExecHeadless(ctx context.Context, d *internal.Display, req *proto.ExecRequest) (*proto.ConfirmationContent, error) {
var confirmation *proto.ConfirmationContent
var 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 = conf
diff --git a/cmd/ax/internal/cliutil/cliutil.go b/cmd/ax/internal/cliutil/cliutil.go
index 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 early
diff --git a/cmd/ax/internal/cliutil/cliutil_harness.go b/cmd/ax/internal/cliutil/cliutil_harness.go
new file mode 100644
index 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.go
index 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.go
index 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.go
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.go
index 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");