Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Update README (#199)
Jaana Dogan6e408be321d1
diff --git a/README.md b/README.mdindex 5ddb8d4..43ac99d 100644--- a/README.md+++ b/README.md@@ -3,15 +3,18 @@> [!WARNING]> π§ This project is in active development and may introduce breaking changes.-AX, a short for Agent eXecutor, is a single-writer agent orchestrator system built in Go. It provides a minimal runtime that coordinates agentic loops, manages executions with event logging, and communicates with both local and remote agents via streaming protocols.+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.## Features-- **Session Management**: Builtin event log management for starting, resuming, forking, and inspecting agentic loop executions+- **Distributed Runtime**: Controller, skills, tools, and agents can execute in isolation+- **Resumption**: Automatic recovery from failures or interruptions- **Local & Remote Agents**: Support for both in-process and remote agent deployment-- **Streaming**: gRPC bidirectional streaming for agent communication- **Tools and Skills**: Built-in bash tool and agent skills support-- **Registry**: Agent discovery+- **Registry**: Agent discovery and selectionBuilt-in consistency and resumability features:- **Single-Writer Architecture**: Centralized controller ensures consistent state management@@ -30,14 +33,15 @@ Built-in consistency and resumability features:ββββββββββββββββββββββββββ```-As agents move from simple interactions to "autonomous workers," most developers-will need what AX provides: a way to manage state, ensure reliability, and audit-the process through a structured event log. It is a "runtime" for agents in the same way-Kubernetes is a runtime for containers. AX is compute agnostic but aims to provide-the most comprehensive experience on Kubernetes.+As agents evolve from simple assistants to autonomous workers,+developers 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+workers becomes a necessity. AX provides the foundational layer to fill these gaps.-AX provides the plumbing so developers can focus on building agentic applications instead-of rebuilding the same infrastructure over and over again.+While compute-agnostic, AX is optimized to provide the best+experience on Kubernetes.## Installation@@ -68,33 +72,45 @@ agents and built-in tools already linked into the AX binary.# Using default ax.yamlax exec --input "Can you list me this directory?"-# Using a custom configuration-ax exec --input "Can you list me this directory?" --config my-config.yaml+# Using exec with an AX server+ax exec --input "Can you list me this directory?" --server localhost:8494```-You can continue a conversation any time:+Conversations can be continued any time:```bash-ax exec --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 --input "Show me the contents of README.md"+ax exec \+ --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \+ --input "Show me the contents of README.md"```You can continue from a previous sequence if client got disconnected-during an conversation. In this example, we skip seeing the events after+during a conversation. In this example, we skip seeing the events up tosequence number 12:+```bash-ax exec --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 --resume --last-seen-seq 12+ax exec \+ --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \+ --last-seen-seq 12 \+ --resume```-Instead of running the default planner agent, you can run any registered agent:+Instead of running the default planning step, you can start executing+from any registered agent:```bash-ax exec --agent coding --input "Can you write me a simple HTTP server in Python?"+ax exec \+ --agent coding \+ --input "Can you write me a simple HTTP server in Python?"```If anything goes wrong during the execution of an agent,you can resume an incomplete execution in a conversation:```bash-ax exec --resume --agent "coding" --conversation "edf98ef5-4bb1-4a9e-a091-3a77e03727e6"+ax exec \+ --conversation edf98ef5-4bb1-4a9e-a091-3a77e03727e6 \+ --agent "coding" \+ --resume```### 2. Run exec with Custom Agents@@ -129,7 +145,6 @@ The server exposes the `AXService` on port `:8494` by default.```bashax exec \--server localhost:8494 \- --conversation 550e8400-e29b-41d4-a716-446655440000 \--input "HELLO, CAN YOU LOWERCASE WHAT I JUST SAID?"```@@ -205,7 +220,6 @@ ax fork --src-id 38460323-9a78-41cb-8991-022b0ff2c19c --src-checkpoint "550e..."ax fork --src-id 38460323-9a78-41cb-8991-022b0ff2c19c --src-checkpoint "550e..." --dest-id e5e26e38-53a2-4f22-b1cb-ae867357df83```-### TraceVisualize the trace of an agentic execution in a Web UI, directly fetching from the SQLite event log.@@ -268,7 +282,6 @@ eventlog:sqlite:filename: "eventlog/log.sqlite"-planner:gemini:model: "gemini-3-flash-preview"@@ -308,19 +321,7 @@ ax serve --config my-config.yamlEvent logs use `ConversationEvent` and `ExecutionEvent` messages available in the proto fileto keep a log of conversations and executions.-## Built-in Capabilities--### Skills--AX includes built-in support for Agent Skills. See [Skills](docs/skills.md) for more.--### Bash Tool--The built-in planner is equipped with a `bash` tool that enables it to execute general-purpose shell commands. The tool automatically adapts to the user's operating system.--For safety and control, any execution initiated by the bash tool requires explicit user approval via a confirmation flow before running.--### Gemini Agent+## Gemini AgentAX includes a built-in Gemini agent that can be used to generate text based on a given prompt. The agent is registered as `gemini` and can be triggered as a standalone agent or used from custom agent implementations.@@ -344,13 +345,33 @@ export GCLOUD_LOCATION="us-central1"export GOOGLE_GENAI_USE_VERTEXAI=True```-## Building Custom Agents+## Extensions++### Skills++AX includes built-in support for Agent Skills. See [Skills](docs/skills.md) for more.++### Bash Tool++The built-in planner is equipped with a `bash` tool that enables+it to execute general-purpose shell commands. The tool automatically+adapts to the user's operating system.++For safety and control, any execution initiated by the bash tool+requires explicit user approval via a confirmation flow before running.++### Custom AgentsThere are several ways to register custom agents in AX by implementingthe `AXAgentService` 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.+* 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.## License