[AAASM-4838] 📝 (examples): Make crewai/langchain-research live-mode honest (was inert)

python/crewai-research-crew/README.md

@@ -44,8 +44,11 @@ audit event.
 | [uv](https://github.com/astral-sh/uv) | latest |
 | Agent Assembly Python SDK | >= 0.0.1rc6 |
 
-The mock demo needs no gateway, no `crewai`, and no API keys. The optional
-`live` extra (`crewai`) is only required for the real-crew integration.
+The mock demo needs no gateway, no `crewai`, and no API keys — and it is the
+only run mode this example implements (see "A real CrewAI integration is not
+shipped in this example" below). The optional `live` extra (`crewai`) is
+declared for a future real-crew integration but is not exercised by any code
+here.
 
 ## Setup
 
@@ -60,8 +63,10 @@ uv sync --extra dev
 uv run python src/main.py --mock
 ```
 
-`--mock` replays a scripted crew delegation trajectory offline. The example also
-auto-falls back to mock mode whenever `OPENAI_API_KEY` is unset.
+`--mock` replays a scripted crew delegation trajectory offline. This is the only
+run mode this example implements — running without `--mock` (with an
+`OPENAI_API_KEY` set) prints a notice that the live CrewAI integration is not
+implemented here and exits without doing anything.
 
 ### Expected governance output
 
@@ -146,24 +151,20 @@ event then records an `allow` decision.
 uv run pytest tests/ -v
 ```
 
-## Switching to the live CrewAI integration
+## A real CrewAI integration is not shipped in this example
 
-1. Install the live extra: `pip install -e '.[live]'` (pulls in `crewai`).
-2. Start an Agent Assembly gateway (or use your SaaS workspace URL).
-3. Copy `.env.example` to `.env` and fill in your credentials.
-4. Configure the approval gate and shared budget in the gateway.
-5. Run without `--mock` and with a real LLM provider key:
+This example is an **offline scripted governance demo** — it replays a fixed
+crew delegation trajectory so the governance wiring can be exercised
+deterministically, with no `crewai` install and no API keys. It does **not**
+drive a real CrewAI crew, and there is no runnable "live" mode: invoking it
+without `--mock` prints a notice to that effect and exits.
 
-```bash
-AGENT_ASSEMBLY_GATEWAY_URL=http://localhost:8080 \
-AGENT_ASSEMBLY_API_KEY=your-key \
-OPENAI_API_KEY=sk-your-real-key \
-uv run python src/main.py
-```
-
-In production, map each `CrewMember` onto a `crewai.Agent` and replace
-`CrewPolicyEngine` with the gateway-backed interceptor; the SDK enforces the
-gateway's policy and emits delegation-aware audit events automatically.
+Wiring a real crew is left as an integration exercise. Conceptually it means
+mapping each `CrewMember` onto a `crewai.Agent`, running the real crew, and
+replacing `CrewPolicyEngine` with the gateway-backed interceptor so the SDK
+enforces the gateway's policy and emits delegation-aware audit events
+automatically. That real loop is intentionally out of scope for this example
+gallery, so nothing here promises a live command that the code does not run.
 
 ## Links
 

python/crewai-research-crew/src/main.py

@@ -12,13 +12,17 @@
     - caps spend across all three agents at $2.00 / day (shared budget)
     - records every call as an AuditEvent with a delegation call stack
 
-Run (offline mock mode — no crewai, no API keys, what CI runs):
+This example is an *offline scripted* governance demo: it replays a fixed crew
+delegation trajectory (``MOCK_TRAJECTORY``) so the governance wiring can be
+exercised deterministically with no ``crewai`` install and no API keys. It does
+**not** drive a real CrewAI crew — there is no live LLM loop wired in here.
+Mapping each ``CrewMember`` onto a real ``crewai.Agent`` is left as an
+integration exercise (see the README); a non-mock invocation is therefore
+refused with a clear message rather than replaying the script mislabelled as
+"live".
+
+Run (what CI runs):
     uv run python src/main.py --mock
-
-For the live CrewAI integration:
-    pip install -e '.[live]'
-    OPENAI_API_KEY=sk-... AGENT_ASSEMBLY_GATEWAY_URL=http://localhost:8080 \\
-    uv run python src/main.py
 """
 from __future__ import annotations
 
@@ -74,7 +78,17 @@ def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
 
 def main(argv: list[str] | None = None) -> None:
     args = _parse_args(argv)
-    mock = args.mock or not os.environ.get("OPENAI_API_KEY")
+    # This example ships only the offline scripted trajectory — no real CrewAI
+    # crew is wired in. Refuse a live run plainly instead of replaying the
+    # script under a "live" label (the inert-live-mode bug this fixes).
+    if not args.mock and os.environ.get("OPENAI_API_KEY"):
+        print(
+            "Live CrewAI integration is not implemented in this example — it is "
+            "an offline scripted governance demo.\n"
+            "Re-run with --mock (or without OPENAI_API_KEY) to replay the crew "
+            "delegation trajectory."
+        )
+        return
 
     print("=" * 64)
     print("  Agent Assembly — CrewAI Multi-Agent Research Crew")
@@ -83,7 +97,7 @@ def main(argv: list[str] | None = None) -> None:
 
     gateway_url = os.environ.get("AGENT_ASSEMBLY_GATEWAY_URL", "http://localhost:8080")
     api_key = os.environ.get("AGENT_ASSEMBLY_API_KEY")
-    mode_label = "mock (offline)" if mock else "live"
+    mode_label = "mock (offline)"
 
     print(f"Initializing Agent Assembly (gateway: {gateway_url}, sdk-only mode)...")
 

python/langchain-research-agent/README.md

@@ -58,8 +58,10 @@ uv sync --extra dev
 uv run python src/main.py --mock
 ```
 
-`--mock` replays a scripted ReAct trajectory offline. The example also auto-falls
-back to mock mode whenever `OPENAI_API_KEY` is unset.
+`--mock` replays a scripted ReAct trajectory offline. This is the only run mode
+this example implements — running without `--mock` (with an `OPENAI_API_KEY`
+set) prints a notice that the live LangChain integration is not implemented here
+and exits without doing anything.
 
 ### Expected governance output
 
@@ -130,22 +132,21 @@ governance evidence a real gateway would persist server-side.
 uv run pytest tests/ -v
 ```
 
-## Switching to production mode
-
-1. Start an Agent Assembly gateway (or use your SaaS workspace URL).
-2. Copy `.env.example` to `.env` and fill in your credentials.
-3. Configure the balanced policy (allowlist / budget / redaction) in the gateway.
-4. Run without `--mock` and with a real LLM provider key:
-
-```bash
-AGENT_ASSEMBLY_GATEWAY_URL=http://localhost:8080 \
-AGENT_ASSEMBLY_API_KEY=your-key \
-OPENAI_API_KEY=sk-your-real-key \
-uv run python src/main.py
-```
-
-In production, replace `BalancedPolicyEngine` with the gateway-backed interceptor;
-the SDK enforces the policy rules configured in the gateway automatically.
+## A real LangChain integration is not shipped in this example
+
+This example is an **offline scripted governance demo** — it replays a fixed
+ReAct trajectory so the governance wiring can be exercised deterministically,
+with no API keys. It does **not** drive a real LangChain agent loop, and there
+is no runnable "live" mode: invoking it without `--mock` prints a notice to that
+effect and exits.
+
+Wiring a real agent is left as an integration exercise. Conceptually it means
+driving a real LangChain ReAct loop over the `web_search` and `calculator` tools
+with an LLM provider, and replacing `BalancedPolicyEngine` with the
+gateway-backed interceptor so the SDK enforces the policy rules configured in
+the gateway automatically. That real loop is intentionally out of scope for this
+example gallery, so nothing here promises a live command that the code does not
+run.
 
 ## Links
 

python/langchain-research-agent/src/main.py

@@ -14,12 +14,16 @@
 The run finishes with a deliberate credential-leak attempt using a SAFE FAKE
 key, which the policy blocks.
 
-Run (offline mock mode — no API keys, what CI runs):
+This example is an *offline scripted* governance demo: it replays a fixed ReAct
+trajectory (``_MOCK_REACT_STEPS``) so the governance wiring can be exercised
+deterministically with no API keys. It does **not** drive a real LangChain
+agent loop — no LLM provider is wired in here. Building a real ReAct loop over
+these tools is left as an integration exercise (see the README); a non-mock
+invocation is therefore refused with a clear message rather than replaying the
+script mislabelled as "live".
+
+Run (what CI runs):
     uv run python src/main.py --mock
-
-For production use, start the Agent Assembly gateway and drop ``--mock``:
-    AGENT_ASSEMBLY_GATEWAY_URL=http://localhost:8080 \\
-    OPENAI_API_KEY=sk-... uv run python src/main.py
 """
 from __future__ import annotations
 
@@ -87,8 +91,17 @@ def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
 
 def main(argv: list[str] | None = None) -> None:
     args = _parse_args(argv)
-    # No real LLM provider is wired in this example, so --mock is the only path.
-    mock = args.mock or not os.environ.get("OPENAI_API_KEY")
+    # No real LLM provider is wired in this example, so the scripted trajectory
+    # is the only path. Refuse a live run plainly instead of replaying the
+    # script under a "live" label (the inert-live-mode bug this fixes).
+    if not args.mock and os.environ.get("OPENAI_API_KEY"):
+        print(
+            "Live LangChain integration is not implemented in this example — it "
+            "is an offline scripted governance demo.\n"
+            "Re-run with --mock (or without OPENAI_API_KEY) to replay the ReAct "
+            "research trajectory."
+        )
+        return
 
     print("=" * 64)
     print("  Agent Assembly — LangChain ReAct Research Agent")
@@ -97,7 +110,7 @@ def main(argv: list[str] | None = None) -> None:
 
     gateway_url = os.environ.get("AGENT_ASSEMBLY_GATEWAY_URL", "http://localhost:8080")
     api_key = os.environ.get("AGENT_ASSEMBLY_API_KEY")
-    mode_label = "mock (offline)" if mock else "live"
+    mode_label = "mock (offline)"
 
     print(f"Initializing Agent Assembly (gateway: {gateway_url}, sdk-only mode)...")