From b6dd0e10d9baf787c5c3e2d7f37f21b12a28f508 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 18 Jul 2026 16:10:05 +0800 Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=93=9D=20(examples):=20De-fictionaliz?= =?UTF-8?q?e=20langchain-js=20real-provider=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The langchain-js-basic-agent README advertised a 'Real-provider mode' (cp .env.example, then pnpm start connects to a real gateway/OpenAI) and an impossible 'Gateway connection refused' troubleshooting row, but src/ reads no env vars — the offline fail-closed policy stub always runs. Replace with an honest offline-only note and drop the non-functional .env.example. Refs AAASM-4837 Co-Authored-By: Claude Opus 4.8 (1M context) --- node/langchain-js-basic-agent/.env.example | 8 -------- node/langchain-js-basic-agent/README.md | 18 ++++++++---------- 2 files changed, 8 insertions(+), 18 deletions(-) delete mode 100644 node/langchain-js-basic-agent/.env.example diff --git a/node/langchain-js-basic-agent/.env.example b/node/langchain-js-basic-agent/.env.example deleted file mode 100644 index 76410cee..00000000 --- a/node/langchain-js-basic-agent/.env.example +++ /dev/null @@ -1,8 +0,0 @@ -# Agent Assembly gateway (optional — omit to use offline/noop mode) -# AAASM_GATEWAY_URL=http://localhost:7391 - -# Agent Assembly API key (optional — required only when gateway auth is enabled) -# AAASM_API_KEY= - -# OpenAI API key (optional — only needed to switch to real-provider mode) -# OPENAI_API_KEY=sk-... diff --git a/node/langchain-js-basic-agent/README.md b/node/langchain-js-basic-agent/README.md index 5b30cdba..2ff1f101 100644 --- a/node/langchain-js-basic-agent/README.md +++ b/node/langchain-js-basic-agent/README.md @@ -73,23 +73,21 @@ Tests run in offline mode — no gateway or API keys required. pnpm typecheck ``` -## Real-provider mode (optional) +## Offline-only demo (no real-provider mode) -Copy `.env.example` to `.env` and fill in your values: - -```bash -cp .env.example .env -# Edit .env: set AAASM_GATEWAY_URL and optionally OPENAI_API_KEY -``` - -Then `pnpm start` will connect to the real gateway and real OpenAI API if configured. +This example runs **fully offline**. Tool calls are governed in-process by a +local fail-closed policy stub (`createPolicyGatewayClient` in `src/policy.ts`) — +no gateway, no API key, and no network are involved. The example reads **no** +environment variables: `AAASM_GATEWAY_URL`, `OPENAI_API_KEY`, and friends have +no effect here, so there is no "real-provider" mode to switch into. Wiring these +examples to a real gateway/LLM via the SDK's `initAssembly` is a possible future +enhancement, tracked separately — not current behavior. ## Troubleshooting | Problem | Solution | |---------|----------| | `Cannot find module '@agent-assembly/sdk'` | Run `pnpm install` | -| Gateway connection refused | Omit `AAASM_GATEWAY_URL` to use offline mode | | TypeScript errors | Run `pnpm typecheck` and check Node.js version | ## Links From e494ed99f064e0f5c284411fbcfd60161d69d640 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 18 Jul 2026 16:10:17 +0800 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=93=9D=20(examples):=20De-fictionaliz?= =?UTF-8?q?e=20openai-node=20real-provider=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Same fiction as langchain-js: a 'Real-provider mode' section and an impossible 'Gateway connection refused' troubleshooting row, while src/ reads no env vars. Replace with the honest offline-only note and drop the non-functional .env.example. (src/tools.ts is owned by AAASM-4846 and left untouched.) Refs AAASM-4837 Co-Authored-By: Claude Opus 4.8 (1M context) --- node/openai-node-tool-policy/.env.example | 8 -------- node/openai-node-tool-policy/README.md | 16 ++++++++-------- 2 files changed, 8 insertions(+), 16 deletions(-) delete mode 100644 node/openai-node-tool-policy/.env.example diff --git a/node/openai-node-tool-policy/.env.example b/node/openai-node-tool-policy/.env.example deleted file mode 100644 index 76410cee..00000000 --- a/node/openai-node-tool-policy/.env.example +++ /dev/null @@ -1,8 +0,0 @@ -# Agent Assembly gateway (optional — omit to use offline/noop mode) -# AAASM_GATEWAY_URL=http://localhost:7391 - -# Agent Assembly API key (optional — required only when gateway auth is enabled) -# AAASM_API_KEY= - -# OpenAI API key (optional — only needed to switch to real-provider mode) -# OPENAI_API_KEY=sk-... diff --git a/node/openai-node-tool-policy/README.md b/node/openai-node-tool-policy/README.md index 400ed5d7..1eb549e5 100644 --- a/node/openai-node-tool-policy/README.md +++ b/node/openai-node-tool-policy/README.md @@ -76,21 +76,21 @@ All tests run offline — no gateway or API key required. pnpm typecheck ``` -## Real-provider mode (optional) +## Offline-only demo (no real-provider mode) -Copy `.env.example` to `.env` and configure: - -```bash -cp .env.example .env -# Set AAASM_GATEWAY_URL and optionally OPENAI_API_KEY -``` +This example runs **fully offline**. Tool calls are governed in-process by a +local fail-closed policy stub (`createPolicyGatewayClient` in `src/policy.ts`) — +no gateway, no API key, and no network are involved. The example reads **no** +environment variables: `AAASM_GATEWAY_URL`, `OPENAI_API_KEY`, and friends have +no effect here, so there is no "real-provider" mode to switch into. Wiring these +examples to a real gateway/LLM via the SDK's `initAssembly` is a possible future +enhancement, tracked separately — not current behavior. ## Troubleshooting | Problem | Solution | |---------|----------| | `Cannot find module '@agent-assembly/sdk'` | Run `pnpm install` | -| Gateway connection refused | Remove `AAASM_GATEWAY_URL` from `.env` to use offline mode | | TypeScript errors | Run `pnpm typecheck` | ## Links From 07824fbb84e8a47a7e9a4e04519191e00d4e112e Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 18 Jul 2026 16:10:40 +0800 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=93=9D=20(examples):=20De-fictionaliz?= =?UTF-8?q?e=20langgraph-js=20env=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'Note on .env.example' told readers to set AAASM_GATEWAY_URL directly to connect to a real gateway, but src/ reads no env vars. Replace with the honest offline-only note and drop the non-functional .env.example. Refs AAASM-4837 Co-Authored-By: Claude Opus 4.8 (1M context) --- node/langgraph-js/.env.example | 8 -------- node/langgraph-js/README.md | 13 +++++++++---- 2 files changed, 9 insertions(+), 12 deletions(-) delete mode 100644 node/langgraph-js/.env.example diff --git a/node/langgraph-js/.env.example b/node/langgraph-js/.env.example deleted file mode 100644 index a5782a95..00000000 --- a/node/langgraph-js/.env.example +++ /dev/null @@ -1,8 +0,0 @@ -# Agent Assembly gateway (optional — omit to use offline/noop mode) -# AAASM_GATEWAY_URL=http://localhost:7391 - -# Agent Assembly API key (optional — required only when gateway auth is enabled) -# AAASM_API_KEY= - -# Provider key (optional — only needed to drive a real LLM inside graph nodes) -# OPENAI_API_KEY=sk-... diff --git a/node/langgraph-js/README.md b/node/langgraph-js/README.md index 071d7c10..711086ef 100644 --- a/node/langgraph-js/README.md +++ b/node/langgraph-js/README.md @@ -86,10 +86,15 @@ No gateway or API key required. All tests run offline. pnpm typecheck ``` -## Note on `.env.example` - -This example uses only mock/offline mode. No provider keys or gateway URL are needed. -To connect to a real gateway, set `AAASM_GATEWAY_URL` in your environment directly. +## Offline-only demo (no real-provider mode) + +This example runs **fully offline**. Tool calls are governed in-process by a +local fail-closed policy stub (`createPolicyGatewayClient` in `src/policy.ts`) — +no gateway, no API key, and no network are involved. The example reads **no** +environment variables: `AAASM_GATEWAY_URL`, `OPENAI_API_KEY`, and friends have +no effect here, so there is no "real-provider" mode to switch into. Wiring these +examples to a real gateway/LLM via the SDK's `initAssembly` is a possible future +enhancement, tracked separately — not current behavior. ## Troubleshooting From 60ddd8ee36f7456e73dbdfb87a3470d216cdc7a9 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 18 Jul 2026 16:10:40 +0800 Subject: [PATCH 4/6] =?UTF-8?q?=F0=9F=93=9D=20(examples):=20De-fictionaliz?= =?UTF-8?q?e=20mastra=20env=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'Note on .env.example' claimed setting AAASM_GATEWAY_URL / OPENAI_API_KEY would connect to a real gateway / drive a real LLM, but src/ reads no env vars. Replace with the honest offline-only note and drop the non-functional .env.example. Refs AAASM-4837 Co-Authored-By: Claude Opus 4.8 (1M context) --- node/mastra/.env.example | 8 -------- node/mastra/README.md | 14 +++++++++----- 2 files changed, 9 insertions(+), 13 deletions(-) delete mode 100644 node/mastra/.env.example diff --git a/node/mastra/.env.example b/node/mastra/.env.example deleted file mode 100644 index adb38536..00000000 --- a/node/mastra/.env.example +++ /dev/null @@ -1,8 +0,0 @@ -# Agent Assembly gateway (optional — omit to use offline/noop mode) -# AAASM_GATEWAY_URL=http://localhost:7391 - -# Agent Assembly API key (optional — required only when gateway auth is enabled) -# AAASM_API_KEY= - -# Provider key (optional — only needed to drive a real LLM with a Mastra Agent) -# OPENAI_API_KEY=sk-... diff --git a/node/mastra/README.md b/node/mastra/README.md index 807dad5b..310a9f7e 100644 --- a/node/mastra/README.md +++ b/node/mastra/README.md @@ -83,11 +83,15 @@ No gateway or API key required. All tests run offline. pnpm typecheck ``` -## Note on `.env.example` - -This example uses only mock/offline mode. No provider keys or gateway URL are needed. -To connect to a real gateway, set `AAASM_GATEWAY_URL` in your environment directly; to -drive a real LLM with a Mastra Agent, set `OPENAI_API_KEY`. +## Offline-only demo (no real-provider mode) + +This example runs **fully offline**. Tool calls are governed in-process by a +local fail-closed policy stub (`createPolicyGatewayClient` in `src/policy.ts`) — +no gateway, no API key, and no network are involved. The example reads **no** +environment variables: `AAASM_GATEWAY_URL`, `OPENAI_API_KEY`, and friends have +no effect here, so there is no "real-provider" mode to switch into. Wiring these +examples to a real gateway/LLM via the SDK's `initAssembly` is a possible future +enhancement, tracked separately — not current behavior. ## Troubleshooting From 89e0f227d9f3bf1a006bbf32afaa2b6bc3656a82 Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 18 Jul 2026 16:10:40 +0800 Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=93=9D=20(examples):=20De-fictionaliz?= =?UTF-8?q?e=20vercel-ai=20env=20guidance?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'Note on .env.example' claimed setting AAASM_GATEWAY_URL / OPENAI_API_KEY would connect to a real gateway / drive a real LLM, but src/ reads no env vars. Replace with the honest offline-only note and drop the non-functional .env.example. Refs AAASM-4837 Co-Authored-By: Claude Opus 4.8 (1M context) --- node/vercel-ai/.env.example | 8 -------- node/vercel-ai/README.md | 14 +++++++++----- 2 files changed, 9 insertions(+), 13 deletions(-) delete mode 100644 node/vercel-ai/.env.example diff --git a/node/vercel-ai/.env.example b/node/vercel-ai/.env.example deleted file mode 100644 index 7d0bdac3..00000000 --- a/node/vercel-ai/.env.example +++ /dev/null @@ -1,8 +0,0 @@ -# Agent Assembly gateway (optional — omit to use offline/noop mode) -# AAASM_GATEWAY_URL=http://localhost:7391 - -# Agent Assembly API key (optional — required only when gateway auth is enabled) -# AAASM_API_KEY= - -# Provider key (optional — only needed to drive a real LLM with the Vercel AI SDK) -# OPENAI_API_KEY=sk-... diff --git a/node/vercel-ai/README.md b/node/vercel-ai/README.md index f12e90a0..a56065e3 100644 --- a/node/vercel-ai/README.md +++ b/node/vercel-ai/README.md @@ -82,11 +82,15 @@ No gateway or API key required. All tests run offline. pnpm typecheck ``` -## Note on `.env.example` - -This example uses only mock/offline mode. No provider keys or gateway URL are needed. -To connect to a real gateway, set `AAASM_GATEWAY_URL` in your environment directly; to -drive a real LLM, set `OPENAI_API_KEY`. +## Offline-only demo (no real-provider mode) + +This example runs **fully offline**. Tool calls are governed in-process by a +local fail-closed policy stub (`createPolicyGatewayClient` in `src/policy.ts`) — +no gateway, no API key, and no network are involved. The example reads **no** +environment variables: `AAASM_GATEWAY_URL`, `OPENAI_API_KEY`, and friends have +no effect here, so there is no "real-provider" mode to switch into. Wiring these +examples to a real gateway/LLM via the SDK's `initAssembly` is a possible future +enhancement, tracked separately — not current behavior. ## Troubleshooting From 7c617bc683a812e0fcf30cd3882e0bdcb06c477c Mon Sep 17 00:00:00 2001 From: Chisanan232 Date: Sat, 18 Jul 2026 16:10:40 +0800 Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=93=9D=20(examples):=20Fix=20custom-t?= =?UTF-8?q?ool-policy=20dangling=20.env.example=20ref?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The 'Note on .env.example' referenced a .env.example that never existed in this directory and claimed AAASM_GATEWAY_URL would connect to a real gateway, but src/ reads no env vars. Replace with the honest offline-only note (drop the dangling reference rather than create a non-functional file). Refs AAASM-4837 Co-Authored-By: Claude Opus 4.8 (1M context) --- node/custom-tool-policy/README.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/node/custom-tool-policy/README.md b/node/custom-tool-policy/README.md index de2ee0c6..dbc39bbd 100644 --- a/node/custom-tool-policy/README.md +++ b/node/custom-tool-policy/README.md @@ -75,9 +75,15 @@ No gateway or API key required. All tests run offline. pnpm typecheck ``` -## Note on `.env.example` - -This example uses only mock/offline mode. No provider keys or gateway URL are needed. To connect to a real gateway, set `AAASM_GATEWAY_URL` in your environment directly. +## Offline-only demo (no real-provider mode) + +This example runs **fully offline**. Tool calls are governed in-process by a +local fail-closed policy stub (`createPolicyGatewayClient` in `src/policy.ts`) — +no gateway, no API key, and no network are involved. The example reads **no** +environment variables: `AAASM_GATEWAY_URL`, `OPENAI_API_KEY`, and friends have +no effect here, so there is no "real-provider" mode to switch into. Wiring these +examples to a real gateway/LLM via the SDK's `initAssembly` is a possible future +enhancement, tracked separately — not current behavior. ## Troubleshooting