framework: strands-python / strands-node — persistent subprocess runner (stdio JSON-RPC)

[initializ-mk]

Summary

Add `framework: strands` as a known value in `forge.yaml`. At startup, Forge spawns a persistent Python subprocess (the Strands runner) and routes A2A `tasks/send` to it via stdio JSON-RPC. Forge keeps owning the trust shell — auth, audit, egress, guardrails, OTel tracer install, platform policy — while Strands owns the executor loop, model providers, tool definitions, and multi-agent patterns.

Builds on the #182/#183 plumbing (W3C trace propagation + binary skill runtime + curated OTEL_* passthrough). Same env-injection pattern, just at process startup instead of per-skill-call.

Design

Transport: stdio JSON-RPC (MCP-style)

Newline-delimited JSON-RPC 2.0 over the runner's stdin/stdout. Same framing Forge already speaks for MCP stdio servers — no new ports, no UDS path management, supervisor reuses MCP's client-side code patterns.

Methods Forge calls on the runner:

Method	Purpose
`invoke`	One A2A `tasks/send` → one invoke. Params carry `prompt`, `session_id`, `traceparent` header (per-request — env-injection only fires at fork time).
`healthz`	Periodic liveness probe.
`shutdown`	Graceful drain before SIGTERM.

Server-pushed notifications (runner → Forge):

Method	Purpose
`ready`	Signal that the runner has built its Strands Agent and is accepting invokes. Forge blocks A2A from listening until this lands.
`audit`	Audit event from inside the Strands loop (LLM call, tool call, guardrail decision). Forge translates to AuditEvent and emits through its existing sink stack.
`stream_token`	SSE-equivalent token delta for `tasks/sendSubscribe`.

Lifecycle (Forge supervises)

• Startup: spawn with full env (HTTP_PROXY, OTEL_* curated allowlist, FORGE_AUDIT_SOCKET, FORGE_AGENT_ID, skill-declared secrets). Wait up to `framework.strands.startup_timeout` (default 30s) for `ready` notification.
• Per-request: open `a2a.` → `strands.bridge.invoke` span. Inject `traceparent` into the invoke message params; the runner's OTel SDK extracts on receive. Strands' own `llm.completion` / `tool.` spans nest correctly.
• Audit: runner emits notifications; Forge stamps `correlation_id` + `task_id` + `seq` from the active invoke and emits through `EmitFromContext` so the audit stream looks identical to a Go-runtime invocation.
• Health: periodic `healthz` (default 30s); miss surfaces in `agent_card_published` if still down at hot-reload time.
• Crash recovery: exponential backoff restart (100ms → 5s cap, mirrors the audit socket sink pattern). Emit `framework_runner_crashed` audit event. In-flight invokes fail-fast with a typed error.
• Hot reload: file-watcher fires on `agent.py` change → drain in-flight → restart → wait for `ready` → resume.
• Shutdown: SIGTERM, wait for drain up to `framework.strands.drain_timeout` (default 10s), then SIGKILL.

forge.yaml

```yaml
framework: strands
strands:
runner_command: ["python3", "-m", "forge_strands_runner"]
startup_timeout: 30s
drain_timeout: 10s
health_interval: 30s
restart_policy:
max_attempts: 5 # 0 = forever
backoff_initial: 100ms
backoff_max: 5s
crash_audit: true
```

Files

```
forge-cli/runtime/
framework_runner.go # process supervisor (lifecycle + JSON-RPC framing)
framework_runner_test.go # spawn / ready / crash / restart / drain
strands_runner_invoke.go # A2A tasks/send → invoke translation + response shaping
strands_runner_audit_bridge.go # notification → AuditEvent translation
forge-cli/templates/strands/
agent.py # operator's Strands Agent factory (skeleton)
requirements.txt # strands-agents>=1.0, forge-strands-runner
forge_strands_runner.py # stdio JSON-RPC loop wrapping the operator's Agent
Dockerfile # python:3.12-slim + forge Go binary
forge-core/catalog/
frameworks.go # register "strands" as a known framework value
forge-core/types/config.go # FrameworkStrands constant + StrandsConfig struct
```

Python shim (`forge_strands_runner`)

Ship as a PyPI package so operators don't write the JSON-RPC plumbing — they write `agent.py` with a `build_agent()` factory; the shim handles ready/invoke/healthz/audit/shutdown messages and the OTel context extraction.

```python

forge_strands_runner.py — shim Forge owns

import json, sys
from opentelemetry.propagate import extract
from opentelemetry import trace

from agent import build_agent

tracer = trace.get_tracer("forge.strands.runner")
agent = build_agent()

def write(obj):
print(json.dumps(obj), flush=True)

write({"jsonrpc": "2.0", "method": "ready"})

for line in sys.stdin:
req = json.loads(line)
method = req.get("method")
if method == "invoke":
ctx = extract({"traceparent": req["params"].get("traceparent", "")})
with tracer.start_as_current_span("strands.invoke", context=ctx):
result = agent(req["params"]["prompt"])
write({"jsonrpc": "2.0", "id": req["id"], "result": {"text": str(result)}})
elif method == "healthz":
write({"jsonrpc": "2.0", "id": req["id"], "result": "ok"})
elif method == "shutdown":
write({"jsonrpc": "2.0", "id": req["id"], "result": "draining"})
break
```

Phased rollout

This issue tracks the whole arc; PRs can land any one phase independently.

1. Phase 1 — Skeleton (1-2 weeks). Supervisor + lifecycle + JSON-RPC framing + `invoke` roundtrip. `forge init --framework strands` scaffolds. No audit bridge, no guardrails. Validates the supervisor + happy path.
2. Phase 2 — Trace + audit bridge (1 week). `strands.bridge.invoke` span. Per-request `traceparent` propagation. Notification → AuditEvent translation with `correlation_id` + `seq` stamping.
3. Phase 3 — Guardrails at the boundary (1 week). Input gate before Forge sends `invoke`. Output gate when response comes back. Tool-call gate via runner notification round-trip.
4. Phase 4 — Container packaging + docs (1-2 weeks). `forge package` emits a working image (python:3.12-slim base + Forge binary + Strands deps + operator agent.py). End-to-end `docs/frameworks/strands.md` walkthrough.
5. Phase 5 — Streaming (optional). `stream_token` notifications wire to A2A `tasks/sendSubscribe` SSE responses.

Open design questions

Question	Default for v1
Session model — Strands' (in-memory) or Forge's (file)?	Strands' in-memory. File-backed continuity is the operator's choice via Strands' Session abstraction.
Tool ownership — Strands tools only, or expose SKILL.md as Strands tools?	Strands tools only. SKILL.md bridge is a follow-up if operators ask for it.
LLM provider — Strands picks (Bedrock/Anthropic/OpenAI/LiteLLM), or Forge proxies?	Strands picks. Forge still tracks the chosen provider in forge.yaml for egress-allowlist auto-merge + security analysis.
Container shape — one image (Forge + Python venv) or two-container Pod?	One image. K8s sidecar pattern is a follow-up if scaling concerns surface.

What this does NOT do (out of scope)

• Embedded Python via cgo. Strands' dep tree (boto3, multiple OTel instrumentations, anthropic, openai...) makes cgo a pain. Subprocess is the practical answer.
• Node / TypeScript runner. Same supervisor pattern works for any subprocess agent runtime; do Node as a follow-up issue once Strands lands.
• Multi-runner orchestration (multiple Strands agents in one pod). One agent.py per Forge agent for v1.
• Bridge from SKILL.md skills into Strands tools. Out of scope for v1.

Risk

Low-medium. The supervisor is a new code path; mitigated by the phased rollout and the fact that the underlying JSON-RPC framing is the same one MCP-stdio already uses. The cgo / dual-language coupling is constrained to a single shim (forge_strands_runner.py). Operators on existing frameworks (custom, crewai, langchain) see no change.

[initializ-mk]

Addendum: zero-code OTel auto-instrumentation as a Phase 4 deliverable

A point worth pinning explicitly in the design: when Forge ships the Strands base image, it should bundle the OTel distro + curated instrumentation packages and launch the runner under `opentelemetry-instrument`. This means the developer can write zero OTel code and add zero OTel deps to their requirements.txt and still get a full trace tree.

What lights up for free

Strands' built-in instrumentation (it ships OTel API calls throughout, no-op without an SDK installed):

• `strands.agent.invoke` — `Agent.call()`
• `strands.agent.event_loop` — internal turn loop
• `strands.model.invoke` — model provider call (Bedrock / Anthropic / OpenAI / LiteLLM); GenAI semconv attrs (`gen_ai.system`, `gen_ai.request.model`, `gen_ai.usage.*`, `gen_ai.response.finish_reasons`)
• `strands.tool.` — every `@tool` invocation
• `strands.subagent.invoke` — nested Agent-as-tool calls

Zero-code Python instrumentation (via `opentelemetry-instrument`):

• `HTTP ` client spans on every outbound — `requests` / `httpx` / `urllib3` / `aiohttp`
• `AWS .` spans — `botocore` (Bedrock invoke, S3, DynamoDB, every AWS API call)
• gRPC client + server spans
• Python `logging` calls → span events

Crucially: `requests` and `httpx` are what Strands' model providers use under the hood. So you get the actual HTTP-level spans on every LLM call (URL, status, latency, retry count) as children of Strands' own `strands.model.invoke` span.

Base image manifest (Phase 4 spec)

```dockerfile
RUN pip install \
opentelemetry-distro \
opentelemetry-exporter-otlp \
opentelemetry-instrumentation-requests \
opentelemetry-instrumentation-httpx \
opentelemetry-instrumentation-urllib3 \
opentelemetry-instrumentation-aiohttp-client \
opentelemetry-instrumentation-botocore \
opentelemetry-instrumentation-grpc \
opentelemetry-instrumentation-logging \
opentelemetry-instrumentation-system-metrics

CMD ["opentelemetry-instrument", \
"--traces_exporter=otlp", \
"--logs_exporter=none", \
"--metrics_exporter=none", \
"python", "-m", "forge_strands_runner"]
```

Logs + metrics off by default — Forge already owns the audit + ops-log streams; tracing is the lane.

Off-by-default GenAI packages

If the operator wants prompt/completion capture on the LLM spans (matching Forge's opt-in `AuditPayloadCapture`), let them flip on the OpenLLMetry packages via an image variant or skill-level install:

```
opentelemetry-instrumentation-openai
opentelemetry-instrumentation-anthropic
opentelemetry-instrumentation-bedrock
```

Configure with `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true` (off by default; matches Forge's metadata-only invariant). Likely needs `OTEL_INSTRUMENTATION_SDK_DISABLED=strands.model` to avoid duplicate spans with Strands' own coverage of the same call — settle the dedupe policy before flipping on.

End-to-end shape with zero developer OTel code

```
a2a.tasks/send [Forge — Go]
└── strands.bridge.invoke [Forge — Go]
└── http.client POST /invoke (stdio) [Forge — Go]
└── strands.agent.invoke [Strands SDK — built-in]
├── strands.agent.event_loop [Strands SDK]
│ ├── strands.model.invoke [Strands SDK]
│ │ └── HTTP POST [opentelemetry-instrumentation-httpx]
│ │ (api.anthropic.com)
│ └── strands.tool.weather [Strands SDK]
│ └── HTTP GET [opentelemetry-instrumentation-requests]
└── strands.agent.event_loop [Strands SDK — turn 2]
└── strands.model.invoke [Strands SDK]
└── HTTP POST [auto]
```

Every outbound HTTP span sits on the egress proxy's wire path, so `egress_allowed` audit events line up byte-for-byte with the HTTP client spans across the language boundary.

What this means for the Phase 4 deliverable

`forge package` for `framework: strands` doesn't just "install Strands". It produces an image that gives operators production-grade observability the developer never wrote a line for. That's the headline value-prop of the integration vs running vanilla Strands. Worth highlighting in `docs/frameworks/strands.md`.

[initializ-mk]

Addendum: OTel dep ownership — dev vs Forge

Clarifying what happens when the developer's `requirements.txt` already includes OTel deps:

• SDK + exporters (`opentelemetry-sdk`, `opentelemetry-exporter-otlp`, `opentelemetry-distro`) — dev's pins always win. Forge doesn't override.
• `opentelemetry-instrumentation-` packages — Forge bundles a curated baseline by default. Most devs install `opentelemetry-sdk` and stop; they don't realize they also need separate `-instrumentation-*` packages for HTTP / Bedrock / Anthropic coverage. The baseline guarantees the headline observability promise.
• OTEL_ env vars* — Forge always injects (endpoint, service name, samplers, propagators). Dev shouldn't think about deployment-time wiring.
• Launcher — Forge controls. Even with packages installed, the process must be launched under `opentelemetry-instrument` for auto-patching to kick in.

Config knobs

```yaml
strands:
otel:
auto_instrument: true # launch under opentelemetry-instrument; default on
bundle_baseline: true # install Forge's curated -instrumentation set; default on
```

When `bundle_baseline: true` (default), `forge package` pip install order:

1. `pip install -r /opt/forge/strands-otel-baseline.txt` (Forge's curated bundle)
2. `pip install -r requirements.txt` (dev's deps — pins win at conflict)

When `bundle_baseline: false`, Forge skips step 1; dev owns everything. Audit logs `framework_otel_baseline_skipped` so operators reading the audit stream can spot it.

Why default to bundling

1. Headline observability is a promise — `docs/frameworks/strands.md` will say "every outbound HTTP is auto-spanned." That promise breaks silently if the dev forgot `opentelemetry-instrumentation-httpx`. Bug reports land on Forge, not on the dev's requirements.
2. Image-size cost is ~15 MB on top of Strands' ~80 MB. Negligible vs the operator confusion of figuring out which packages are missing.

Power users who want strict control flip `bundle_baseline: false` and accept ownership. Default protects everyone else.

[initializ-mk]

Refactor: split into `strands-python` and `strands-node` framework values

The Python and Node Strands SDKs are the same conceptual integration but diverge enough at the implementation layer (package manager, base image, OTel auto-instrumentation stack, shim language) that one `framework: strands` value would create config-time ambiguity. Split into two:

```yaml
framework: strands-python # python:3.12-slim base, pip, opentelemetry-instrument launcher
framework: strands-node # node:22-slim base, npm, --require auto-instrumentation
```

The Go-side process supervisor (`framework_runner.go`) is identical for both — JSON-RPC over stdio doesn't care what's on the other end. The split is purely at packaging + scaffolding.

What differs per language

Concern	`strands-python`	`strands-node`
Base image	`python:3.12-slim`	`node:22-slim`
Dep manifest	`requirements.txt` (pip)	`package.json` + lockfile (npm / pnpm)
Strands SDK	`strands-agents` (PyPI)	`@strands-agents/sdk` (npm)
Agent factory	`agent.py` (`build_agent()`)	`agent.ts` (default-exported `buildAgent()`)
Runner shim	`forge_strands_runner.py`	`@initializ/forge-strands-runner` (npm)
OTel SDK	`opentelemetry-sdk` + `opentelemetry-distro`	`@opentelemetry/sdk-node`
OTel exporter	`opentelemetry-exporter-otlp`	`@opentelemetry/exporter-trace-otlp-http`
Auto-instrumentation bundle	curated `opentelemetry-instrumentation-{requests,httpx,botocore,grpc,logging}`	`@opentelemetry/auto-instrumentations-node` (single meta-package covers http/fetch/fs/aws-sdk/grpc/...)
Launcher	`opentelemetry-instrument python -m forge_strands_runner`	`node --require @opentelemetry/auto-instrumentations-node/register dist/runner.js`
Hot-reload signal	`agent.py`	`agent.ts` (or `dist/agent.js` post-`tsc`)

What stays the same

• `framework_runner.go` — one supervisor, one JSON-RPC framing layer, one lifecycle manager. Reads `framework.runner_command` from forge.yaml; doesn't know or care which language the subprocess speaks.
• Per-request traceparent in the invoke message — both Python and Node OTel SDKs honor it via their propagator extract.
• Audit notification translation — both shims emit identical JSON-RPC notifications (`{"method":"audit","params":{...}}`); Forge translates once.
• Egress proxy — `HTTP_PROXY` / `HTTPS_PROXY` env vars work for `httpx`/`requests`/`urllib3` (Python) and `undici`/`fetch`/`axios`/`http`/`https` (Node).
• Container packaging contract — single image with the right base + Forge Go binary + runner shim + operator agent code.
• `framework_runner_crashed` audit + restart policy + healthz — identical.

forge.yaml shape

```yaml
framework: strands-python # or strands-node
strands:
startup_timeout: 30s
drain_timeout: 10s
health_interval: 30s
restart_policy:
max_attempts: 5
backoff_initial: 100ms
backoff_max: 5s
otel:
auto_instrument: true # both languages — controls the launcher
bundle_baseline: true # both languages — controls baseline package install
```

The `strands` config block is shared across both runtimes. Only `framework:` selects the scaffolding + base image.

Phase 4 template trees

```
forge-cli/templates/strands-python/
agent.py
requirements.txt
strands-otel-baseline.txt
Dockerfile

forge-cli/templates/strands-node/
agent.ts
package.json
package-lock.json
tsconfig.json
Dockerfile
```

`forge init --framework strands-python` and `forge init --framework strands-node` pick the right tree. Validation in `forge-core/catalog/frameworks.go` lists both as known values.

[initializ-mk]

Developer experience contract — where the developer's code lives

The developer brings their Strands code to Forge by writing one entry-point file at the project root that exposes a `build_agent()` factory. Everything else is config or scaffolding.

Project layout (`strands-python`)

```
my-agent/
├── forge.yaml Forge config (framework, auth, egress, channels)
├── agent.py ← developer's entrypoint (REQUIRED)
├── tools/ ← developer's tool functions (optional)
│ ├── weather.py
│ └── kb_query.py
├── requirements.txt ← developer's pip deps (existing one works)
├── prompts/ ← optional, developer's choice
│ └── system.md
├── Dockerfile ← auto-generated by `forge build`; can override
└── .forge/ ← Forge-internal, gitignored
├── secrets.enc
└── sessions/
```

The one contract: `build_agent()`

`agent.py` must export a `build_agent()` function returning a Strands `Agent`. The shim (`forge_strands_runner`) imports this module once at startup, holds the returned Agent in memory, calls `agent(prompt)` on every inbound A2A request.

```python

agent.py

from strands import Agent
from strands.models import AnthropicModel
from tools.weather import get_weather

def build_agent() -> Agent:
return Agent(
model=AnthropicModel(model_id="claude-sonnet-4-5"),
tools=[get_weather],
system_prompt=open("prompts/system.md").read(),
)
```

Inside `build_agent()` the developer is in vanilla Strands land — model, tools, session strategy, multi-agent pattern, MCP servers, callback handlers — Forge doesn't peek inside.

Node variant (`strands-node`)

Same shape; `agent.ts` exports a default `buildAgent()` factory:

```ts
import { Agent } from "@strands-agents/sdk";
export async function buildAgent(): Promise {
return new Agent({ model: ..., tools: [...] });
}
```

Migration paths

Starting point	Path
Brand new	`forge init --framework strands-python my-agent` — scaffolds the layout, dev edits placeholders
Existing Strands repo, adopt in place	`forge init --framework strands-python --adopt .` — scaffolds `forge.yaml` + a thin re-export `agent.py` (`from my_app.agent import build_agent`). Existing tools, deps, prompts stay where they are.
Monorepo with multiple agents	Each Forge agent gets its own directory with its own `forge.yaml` + `agent.py` that re-exports from shared monorepo packages. `forge run --workdir ` picks the right project.

Ownership

File	Owned by	Edit?
`agent.py` / `agent.ts`	developer	yes
`tools/`	developer	yes
`requirements.txt` / `package.json`	developer	yes
`prompts/`	developer	yes
`forge.yaml`	developer	yes
`Dockerfile`	Forge-generated, dev can override	optional
`forge_strands_runner` (the shim)	Forge	don't edit — shipped via PyPI / npm
`.forge/secrets.enc`	Forge	managed via `forge secret set`
`.forge/sessions/`	Forge	runtime state, gitignored

What the developer never has to touch

• W3C trace context propagation
• Audit event emission to Forge's audit pipeline
• Egress proxy (`HTTP_PROXY` env auto-set)
• OTel SDK bootstrap (`opentelemetry-instrument` launcher; baseline package bundle)
• A2A wire protocol
• Auth / rate limit / guardrails

End-state: a developer who knows Strands but has never heard of Forge can drop their existing `Agent(...)` construction into `agent.py`, run `forge init && forge run`, and have a production-ready A2A endpoint with audit + tracing + egress control + auth — without writing a single line of Forge-specific code beyond `forge.yaml`.

This developer-experience contract is the headline value-prop of the integration. Worth documenting prominently in `docs/frameworks/strands-python.md` and `docs/frameworks/strands-node.md`.

[initializ-mk]

Documentation deliverables — developer onboarding walkthrough

The Phase 4 docs deliverable (`docs/frameworks/strands-python.md` and `docs/frameworks/strands-node.md`) must include a complete, copy-pasteable end-to-end walkthrough showing the developer's minimal diff against existing Strands code. This is the headline value-prop in concrete form. Spec below.

Required sections (both docs)

1. What changes vs vanilla Strands — the minimal diff. Show a real Strands agent before/after, with the changes color-coded.
2. The `build_agent()` / `buildAgent()` contract — the single Forge requirement.
3. `forge.yaml` reference — every knob explained, with sensible defaults annotated.
4. `requirements.txt` / `package.json` — what's required, what Forge bundles for free.
5. Local dev — `forge init` → edit `agent.py` → `forge run` → `forge dev` REPL.
6. Production deploy — `forge build` → `forge package` → kubectl apply.
7. Migrating existing code — three paths (new project / adopt-in-place / monorepo).
8. Backward-compat REPL pattern — keep `if name == "main":` for offline debugging alongside the Forge factory.
9. Operator-visible observability — sample audit stream + sample trace tree from one invocation.
10. Troubleshooting — startup failures, common Anthropic / Bedrock auth pitfalls, egress denials, OTel exporter misconfig.

Canonical example — DDG-backed RecipeBot

Both docs use the same example agent so an operator skimming both pages sees the contract is identical. Source agent below; both docs walk it through.

Original vanilla-Strands code (what the developer has today):

```python
import logging
from ddgs import DDGS
from ddgs.exceptions import DDGSException, RatelimitException
from strands import Agent, tool

logging.getLogger("strands").setLevel(logging.INFO)

@tool
def websearch(keywords: str, region: str = "us-en", max_results: int | None = None) -> str:
"""Search the web to get updated information."""
try:
results = DDGS().text(keywords, region=region, max_results=max_results)
return results if results else "No results found."
except RatelimitException:
return "RatelimitException: Please try again after a short delay."
except DDGSException as d:
return f"DuckDuckGoSearchException: {d}"
except Exception as e:
return f"Exception: {e}"

recipe_agent = Agent(
system_prompt="You are RecipeBot...",
tools=[websearch],
)

if name == "main":
while True:
user_input = input("\nYou > ")
if user_input.lower() == "exit":
break
print(f"\nRecipeBot > {recipe_agent(user_input)}")
```

After dropping into Forge (the `agent.py` Forge expects):

```python
import logging
from ddgs import DDGS
from ddgs.exceptions import DDGSException, RatelimitException
from strands import Agent, tool

logging.getLogger("strands").setLevel(logging.INFO)

@tool
def websearch(keywords: str, region: str = "us-en", max_results: int | None = None) -> str:
"""Search the web to get updated information."""
try:
results = DDGS().text(keywords, region=region, max_results=max_results)
return results if results else "No results found."
except RatelimitException:
return "RatelimitException: Please try again after a short delay."
except DDGSException as d:
return f"DuckDuckGoSearchException: {d}"
except Exception as e:
return f"Exception: {e}"

def build_agent() -> Agent:
"""Forge calls this once at process startup; the returned Agent is held in memory
for every inbound A2A invocation."""
return Agent(
system_prompt="You are RecipeBot, a helpful cooking assistant...",
tools=[websearch],
)

Optional: keep the REPL for ad-hoc local debugging.

Forge does NOT use this branch — forge dev provides an equivalent REPL

that goes through the full A2A + audit + tracing path.

if name == "main":
agent = build_agent()
while True:
user_input = input("\nYou > ")
if user_input.lower() == "exit":
break
print(f"\nRecipeBot > {agent(user_input)}")
```

Diff summary:

• Wrap module-level `Agent(...)` construction in a `build_agent()` factory.
• (Optional) Adjust the `main` block to instantiate via the factory — keeps offline debugging working with zero drift between `python agent.py` and `forge run`.

Tool definition, imports, logging, error handling — unchanged.

Accompanying `forge.yaml` (in the docs)

```yaml
agent_id: recipe-bot
framework: strands-python
version: "0.1.0"

model:

Used by forge build's security analysis + auto-merged into egress allowlist.

Strands picks its actual provider inside Agent() construction.

provider: anthropic
name: claude-sonnet-4-5

strands:
startup_timeout: 30s
health_interval: 30s
otel:
auto_instrument: true # launch under opentelemetry-instrument
bundle_baseline: true # Forge installs the curated -instrumentation set

auth:
providers:
- type: static_token

egress:
mode: allowlist
allowed_domains:
- api.anthropic.com # Strands' LLM call
- duckduckgo.com # ddgs primary
- html.duckduckgo.com # ddgs HTML fallback
- lite.duckduckgo.com # ddgs lite fallback

secrets:
providers:
- encrypted-file
- env # picks up ANTHROPIC_API_KEY from OS env
```

`requirements.txt`

```
strands-agents>=1.0
ddgs
forge-strands-runner # the Forge shim — handles JSON-RPC over stdio
```

OTel auto-instrumentation packages are bundled by Forge (`bundle_baseline: true`), so they don't appear here.

Local dev section (docs)

```bash
forge init --framework strands-python recipe-bot
cd recipe-bot

Paste agent.py with the build_agent() factory.

echo "strands-agents>=1.0" > requirements.txt
echo "ddgs" >> requirements.txt
echo "forge-strands-runner" >> requirements.txt

export ANTHROPIC_API_KEY=sk-ant-... # or: forge secret set ANTHROPIC_API_KEY

forge run # starts Forge + persistent Python runner

In another shell:

forge dev # interactive REPL hitting the local A2A endpoint

What can I make with chicken and tomatoes?
RecipeBot > Here's a recipe for Chicken Pomodoro...
```

Observability section (docs)

Show the audit stream and trace tree the operator gets from one invocation — pin in the docs that this comes "for free" with zero developer OTel code.

Sample audit stream:

```
auth_verify seq=1
session_start seq=2
framework_runner_invoke seq=3
llm_call seq=4 provider=anthropic, input_tokens=412, output_tokens=18
tool_exec seq=5 tool=websearch, phase=start
egress_allowed seq=6 domain=html.duckduckgo.com
egress_allowed seq=7 domain=lite.duckduckgo.com
tool_exec seq=8 tool=websearch, phase=end, duration_ms=1843
llm_call seq=9 provider=anthropic, input_tokens=978, output_tokens=421
invocation_complete seq=10 duration_ms=4127, llm_call_count=2
session_end seq=11 state=completed
```

Sample trace tree:

```
a2a.tasks/send [Forge — Go]
└── strands.bridge.invoke [Forge — Go]
└── strands.invoke [shim — Python]
└── strands.agent.invoke [Strands SDK]
├── strands.agent.event_loop [Strands SDK — turn 1]
│ ├── strands.model.invoke [Strands SDK]
│ │ └── HTTPS POST [opentelemetry-instrumentation-httpx]
│ │ api.anthropic.com/v1/messages
│ └── strands.tool.websearch [Strands SDK]
│ ├── HTTPS GET [opentelemetry-instrumentation-requests]
│ │ html.duckduckgo.com/...
│ └── HTTPS GET [opentelemetry-instrumentation-requests]
│ lite.duckduckgo.com/...
└── strands.agent.event_loop [Strands SDK — turn 2]
└── strands.model.invoke [Strands SDK]
└── HTTPS POST [auto-instrumented]
```

Migration patterns section (docs)

Three named flows with copy-pasteable commands:

Starting point	Command	What scaffolds
Brand new project	`forge init --framework strands-python my-agent`	Full layout: `forge.yaml`, `agent.py` skeleton, `requirements.txt`, `Dockerfile`
Existing Strands repo, adopt in place	`forge init --framework strands-python --adopt .`	Only `forge.yaml` + a thin re-export `agent.py` (`from my_app.agent import build_agent`). Existing tools, deps, prompts stay where they are.
Monorepo with multiple agents	One subdir per agent, each with its own `forge.yaml` + `agent.py` that re-exports from shared packages	`forge run --workdir src/myorg/agents/triage` picks the right project.

Node-side parity

Same structure, same canonical example translated to TypeScript:

```ts
// agent.ts
import { Agent, tool } from "@strands-agents/sdk";
import { AnthropicModel } from "@strands-agents/sdk/models";

const websearch = tool({
name: "websearch",
description: "Search the web to get updated information.",
parameters: { /* ... */ },
async execute({ keywords, region = "us-en", maxResults }) {
// dev's implementation (e.g. duck-duck-scrape)
},
});

export async function buildAgent(): Promise {
return new Agent({
model: new AnthropicModel({ modelId: "claude-sonnet-4-5" }),
tools: [websearch],
systemPrompt: "You are RecipeBot...",
});
}
```

Same `forge.yaml` shape (just `framework: strands-node` and `package.json` instead of `requirements.txt`). Same audit stream + trace tree.

Troubleshooting section (docs)

Minimum the docs must cover, with audit-event-grep recipes:

Symptom	Diagnosis path
Runner won't start	Check `framework_runner_crashed` audit; `forge run --verbose` shows the Python import failure; usually missing dep or wrong Python version
Egress denied unexpectedly	`jq 'select(.event=="egress_blocked")' forge.log`; check `forge.yaml` `egress.allowed_domains`
`ANTHROPIC_API_KEY` not found	Either secrets provider chain doesn't include `env`, or key not in OS env / `.forge/secrets.enc`; see Secret management
Spans missing from trace	Confirm `OTEL_EXPORTER_OTLP_ENDPOINT` set; check `strands.otel.auto_instrument` is `true`; verify collector reachable via the egress allowlist
Slow cold start	Expected — first invocation builds the Python interpreter cache. Persistent subprocess amortizes after that.
Hot reload not picking up changes	Confirm file watcher is active; restart with `forge run --no-watch` to test without reload; check `framework_runner_crashed` for restart loop

Cross-references in the new docs

• Trust + audit model: `docs/security/audit-logging.md`
• Egress enforcement: `docs/security/egress-control.md`
• OTel tracing pipeline: `docs/core-concepts/observability-tracing.md`
• Secret management: `docs/security/secret-management.md`
• Per-agent forge.yaml schema: `docs/reference/forge-yaml-schema.md`
• A2A protocol surface: `docs/reference/a2a-agent-card.md`

Acceptance criteria for the docs deliverable

• An operator who has never used Forge can run `forge init --framework strands-python` → edit the placeholder `agent.py` → `forge run` → curl the A2A endpoint → see the audit + trace output described above, in under 15 minutes.
• The canonical example agent (RecipeBot) in the docs matches a working e2e test in `forge-cli/runtime/strands_runner_e2e_test.go` (or equivalent), so docs can't drift from runtime behavior.
• Migration patterns table includes a working command for each of the three starting points.
• Troubleshooting section addresses every audit event the framework runner can emit on failure paths.