{
  "markdown": "# aeo-skill-builder-runtime\n\nThe **Conversational Skill Builder** — a Bedrock AgentCore Runtime (`serverProtocol:\nAGUI`) that turns an org's onboarding context into a prospect-scanning **skill config\ndocument** through a streaming chat.\n\n**Emit-only.** It emits AG-UI events and tool-call *requests*; the gateway performs\nevery side-effect. It has no database handle and no network write authority at all,\nwhich is also the prompt-injection backstop.\n\nStateless per turn — state is reconstructed from the gateway's snapshots on every\ninvocation. `skill_builder_sessions` (gateway-owned) is the only durable truth.\n\n## Ownership\n\n**We own this end to end — development, the runtime, and deployment to Bedrock AgentCore**\n(standing instruction from Leo, 2026-09-02). It is not another team's and it is not blocked\non AWS access. See [CLAUDE.md](CLAUDE.md) for the self-serve boundary and the three things\nthat still need an administrator.\n\n## Why this repo exists\n\nSplit out of `aeo-agent-service` on 2026-08-07, mirroring how\n`aeo-groundtruth-browser-runtime` was separated. That service is a Redis-queue worker;\nthis is an ASGI app with its own entrypoint, its own image and its own execution role.\nKeeping them together meant an image carrying PostgreSQL, Redis, Neo4j and the whole\nSoV surface for a runtime that imports none of it.\n\n**`app/skill_builder/` moved here verbatim.** The only coupling to the old service was\n`app.config.get_settings`, so `app/config.py` here is a seven-field port — see its\ndocstring for what was deliberately left behind.\n\n## Layout\n\n| Path | What |\n|---|---|\n| `app/skill_builder/server.py` | the ASGI app: `POST /invocations`, `GET /ping` |\n| `app/skill_builder/runtime.py` | `handle_turn` — never crashes; failures become in-stream `RUN_ERROR` |\n| `app/skill_builder/protocol/agui.py` | the one owned AG-UI module: events, emitter, SSE encoding |\n| `app/skill_builder/stubs/` | the **five pinned contracts**, verbatim copies of the gateway's ratified files — `config_schema`, `context_field_keys`, `tool_schemas`, `agui_state_envelope`, `agui_run_finished` |\n| `scripts/provision.py` | idempotent deploy — create or update in place, same ARN |\n| `docs/admin-request-skillbuilder-role.md` | the one thing we cannot self-serve |\n\n`app/skill_builder/README.md` is the module-level guide and stays authoritative for\nthe internals.\n\n## Develop\n\n```bash\npython -m venv .venv\n.venv/Scripts/python -m pip install -r requirements.txt pytest\n.venv/Scripts/python -m pytest tests/ -q          # 299 tests, no AWS needed\n```\n\nNothing in the suite touches AWS or a network: the model is injected as a FastAPI\ndependency and tests supply a `FakeChatModel`.\n\n⚠️ **`tests/test_skill_builder_contracts.py` hashes the five pinned stubs against the\ngateway's real files** at `../../aeo-backend/src/backend/skills/config/`, resolved as\n`Path(__file__).resolve().parents[2]`. That happens to keep working after the move\nonly because this repo sits at the same depth beside `aeo-backend` as the old one did.\nIt **skips when that directory is absent** and guards its own skip, so a path typo\nfails loudly rather than leaving the test green while comparing nothing.\n\n## Deploy\n\n```bash\npython scripts/provision.py --check                # read-only inventory\npython scripts/provision.py --role-arn <role-arn>  # build, push, create/update\n```\n\nIdempotent, and an update **keeps the same runtime ARN** — which matters, because that\nARN is what the gateway holds for R2.\n\n### Three things that will bite you\n\nInherited from the sibling repo's `docs/RUNBOOK-agentcore-runtime.md`, which is worth\nreading in full before touching AWS here.\n\n1. **`docker buildx` needs `--provenance=false`.** The default OCI attestation makes\n   the pushed artifact a manifest *list*, which AgentCore rejects without ever\n   mentioning attestations.\n2. **`update-agent-runtime` is a full REPLACE, not a merge.** Omitting\n   `environmentVariables` wipes them, and the damage is invisible while the values\n   match the defaults in `config.py`.\n3. **`CreateAgentRuntime` authorizes three actions whose names are not inferable** —\n   it implicitly creates a DEFAULT endpoint and a workload identity whose resource is\n   not a `runtime/*` ARN. `provision.py` prints AWS's own error text rather than\n   guessing which grant to request, because a grant on the wrong resource denies\n   byte-for-byte identically.\n\n## Status\n\nVerified against AWS on 2026-09-02, not transcribed.\n\n| | |\n|---|---|\n| Code | ✅ 299 tests pass |\n| ECR repository | ✅ `aeo-groundtruth/skill-builder` (see the namespace note in `provision.py`) |\n| Execution role | ✅ `AmazonBedrockAgentCoreAEOSkillBuilderRole` |\n| Runtime / ARN | ✅ `arn:aws:bedrock-agentcore:us-east-1:082585646836:runtime/aeo_skill_builder-MQ0z2m8tqB` |\n| Deployed | ✅ **v33**, `READY` — `SKILL_BUILDER_BUILD_VERSION=d4a969b@2fb2b5c343bd` |\n| Bedrock model access | ✅ established — model-backed turns run (`anthropic.claude-sonnet-5`) |\n\nThis block sat at **v24** while v33 was live, which is the same failure it warns about\nbelow — nine versions of drift in a table nobody re-verified.\n\n⚠️ **This table was wrong for longer than it was right, and it cost a real detour.** It\ncarried \"role blocked / runtime not created\" through v23 being live, so a reader\nreasoning from it concluded the runtime did not exist and went to AWS to find out.\n**Check `provision.py --check` before trusting this block** — it is read-only, takes a\nsecond, and is the only statement here that cannot go stale.\n\nDeploys are recorded by `SKILL_BUILDER_BUILD_VERSION` on the runtime itself, in the form\n`<git-tag>@<digest-prefix>`. Both halves earn their place: the tag says which source, the\ndigest says which artifact, and they can legitimately disagree (a `-dirty` tag, or a\nrebuild of one commit). That value is the answer to \"what is actually running\", and it is\nauthoritative where this file is not.\n\n## Related\n\n- `aeo-agent-service` — the Redis worker this was split out of\n- `aeo-groundtruth-browser-runtime` — the sibling AgentCore runtime and its runbook\n- `conqrse-projects/aeo-triage/conversational-skill-builder.md` — the cross-repo\n  tracker and Live thread (five repos ship parts of this feature)\n",
  "bytes": 6214,
  "sha": "87ede153d97f3e4fd110cff41358537f076736100f6e1dc1f7cd7b41802f4076",
  "repo_slug": "conexustech/aeo-skill-builder-runtime",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_conexustech_aeo_skill_builder_runtime_ok_9ba0c315/readme"
}