Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Rename AgentService to AXAgentService (#197)
Jaana Dogan8fe7e60e632b
diff --git a/README.md b/README.mdindex abf6c15..c8d3dfb 100644--- a/README.md+++ b/README.md@@ -101,13 +101,13 @@ ax exec --resume --agent "coding" --conversation "edf98ef5-4bb1-4a9e-a091-3a77e0Most 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-through the `AgentService.Process` RPC.+through the `AXAgentService.Connect` RPC.**Terminal 1** - Start the remote agent server:```bashgo run examples/remote_agent/main.go```-The remote agent runs as a gRPC server implementing `AgentService` on port `:50051`.+The remote agent runs as a gRPC server implementing `AXAgentService` on port `:50051`.**Terminal 2** - Start the AX controller server:```bash@@ -347,7 +347,7 @@ export GOOGLE_GENAI_USE_VERTEXAI=True## Building Custom AgentsThere are several ways to register custom agents in AX by implementing-the `AgentService` interface defined in `proto/ax.proto`:+the `AXAgentService` interface defined in `proto/ax.proto`:- [Remote Agent](docs/remote-agent.md)- [Kubernetes Sandbox Agents](docs/k8s-sandbox-agent.md)- [Remote Python Agent](docs/python-agent.md)diff --git a/docs/remote-agent.md b/docs/remote-agent.mdindex 78be611..57a2b3b 100644--- a/docs/remote-agent.md+++ b/docs/remote-agent.md@@ -1,6 +1,6 @@# Remote Agent-Remote agents run as gRPC servers implementing the `AgentService` interface defined in `proto/ax.proto`. The controller executes remote agents by calling their `Process` RPC with bidirectional streaming.+Remote agents run as gRPC servers implementing the `AXAgentService` interface defined in `proto/ax.proto`. The controller executes remote agents by calling their `Connect` RPC with bidirectional streaming.See `examples/remote_agent/main.go` for a complete implementation.@@ -8,7 +8,7 @@ See `examples/remote_agent/main.go` for a complete implementation.1. Remote agent starts as gRPC server on a port (e.g., :50051)2. Start the server: `ax serve`3. Register the agent: `ax register --agent-id my-agent --agent-name "My Agent" --agent-description "Agent description" --agent-addr localhost:50051`-4. When the server executes, it calls the agent's `Process` RPC+4. When the server executes, it calls the agent's `Connect` RPC5. AX streams input content → Agent processes → Agent streams output backSee `examples/remote_agent/main.go` for a complete implementation.diff --git a/examples/k8s_sandbox_agent/main.go b/examples/k8s_sandbox_agent/main.goindex e5861d9..ad8c098 100644--- a/examples/k8s_sandbox_agent/main.go+++ b/examples/k8s_sandbox_agent/main.go@@ -31,7 +31,7 @@ import ()type server struct {- proto.UnimplementedAgentServiceServer+ proto.UnimplementedAXAgentServiceServer}func (s *server) HealthCheck(ctx context.Context, req *proto.HealthCheckRequest) (*proto.HealthCheckResponse, error) {@@ -122,7 +122,7 @@ func main() {// 2. Create gRPC servers := grpc.NewServer()- proto.RegisterAgentServiceServer(s, &server{})+ proto.RegisterAXAgentServiceServer(s, &server{})reflection.Register(s)// 3. Graceful shutdown handlerdiff --git a/examples/remote_agent/main.go b/examples/remote_agent/main.goindex d8fdcb4..c61a186 100644--- a/examples/remote_agent/main.go+++ b/examples/remote_agent/main.go@@ -32,7 +32,7 @@ const port = ":50051"// server implements the AgentService gRPC server.type server struct {- proto.UnimplementedAgentServiceServer+ proto.UnimplementedAXAgentServiceServer}// Connect implements bidirectional streaming for agent processing.@@ -112,7 +112,7 @@ func main() {}grpcServer := grpc.NewServer()- proto.RegisterAgentServiceServer(grpcServer, &server{})+ proto.RegisterAXAgentServiceServer(grpcServer, &server{})fmt.Println("\nAgent server is running...")if err := grpcServer.Serve(lis); err != nil {diff --git a/internal/agent/remote.go b/internal/agent/remote.goindex e43530b..79b42df 100644--- a/internal/agent/remote.go+++ b/internal/agent/remote.go@@ -73,7 +73,7 @@ func (a *RemoteAgent) Connect(ctx context.Context, execID string, start *proto.A}defer conn.Close()- client := proto.NewAgentServiceClient(conn)+ client := proto.NewAXAgentServiceClient(conn)stream, err := client.Connect(ctx)if err != nil {return fmt.Errorf("failed to create stream: %w", err)@@ -134,7 +134,7 @@ func (a *RemoteAgent) HealthCheck(ctx context.Context) error {}defer conn.Close()- client := proto.NewAgentServiceClient(conn)+ client := proto.NewAXAgentServiceClient(conn)resp, err := client.HealthCheck(ctx, &proto.HealthCheckRequest{})if err != nil {return fmt.Errorf("health check failed: %w", err)diff --git a/internal/controller/registry_test.go b/internal/controller/registry_test.goindex 59fd78a..c970524 100644--- a/internal/controller/registry_test.go+++ b/internal/controller/registry_test.go@@ -29,7 +29,7 @@ import ()type mockAgentServer struct {- proto.UnimplementedAgentServiceServer+ proto.UnimplementedAXAgentServiceServerhealthy bool}@@ -43,7 +43,7 @@ func startMockGRPCServer(t *testing.T, healthy bool) (string, func()) {t.Fatalf("failed to listen: %v", err)}s := grpc.NewServer()- proto.RegisterAgentServiceServer(s, &mockAgentServer{healthy: healthy})+ proto.RegisterAXAgentServiceServer(s, &mockAgentServer{healthy: healthy})go func() {if err := s.Serve(lis); err != nil {// server might be closeddiff --git a/proto/ax.pb.go b/proto/ax.pb.goindex cb69358..3b4a70d 100644--- a/proto/ax.pb.go+++ b/proto/ax.pb.go@@ -1660,8 +1660,8 @@ const file_proto_ax_proto_rawDesc = "" +"\x11STATE_UNSPECIFIED\x10\x00\x12\x11\n" +"\rSTATE_PENDING\x10\x01\x12\x10\n" +"\fSTATE_FAILED\x10\x02\x12\x13\n" +- "\x0fSTATE_COMPLETED\x10\x032\x8d\x01\n" +- "\fAgentService\x127\n" ++ "\x0fSTATE_COMPLETED\x10\x032\x8f\x01\n" ++ "\x0eAXAgentService\x127\n" +"\aConnect\x12\x13.proto.AgentMessage\x1a\x13.proto.AgentMessage(\x010\x01\x12D\n" +"\vHealthCheck\x12\x19.proto.HealthCheckRequest\x1a\x1a.proto.HealthCheckResponse2\xbb\x01\n" +"\tAXService\x121\n" +@@ -1742,13 +1742,13 @@ var file_proto_ax_proto_depIdxs = []int32{24, // 24: proto.RegisterAgentRequest.metadata:type_name -> proto.RegisterAgentRequest.MetadataEntry20, // 25: proto.RegisterAgentRequest.remote:type_name -> proto.RemoteAgentConfig28, // 26: proto.GeminiConfig.timeout:type_name -> google.protobuf.Duration- 3, // 27: proto.AgentService.Connect:input_type -> proto.AgentMessage- 14, // 28: proto.AgentService.HealthCheck:input_type -> proto.HealthCheckRequest+ 3, // 27: proto.AXAgentService.Connect:input_type -> proto.AgentMessage+ 14, // 28: proto.AXAgentService.HealthCheck:input_type -> proto.HealthCheckRequest16, // 29: proto.AXService.Exec:input_type -> proto.ExecRequest18, // 30: proto.AXService.Fork:input_type -> proto.ForkRequest21, // 31: proto.AXService.RegisterAgent:input_type -> proto.RegisterAgentRequest- 3, // 32: proto.AgentService.Connect:output_type -> proto.AgentMessage- 15, // 33: proto.AgentService.HealthCheck:output_type -> proto.HealthCheckResponse+ 3, // 32: proto.AXAgentService.Connect:output_type -> proto.AgentMessage+ 15, // 33: proto.AXAgentService.HealthCheck:output_type -> proto.HealthCheckResponse17, // 34: proto.AXService.Exec:output_type -> proto.ExecResponse19, // 35: proto.AXService.Fork:output_type -> proto.ForkResponse22, // 36: proto.AXService.RegisterAgent:output_type -> proto.RegisterAgentResponsediff --git a/proto/ax.proto b/proto/ax.protoindex 1aa1e53..6d0d86b 100644--- a/proto/ax.proto+++ b/proto/ax.proto@@ -144,8 +144,8 @@ message HealthCheckResponse {string message = 2;}-// AgentService defines the gRPC service for agent communication-service AgentService {+// AXAgentService defines the gRPC service for agent communication+service AXAgentService {// Connect is used by agents to connect to the controller.rpc Connect(stream AgentMessage) returns (stream AgentMessage);diff --git a/proto/ax_grpc.pb.go b/proto/ax_grpc.pb.goindex d7c6c0e..a219543 100644--- a/proto/ax_grpc.pb.go+++ b/proto/ax_grpc.pb.go@@ -33,33 +33,33 @@ import (const _ = grpc.SupportPackageIsVersion9const (- AgentService_Connect_FullMethodName = "/proto.AgentService/Connect"- AgentService_HealthCheck_FullMethodName = "/proto.AgentService/HealthCheck"+ AXAgentService_Connect_FullMethodName = "/proto.AXAgentService/Connect"+ AXAgentService_HealthCheck_FullMethodName = "/proto.AXAgentService/HealthCheck")-// AgentServiceClient is the client API for AgentService service.+// AXAgentServiceClient is the client API for AXAgentService service.//// 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-type AgentServiceClient interface {+// AXAgentService defines the gRPC service for agent communication+type AXAgentServiceClient interface {// Connect is used by agents to connect to the controller.Connect(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[AgentMessage, AgentMessage], error)// HealthCheck checks if the agent is healthy and responsiveHealthCheck(ctx context.Context, in *HealthCheckRequest, opts ...grpc.CallOption) (*HealthCheckResponse, error)}-type agentServiceClient struct {+type aXAgentServiceClient struct {cc grpc.ClientConnInterface}-func NewAgentServiceClient(cc grpc.ClientConnInterface) AgentServiceClient {- return &agentServiceClient{cc}+func NewAXAgentServiceClient(cc grpc.ClientConnInterface) AXAgentServiceClient {+ return &aXAgentServiceClient{cc}}-func (c *agentServiceClient) Connect(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[AgentMessage, AgentMessage], error) {+func (c *aXAgentServiceClient) Connect(ctx context.Context, opts ...grpc.CallOption) (grpc.BidiStreamingClient[AgentMessage, AgentMessage], error) {cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)- stream, err := c.cc.NewStream(ctx, &AgentService_ServiceDesc.Streams[0], AgentService_Connect_FullMethodName, cOpts...)+ stream, err := c.cc.NewStream(ctx, &AXAgentService_ServiceDesc.Streams[0], AXAgentService_Connect_FullMethodName, cOpts...)if err != nil {return nil, err}@@ -68,106 +68,106 @@ func (c *agentServiceClient) Connect(ctx context.Context, opts ...grpc.CallOptio}// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.-type AgentService_ConnectClient = grpc.BidiStreamingClient[AgentMessage, AgentMessage]+type AXAgentService_ConnectClient = grpc.BidiStreamingClient[AgentMessage, AgentMessage]-func (c *agentServiceClient) HealthCheck(ctx context.Context, in *HealthCheckRequest, opts ...grpc.CallOption) (*HealthCheckResponse, error) {+func (c *aXAgentServiceClient) HealthCheck(ctx context.Context, in *HealthCheckRequest, opts ...grpc.CallOption) (*HealthCheckResponse, error) {cOpts := append([]grpc.CallOption{grpc.StaticMethod()}, opts...)out := new(HealthCheckResponse)- err := c.cc.Invoke(ctx, AgentService_HealthCheck_FullMethodName, in, out, cOpts...)+ err := c.cc.Invoke(ctx, AXAgentService_HealthCheck_FullMethodName, in, out, cOpts...)if err != nil {return nil, err}return out, nil}-// AgentServiceServer is the server API for AgentService service.-// All implementations must embed UnimplementedAgentServiceServer+// AXAgentServiceServer is the server API for AXAgentService service.+// All implementations must embed UnimplementedAXAgentServiceServer// for forward compatibility.//-// AgentService defines the gRPC service for agent communication-type AgentServiceServer interface {+// AXAgentService defines the gRPC service for agent communication+type AXAgentServiceServer interface {// Connect is used by agents to connect to the controller.Connect(grpc.BidiStreamingServer[AgentMessage, AgentMessage]) error// HealthCheck checks if the agent is healthy and responsiveHealthCheck(context.Context, *HealthCheckRequest) (*HealthCheckResponse, error)- mustEmbedUnimplementedAgentServiceServer()+ mustEmbedUnimplementedAXAgentServiceServer()}-// UnimplementedAgentServiceServer must be embedded to have+// UnimplementedAXAgentServiceServer must be embedded to have// forward compatible implementations.//// NOTE: this should be embedded by value instead of pointer to avoid a nil// pointer dereference when methods are called.-type UnimplementedAgentServiceServer struct{}+type UnimplementedAXAgentServiceServer struct{}-func (UnimplementedAgentServiceServer) Connect(grpc.BidiStreamingServer[AgentMessage, AgentMessage]) error {+func (UnimplementedAXAgentServiceServer) Connect(grpc.BidiStreamingServer[AgentMessage, AgentMessage]) error {return status.Errorf(codes.Unimplemented, "method Connect not implemented")}-func (UnimplementedAgentServiceServer) HealthCheck(context.Context, *HealthCheckRequest) (*HealthCheckResponse, error) {+func (UnimplementedAXAgentServiceServer) HealthCheck(context.Context, *HealthCheckRequest) (*HealthCheckResponse, error) {return nil, status.Errorf(codes.Unimplemented, "method HealthCheck not implemented")}-func (UnimplementedAgentServiceServer) mustEmbedUnimplementedAgentServiceServer() {}-func (UnimplementedAgentServiceServer) testEmbeddedByValue() {}+func (UnimplementedAXAgentServiceServer) mustEmbedUnimplementedAXAgentServiceServer() {}+func (UnimplementedAXAgentServiceServer) testEmbeddedByValue() {}-// UnsafeAgentServiceServer may be embedded to opt out of forward compatibility for this service.-// Use of this interface is not recommended, as added methods to AgentServiceServer will+// UnsafeAXAgentServiceServer may be embedded to opt out of forward compatibility for this service.+// Use of this interface is not recommended, as added methods to AXAgentServiceServer will// result in compilation errors.-type UnsafeAgentServiceServer interface {- mustEmbedUnimplementedAgentServiceServer()+type UnsafeAXAgentServiceServer interface {+ mustEmbedUnimplementedAXAgentServiceServer()}-func RegisterAgentServiceServer(s grpc.ServiceRegistrar, srv AgentServiceServer) {- // If the following call pancis, it indicates UnimplementedAgentServiceServer was+func RegisterAXAgentServiceServer(s grpc.ServiceRegistrar, srv AXAgentServiceServer) {+ // If the following call pancis, it indicates UnimplementedAXAgentServiceServer 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.if t, ok := srv.(interface{ testEmbeddedByValue() }); ok {t.testEmbeddedByValue()}- s.RegisterService(&AgentService_ServiceDesc, srv)+ s.RegisterService(&AXAgentService_ServiceDesc, srv)}-func _AgentService_Connect_Handler(srv interface{}, stream grpc.ServerStream) error {- return srv.(AgentServiceServer).Connect(&grpc.GenericServerStream[AgentMessage, AgentMessage]{ServerStream: stream})+func _AXAgentService_Connect_Handler(srv interface{}, stream grpc.ServerStream) error {+ return srv.(AXAgentServiceServer).Connect(&grpc.GenericServerStream[AgentMessage, AgentMessage]{ServerStream: stream})}// This type alias is provided for backwards compatibility with existing code that references the prior non-generic stream type by name.-type AgentService_ConnectServer = grpc.BidiStreamingServer[AgentMessage, AgentMessage]+type AXAgentService_ConnectServer = grpc.BidiStreamingServer[AgentMessage, AgentMessage]-func _AgentService_HealthCheck_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {+func _AXAgentService_HealthCheck_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {in := new(HealthCheckRequest)if err := dec(in); err != nil {return nil, err}if interceptor == nil {- return srv.(AgentServiceServer).HealthCheck(ctx, in)+ return srv.(AXAgentServiceServer).HealthCheck(ctx, in)}info := &grpc.UnaryServerInfo{Server: srv,- FullMethod: AgentService_HealthCheck_FullMethodName,+ FullMethod: AXAgentService_HealthCheck_FullMethodName,}handler := func(ctx context.Context, req interface{}) (interface{}, error) {- return srv.(AgentServiceServer).HealthCheck(ctx, req.(*HealthCheckRequest))+ return srv.(AXAgentServiceServer).HealthCheck(ctx, req.(*HealthCheckRequest))}return interceptor(ctx, in, info, handler)}-// AgentService_ServiceDesc is the grpc.ServiceDesc for AgentService service.+// AXAgentService_ServiceDesc is the grpc.ServiceDesc for AXAgentService service.// It's only intended for direct use with grpc.RegisterService,// and not to be introspected or modified (even as a copy)-var AgentService_ServiceDesc = grpc.ServiceDesc{- ServiceName: "proto.AgentService",- HandlerType: (*AgentServiceServer)(nil),+var AXAgentService_ServiceDesc = grpc.ServiceDesc{+ ServiceName: "proto.AXAgentService",+ HandlerType: (*AXAgentServiceServer)(nil),Methods: []grpc.MethodDesc{{MethodName: "HealthCheck",- Handler: _AgentService_HealthCheck_Handler,+ Handler: _AXAgentService_HealthCheck_Handler,},},Streams: []grpc.StreamDesc{{StreamName: "Connect",- Handler: _AgentService_Connect_Handler,+ Handler: _AXAgentService_Connect_Handler,ServerStreams: true,ClientStreams: true,},