Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Update README and proto with more background (#247)
Jaana Dogan67b02d786549
diff --git a/README.md b/README.mdindex 58f7781..f03c17a 100644--- a/README.md+++ b/README.md@@ -1,24 +1,26 @@# Agent eXecutor (AX)> [!WARNING]-> π§ This project is in active development and may introduce breaking changes.+> π§ This project is in active development and WILL introduce breaking changes.AX, short for Agent eXecutor, is a distributed agent runtime. It provides aruntime that coordinates agentic loops, manages executions with event logging,-and communicates with both local and remote agents via streaming protocols.-AX knows how to resume and recover from failures, even in distributed fashion.+and communicates with both local and remote actors.+AX is designed for reliability, with native support for recovery+and execution resumption, even in complex distributed setups.## Features-- **Distributed Runtime**: Controller, skills, tools, and agents can execute in isolation+- **Distributed Runtime**: Controller, skills, tools, and agents can execute in isolation without having side effects on each other- **Resumption**: Automatic recovery from failures or interruptions-- **Local & Remote Agents**: Support for both in-process and remote agent deployment-- **Tools and Skills**: Built-in bash tool and agent skills support-- **Registry**: Agent discovery and selection+- **Skills, Tools, Agents**: Support for skill, tool, and agent selection and execution+- **Auditing and Policy**: All user and agentic calls are coordinated by a central controller, easy to control and audit the overall execution and skill/tool/agent calls+- **Built-in Capabilities**: Antigravity as the default harness, integrated Bash tool, and Gemini agent supportBuilt-in consistency and resumability features:- **Single-Writer Architecture**: Centralized controller ensures consistent state management- **Event Log**: Durable execution state with automatic recovery+- **Advanced Resumption**: Support for compute-layer actor resumption on compatible platforms## Overview@@ -28,13 +30,13 @@ Built-in consistency and resumability features:β - Executor β--(in process)---| local agent |β - Event Log β βββββββββββββββββ - Registry β ββββββββββββββββ-β - Local Agents β--(gRPC stream)--| remote agent |-β - Tools & Skills β ββββββββββββββββ+β - Tools β--(gRPC stream)--| remote agent |+β - Skills β ββββββββββββββββββββββββββββββββββββββββββ```-As agents evolve from simple assistants to autonomous workers,-developers need a robust runtime to manage state, ensure reliability,+As agents evolve from simple assistants to autonomous long running workers,+builders need a robust runtime to manage state, ensure reliability,and audit execution. As we are moving away from monolithic agents towardsdistributed harnesses where tools, skills and agents are deployed asisolated actors, a distributed runtime with dynamically spawned isolated@@ -43,6 +45,12 @@ workers becomes a necessity. AX provides the foundational layer to fill these gaWhile compute-agnostic, AX is optimized to provide the bestexperience on Kubernetes.+We expect every sophisticated agentic application will need the capabilities provided by AX.+We are building this layer as a general widely available foundation,+enabling builders to focus on building their applications rather than infrastructure.+We decided to build this project in public to validate every design decision before+a stable release is cut. We highly encourage you to give us feedback.+## InstallationInstall the ax CLI directly from the repository:@@ -63,7 +71,7 @@ You should see the ax CLI usage information.## Quick Start-### 1. Run exec+### 1. ExecuteThe CLI provides an easy way to execute by using theagents and built-in tools already linked into the AX binary.@@ -113,7 +121,7 @@ ax exec \--resume```-### 2. Run exec with Custom Agents+### 2. Execute with Custom AgentsMost developers want to build their own agents. AX allows running custom agents as remoteor sandbox agents. This example demonstrates how the AX server executes remote agents@@ -139,7 +147,7 @@ registry:ax serve```-The server exposes the `AXService` on port `:8494` by default.+The server exposes the service on port `:8494` by default.**Terminal 3** - Register the remote agent and execute:```bash@@ -351,16 +359,26 @@ requires explicit user approval via a confirmation flow before running.### Custom Agents-There are several ways to register custom agents in AX by implementing+Custom agents can be registered by implementingthe `AgentService` interface defined in `proto/ax.proto`:- [Remote Agent](docs/remote-agent.md)- [Kubernetes Sandbox Agents](docs/k8s-sandbox-agent.md)## What AX is NOT?-* An agentic framework, AX is agnostic of the framework used to build agents.+* An agentic framework, AX is agnostic of the framework used to build agents. We are working with+ framework authors (e.g. ADK) to provide built-in support for AX.* A container or job scheduler, we delegate it to the new capabilities in Kubernetes.* A specific harness like a coding agent, we allow bringing any harness as an agent.+* A model specific controller. AX is agnostic of the models used.++## Acknowledgements++We thank Google DeepMind for their earlier work in distributed harnesses and+their current work on Antigravity. AX is heavily influenced by this collobration+and the internal agentic stack we together have built for Google.+We thank the Google Kubernetes Engine team for their deep contributions and+insights regarding isolation, resumption and job scheduling.## Licensediff --git a/internal/testagent/proto/testagent.pb.go b/internal/testagent/proto/testagent.pb.goindex 1b8e2d7..c699cb9 100644--- a/internal/testagent/proto/testagent.pb.go+++ b/internal/testagent/proto/testagent.pb.go@@ -21,11 +21,12 @@package protoimport (- protoreflect "google.golang.org/protobuf/reflect/protoreflect"- protoimpl "google.golang.org/protobuf/runtime/protoimpl"reflect "reflect"sync "sync"unsafe "unsafe"++ protoreflect "google.golang.org/protobuf/reflect/protoreflect"+ protoimpl "google.golang.org/protobuf/runtime/protoimpl")const (diff --git a/proto/ax.pb.go b/proto/ax.pb.goindex c96436f..72fa7fd 100644--- a/proto/ax.pb.go+++ b/proto/ax.pb.go@@ -21,14 +21,15 @@package protoimport (+ reflect "reflect"+ sync "sync"+ unsafe "unsafe"+protoreflect "google.golang.org/protobuf/reflect/protoreflect"protoimpl "google.golang.org/protobuf/runtime/protoimpl"anypb "google.golang.org/protobuf/types/known/anypb"durationpb "google.golang.org/protobuf/types/known/durationpb"timestamppb "google.golang.org/protobuf/types/known/timestamppb"- reflect "reflect"- sync "sync"- unsafe "unsafe")const (diff --git a/proto/ax.proto b/proto/ax.protoindex 34fbe78..0e5c61d 100644--- a/proto/ax.proto+++ b/proto/ax.proto@@ -92,7 +92,13 @@ message HealthCheckResponse {string message = 2;}-// AgentService defines the gRPC service for agent communication+// AgentService defines the gRPC service for agent communication.+// This protocol enables a bidirectional communication between the+// controller and the agent. Agents can start new agentic calls via+// the controller within the same execution boundary by using the channel.+//+// WARNING: There will be significant changes to this protocol as+// we are solidifying resumption on the wire.service AgentService {// Connect is used by agents to connect to the controller.rpc Connect(stream AgentMessage) returns (stream AgentMessage);@@ -113,7 +119,7 @@ enum State {message ExecRequest {string conversation_id = 1; // Unique conversation identifierrepeated Message inputs = 2; // New inputs- int32 last_seq = 3; // Last sequence number seen by the client+ int32 last_seq = 3; // Last sequence number seen by the clientstring agent_id = 4; // Agent ID, if empty planner is usedgoogle.protobuf.Any agent_config = 5; // Agent configuration if anydiff --git a/proto/ax_grpc.pb.go b/proto/ax_grpc.pb.goindex f22eac3..51ee65b 100644--- a/proto/ax_grpc.pb.go+++ b/proto/ax_grpc.pb.go@@ -22,6 +22,7 @@ package protoimport (context "context"+grpc "google.golang.org/grpc"codes "google.golang.org/grpc/codes"status "google.golang.org/grpc/status"@@ -41,7 +42,13 @@ const (//// For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.//-// AgentService defines the gRPC service for agent communication+// AgentService defines the gRPC service for agent communication.+// This protocol enables a bidirectional communication between the+// controller and the agent. Agents can start new agentic calls via+// the controller within the same execution boundary by using the channel.+//+// WARNING: There will be significant changes to this protocol as+// we are solidifying resumption on the wire.type AgentServiceClient interface {// Connect is used by agents to connect to the controller.Connect(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[AgentMessage, AgentMessage], error)@@ -84,7 +91,13 @@ func (c *agentServiceClient) HealthCheck(ctx context.Context, in *HealthCheckReq// All implementations must embed UnimplementedAgentServiceServer// for forward compatibility.//-// AgentService defines the gRPC service for agent communication+// AgentService defines the gRPC service for agent communication.+// This protocol enables a bidirectional communication between the+// controller and the agent. Agents can start new agentic calls via+// the controller within the same execution boundary by using the channel.+//+// WARNING: There will be significant changes to this protocol as+// we are solidifying resumption on the wire.type AgentServiceServer interface {// Connect is used by agents to connect to the controller.Connect(grpc.BidiStreamingServer[AgentMessage, AgentMessage]) error@@ -101,10 +114,10 @@ type AgentServiceServer interface {type UnimplementedAgentServiceServer struct{}func (UnimplementedAgentServiceServer) Connect(grpc.BidiStreamingServer[AgentMessage, AgentMessage]) error {- return status.Error(codes.Unimplemented, "method Connect not implemented")+ return status.Errorf(codes.Unimplemented, "method Connect not implemented")}func (UnimplementedAgentServiceServer) HealthCheck(context.Context, *HealthCheckRequest) (*HealthCheckResponse, error) {- return nil, status.Error(codes.Unimplemented, "method HealthCheck not implemented")+ return nil, status.Errorf(codes.Unimplemented, "method HealthCheck not implemented")}func (UnimplementedAgentServiceServer) mustEmbedUnimplementedAgentServiceServer() {}func (UnimplementedAgentServiceServer) testEmbeddedByValue() {}@@ -117,7 +130,7 @@ type UnsafeAgentServiceServer interface {}func RegisterAgentServiceServer(s grpc.ServiceRegistrar, srv AgentServiceServer) {- // If the following call panics, it indicates UnimplementedAgentServiceServer was+ // If the following call pancis, it indicates UnimplementedAgentServiceServer was// embedded by pointer and is nil. This will cause panics if an// unimplemented method is ever invoked, so we test this at initialization// time to prevent it from happening at runtime later due to I/O.@@ -248,10 +261,10 @@ type ControllerServiceServer interface {type UnimplementedControllerServiceServer struct{}func (UnimplementedControllerServiceServer) Exec(*ExecRequest, grpc.ServerStreamingServer[ExecResponse]) error {- return status.Error(codes.Unimplemented, "method Exec not implemented")+ return status.Errorf(codes.Unimplemented, "method Exec not implemented")}func (UnimplementedControllerServiceServer) RegisterAgent(context.Context, *RegisterAgentRequest) (*RegisterAgentResponse, error) {- return nil, status.Error(codes.Unimplemented, "method RegisterAgent not implemented")+ return nil, status.Errorf(codes.Unimplemented, "method RegisterAgent not implemented")}func (UnimplementedControllerServiceServer) mustEmbedUnimplementedControllerServiceServer() {}func (UnimplementedControllerServiceServer) testEmbeddedByValue() {}@@ -264,7 +277,7 @@ type UnsafeControllerServiceServer interface {}func RegisterControllerServiceServer(s grpc.ServiceRegistrar, srv ControllerServiceServer) {- // If the following call panics, it indicates UnimplementedControllerServiceServer was+ // If the following call pancis, it indicates UnimplementedControllerServiceServer was// embedded by pointer and is nil. This will cause panics if an// unimplemented method is ever invoked, so we test this at initialization// time to prevent it from happening at runtime later due to I/O.@@ -404,13 +417,13 @@ type EventLogServiceServer interface {type UnimplementedEventLogServiceServer struct{}func (UnimplementedEventLogServiceServer) List(context.Context, *ListRequest) (*ListResponse, error) {- return nil, status.Error(codes.Unimplemented, "method List not implemented")+ return nil, status.Errorf(codes.Unimplemented, "method List not implemented")}func (UnimplementedEventLogServiceServer) Delete(context.Context, *DeleteRequest) (*DeleteResponse, error) {- return nil, status.Error(codes.Unimplemented, "method Delete not implemented")+ return nil, status.Errorf(codes.Unimplemented, "method Delete not implemented")}func (UnimplementedEventLogServiceServer) Fork(context.Context, *ForkRequest) (*ForkResponse, error) {- return nil, status.Error(codes.Unimplemented, "method Fork not implemented")+ return nil, status.Errorf(codes.Unimplemented, "method Fork not implemented")}func (UnimplementedEventLogServiceServer) mustEmbedUnimplementedEventLogServiceServer() {}func (UnimplementedEventLogServiceServer) testEmbeddedByValue() {}@@ -423,7 +436,7 @@ type UnsafeEventLogServiceServer interface {}func RegisterEventLogServiceServer(s grpc.ServiceRegistrar, srv EventLogServiceServer) {- // If the following call panics, it indicates UnimplementedEventLogServiceServer was+ // If the following call pancis, it indicates UnimplementedEventLogServiceServer was// embedded by pointer and is nil. This will cause panics if an// unimplemented method is ever invoked, so we test this at initialization// time to prevent it from happening at runtime later due to I/O.diff --git a/proto/content.pb.go b/proto/content.pb.goindex 42aa24a..100ab27 100644--- a/proto/content.pb.go+++ b/proto/content.pb.go@@ -21,12 +21,13 @@package protoimport (- protoreflect "google.golang.org/protobuf/reflect/protoreflect"- protoimpl "google.golang.org/protobuf/runtime/protoimpl"- structpb "google.golang.org/protobuf/types/known/structpb"reflect "reflect"sync "sync"unsafe "unsafe"++ protoreflect "google.golang.org/protobuf/reflect/protoreflect"+ protoimpl "google.golang.org/protobuf/runtime/protoimpl"+ structpb "google.golang.org/protobuf/types/known/structpb")const (