Governed Agentic Companion — a starter kit

A fork-and-build starter kit for a governed, orchestrator-driven multi-agent builder companion on Amazon Bedrock AgentCore, reachable from Kiro, Claude Code, or any MCP client. It is safe by construction: it never deploys or mutates an environment, never leaks a secret, and never presents an ungrounded guess as fact — and the boundary that keeps it safe has no off switch.

This kit is the reference implementation of the AWS Prescriptive Guidance pattern "The Governed Companion." It is product- and customer-agnostic: it ships with two example specialists and a tiny generic knowledge base so you can see the governance work in seconds, then swap in your own specialists and knowledge.

Run it now, no cloud, no LLM:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
./run.sh status                                   # governance integrity + knowledge load
./run.sh ask "what is the deployment policy?"     # grounded, deterministic, with a footer
echo "I have deployed to production." | ./run.sh gate   # watch the gate BLOCK it

What you get

• A governed Orchestrator that classifies each request and routes it to one specialist.

• An always-on Governance Gate (agents/governance_gate.py) that enforces the tenets as code — with no mode flag to turn it off.

• Example specialists over a common BaseAgent (measured confidence + grounding sources).

• A three-tier execution model — deterministic → local LLM (Ollama) → cloud LLM (Bedrock) — so the core works with no LLM at all.

• A hybrid knowledge base — an in-repo Tier-A baseline (locked) + an optional S3 Tier-B overlay (human-promoted) that fails open to the baseline.

• Two IDE front doors — a local stdio MCP bridge (frontdoor/mcp_bridge.py) and a direct AgentCore Gateway HTTP path — plus a token-refresh helper (frontdoor/gateway_token.py).

• A governance re-baseline script (scripts/rebaseline_integrity.py) — human-run, for when you adapt the constitution. The AWS provisioning steps (identity, S3, gateway, the KB-read IAM grant) are documented as human-run commands in docs/DEPLOY.md (Tenet 1 — the kit prepares configs and commands; a human runs every cloud mutation).

• Tests that run with no AWS and no LLM.

Related MCP server: agentic-orchestrator MCP server

The governance model (13 tenets)

Codified in PRINCIPLES.md, SHA-256 integrity-verified at startup. Two are absolute — they cannot be relaxed by configuration, prompt, or agent reasoning:

Make it yours (adoption path)

1. Run it locally — ./run.sh status shows the integrity check passing; ask a question and watch it answer on the deterministic tier with a governance-outcome footer. No AWS/LLM yet.

2. Keep the constitution; adjust the wording of the non-absolute tenets to your org, then re-baseline the integrity hash (scripts/rebaseline_integrity.py). Do not add an off switch.

3. Replace the example specialists (agents/specialists/) with your domain specialists — each is a small class over BaseAgent; routing and gating come for free.

4. Seed your knowledge base — locked constraints in knowledge/tier_a/, medium-velocity references in knowledge/tier_b/ (S3-overlay-eligible via the explicit allowlist).

5. Turn on a model tier when you want depth (config.yaml).

6. Provision AgentCore + identity (human-run) — see docs/DEPLOY.md.

7. Point your IDE at it — see docs/FRONT-DOORS.md.

Layout

sample-governed-agentic-companion/
├── PRINCIPLES.md              # the constitution (the 13 tenets)
├── governance/
│   ├── integrity.yaml         # SHA-256 baseline of PRINCIPLES.md
│   └── integrity_check.py     # startup tamper verification
├── agents/
│   ├── base_agent.py          # measured confidence + grounding sources
│   ├── orchestrator.py        # classify + route to one specialist
│   ├── governance_gate.py     # the always-on gate (no off switch)
│   ├── kb_overlay.py          # hybrid KB: Tier-A baseline + Tier-B S3 overlay
│   └── specialists/           # platform_specialist.py, security_specialist.py (examples)
├── knowledge/
│   ├── PRINCIPLES.yaml         # machine-readable threat model + enforcement roadmap
│   ├── tier_a/                # locked, in-repo, code-reviewed only
│   └── tier_b/                # medium-velocity, S3-overlay-eligible (explicit allowlist)
├── frontdoor/                 # IDE front doors (see frontdoor/README.md)
│   ├── mcp_bridge.py          # local stdio MCP bridge
│   ├── cognito_token.py       # mints + auto-refreshes the runtime token
│   ├── gateway_token.py       # gateway JWT refresh helper (print/write-env/daemon)
│   └── mcp.example.json       # copy into your IDE's MCP config
├── agentcore/                 # AgentCore Runtime packaging
│   ├── agentcore.json.example # runtime/gateway config template
│   └── app/                   # container entrypoint(s)
├── scripts/
│   └── rebaseline_integrity.py # re-baseline the PRINCIPLES.md hash after a governance change
├── docs/                      # DEPLOY.md, FRONT-DOORS.md, GOVERNANCE.md
├── tests/                     # run with no AWS / no LLM
├── config.yaml.example        # copy to config.yaml (gitignored)
├── run.sh / main.py           # the governed CLI (status / ask / gate)
└── requirements.txt

Governance, honestly

The absolute boundaries (no deploy, no system-of-record write, no secret leak, no fetch-and-execute directive, grounding-block) are enforced today. Some mechanical controls — a network-layer egress allowlist, hard resource ceilings, a single action-layer seam across all front doors — ship as first-increment text detectors now, with mechanical enforcement on a tracked roadmap (knowledge/PRINCIPLES.yaml). We state which controls are deterministic vs advisory rather than overclaiming — that honesty is itself a tenet.

Security

See CONTRIBUTING for more information.

License

This library is licensed under the MIT-0 License. See the LICENSE file.