Skip to content

armgit / ax

Public Imported from GitHub
0

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.md
index 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 a
runtime 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 support
Built-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 towards
distributed harnesses where tools, skills and agents are deployed as
isolated actors, a distributed runtime with dynamically spawned isolated
@@ -43,6 +45,12 @@ workers becomes a necessity. AX provides the foundational layer to fill these ga
While compute-agnostic, AX is optimized to provide the best
experience 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.
+
## Installation
Install 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. Execute
The CLI provides an easy way to execute by using the
agents 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 Agents
Most developers want to build their own agents. AX allows running custom agents as remote
or 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 implementing
the `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.
## License
diff --git a/internal/testagent/proto/testagent.pb.go b/internal/testagent/proto/testagent.pb.go
index 1b8e2d7..c699cb9 100644
--- a/internal/testagent/proto/testagent.pb.go
+++ b/internal/testagent/proto/testagent.pb.go
@@ -21,11 +21,12 @@
package proto
import (
- 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.go
index c96436f..72fa7fd 100644
--- a/proto/ax.pb.go
+++ b/proto/ax.pb.go
@@ -21,14 +21,15 @@
package proto
import (
+ 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.proto
index 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 identifier
repeated 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 client
string agent_id = 4; // Agent ID, if empty planner is used
google.protobuf.Any agent_config = 5; // Agent configuration if any
diff --git a/proto/ax_grpc.pb.go b/proto/ax_grpc.pb.go
index f22eac3..51ee65b 100644
--- a/proto/ax_grpc.pb.go
+++ b/proto/ax_grpc.pb.go
@@ -22,6 +22,7 @@ package proto
import (
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.go
index 42aa24a..100ab27 100644
--- a/proto/content.pb.go
+++ b/proto/content.pb.go
@@ -21,12 +21,13 @@
package proto
import (
- 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 (