From 9e119a71cdcaebc8ef5c62f863b8d4d835bb0e88 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 5 Aug 2026 12:48:42 +0200 Subject: [PATCH 1/7] docs: add how-to guide for reporting AgentCore environments Documentation-driven development for kosli-dev/docs#355. The page specifies the intended UX for `kosli snapshot agentcore` before the CLI and server work is scoped, so it is reviewed on the preview environment first. Every Kosli command is marked as proposed, since neither the command nor the `agentcore` environment type exists yet. The AWS commands are real and were checked against the current AWS reference docs, not only the spike corpus. The page leads with the CI-build-and-attest argument rather than treating it as an aside: `agentcore deploy` builds the image server-side in CodeBuild, so CI never produces an artifact to attest and the snapshot has nothing to match against. That is the substance of the guide, not a footnote. Scoped to container builds. CodeZip is named as an explicit limitation. Note the reason is narrower than the spike first concluded: `codeConfiguration` does define an optional `versionId`, but it is supplied by the deployer rather than computed by AgentCore, and it was absent from the captured response because nothing set it. There is still no service-computed content hash, so the limitation stands - but "the field does not exist" would have been wrong. Recommends pinning `containerUri` by digest. The documented pattern accepts `:tag` or `@sha256:digest`, and the digest form names exactly the image that was attested and cannot be repointed later. Granularity resolved as one Kosli environment per account and region covering all runtimes, with ECS-style include/exclude filtering flags. That matches the existing ECS and Lambda reporters and keeps one snapshot diff meaningful across the whole agent fleet. Reporting reads the live version rather than the newest one: endpoints pin versions independently, so DEFAULT can be on v4 while a named endpoint still serves v2. --- config/navigation.json | 1 + tutorials/report_agentcore_envs.md | 292 +++++++++++++++++++++++++++++ tutorials/report_aws_envs.md | 1 + 3 files changed, 294 insertions(+) create mode 100644 tutorials/report_agentcore_envs.md diff --git a/config/navigation.json b/config/navigation.json index e2f857e..4802494 100644 --- a/config/navigation.json +++ b/config/navigation.json @@ -97,6 +97,7 @@ "group": "Reporting environments", "pages": [ "tutorials/report_aws_envs", + "tutorials/report_agentcore_envs", "tutorials/report_k8s_envs", "tutorials/report_cloud_run_envs" ] diff --git a/tutorials/report_agentcore_envs.md b/tutorials/report_agentcore_envs.md new file mode 100644 index 0000000..0ffb021 --- /dev/null +++ b/tutorials/report_agentcore_envs.md @@ -0,0 +1,292 @@ +--- +title: "Report AWS Bedrock AgentCore environments to Kosli" +description: "How to build an agent container image in CI, attest it to Kosli, and report the AgentCore runtimes running it as a Kosli environment." +--- + + +**This page describes a proposed feature.** `kosli snapshot agentcore` does not +exist yet, and there is no `agentcore` environment type on the Kosli server. +Every Kosli command on this page is marked as proposed where it is not yet +available. The AWS commands are real and work today. + + +AWS Bedrock AgentCore runs your agent as a managed runtime. To hold an agent to +the same standard as the rest of your services, you need to know which build is +serving traffic and be able to trace it back to the commit and the pipeline that +produced it. + +This guide covers the two halves of that: + +- **Build the agent image in your own CI and attest it**, so an artifact exists + in Kosli to compare against. +- **Report the running AgentCore runtimes to Kosli** as an environment snapshot, + so you can see what is actually serving. + +The first half matters more than it looks, so start there. + +## Prerequisites + +* Have access to AWS, with AgentCore runtimes deployed from container images. +* [Create an AgentCore Kosli environment](/getting_started/environments#create-an-environment) named `agentcore-env-tutorial`. *(Proposed: the `agentcore` environment type is not yet available.)* +* [Get a Kosli API token](/getting_started/authenticating_to_kosli). +* [Install Kosli CLI](/getting_started/install). + +Reporting reads AgentCore and ECR. This read-only policy is sufficient for the +whole chain: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "bedrock-agentcore:List*", + "bedrock-agentcore:Get*", + "ecr:BatchGetImage", + "ecr:DescribeImages" + ], + "Resource": "*" + } + ] +} +``` + +The ECR permissions are not optional. AgentCore returns the image reference +exactly as it was supplied, which is usually a tag, and Kosli has to resolve +that tag to a digest before it means anything. See +[How Kosli fingerprints an agent](#how-kosli-fingerprints-an-agent). + + +This policy uses wildcards to keep it readable. For production, AWS recommends +scoping to specific runtime ARNs rather than `"Resource": "*"`. See +[Security best practices for AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-security-best-practices.html). + + +## Build the image in CI, not in AWS + +The AgentCore CLI's `agentcore deploy` builds your container image **inside your +AWS account**. It provisions a CodeBuild project and builds from source there. + +That is convenient, and it breaks the chain you are trying to establish. If AWS +builds the image, your CI never produces an artifact, so there is nothing in +Kosli to compare the running runtime against. The snapshot tells you a digest is +running and nothing can tell you where it came from. + +Build the image yourself instead, and point AgentCore at it. + + + +AgentCore runtimes are `aarch64`. If your CI runners are `x86_64`, cross-build +with buildx: + +```shell +docker buildx build \ + --platform linux/arm64 \ + --tag .dkr.ecr..amazonaws.com/: \ + --push . +``` + +Pushing here rather than in a separate step gives you the digest buildx +calculated, which is what you want to attest. + +ARM64 is a hard requirement, not a preference. AgentCore Runtime runs on AWS +Graviton, and an image built for another architecture fails at deploy time. + + + +Report the artifact with the digest that will be running: + +```shell +kosli attest artifact .dkr.ecr..amazonaws.com/: \ + --artifact-type oci \ + --name agent \ + --flow \ + --trail \ + --api-token \ + --org +``` + +Add whatever else your pipeline proves about this build with +[`kosli attest`](/client_reference/kosli_attest_generic) - test results, scan +results, approvals. That evidence is what makes the running agent auditable +later. + + + +`CreateAgentRuntime` accepts a container image directly, so AgentCore does not +have to build anything. Reference the image **by digest** rather than by tag: + +```shell +aws bedrock-agentcore-control create-agent-runtime \ + --agent-runtime-name \ + --role-arn \ + --network-configuration '{"networkMode":"PUBLIC"}' \ + --agent-runtime-artifact '{ + "containerConfiguration": { + "containerUri": ".dkr.ecr..amazonaws.com/@sha256:" + } + }' +``` + +`containerUri` accepts either `:tag` or `@sha256:digest`. Using the digest is +worth the small inconvenience: it names exactly the image you attested, and it +cannot be repointed at different content later. Use `update-agent-runtime` with +the same artifact shape to roll out a new build, which creates a new runtime +version. + + +`--agent-runtime-artifact` is a tagged union: set either +`containerConfiguration` or `codeConfiguration`, never both. AWS documents +deploying a pre-built ECR image as a supported pattern, including +`AgentRuntimeArtifact.fromEcrRepository` and `fromImageUri` in the CDK. Kosli +has not yet run reporting against a runtime deployed this way end to end, so +treat the invocation above as a starting point rather than a tested recipe. + + + + +Now the digest running in AgentCore is a digest your CI produced and attested, +and the environment snapshot below can be matched against it. + +## Report using Kosli CLI + + +Proposed. This command does not exist yet. + + +Export your AWS credentials: + +```shell +export AWS_REGION=yourAWSRegion +export AWS_ACCESS_KEY_ID=yourAWSAccessKeyID +export AWS_SECRET_ACCESS_KEY=yourAWSSecretAccessKey +``` + +Report every AgentCore runtime in the region: + +```shell +kosli snapshot agentcore agentcore-env-tutorial \ + --api-token \ + --org +``` + +One Kosli environment covers all AgentCore runtimes in one AWS account and +region, and each runtime appears as one artifact in the snapshot. This matches +how [`kosli snapshot ecs`](/client_reference/kosli_snapshot_ecs) and +[`kosli snapshot lambda`](/client_reference/kosli_snapshot_lambda) work, and it +means one snapshot diff shows you every agent that moved. + +Filter with the same flags as the ECS reporter when you want a narrower +environment: + +```shell +# include runtimes matching a list of names +kosli snapshot agentcore agentcore-env-tutorial --runtimes runtime1,runtime2 ... + +# include runtimes matching a pattern +kosli snapshot agentcore agentcore-env-tutorial --runtimes-regex "prod-*" ... + +# exclude runtimes matching a pattern +kosli snapshot agentcore agentcore-env-tutorial --exclude-regex "dev-*" ... +``` + +All filtering is case-sensitive. Include and exclude flags are mutually +exclusive. + +## How Kosli fingerprints an agent + +Kosli records the **image digest**, not the URI AgentCore hands back. + +AgentCore returns the image reference exactly as it was supplied. If it was +supplied as a tag, that is what you get back: + +```json +{ + "agentRuntimeArtifact": { + "containerConfiguration": { + "containerUri": ".dkr.ecr..amazonaws.com/:66fe54aab857..." + } + } +} +``` + +That trailing 64-character hex string sits in the tag position, after the `:`, +not the digest position, which would be `@sha256:`. Build tooling often uses a +content hash as a tag, which makes it look immutable when it is not: the same +tag can be repointed at different content. The actual digest of that image is a +different value. + +So Kosli resolves the tag through ECR to get the real digest, the same way the +ECS reporter does. That is why `ecr:BatchGetImage` and `ecr:DescribeImages` are +in the policy above, and it is why the digest in your snapshot will not match +the hex string in `containerUri`. It is not meant to. + +If you pin by digest as recommended above, the reference is already immutable +and unambiguous. Kosli still verifies it through ECR, but there is nothing left +to resolve. + +Kosli reads the version that is actually **live** rather than the newest one. +AgentCore creates a new runtime version on every image update and keeps the old +ones, and endpoints decide which version serves traffic. The `DEFAULT` endpoint +follows the newest version, but a named endpoint does not: you can have +`DEFAULT` on version 4 while a `PROD` endpoint still serves version 2. Reading +the newest version would report an image that nothing is running. + +## Report using Terraform module + +Planned for a future iteration. There is no AgentCore support in the +[Kosli reporter Terraform module](https://registry.terraform.io/modules/kosli-dev/kosli-reporter/aws/latest) +yet. Until then, run the CLI from your own scheduled job or pipeline. + +## Limitations + +**CodeZip builds are not supported.** AgentCore runtimes deployed from an S3 +code bundle describe their artifact by location, not by content: + +```json +{ + "agentRuntimeArtifact": { + "codeConfiguration": { + "code": { "s3": { "bucket": "...", "prefix": "....zip" } } + } + } +} +``` + +AWS Lambda deploys the same way and hands you a `CodeSha256` computed by the +service. AgentCore has no equivalent, and nothing in the response is guaranteed +to change when the code changes: + +- The `s3` block does define an optional `versionId`, but it is **supplied by + whoever deploys**, not computed by AgentCore. It defaults to the latest + version of the object, and it is absent from the response when the deployer + did not set it, so a reporter cannot depend on it being there. +- The `prefix` is sometimes a content hash, but only because some deployment + tools happen to name the object that way. Others use a stable path that never + changes. + +Either way, Kosli would be recording where the code lives rather than what the +code is. + +Rather than record a fingerprint that may be silently wrong, Kosli reports +container-based runtimes only. If you deploy agents from code bundles today, +moving to container builds is also what puts you on the CI-build-and-attest path +described above. + +**Agent configuration is not tracked.** A snapshot covers the image that is +running. Prompts, tool availability, and model choice are not part of the +fingerprint. + +## What you've accomplished + +You have an agent image built and attested in your own CI, and a Kosli +environment showing which AgentCore runtimes are serving which build. When an +agent changes, Kosli records it, and you can trace the running digest back to +the commit that produced it. + +From here you can: +* Query your environment with [`kosli list snapshots`](/client_reference/kosli_list_snapshots) and [`kosli get snapshot`](/client_reference/kosli_get_snapshot) +* [Compare snapshots to see what changed](/client_reference/kosli_diff_snapshots) +* Trace a running artifact back to its git commit with the [From commit to production](/tutorials/following_a_git_commit_to_runtime_environments) tutorial +* Report your other AWS workloads with the [Report AWS environments](/tutorials/report_aws_envs) guide diff --git a/tutorials/report_aws_envs.md b/tutorials/report_aws_envs.md index c65ce62..d7b0d2d 100644 --- a/tutorials/report_aws_envs.md +++ b/tutorials/report_aws_envs.md @@ -274,3 +274,4 @@ From here you can: * Query your environment with [`kosli list snapshots`](/client_reference/kosli_list_snapshots) and [`kosli get snapshot`](/client_reference/kosli_get_snapshot) * [Compare snapshots to see what changed](/client_reference/kosli_diff_snapshots) * Trace a running artifact back to its git commit with the [From commit to production](/tutorials/following_a_git_commit_to_runtime_environments) tutorial +* Report AWS Bedrock AgentCore agent runtimes with the [Report AgentCore environments](/tutorials/report_agentcore_envs) guide From a222e603e5989432cdfc0bc405e291815fdea41e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 5 Aug 2026 12:59:18 +0200 Subject: [PATCH 2/7] docs: re-argue AgentCore CI recommendation as build/release separation The previous version repeated the rationale from kosli-dev/docs#355: that `agentcore deploy` building the image server-side means "CI never produces an artifact it can attest, so there is nothing to match against what is running." That is wrong, and it was the load-bearing sentence of the section. `kosli attest artifact --artifact-type oci` resolves the digest from the registry manifest and does not care who built the image, so attesting the ECR image after `agentcore deploy` produces a fingerprint that matches the snapshot perfectly well. The real problem is ordering, not attribution. `agentcore deploy` builds the image and creates or updates the runtime in one CloudFormation operation, so there is no point at which the image exists and the runtime is not already pointed at it. Anything attested afterwards describes something already serving traffic: a policy reports a violation instead of preventing one, and scans and approvals land post-release. So the recommendation stands but the argument changes: post-hoc attestation buys an audit trail, separating build from release buys a gate. Both are now documented, with the tradeoff stated, which also makes the page a better answer to "how should we structure the pipeline". Cites AWS's own GitHub Actions reference pipeline as precedent - it builds and pushes to ECR from the Dockerfile, scans with Inspector, then creates the runtime from that image, and does not use `agentcore deploy`. Attesting to Kosli occupies the same slot as the scan. This reverses a decision recorded as settled in #355 and must be called out in the PR description rather than landing as a quiet edit. --- tutorials/report_agentcore_envs.md | 50 +++++++++++++++++++++++------- 1 file changed, 39 insertions(+), 11 deletions(-) diff --git a/tutorials/report_agentcore_envs.md b/tutorials/report_agentcore_envs.md index 0ffb021..bb1123b 100644 --- a/tutorials/report_agentcore_envs.md +++ b/tutorials/report_agentcore_envs.md @@ -17,12 +17,13 @@ produced it. This guide covers the two halves of that: -- **Build the agent image in your own CI and attest it**, so an artifact exists - in Kosli to compare against. +- **Attest the agent image before you release it**, so the evidence exists while + you can still act on it. - **Report the running AgentCore runtimes to Kosli** as an environment snapshot, so you can see what is actually serving. -The first half matters more than it looks, so start there. +How you structure the first half decides whether Kosli can gate a release or only +record it, so start there. ## Prerequisites @@ -63,17 +64,41 @@ scoping to specific runtime ARNs rather than `"Resource": "*"`. See [Security best practices for AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-security-best-practices.html). -## Build the image in CI, not in AWS +## Separate the build from the release The AgentCore CLI's `agentcore deploy` builds your container image **inside your -AWS account**. It provisions a CodeBuild project and builds from source there. +AWS account**: it provisions a CodeBuild project, builds from source there, and +creates or updates the runtime in the same operation. + +The problem is not that AWS did the building. You can attest an image you did not +build - `kosli attest artifact` with `--artifact-type oci` reads the digest from +the registry - so running it after `agentcore deploy` does produce an artifact in +Kosli whose fingerprint matches the snapshot. + +The problem is **when** the artifact becomes known. Because the build and the +runtime update are one operation, there is no point at which the image exists and +the runtime has not already been pointed at it. Anything you attest afterwards +describes something that is already serving traffic: + +- A Kosli policy on that artifact reports a violation instead of preventing one. +- Vulnerability scans, approvals, and test evidence all land post-release. +- Until you attest, the snapshot shows a running artifact Kosli has never seen, + which reads as a compliance gap that later resolves itself. + +Splitting build from release fixes all of that, and it's the pattern AWS itself +publishes for CI/CD: their +[GitHub Actions reference pipeline](https://aws.amazon.com/blogs/machine-learning/deploy-ai-agents-on-amazon-bedrock-agentcore-using-github-actions/) +builds and pushes the image to ECR from the Dockerfile, scans it with Amazon +Inspector, and only then creates the AgentCore runtime from that image. It does +not use `agentcore deploy`. Attesting to Kosli goes in the same slot as the scan. -That is convenient, and it breaks the chain you are trying to establish. If AWS -builds the image, your CI never produces an artifact, so there is nothing in -Kosli to compare the running runtime against. The snapshot tells you a digest is -running and nothing can tell you where it came from. - -Build the image yourself instead, and point AgentCore at it. + +If you are staying on `agentcore deploy` for now, attesting the ECR image +afterwards is still worth doing. You get a complete audit trail of what is +running and where it came from. What you do not get is the ability to stop a bad +build from reaching production, because by the time you can attest it, it is +already live. + @@ -111,6 +136,9 @@ Add whatever else your pipeline proves about this build with [`kosli attest`](/client_reference/kosli_attest_generic) - test results, scan results, approvals. That evidence is what makes the running agent auditable later. + +This is the step that has to happen before the release, not after it. Gate the +next step on it if you want the build blocked rather than merely recorded. From fdf0791fb4482be53afd07ad6e33fb9cab9f8d57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 5 Aug 2026 13:17:25 +0200 Subject: [PATCH 3/7] docs: sharpen the AgentCore configuration limitation The old version was one line saying configuration is not tracked, which undersells it. For ECS or Lambda the image is most of what the workload does, so a digest is a fair proxy for behavior. An AgentCore runtime is not like that: a role swap, a new EFS mount, a widened inbound auth audience or a changed model ID in an environment variable all change what the agent can do while the image digest stays identical. Names the four fields worth capturing first - roleArn, networkConfiguration, authorizerConfiguration, filesystemConfigurations - in a table with what a change to each one means, and calls out environmentVariables separately since it is the most decisive of the set but is marked sensitive in the AWS SDKs and must never be stored as values. Stated as "not yet" with the reason rather than as a roadmap commitment, since kosli-dev/docs#355 scopes configuration tracking out. Ends with the mitigation a reader can act on today: pin those fields in the IaC that creates the runtime and review changes there. Note filesystemConfigurations and requestHeaderConfiguration postdate the spike corpus, so the corpus is no longer a complete picture of the response. --- tutorials/report_agentcore_envs.md | 25 ++++++++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/tutorials/report_agentcore_envs.md b/tutorials/report_agentcore_envs.md index bb1123b..1700441 100644 --- a/tutorials/report_agentcore_envs.md +++ b/tutorials/report_agentcore_envs.md @@ -302,9 +302,28 @@ container-based runtimes only. If you deploy agents from code bundles today, moving to container builds is also what puts you on the CI-build-and-attest path described above. -**Agent configuration is not tracked.** A snapshot covers the image that is -running. Prompts, tool availability, and model choice are not part of the -fingerprint. +**Runtime configuration is not tracked yet, and for agents that gap is wider +than usual.** A snapshot covers the image digest. For an ECS service or a Lambda +function, the image or the code is most of what the workload does, so the digest +is a good proxy for its behavior. An AgentCore runtime is different: a lot of +what the agent can actually do lives in configuration that never touches the +image, and all of the following can change while the digest stays identical. + +| Field | What a change means | +| --- | --- | +| `roleArn` | The execution role. Swap it and the agent reaches different data. | +| `networkConfiguration` | `PUBLIC` or `VPC`, with subnets and security groups. Egress posture. | +| `authorizerConfiguration` | Inbound JWT auth, including allowed audience and clients. Its absence means the endpoint is unauthenticated. | +| `filesystemConfigurations` | Mounted EFS access points, S3 Files access points, and session storage. What persistent data the agent reads and writes. | + +`environmentVariables` belongs on that list too, and is often the most decisive +of all, since model IDs, tool endpoints, and sometimes prompts are passed that +way. It is also where secrets end up, and the AWS SDKs mark it sensitive, so it +needs different handling from the rest: a key set or a hash, never the values. + +Treat the digest as answering "which build is running", not "what is this agent +allowed to do". Until Kosli reports configuration, pin the fields above in the +infrastructure code that creates the runtime and review changes to them there. ## What you've accomplished From d30681208fff8aae4e082f4804d5229cf310a5bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 5 Aug 2026 13:20:30 +0200 Subject: [PATCH 4/7] docs: gather the AgentCore known gaps into one callout The page marked deferred work in four separate places: the top warning, a prerequisites aside, the CLI section warning and the Terraform note, plus the configuration limitation. Each marker is correct where it sits, but there was nowhere a reader could look to answer "what will this eventually do". Adds one at the end of Limitations collecting the four gaps, with a cross-reference to the Terraform section rather than restating it. This is the sixth callout on the page and CLAUDE.md says to use them sparingly, so it is justified only because it consolidates rather than adding another inline marker. Framed as direction with no order or dates implied. The page is already a specification for unbuilt work, and turning its gaps into an implied schedule would overpromise on something #355 has not scoped. --- tutorials/report_agentcore_envs.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/tutorials/report_agentcore_envs.md b/tutorials/report_agentcore_envs.md index 1700441..b56cf52 100644 --- a/tutorials/report_agentcore_envs.md +++ b/tutorials/report_agentcore_envs.md @@ -325,6 +325,19 @@ Treat the digest as answering "which build is running", not "what is this agent allowed to do". Until Kosli reports configuration, pin the fields above in the infrastructure code that creates the runtime and review changes to them there. + +**Known gaps, gathered in one place.** These are the limits described above and +elsewhere on this page, expected to close in later iterations. They are +direction rather than commitments, with no order or dates implied. + +- **Configuration reporting**, starting with the four fields in the table above. +- **CodeZip support**, once there is a fingerprint that cannot be silently wrong. +- **Terraform module support**, so reporting runs continuously instead of from + your own scheduled job. See [Report using Terraform module](#report-using-terraform-module). +- **`kosli snapshot agentcore` itself**, along with the `agentcore` environment + type. Nothing on this page runs until that ships. + + ## What you've accomplished You have an agent image built and attested in your own CI, and a Kosli From 1b232e76612e48a467c69f8f2f63972815bb8afb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 5 Aug 2026 13:28:24 +0200 Subject: [PATCH 5/7] docs: add a verification step to the AgentCore pipeline The page asserted that the running digest matches what CI attested but never showed how to confirm it. Adds a fourth step reading the snapshot back with `kosli get snapshot`, with the table output and the three columns that prove the pipeline is wired up: Fingerprint against the attested digest, FLOW and COMMIT for traceability, COMPLIANCE. Notes that Kosli stores the digest without its `sha256:` prefix, since the reader is comparing it by eye against what they pushed. Also names the failure signal: FLOW of N/A with NON-COMPLIANT means the image reached the runtime without being attested, which is what attesting after release looks like from the environment side. That makes the ordering argument earlier in the section concrete rather than theoretical. `kosli get snapshot` exists today so it needs no proposed marker, but it can only show an AgentCore snapshot once the reporter ships, and it depends on the reporting section below, so the step points there explicitly rather than leaving the order implicit. Drops `kosli get snapshot` from the closing list, where it is now redundant. --- tutorials/report_agentcore_envs.md | 44 +++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 4 deletions(-) diff --git a/tutorials/report_agentcore_envs.md b/tutorials/report_agentcore_envs.md index b56cf52..4e21623 100644 --- a/tutorials/report_agentcore_envs.md +++ b/tutorials/report_agentcore_envs.md @@ -172,10 +172,46 @@ has not yet run reporting against a runtime deployed this way end to end, so treat the invocation above as a starting point rather than a tested recipe. + + +Report the environment as described in +[Report using Kosli CLI](#report-using-kosli-cli), then read the snapshot back +with [`kosli get snapshot`](/client_reference/kosli_get_snapshot): + +```shell +kosli get snapshot agentcore-env-tutorial \ + --api-token \ + --org +``` + +``` +COMMIT ARTIFACT FLOW COMPLIANCE RUNNING_SINCE REPLICAS +a1b2c3d Name: my-agent my-agent COMPLIANT 2 minutes ago 1 + Fingerprint: 4f9c2b8e1d7a... +``` + +Three columns tell you whether the pipeline is wired up correctly: + +- **`Fingerprint`** matches the image you attested. Kosli stores the digest + without its `sha256:` prefix, so compare it against the hex part of the digest + you pushed. +- **`FLOW`** names the flow you attested to, and **`COMMIT`** the commit that + produced the image. This is the traceability the whole pipeline exists for. +- **`COMPLIANCE`** reads `COMPLIANT`. + +A `FLOW` of `N/A` alongside `NON-COMPLIANT` means Kosli has no record of the +running image: it reached the runtime without being attested first. That is the +exact failure the ordering in this section prevents, and it is what you would see +if you attested after releasing rather than before. + +Add `-o json` to assert on this from a pipeline rather than reading it by eye. +To look further back, `agentcore-env-tutorial~1` gets the previous snapshot and +`agentcore-env-tutorial#N` gets the Nth. + -Now the digest running in AgentCore is a digest your CI produced and attested, -and the environment snapshot below can be matched against it. +The digest running in AgentCore is now a digest your CI produced and attested, +and you have a way to prove it. ## Report using Kosli CLI @@ -346,7 +382,7 @@ agent changes, Kosli records it, and you can trace the running digest back to the commit that produced it. From here you can: -* Query your environment with [`kosli list snapshots`](/client_reference/kosli_list_snapshots) and [`kosli get snapshot`](/client_reference/kosli_get_snapshot) -* [Compare snapshots to see what changed](/client_reference/kosli_diff_snapshots) +* List an environment's history with [`kosli list snapshots`](/client_reference/kosli_list_snapshots) +* [Compare two snapshots to see what changed](/client_reference/kosli_diff_snapshots) * Trace a running artifact back to its git commit with the [From commit to production](/tutorials/following_a_git_commit_to_runtime_environments) tutorial * Report your other AWS workloads with the [Report AWS environments](/tutorials/report_aws_envs) guide From a77e0f3e85b80e1eb08a4f829e0aa186a2de4cee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 5 Aug 2026 13:39:09 +0200 Subject: [PATCH 6/7] docs: explain what REPLICAS means for AgentCore REPLICAS is len(creationTimestamp), which the server builds with one entry per running instance of an artifact: one per task for ECS, one per pod for K8s. An AgentCore reporter would emit one entry per runtime, so the column would read 1 for a single runtime while AgentCore may be running many session microVMs or none at all. Left unexplained it invites the reader to treat it as a concurrency count, which it is not for this environment type. Also records the consequence of grouping by fingerprint: two runtimes serving the same image collapse into one row, so their identity is lost. Added to the known gaps, since ECS and Cloud Run already solve this with a per-type context object on the artifact (task_arn/cluster_name/service_name and kind/service_name/revision_name), and AgentCore will need the equivalent to support one environment per account and region. --- tutorials/report_agentcore_envs.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tutorials/report_agentcore_envs.md b/tutorials/report_agentcore_envs.md index 4e21623..c88c622 100644 --- a/tutorials/report_agentcore_envs.md +++ b/tutorials/report_agentcore_envs.md @@ -199,6 +199,12 @@ Three columns tell you whether the pipeline is wired up correctly: produced the image. This is the traceability the whole pipeline exists for. - **`COMPLIANCE`** reads `COMPLIANT`. +`REPLICAS` needs care. It counts reported entries sharing one digest, which for +ECS is the number of tasks. AgentCore runs each session in its own microVM and +does not expose a count, so the number here is how many runtimes are on that +image, not how many instances are up. Rows are grouped by digest, so two +runtimes serving the same image appear as a single row with `REPLICAS: 2`. + A `FLOW` of `N/A` alongside `NON-COMPLIANT` means Kosli has no record of the running image: it reached the runtime without being attested first. That is the exact failure the ordering in this section prevents, and it is what you would see @@ -367,6 +373,8 @@ elsewhere on this page, expected to close in later iterations. They are direction rather than commitments, with no order or dates implied. - **Configuration reporting**, starting with the four fields in the table above. +- **Per-runtime identity in snapshots**, so two runtimes serving the same image + can be told apart instead of grouping into one row. - **CodeZip support**, once there is a fingerprint that cannot be silently wrong. - **Terraform module support**, so reporting runs continuously instead of from your own scheduled job. See [Report using Terraform module](#report-using-terraform-module). From 70163551f8051fa910ac9183d74ed20084774889 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Wed, 5 Aug 2026 13:55:38 +0200 Subject: [PATCH 7/7] docs: fix regex filter examples and name the AWS blog post Review feedback on #356. `prod-*` and `dev-*` are glob habits, not regexes. Verified with Go's regexp: `prod-*` compiles but means `prod-` followed by zero or more hyphens, so it also matches a runtime called `prod`. Corrected to `prod-.*` and `dev-.*`. Rather than only fixing the two examples, added a paragraph naming the trap: the `-regex` flags take Go regular expressions, not shell globs, they are unanchored, and `^`/`$` are needed for an exact match. The examples were copied from the CLI's own help text, so a reader arriving with the same assumption will make the same mistake on the next flag they reach. Also replaced the descriptive link text with the AWS post's actual title, so the reference is recoverable if the URL moves. --- tutorials/report_agentcore_envs.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/tutorials/report_agentcore_envs.md b/tutorials/report_agentcore_envs.md index c88c622..efcc628 100644 --- a/tutorials/report_agentcore_envs.md +++ b/tutorials/report_agentcore_envs.md @@ -86,8 +86,8 @@ describes something that is already serving traffic: which reads as a compliance gap that later resolves itself. Splitting build from release fixes all of that, and it's the pattern AWS itself -publishes for CI/CD: their -[GitHub Actions reference pipeline](https://aws.amazon.com/blogs/machine-learning/deploy-ai-agents-on-amazon-bedrock-agentcore-using-github-actions/) +publishes for CI/CD. Their reference pipeline +[Deploy AI agents on Amazon Bedrock AgentCore using GitHub Actions](https://aws.amazon.com/blogs/machine-learning/deploy-ai-agents-on-amazon-bedrock-agentcore-using-github-actions/) builds and pushes the image to ECR from the Dockerfile, scans it with Amazon Inspector, and only then creates the AgentCore runtime from that image. It does not use `agentcore deploy`. Attesting to Kosli goes in the same slot as the scan. @@ -255,15 +255,20 @@ environment: kosli snapshot agentcore agentcore-env-tutorial --runtimes runtime1,runtime2 ... # include runtimes matching a pattern -kosli snapshot agentcore agentcore-env-tutorial --runtimes-regex "prod-*" ... +kosli snapshot agentcore agentcore-env-tutorial --runtimes-regex "prod-.*" ... # exclude runtimes matching a pattern -kosli snapshot agentcore agentcore-env-tutorial --exclude-regex "dev-*" ... +kosli snapshot agentcore agentcore-env-tutorial --exclude-regex "dev-.*" ... ``` All filtering is case-sensitive. Include and exclude flags are mutually exclusive. +The `-regex` flags take Go regular expressions, not shell globs, and they are +unanchored. Write `prod-.*` rather than `prod-*`: the latter is valid but means +`prod-` followed by any number of hyphens, so it also matches a runtime called +`prod`. Anchor with `^` and `$` when you want an exact match. + ## How Kosli fingerprints an agent Kosli records the **image digest**, not the URI AgentCore hands back.