Skip to content

armgit / ax

Public Imported from GitHub
0

Agent Executor (AX) is Google's open agentic orchestration runtime

Go

Split out custom agents into their own pages (#139)

Jaana Doganb10de4c4d3d8
diff --git a/README.md b/README.md
index 59adfed..ed084b4 100644
--- a/README.md
+++ b/README.md
@@ -339,159 +339,9 @@ export GOOGLE_GENAI_USE_VERTEXAI=True
There are several ways to register custom agents in AX by implementing
the `AgentService` interface defined in `proto/ax.proto`:
-- Remote agents
-- GKE Sandbox agents
-
-### 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.
-
-See `examples/remote_agent/main.go` for a complete implementation.
-
-**Workflow:**
-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
-5. AX streams input content → Agent processes → Agent streams output back
-
-See `examples/remote_agent/main.go` for a complete implementation.
-
-### GKE Sandbox Agents
-
-AX supports dynamically provisioning secure, isolated agents on Google Kubernetes Engine (GKE) via the [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) feature. When an agent requires a Sandbox Agent, the AX server requests a temporary remote agent container in the cluster, establishes a secure connection locally (using port-forwarding via a proxy service), and cleans up the sandbox claim automatically upon closing.
-
-#### Prerequisites
-- A running Kubernetes cluster.
-- The [Agent Sandbox Controller](https://github.com/kubernetes-sigs/agent-sandbox?tab=readme-ov-file#installation) installed.
-- `kubectl` installed and configured locally.
-
-#### Setup: Deploying the Router
-Before using Sandbox Agents remotely and developing locally, you must deploy the `sandbox-router` into your cluster. This router proxies traffic securely to the isolated gVisor pods (direct port-forwarding to gVisor pods is not supported by Kubernetes due to netstack isolation).
-
-1. Cross-compile the proxy binary via Make and inject it into an Alpine Pod:
-```bash
-# Build the router for linux and copy it into the cluster
-make build-router
-kubectl apply -f cmd/sandbox-router/sandbox-router.yaml
-kubectl wait --for=condition=Ready pod -l app=sandbox-router --timeout=60s
-POD_NAME=$(kubectl get pods -l app=sandbox-router -o jsonpath='{.items[0].metadata.name}')
-kubectl cp sandbox-router $POD_NAME:/app/sandbox-router
-kubectl exec $POD_NAME -- touch /app/.done
-```
-
-2. Expose it as a service:
-```bash
-kubectl expose deployment sandbox-router --port=8080 --target-port=8080
-```
-
-To use a Sandbox Agent, specify it in your `ax.yaml` configuration:
-
-```yaml
-registry:
- k8s_sandbox_agents:
- - id: "my-sandbox-agent"
- name: "Sandbox Worker"
- description: "An ephemeral sandbox processor"
- sandbox_template_ref: "your-gke-sandbox-template-name"
- container_port: 8494
-```
-
-#### End-to-End Example (Uppercase Agent)
-
-AX provides a complete example of a Sandbox Agent in `examples/k8s_sandbox_agent/`. It receives text input via gRPC and returns the same text converted to uppercase.
-
-You can test this agent end-to-end using the `ax` binary, which exercises the full `SandboxAgent` lifecycle (provisioning, port-forwarding, and remote execution).
-
-**1. Build the Agent Image**
-
-From the root of the AX repository:
-```bash
-docker build -t ax-uppercase:latest -f examples/sandbox_agent/Dockerfile .
-```
-
-**2. Publish Image to Registry**
-
-When deploying to a cluster, you can host the agent container image in **any standard container registry** accessible by your Kubernetes cluster (e.g., Docker Hub, Google Artifact Registry, GitHub Container Registry).
-- For production, update the `image` field in `examples/k8s_sandbox_agent/sandbox-template-and-pool.yaml` to your full registry path.
-
-Once the image is available, register the SandboxTemplate:
-```bash
-kubectl apply -f examples/k8s_sandbox_agent/sandbox-template-and-pool.yaml
-```
-
-**3. Configure ax.yaml**
-Ensure your `ax.yaml` references this sandbox agent:
-```yaml
-registry:
- k8s_sandbox_agents:
- - id: "uppercase"
- sandbox_template_ref: "uppercase-agent-template"
- container_port: 8494
- use_router: true
-```
-
-**4. Run the Server**
-```bash
-ax serve --config ax.yaml
-```
-
-**5. Run the Agent**
-In a separate terminal:
-```bash
-ax exec --agent "uppercase" --input "hello world"
-```
-
-The system will dynamically create a `SandboxClaim`, establish a connection via `kubectl port-forward`, execute the code securely, and return the result.
-
-
-#### Viewing Sandbox Logs
-If you want to monitor the internal agent output or see if your gVisor sandbox received the physical gRPC requests:
-
-1. List the active sandbox Pods:
-```bash
-kubectl get pods -n default
-```
-
-2. Fetch the logs for your specific sandbox claim:
-```bash
-kubectl logs -f ax-claim-uppercase-<hash_id>
-```
-
-### Remote Python Agent
-
-AX is language agnostic and supports remote agents written in any language that can implement the `AgentService` interface. Python is a popular choice for AI agents, and AX provides first-class support for Python agents.
-
-To build a Python agent, first set up your environment by installing dependencies and generating the gRPC artifacts from the protobuf definitions:
-
-```bash
-# Install dependencies
-pip install grpcio grpcio-tools
-
-# Generate Python code from proto file
-python -m grpc_tools.protoc -I. --python_out=python --grpc_python_out=python proto/ax.proto
-```
-
-See `python/example_agent.py` for a complete implementation.
-
-**Register and use:**
-```bash
-# Start the Python agent
-python python/example_agent.py
-
-# Register the agent (in another terminal)
-ax register \
- --server localhost:8494 \
- --agent-id "echo-agent" \
- --agent-name "Echo Agent" \
- --agent-description "An agent that echoes the input." \
- --agent-addr localhost:50051
-
-ax exec \
- --server localhost:8494 \
- --id exec123 \
- --input "Hello, can you echo what I just said?"
-```
+- [Remote Agent](docs/remote-agent.md)
+- [Kubernetes Sandbox Agents](docs/k8s-sandbox-agent.md)
+- [Remote Python Agent](docs/python-agent.md)
## License
diff --git a/docs/k8s-sandbox-agent.md b/docs/k8s-sandbox-agent.md
new file mode 100644
index 0000000..1c9f61a
--- /dev/null
+++ b/docs/k8s-sandbox-agent.md
@@ -0,0 +1,100 @@
+# Kubernetes Sandbox Agents
+
+AX supports dynamically provisioning secure, isolated agents on Kubernetes via the [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) feature. When an agent requires a Sandbox Agent, the AX server requests a temporary remote agent container in the cluster, establishes a secure connection locally (using port-forwarding via a proxy service), and cleans up the sandbox claim automatically upon closing.
+
+## Prerequisites
+- A running Kubernetes cluster.
+- The [Agent Sandbox Controller](https://github.com/kubernetes-sigs/agent-sandbox?tab=readme-ov-file#installation) installed.
+- `kubectl` installed and configured locally.
+
+## Setup: Deploying the Router
+Before using Sandbox Agents remotely and developing locally, you must deploy the `sandbox-router` into your cluster. This router proxies traffic securely to the isolated gVisor pods (direct port-forwarding to gVisor pods is not supported by Kubernetes due to netstack isolation).
+
+1. Cross-compile the proxy binary via Make and inject it into an Alpine Pod:
+```bash
+# Build the router for linux and copy it into the cluster
+make build-router
+kubectl apply -f cmd/sandbox-router/sandbox-router.yaml
+kubectl wait --for=condition=Ready pod -l app=sandbox-router --timeout=60s
+POD_NAME=$(kubectl get pods -l app=sandbox-router -o jsonpath='{.items[0].metadata.name}')
+kubectl cp sandbox-router $POD_NAME:/app/sandbox-router
+kubectl exec $POD_NAME -- touch /app/.done
+```
+
+2. Expose it as a service:
+```bash
+kubectl expose deployment sandbox-router --port=8080 --target-port=8080
+```
+
+To use a Sandbox Agent, specify it in your `ax.yaml` configuration:
+
+```yaml
+registry:
+ k8s_sandbox_agents:
+ - id: "my-sandbox-agent"
+ name: "Sandbox Worker"
+ description: "An ephemeral sandbox processor"
+ sandbox_template_ref: "your-gke-sandbox-template-name"
+ container_port: 8494
+```
+
+## End-to-End Example (Uppercase Agent)
+
+AX provides a complete example of a Sandbox Agent in `examples/k8s_sandbox_agent/`. It receives text input via gRPC and returns the same text converted to uppercase.
+
+You can test this agent end-to-end using the `ax` binary, which exercises the full `SandboxAgent` lifecycle (provisioning, port-forwarding, and remote execution).
+
+**1. Build the Agent Image**
+
+From the root of the AX repository:
+```bash
+docker build -t ax-uppercase:latest -f examples/k8s_sandbox_agent/Dockerfile .
+```
+
+**2. Publish Image to Registry**
+
+When deploying to a cluster, you can host the agent container image in **any standard container registry** accessible by your Kubernetes cluster (e.g., Docker Hub, Google Artifact Registry, GitHub Container Registry).
+- For production, update the `image` field in `examples/k8s_sandbox_agent/sandbox-template-and-pool.yaml` to your full registry path.
+
+Once the image is available, register the SandboxTemplate:
+```bash
+kubectl apply -f examples/k8s_sandbox_agent/sandbox-template-and-pool.yaml
+```
+
+**3. Configure ax.yaml**
+Ensure your `ax.yaml` references this sandbox agent:
+```yaml
+registry:
+ k8s_sandbox_agents:
+ - id: "uppercase"
+ sandbox_template_ref: "uppercase-agent-template"
+ container_port: 8494
+ use_router: true
+```
+
+**4. Run the Server**
+```bash
+ax serve --config ax.yaml
+```
+
+**5. Run the Agent**
+In a separate terminal:
+```bash
+ax exec --agent "uppercase" --input "hello world"
+```
+
+The system will dynamically create a `SandboxClaim`, establish a connection via `kubectl port-forward`, execute the code securely, and return the result.
+
+
+## Viewing Sandbox Logs
+If you want to monitor the internal agent output or see if your gVisor sandbox received the physical gRPC requests:
+
+1. List the active sandbox Pods:
+```bash
+kubectl get pods -n default
+```
+
+2. Fetch the logs for your specific sandbox claim:
+```bash
+kubectl logs -f ax-claim-uppercase-<hash_id>
+```
diff --git a/docs/python-agent.md b/docs/python-agent.md
new file mode 100644
index 0000000..dd81405
--- /dev/null
+++ b/docs/python-agent.md
@@ -0,0 +1,34 @@
+# Remote Python Agent
+
+AX is language agnostic and supports remote agents written in any language that can implement the `AgentService` interface. Python is a popular choice for AI agents, and AX provides first-class support for Python agents.
+
+To build a Python agent, first set up your environment by installing dependencies and generating the gRPC artifacts from the protobuf definitions:
+
+```bash
+# Install dependencies
+pip install grpcio grpcio-tools
+
+# Generate Python code from proto file
+python -m grpc_tools.protoc -I. --python_out=python --grpc_python_out=python proto/ax.proto
+```
+
+See `python/example_agent.py` for a complete implementation.
+
+**Register and use:**
+```bash
+# Start the Python agent
+python python/example_agent.py
+
+# Register the agent (in another terminal)
+ax register \
+ --server localhost:8494 \
+ --agent-id "echo-agent" \
+ --agent-name "Echo Agent" \
+ --agent-description "An agent that echoes the input." \
+ --agent-addr localhost:50051
+
+ax exec \
+ --server localhost:8494 \
+ --id exec123 \
+ --input "Hello, can you echo what I just said?"
+```
diff --git a/docs/remote-agent.md b/docs/remote-agent.md
new file mode 100644
index 0000000..78be611
--- /dev/null
+++ b/docs/remote-agent.md
@@ -0,0 +1,14 @@
+# 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.
+
+See `examples/remote_agent/main.go` for a complete implementation.
+
+**Workflow:**
+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
+5. AX streams input content → Agent processes → Agent streams output back
+
+See `examples/remote_agent/main.go` for a complete implementation.
diff --git a/examples/gke_sandbox_agent/Dockerfile b/examples/k8s_sandbox_agent/Dockerfile
similarity index 100%
rename from examples/gke_sandbox_agent/Dockerfile
rename to examples/k8s_sandbox_agent/Dockerfile
diff --git a/examples/gke_sandbox_agent/main.go b/examples/k8s_sandbox_agent/main.go
similarity index 100%
rename from examples/gke_sandbox_agent/main.go
rename to examples/k8s_sandbox_agent/main.go
diff --git a/examples/gke_sandbox_agent/main_test.go b/examples/k8s_sandbox_agent/main_test.go
similarity index 100%
rename from examples/gke_sandbox_agent/main_test.go
rename to examples/k8s_sandbox_agent/main_test.go
diff --git a/examples/gke_sandbox_agent/sandbox-template-and-pool.yaml b/examples/k8s_sandbox_agent/sandbox-template-and-pool.yaml
similarity index 100%
rename from examples/gke_sandbox_agent/sandbox-template-and-pool.yaml
rename to examples/k8s_sandbox_agent/sandbox-template-and-pool.yaml