From e237c22c86fc89c5abbb446855941b7a1d93b283 Mon Sep 17 00:00:00 2001 From: Bryant Date: Sun, 19 Jul 2026 11:05:15 +0800 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Promote=20AA=5F*?= =?UTF-8?q?=20env=20vars=20as=20canonical=20in=20configuration?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document AA_GATEWAY_URL / AA_API_KEY as the canonical resolver env vars (gateway_resolver.py:53-54), keeping AAASM_* only as a deprecated alias that now emits a DeprecationWarning. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/configuration.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/configuration.md b/docs/configuration.md index 6e58fda3..3e75b5ba 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -45,7 +45,9 @@ When `gateway_url` / `api_key` are not passed explicitly, the SDK resolves each fallback chain (see `agent_assembly.core.gateway_resolver`): 1. **Explicit argument** — the value you pass to `init_assembly()`. -2. **Environment variable** — `AAASM_GATEWAY_URL` / `AAASM_API_KEY`. +2. **Environment variable** — `AA_GATEWAY_URL` / `AA_API_KEY`. (The legacy + `AAASM_GATEWAY_URL` / `AAASM_API_KEY` names still resolve but emit a + `DeprecationWarning` — prefer the `AA_*` names.) 3. **Config file** — `~/.aasm/config.yaml`. 4. **Local default** — probe `http://localhost:7391/healthz`; if no gateway is running, the SDK attempts to **auto-start** a local one (`aasm start --mode local --foreground`). @@ -71,8 +73,8 @@ For the full gateway configuration surface (policy files, budgets, mTLS) and the [CLI reference](https://docs.agent-assembly.com/core/latest/cli/overview.html) docs. ```bash -export AAASM_GATEWAY_URL="https://gateway.example.com" -export AAASM_API_KEY="…" +export AA_GATEWAY_URL="https://gateway.example.com" +export AA_API_KEY="…" ``` ### Config file format From f256f1d5dc8562cbbe55d5e4290d411551431937 Mon Sep 17 00:00:00 2001 From: Bryant Date: Sun, 19 Jul 2026 11:05:17 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Use=20canonical=20?= =?UTF-8?q?AA=5F*=20env=20vars=20in=20troubleshooting?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/troubleshooting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 194ff924..0278cbcc 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -11,7 +11,7 @@ safe. | Message | Cause | Fix | | --- | --- | --- | -| `gateway_url is required` | No gateway URL could be resolved (no argument, no `AAASM_GATEWAY_URL`, no config file, no local gateway). | Pass `gateway_url=...`, set `AAASM_GATEWAY_URL`, or start a local gateway. See [Configuration](configuration.md#resolution-order). | +| `gateway_url is required` | No gateway URL could be resolved (no argument, no `AA_GATEWAY_URL`, no config file, no local gateway). | Pass `gateway_url=...`, set `AA_GATEWAY_URL`, or start a local gateway. See [Configuration](configuration.md#resolution-order). | | `mode must be one of: auto, ebpf, proxy, sdk-only` | An unknown `mode` value. | Use one of the four valid modes. | | `enforcement_mode must be one of: enforce, observe, disabled` | An unknown `enforcement_mode`. | Use a valid posture or leave it `None`. | | `eBPF mode is not supported on this platform.` | `mode="ebpf"` on a non-Linux host. | Use `mode="sdk-only"` or `mode="proxy"` off Linux. | @@ -24,7 +24,7 @@ network layer but the gateway didn't answer. - Confirm the gateway is running and the URL is correct — by default the SDK probes `http://localhost:7391/healthz`. -- Check `AAASM_GATEWAY_URL` / `AAASM_API_KEY` aren't pointing somewhere stale. +- Check `AA_GATEWAY_URL` / `AA_API_KEY` (or the deprecated `AAASM_*` aliases) aren't pointing somewhere stale. - For a quick local loop, run an `aasm` gateway yourself, or let the SDK auto-start one (`aasm start --mode local --foreground`). If auto-start fails, ensure the `aasm` binary is on `PATH` — install it via the `agent-assembly[runtime]` extra or the Homebrew tap. From 734b5089f2153ca52ae425c7024c79e97f06dd09 Mon Sep 17 00:00:00 2001 From: Bryant Date: Sun, 19 Jul 2026 11:05:19 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=F0=9F=93=9D=20(docs):=20Fix=20AASM=5F*=20t?= =?UTF-8?q?ypo=20to=20AA=5F*=20in=20runtime=20env=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The resolver reads AA_GATEWAY_URL / AA_API_KEY; the AASM_* name in this paragraph exists nowhere in the code. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/examples/preparing-the-runtime-environment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/examples/preparing-the-runtime-environment.md b/docs/examples/preparing-the-runtime-environment.md index 5a8c1306..292b48d8 100644 --- a/docs/examples/preparing-the-runtime-environment.md +++ b/docs/examples/preparing-the-runtime-environment.md @@ -124,7 +124,7 @@ uv run python src/main.py The examples pass `gateway_url` / `api_key` **explicitly** to `init_assembly()`, reading them from the `AGENT_ASSEMBLY_*` variables shown above and defaulting to `http://localhost:8080`. The SDK *itself* has a separate built-in resolver chain that, - when you **omit** those arguments, reads `AASM_GATEWAY_URL` / `AASM_API_KEY`, then + when you **omit** those arguments, reads `AA_GATEWAY_URL` / `AA_API_KEY`, then `~/.aasm/config.yaml`, then probes a local gateway on `http://localhost:7391`. See [Configuration](../configuration.md#resolution-order) for that resolver. The examples use explicit arguments, so they use the `AGENT_ASSEMBLY_*` names and the `:8080` default —