Skip to content

armgit / ax

Public Imported from GitHub
0

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

Go

docs: add Substrate prerequisites; demo: fail early if Substrate missing (#399)

Aditya Shantanu98f4f2cebaf1
diff --git a/README.md b/README.md
index db113c5..22b385a 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,20 @@ Everything is expressed as `ax.io/v1alpha1` manifests and applied with a single
## Quick start
+### Prerequisites
+
+AX schedules every task as a sandboxed actor on [Agent Substrate](https://github.com/agent-substrate/substrate), so Substrate must be running in your cluster before you deploy AX. You need:
+
+- A Kubernetes cluster with **Agent Substrate** installed (see below)
+- [Go](https://go.dev/doc/install) and `kubectl`
+- [`ko`](https://ko.build/) (`brew install ko`) and a container registry your cluster can pull from
+
+To install Agent Substrate, follow the instructions in the [Substrate README](https://github.com/agent-substrate/substrate#readme). Substrate lands in the `ate-system` namespace and exposes its Control API at `api.ate-system.svc.cluster.local:443`, which is where AX expects to find it. Verify it is up before moving on:
+
+```bash
+kubectl get svc api -n ate-system
+```
+
### 1. Install the CLI
```bash
@@ -68,7 +82,7 @@ This puts the `ax` binary in `$(go env GOPATH)/bin`. Make sure that directory is
### 2. Deploy the control plane
-You need a Kubernetes cluster, [`ko`](https://ko.build/) (`brew install ko`), a container registry your cluster can pull from, and a reachable Agent Substrate Control API (in-cluster default: `api.ate-system.svc.cluster.local:443`).
+With the [prerequisites](#prerequisites) in place — most importantly a reachable Agent Substrate Control API — deploy the AX control plane:
```bash
make deploy AX_IMAGE_REPO=<your-registry>
diff --git a/demo.sh b/demo.sh
index b0b851f..a0cf6e2 100755
--- a/demo.sh
+++ b/demo.sh
@@ -21,13 +21,15 @@
# 4. Suspend the task, checkpointing its workspace.
#
# Environment:
-# AX_BIN path to the ax CLI (default: ./bin/ax)
-# ATESPACE atespace to run the demo in (default: default)
-# NO_COLOR set to disable colored output
+# AX_BIN path to the ax CLI (default: ./bin/ax)
+# ATESPACE atespace to run the demo in (default: default)
+# SUBSTRATE_NAMESPACE namespace Agent Substrate is installed in (default: ate-system)
+# NO_COLOR set to disable colored output
set -euo pipefail
AX_BIN="${AX_BIN:-./bin/ax}"
+SUBSTRATE_NAMESPACE="${SUBSTRATE_NAMESPACE:-ate-system}"
# ax runs the CLI at AX_BIN so the commands below read the way you would type them.
ax() { "${AX_BIN}" "$@"; }
@@ -112,6 +114,27 @@ wait_for() {
printf '\n%s🚀 AX demo%s %sworkspace=%s task=%s atespace=%s%s\n' \
"${BOLD}" "${RESET}" "${DIM}" "${WORKSPACE_NAME}" "${TASK_NAME}" "${ATESPACE}" "${RESET}"
+step "Preflight checks"
+if ! command -v "${AX_BIN}" >/dev/null 2>&1 && [[ ! -x "${AX_BIN}" ]]; then
+ err "ax CLI not found at '${AX_BIN}'. Build it with 'make build' or point AX_BIN at your binary."
+ exit 1
+fi
+ok "ax CLI found at ${AX_BIN}"
+if ! command -v kubectl >/dev/null 2>&1; then
+ err "kubectl not found. It is needed to verify that Agent Substrate is installed."
+ exit 1
+fi
+# AX schedules tasks as actors on Agent Substrate; without it every task
+# fails at actor creation. Check for its Control API before touching anything.
+if ! kubectl get svc api -n "${SUBSTRATE_NAMESPACE}" --request-timeout=10s >/dev/null 2>&1; then
+ err "Agent Substrate not detected: no 'api' Service in namespace '${SUBSTRATE_NAMESPACE}'."
+ note "Install Agent Substrate first — see the Prerequisites section of the AX README"
+ note "or https://github.com/agent-substrate/substrate. If it is installed in a"
+ note "different namespace, set SUBSTRATE_NAMESPACE."
+ exit 1
+fi
+ok "Agent Substrate Control API found in namespace ${SUBSTRATE_NAMESPACE}"
+
step "Clean up any previous demo run"
CLEANED=0
ax delete task "${TASK_NAME}" -a "${ATESPACE}" >/dev/null 2>&1 && { ok "removed old task"; CLEANED=1; } || true