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.mdindex 59adfed..ed084b4 100644--- a/README.md+++ b/README.md@@ -339,159 +339,9 @@ export GOOGLE_GENAI_USE_VERTEXAI=TrueThere are several ways to register custom agents in AX by implementingthe `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)## Licensediff --git a/docs/k8s-sandbox-agent.md b/docs/k8s-sandbox-agent.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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/Dockerfilesimilarity index 100%rename from examples/gke_sandbox_agent/Dockerfilerename to examples/k8s_sandbox_agent/Dockerfilediff --git a/examples/gke_sandbox_agent/main.go b/examples/k8s_sandbox_agent/main.gosimilarity index 100%rename from examples/gke_sandbox_agent/main.gorename to examples/k8s_sandbox_agent/main.godiff --git a/examples/gke_sandbox_agent/main_test.go b/examples/k8s_sandbox_agent/main_test.gosimilarity index 100%rename from examples/gke_sandbox_agent/main_test.gorename to examples/k8s_sandbox_agent/main_test.godiff --git a/examples/gke_sandbox_agent/sandbox-template-and-pool.yaml b/examples/k8s_sandbox_agent/sandbox-template-and-pool.yamlsimilarity index 100%rename from examples/gke_sandbox_agent/sandbox-template-and-pool.yamlrename to examples/k8s_sandbox_agent/sandbox-template-and-pool.yaml