docs: add how-to guide for reporting AWS Bedrock AgentCore environments

[dangrondahl]

Summary

Add a how-to guide covering how to report AWS Bedrock AgentCore runtimes to Kosli as an environment, modelled on /tutorials/report_aws_envs.

This is documentation-driven development. The guide is written first, reviewed on the PR preview environment, and used to pin down the intended user experience before the CLI and server work is scoped.

⚠️ Read this before writing a single line

The feature does not exist yet. There is no kosli snapshot agentcore command and no agentcore environment type on the server. This page is a specification wearing the clothes of a how-to guide.

Consequences for whoever picks this up:

• Open the PR as a draft and do not merge it while it describes commands that do not run. The preview environment is the review surface.
• Every command and flag shown must either exist today or be explicitly marked as proposed. A reader must never be left unable to tell the difference.
• If writing it reveals that the proposed UX is wrong, that is the deliverable. Say so in the PR rather than papering over it.

Background: what we know about the AgentCore API

An internal spike deployed real AgentCore runtimes in both build types and recorded a corpus of live bedrock-agentcore-control responses. Findings that shape this page:

Two build types, and they behave very differently.

	Container build	CodeZip build
Artifact field	agentRuntimeArtifact.containerConfiguration.containerUri	agentRuntimeArtifact.codeConfiguration.code.s3
What you get	an ECR image URI ending in a tag	bucket + prefix, nothing else
Fingerprintable?	Yes — resolve the tag to a digest via ECR	Not solved — see below

The two shapes are disjoint: a container runtime has no codeConfiguration, and a CodeZip runtime has no containerConfiguration.

containerUri is a tag, not a digest. It typically ends in a 64-hex string that looks exactly like a digest but sits in the tag position. The real digest is a different value. Reporting the URI verbatim would record a mutable reference that appears immutable. Kosli must resolve tag → digest via ECR, as the ECS reporter already does.

CodeZip has no content hash. There is no versionId in the response, and no equivalent of Lambda's CodeSha256. This is the sharpest gap: Lambda is the same deployment shape (code as a zip) and AWS hands you a hash for free; AgentCore does not. Without an agreed fingerprint source, this guide should not claim CodeZip support.

Other API facts worth knowing:

• Read chain: ListAgentRuntimes → ListAgentRuntimeEndpoints → GetAgentRuntimeEndpoint → GetAgentRuntime(version=liveVersion). ListAgentRuntimeVersions returns all versions in one call and is the cleaner path.
• Version numbers are strings ("1", "2"), not integers.
• targetVersion is never populated, even across an update. Don't document it as meaningful.
• Responses are deterministic — two reads of an unchanged runtime are byte-identical.
• A read-only IAM policy of bedrock-agentcore:List* / Get* plus ecr:BatchGetImage / ecr:DescribeImages was verified sufficient for the whole chain. That belongs in the Prerequisites section.

The recommendation this guide has to make

agentcore deploy builds container images server-side: it provisions a Lambda-backed CloudFormation custom resource that drives a CodeBuild project. The image is built in AWS from source.

That is convenient and it breaks the provenance chain. If AWS builds the image, the user's CI never produces an artifact it can attest, so there is nothing to match against what is running.

The guide should therefore steer readers toward:

1. Build the container image in your own CI (cross-build for ARM64 with buildx — AgentCore runtimes are aarch64).
2. Attest it to Kosli with its digest.
3. Push to ECR.
4. Point AgentCore at that image rather than letting the CLI build it. The CreateAgentRuntime API accepts containerConfiguration.containerUri directly, so a pre-built image is supported.

Getting this argument across clearly, to someone who has not thought about provenance, is the hardest and most valuable part of this page.

Decisions made

These were settled before the page is written. Don't relitigate them without a reason.

• Scope: container builds only. CodeZip is named as an explicit limitation with the reason given, not silently omitted. Documenting a build type we cannot fingerprint would be worse than leaving it out.
• Naming: kosli snapshot agentcore, environment type agentcore. Kebab/lowercase, consistent with report/azure-apps and report/cloud-run.
• Terraform section: mark as planned for a future iteration. No module exists yet. Include the heading with a short note so readers know it is coming rather than missing.
• Form: a new standalone page. It stays a self-contained one-pager so it can be reviewed on the preview environment and shared on its own. Follow-up (not this issue): once the feature ships, this should be folded into /tutorials/report_aws_envs alongside ECS, Lambda and S3 rather than living separately forever.

Still open

• Granularity. One Kosli environment per region covering all runtimes, or one per runtime? What do the filtering flags look like — by runtime name, by tag? Deliberately left open — resolve it while writing, since drafting the CLI examples is what will make the right answer obvious. Whatever you choose, say so explicitly in the PR description so it gets reviewed as a decision rather than slipping through as prose.

Page requirements

Per CLAUDE.md in this repo:

• Create tutorials/report_agentcore_envs.md and add "tutorials/report_agentcore_envs" to the Reporting environments group in config/navigation.json. Both steps are required or the page will not appear.
• YAML front matter with title and description.
• Root-relative internal links only (/getting_started/install), never relative.
• Sentence case headings, active voice, imperative mood, American spelling (Vale enforces this).
• Reuse the structure of report_aws_envs: Prerequisites → Report using Kosli CLI → (Terraform) → What you've accomplished. Use <Tabs> if more than one variant is documented.
• Branch + PR, Conventional Commit title (docs: ...). Never commit to main.
• Run mint broken-links before pushing navigation changes.

Acceptance criteria

• Page created and registered in config/navigation.json
• Preview environment renders correctly and has been reviewed internally
• Every command shown is either real or unambiguously marked as proposed
• The CI-build-and-attest recommendation is stated plainly, with the reason
• CodeZip limitation stated honestly rather than omitted silently
• Cross-linked from/to /tutorials/report_aws_envs
• mint broken-links passes
• No customer-identifying information anywhere in the page

Out of scope

• Implementing kosli snapshot agentcore in the CLI, or the server-side environment type
• Designing a CodeZip fingerprint
• Tracking agent configuration (tool availability, prompts) as a compliance-relevant change — related but a separate problem
• Merging this page into /tutorials/report_aws_envs — a deliberate follow-up once the feature ships, see Decisions made

Where to start

1. Read tutorials/report_aws_envs.md and CLAUDE.md in this repo.
2. Ask the team for the internal spike findings — every API claim above is backed by a recorded live response.
3. Draft the page, open a draft PR, and review on the preview environment.