Skip to content

QUICK_START.mdx

Latest commit

 

History

History
575 lines (382 loc) · 31.6 KB

QUICK_START.mdx

File metadata and controls

575 lines (382 loc) · 31.6 KB
Raw
title Quick start

import { Tabs, TabItem } from '@astrojs/starlight/components';

Quick start

Go from zero to your first agent-created pull request in about 30 minutes. This guide covers only the minimum path - see the Developer guide and User guide for the full details.

Steps 4–6 offer ABCA CLI and AWS CLI tabs on each step (ABCA CLI is the default). Steps 4–5 share the same tab choice; Step 6 uses a separate tab group because submit adds a REST API call via curl on the AWS CLI path.

Prerequisites

Install these before you begin:

  • AWS account with credentials configured (aws configure). If you use named profiles, set AWS_PROFILE before running any commands in this guide.
  • Amazon Bedrock — The agent invokes Claude through Bedrock. IAM grantInvoke in the CDK stack is required but not sufficient: your account must also satisfy Amazon Bedrock model access for the model you use (including Anthropic first-time use where applicable, Marketplace subscription flow on first serverless use, and a valid payment method for Marketplace-backed models). See Amazon Bedrock before your first task after Step 3.
  • Docker - for building the agent container image. On an x86_64 host you also need QEMU/binfmt to build the arm64 (Graviton) image — see the caution in Step 3.
  • Node.js v20 or later (Node 24 is the supported maximum — see CI matrix)
  • mise - task runner (install guide)
  • AWS CDK CLI - npm install -g aws-cdk (after mise is active)
  • GitHub account — You need a GitHub profile to fork the sample repository and create a fine-grained personal access token (PAT) the agent uses to push branches and open pull requests. A free github.com account is sufficient.

:::note[mise provisions Node, Yarn, and the CDK CLI for you]

If a prerequisite check reports Node, Yarn, and CDK as "not found" all at once, your environment isn't broken — mise installs those tool versions in Step 1, so they only appear on PATH after mise install + shell activation. A few mise gotchas worth knowing up front:

  • Non-interactive / spawned shells (CI, scripts, some agent runners) don't pick up mise's shell hook, so mise/node/yarn may not be on PATH. Use the full path ~/.local/bin/mise or prefix commands with mise exec --.
  • Headless Linux (EC2, containers) often lacks a working gpg-agent, so mise install can fail Node on GPG signature verification. If so, run mise settings set node.gpg_verify false (downloads are still checksum-verified) and retry.
  • Two trust prompts: you may need to mise trust both the project mise.toml and your user-global ~/.config/mise/config.toml if you change a global setting.

:::

Step 1 - Clone and install

This project uses mise to manage tool versions (Node.js, Python, security scanners) and run tasks across the monorepo. Yarn Classic handles JavaScript workspaces (cdk/, cli/, docs/).

git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git
cd sample-autonomous-cloud-coding-agents

# Trust mise config and install tools
mise trust
mise install

# Enable Yarn via Corepack
corepack enable
corepack prepare yarn@1.22.22 --activate

# Install dependencies and build
export MISE_EXPERIMENTAL=1
mise run install
mise run build

mise run install installs all JavaScript and Python dependencies across the monorepo. mise run build compiles the CDK app, the CLI, the agent image, and the docs site. A successful build means you are ready to deploy.

:::note[Expect noisy build output — trust the exit code]

mise run build prints many ERROR/WARN lines, cdk-nag warnings, and sometimes A worker process has failed to exit gracefully. These are benign — test fixtures deliberately exercise failure paths. The only reliable success signal is the exit code: 0 means the build passed. Don't be alarmed by the log volume.

:::

:::note[ABCA CLI commands in this guide]

This Quick Start does not assume a global bgagent install (npm install -g …). Step 1 compiles the CLI into cli/lib/. On every ABCA CLI tab below, run from the cli/ directory:

cd cli then node lib/bin/bgagent.js <command> …

If lib/bin/bgagent.js is missing, run mise run build from cli/ (or repeat Step 1's full build from the repo root).

:::

Note: mise run build includes CDK synthesis, which queries AWS for availability zones. Your active AWS credentials must have at least ec2:DescribeAvailabilityZones permission, or the build will fail. If you use named profiles, make sure AWS_PROFILE is set before running the build.

Step 2 - Prepare a repository

The agent works by cloning a GitHub repository, creating a branch, making code changes, running the build and tests, and opening a pull request. This means it needs write access to a real repository you control.

The Quick Start uses awslabs/agent-plugins — a lightweight sample repo designed for testing the platform. You must fork it to your own GitHub account before continuing; do not point the platform at the upstream awslabs/agent-plugins repo unless you have direct write access there (most users do not).

:::danger[Fork the sample repo — do not skip]

The agent pushes branches and opens pull requests on whichever owner/repo you register in the Blueprint. If you skip forking and keep the default awslabs/agent-plugins name, or your PAT is scoped to a different repository, tasks fail with permission errors that look like platform bugs but are really a repo/token mismatch.

:::

Fork the sample repository

  1. Sign in to GitHub and open github.com/awslabs/agent-plugins.
  2. Click Fork (top-right), choose your personal account (or an organization you admin), and confirm.
  3. Wait for the fork to finish. Your copy lives at https://github.com/<your-username>/agent-plugins.
  4. Note the owner/repo slug — for example jane-doe/agent-plugins. You will use this exact string in CDK context, the PAT repository scope, and every submit --repo … command in Step 6.

Register your fork in CDK

Every repository the agent can work on must be onboarded as a Blueprint construct in the CDK stack. The Blueprint writes a configuration record to DynamoDB; the orchestrator checks this before accepting tasks.

For the sample AgentPlugins blueprint, cdk/src/stacks/agent.ts resolves the GitHub owner/repo in this order: the BLUEPRINT_REPO environment variable, then CDK context blueprintRepo, then the default awslabs/agent-plugins:

const blueprintRepo = process.env.BLUEPRINT_REPO ?? this.node.tryGetContext('blueprintRepo') ?? 'awslabs/agent-plugins';
const agentPluginsBlueprint = new Blueprint(this, 'AgentPluginsBlueprint', {
  repo: blueprintRepo,
  repoTable: repoTable.table,
});

Recommended: add your fork to cdk/cdk.json so the value is checked in and you do not have to export an environment variable in every shell session. Edit cdk/cdk.json and add a "context" block (create it if missing):

{
  "app": "npx ts-node -P tsconfig.json --prefer-ts-exts src/main.ts",
  "context": {
    "blueprintRepo": "your-username/agent-plugins"
  }
}

Replace your-username/agent-plugins with the slug from your fork in the previous step.

After changing cdk.json, recompile the CDK app so the updated context is picked up before deploy:

export MISE_EXPERIMENTAL=1
mise //cdk:compile

You can also run a full mise run build (includes compile). Then deploy in Step 3 with mise //cdk:deploy. If you already deployed once with the wrong repo name, edit cdk.json and redeploy — the Blueprint updates the DynamoDB record on stack update.

Alternatively, for a one-off deploy without editing cdk.json:

export BLUEPRINT_REPO=your-username/agent-plugins

Or pass context on the command line: cdk deploy -c blueprintRepo=your-username/agent-plugins. The environment variable wins over context when both are set.

The resolved repo value must match exactly what you pass to the CLI later (owner/repo format). To onboard additional repositories, add more Blueprint constructs in agent.ts and redeploy (see Onboard your own repositories below).

Create a GitHub personal access token

The agent authenticates to GitHub using a fine-grained personal access token (PAT). Go to GitHub → Settings → Developer settings → Fine-grained tokens → Generate new token.

:::caution[Scope the token to your fork]

Under Repository access, choose Only select repositories and pick the fork you created above (your-username/agent-plugins). Do not scope the token to awslabs/agent-plugins unless you own that upstream repo. The token repository must match the blueprintRepo value you set in cdk/cdk.json (or BLUEPRINT_REPO).

:::

Grant these permissions on that repository:

Permission Access Why
Contents Read and write Clone the repo and push branches
Pull requests Read and write Create and update pull requests
Issues Read Read issue context for tasks that reference an issue
Metadata Read (default) Required by GitHub for all fine-grained tokens

Keep the token value — you will store it in AWS Secrets Manager in Step 4.

:::note[Already configured your fork?]

If you have not yet added blueprintRepo to cdk/cdk.json, go back to Register your fork in CDK, set "blueprintRepo": "your-username/agent-plugins", run mise //cdk:compile, and redeploy before submitting tasks. The PAT, Blueprint repo name, and --repo argument in Step 6 must all refer to the same fork.

:::

:::note[Collaborator or cross-org repos?]

Fine-grained tokens only work for repos you own (or orgs that have opted in). If you're a collaborator on someone else's repo, create a classic PAT with repo + read:org scopes instead. See agent/README.md for details.

:::

Step 3 - Deploy

The CDK stack deploys the full platform: API Gateway, Lambda functions (orchestrator, task CRUD, webhooks), DynamoDB tables, AgentCore Runtime, VPC with network isolation, Cognito user pool, and CloudWatch dashboards.

# Bootstrap CDK (first time only)
mise //cdk:bootstrap

# Deploy the stack (~10 minutes). --require-approval never lets it run
# unattended; drop the flag if you want to review IAM/security-group changes.
mise //cdk:deploy -- --require-approval never

CDK bootstrap provisions the staging resources CDK needs (S3 bucket, IAM roles). The deploy itself takes around 10 minutes — most of the time is spent building the Docker image and provisioning the AgentCore Runtime.

:::caution[Building on an x86 host? Register arm64 emulation first.]

The agent runs on AgentCore (Graviton / arm64), so the container image is built for linux/arm64. On an x86_64 build host (most cloud dev boxes, many laptops), the image build fails partway with exec /bin/sh: exec format error unless QEMU emulation is registered:

docker run --privileged --rm tonistiigi/binfmt --install arm64

If docker run --privileged is blocked on your host (common on security-managed machines), build from a native arm64 host instead (Graviton EC2 or Apple Silicon) — no emulation needed. Apple Silicon and other arm64 hosts can skip this step entirely. Note that the emulated build is noticeably slower than a native one.

:::

:::note[X-Ray → CloudWatch Logs tracing is optional — skip it for your first deploy.]

The stack ships with X-Ray span export to CloudWatch Logs disabled (tracingEnabled in cdk/src/stacks/agent.ts), so the platform deploys and runs fully without any X-Ray account setup. You do not need to run aws xray update-trace-segment-destination to get a working deployment.

If you later enable tracing, it needs a one-time per-account setup — and on a security-managed AWS Organization account an SCP may block the X-Ray service from writing to aws/spans entirely (the update-trace-segment-destination call returns AccessDeniedException no matter what the deploying identity does; that's an Org-level policy, not a setup mistake). Treat tracing as an opt-in extra, not a prerequisite. See the Developer Guide for the enable steps.

:::

Amazon Bedrock before your first task

The stack grants the AgentCore runtime bedrock:InvokeModel* on the foundation models and cross-Region inference profiles declared in cdk/src/stacks/agent.ts (grantInvoke). That covers IAM only.

You must also be able to invoke the model in Bedrock from your account (and Region):

  1. Access and subscription — Bedrock serverless foundation models are used with the right IAM and, for third-party models, AWS Marketplace permissions; first-time subscription can take up to several minutes. Missing prerequisites often surface as AccessDeniedException. See Request access to models in the Bedrock User Guide.
  2. Anthropic first-time use — For Anthropic models, submit use-case details once per account (console model catalog or PutUseCaseForModelAccess) before invocation, as described in the same guide (unless you use the documented bedrock-mantle exception).
  3. Inference profile as modelId — For InvokeModel / streaming, pass the inference profile ID or ARN where Bedrock requires it (for example us.anthropic.claude-sonnet-4-6 for US cross-Region Sonnet 4.6). See Use an inference profile in model invocation.
  4. Cross-Region routing — System-defined inference profiles can route across Regions within a geography. IAM (and any SCPs) must allow the profile and underlying model in all relevant Regions; see Supported Regions and models for inference profiles.

If a task fails immediately with text like the model is not available on your Bedrock deployment, open the Bedrock console model catalog for your deployment Region, complete access steps for that model family, align the repo model_id (DynamoDB / Blueprint) and runtime IAM with an enabled inference profile, then redeploy and retry.

Step 4 - Store the GitHub token

The agent reads the GitHub PAT from AWS Secrets Manager at runtime. The CDK stack created an empty secret for you - now you need to put your token value in it. Replace ghp_your_token_here with the actual token from Step 2. Make sure REGION matches where you deployed - if it is empty, the AWS CLI builds a malformed endpoint URL and fails silently.

cd cli

REGION=us-east-1  # your deployment region

# Interactive prompt — stores in the platform GitHubTokenSecretArn output
node lib/bin/bgagent.js github set-token --region "$REGION" --stack-name backgroundagent-dev

For a repository with a per-blueprint token secret (credentials.githubTokenSecretArn on the Blueprint), target that repo instead:

cd cli

node lib/bin/bgagent.js github set-token --region "$REGION" --repo your-org/your-repo
REGION=us-east-1  # your deployment region

SECRET_ARN=$(aws cloudformation describe-stacks \
  --stack-name backgroundagent-dev \
  --region "$REGION" \
  --query 'Stacks[0].Outputs[?OutputKey==`GitHubTokenSecretArn`].OutputValue | [0]' \
  --output text)

aws secretsmanager put-secret-value \
  --region "$REGION" \
  --secret-id "$SECRET_ARN" \
  --secret-string "ghp_your_token_here"

Step 5 - Create a Cognito user

The REST API uses Amazon Cognito for authentication. Self-signup is disabled, so an operator must create users (AWS credentials with cognito-idp:AdminCreateUser and cognito-idp:AdminSetUserPassword on the pool — no ABCA CLI configure required yet). The pool requires the username to be a valid email, a password of at least 12 characters mixing uppercase, lowercase, digits, and symbols, and the user's email to be pre-verified.

cd cli

REGION=us-east-1  # your deployment region (same as Step 4)

# Creates the user, sets a permanent password, and writes credentials + configure bundle
# to ~/.bgagent/invites/you@example.com.txt (mode 0600)
node lib/bin/bgagent.js admin invite-user you@example.com \
  --region "$REGION" \
  --stack-name backgroundagent-dev

The command wraps AdminCreateUser + AdminSetUserPassword: email is pre-verified, the welcome email is suppressed (avoids SES errors on new accounts), and the password is permanent (no forced change on first login). When stack outputs are available, the invite file also includes a configure bundle for Step 6.

To manage users later:

cd cli

node lib/bin/bgagent.js admin list-users --region "$REGION" --stack-name backgroundagent-dev
node lib/bin/bgagent.js admin reset-password you@example.com --region "$REGION"
node lib/bin/bgagent.js admin delete-user someone@example.com --region "$REGION"

Requires the AWS CLI with credentials that can call cognito-idp:Admin* on the deployment user pool. No ABCA CLI build or node lib/bin/bgagent.js invocation is needed on this path.

REGION=us-east-1  # your deployment region (same as Step 4)

USER_POOL_ID=$(aws cloudformation describe-stacks --stack-name backgroundagent-dev \
  --region "$REGION" \
  --query 'Stacks[0].Outputs[?OutputKey==`UserPoolId`].OutputValue' --output text)

aws cognito-idp admin-create-user \
  --region "$REGION" \
  --user-pool-id $USER_POOL_ID \
  --username you@example.com \
  --user-attributes Name=email,Value=you@example.com Name=email_verified,Value=true \
  --temporary-password 'TempPass123!@' \
  --message-action SUPPRESS

aws cognito-idp admin-set-user-password \
  --region "$REGION" \
  --user-pool-id $USER_POOL_ID \
  --username you@example.com \
  --password 'YourPerm@nent1Pass!' \
  --permanent

The first command creates the user with a temporary password, pre-verifies the email (required or login fails with User is not confirmed), and suppresses Cognito's welcome email (which otherwise errors on accounts without SES configured). The second sets a permanent password so you do not have to go through a password change flow on first login. Remember the password you set — you will need it in Step 6.

Step 6 - Configure and submit a task

Authenticate, then submit your first task. A typical simple task takes 2-5 minutes. When it completes, you will see a PR URL — open it in your browser to review the agent's work.

The ABCA CLI handles Cognito authentication, token caching, and output formatting.

cd cli

REGION=us-east-1  # your deployment region (same as Step 4)

# After Step 5 invite-user: paste the bundle from ~/.bgagent/invites/you@example.com.txt
node lib/bin/bgagent.js configure --from-bundle "<paste bundle from invite file>"

# Or read ApiUrl / UserPoolId / AppClientId from CloudFormation (same as `platform outputs`)
node lib/bin/bgagent.js configure --region "$REGION" --stack-name backgroundagent-dev

# Log in (password from ~/.bgagent/invites/you@example.com.txt)
node lib/bin/bgagent.js login --username you@example.com

# Submit your first task and wait for it to complete
node lib/bin/bgagent.js submit \
  --repo your-username/agent-plugins \
  --task "Add a CODEOWNERS file to the repository root" \
  --wait

The --wait flag polls until the task reaches a terminal state. You can still pass --api-url, --user-pool-id, or --client-id to override individual stack outputs.

Uses the AWS CLI for Cognito authentication and curl for the task REST API. Use the password you set in Step 5 (YourPerm@nent1Pass! if you followed the AWS CLI tab there). Requires curl and the AWS CLI — no ABCA CLI build.

REGION=us-east-1  # your deployment region (same as Step 4)

API_URL=$(aws cloudformation describe-stacks --stack-name backgroundagent-dev \
  --region "$REGION" \
  --query 'Stacks[0].Outputs[?OutputKey==`ApiUrl`].OutputValue' --output text)
APP_CLIENT_ID=$(aws cloudformation describe-stacks --stack-name backgroundagent-dev \
  --region "$REGION" \
  --query 'Stacks[0].Outputs[?OutputKey==`AppClientId`].OutputValue' --output text)

TOKEN=$(aws cognito-idp initiate-auth \
  --region "$REGION" \
  --client-id "$APP_CLIENT_ID" \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=you@example.com,PASSWORD='YourPerm@nent1Pass!' \
  --query 'AuthenticationResult.IdToken' --output text)

curl -X POST "$API_URL/tasks" \
  -H "Authorization: $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "your-username/agent-plugins",
    "task_description": "Add a CODEOWNERS file to the repository root"
  }'

Poll task status until COMPLETED (or a terminal failure state):

curl "$API_URL/tasks/<TASK_ID>" -H "Authorization: $TOKEN"

See User guide → Using the REST API for list, cancel, and events endpoints.

ABCA CLI-only helpers after submit — use watch to stream progress events in real time:

cd cli

node lib/bin/bgagent.js watch <TASK_ID>

While a task is running, you can steer the agent with a nudge:

cd cli

node lib/bin/bgagent.js nudge <TASK_ID> "Also add a test for the edge case"

Step 7 - See an approval gate in action

If your blueprint defines any Cedar HITL policies tagged @tier("soft"), the agent pauses on matching tool calls and waits for your decision. This step walks through the flow end-to-end. Run the commands below from the cli/ directory (cd cli from the repo root).

First, check which rules apply to your repo:

cd cli

node lib/bin/bgagent.js policies list --repo owner/repo

Submit a task that will plausibly trip a soft-deny rule — for example, one of the default blueprint rules guards force-pushes:

cd cli

node lib/bin/bgagent.js submit --repo owner/repo \
  --task "Force-push the feature branch so the history is linear"

In a second terminal, watch the task:

cd cli

node lib/bin/bgagent.js watch <TASK_ID>

When the agent hits the guarded tool call, watch prints an approval_requested event and the task status flips to AWAITING_APPROVAL. List the pending approval:

cd cli

node lib/bin/bgagent.js pending

The output includes ready-to-run approve/deny lines. Pick one:

cd cli

# Approve just this call
node lib/bin/bgagent.js approve <TASK_ID> <REQUEST_ID>

# Or deny with a reason that nudges the agent toward a safer approach
node lib/bin/bgagent.js deny <TASK_ID> <REQUEST_ID> \
  --reason "Don't force-push shared branches; open a revert PR instead"

The task transitions back to RUNNING immediately on a decision. The denial reason is injected into the agent's context so it can adapt rather than retry the same tool call. If no decision arrives within the rule's timeout (300 s by default), the gate is treated as a denial with timed_out as the reason.

If you want a task to run without interactive gates (e.g. an unattended overnight job), pre-approve the scopes you trust up-front:

cd cli

node lib/bin/bgagent.js submit --repo owner/repo --issue 42 \
  --pre-approve tool_type:Bash \
  --pre-approve write_path:tests/**

Hard-deny rules (no @tier("soft") annotation) are always enforced — --pre-approve only short-circuits soft-deny rules. For the full command reference see User guide — Approval gates; for authoring your own rules see the Cedar policy guide.

What happened behind the scenes

Here is what the platform did after you ran node lib/bin/bgagent.js submit:

  1. Task creation - The CLI authenticated via Cognito and sent a POST /v1/tasks request. The API validated the request, checked idempotency, and stored a task record in DynamoDB with status SUBMITTED.
  2. Orchestration - The durable orchestrator picked up the task and ran admission control (concurrency limits). It then ran pre-flight checks - calling the GitHub API to verify your token can access the repository with push permissions. If the token were read-only, the task would have failed here with a clear error instead of failing later inside the agent.
  3. Context hydration - The orchestrator assembled the agent's prompt: your task description, any repository memory from past tasks, and the system prompt that defines the agent's behavioral contract. The task transitioned to HYDRATING.
  4. Agent execution - An isolated MicroVM started via AgentCore Runtime. The agent cloned your repository, created a branch (bgagent/<task-id>/<description-slug>), made the requested changes, ran mise run build to verify the build passes, committed incrementally, and opened a pull request. The task transitioned to RUNNING.
  5. Finalization - The orchestrator detected the agent finished, recorded the PR URL, cost, and duration on the task record, and transitioned to COMPLETED.

Common errors

Error Cause Fix
yarn: command not found Corepack not enabled or mise not activated in your shell Run eval "$(mise activate zsh)", then corepack enable && corepack prepare yarn@1.22.22 --activate
MISE_EXPERIMENTAL required Namespaced tasks need the experimental flag export MISE_EXPERIMENTAL=1
exec /bin/sh: exec format error during image build x86 host building the arm64 (Graviton) agent image without QEMU/binfmt Run docker run --privileged --rm tonistiigi/binfmt --install arm64, or build from a native arm64 host (see Step 3 caution)
AccessDeniedException on update-trace-segment-destination X-Ray → CloudWatch Logs tracing is optional and the call may be SCP-blocked on Org accounts Skip it — tracing is disabled by default and not required to deploy (see Step 3 note)
mise run build fails with ec2:DescribeAvailabilityZones error AWS credentials missing or insufficient for CDK synth Set AWS_PROFILE or configure credentials with at least EC2 read access
CDK deploy prompts for approval and hangs Non-interactive terminal (CI/CD, scripts) Pass --require-approval never to cdk deploy (Step 3 uses it) or use an interactive terminal
Deploy rolled back; can't redeploy (ROLLBACK_COMPLETE) A first-create failure leaves the stack un-updatable mise //cdk:destroy (or delete the stack), then deploy again. Do not force-delete past stuck VPC resources — it orphans the VPC, and VPCs are quota-capped per Region
Stack stuck in DELETE_FAILED on a security group / subnet AgentCore's service-managed (Hyperplane) ENIs reclaim asynchronously after the runtime is gone Wait ~20–40 min for AWS to release the ENIs, then retry mise //cdk:destroy. You cannot force-detach an amazon-aws-owned ENI
put-secret-value returns double-dot endpoint REGION variable is empty Set REGION=us-east-1 (or your actual region) before running the command
Model / Bedrock errors in logs (not available on your bedrock, zero tokens) Model not entitled for the account or Region, wrong modelId shape, or missing Marketplace / FTU steps Follow Amazon Bedrock before your first task above; confirm model access and use an inference profile ID such as us.anthropic.claude-sonnet-4-6 where required; keep grantInvoke in agent.ts aligned with that model
REPO_NOT_ONBOARDED on task submit Blueprint repo does not match what you passed to the CLI Confirm BLUEPRINT_REPO, CDK context blueprintRepo, or the repo prop on the Blueprint in cdk/src/stacks/agent.ts resolves to exactly the same owner/repo you pass to the CLI
INSUFFICIENT_GITHUB_REPO_PERMISSIONS PAT is missing required permissions or is scoped to the wrong repo Regenerate the PAT with Contents (read/write) and Pull requests (read/write) scoped to your fork, then update Secrets Manager
Task stuck in SUBMITTED Orchestrator Lambda may not have been invoked Check CloudWatch logs for the orchestrator Lambda; verify the stack deployed successfully
node: command not found in cli/ mise shell activation missing Run eval "$(mise activate zsh)" and confirm node --version shows v22.x

Customizing the platform

Once you have the basic flow working, here are the main ways to customize the platform for your needs.

Onboard your own repositories

Add more Blueprint constructs in cdk/src/stacks/agent.ts and redeploy. Each Blueprint registers one repository. You can onboard as many repos as you want - each one gets its own configuration record in DynamoDB.

new Blueprint(this, 'MyServiceBlueprint', {
  repo: 'my-org/my-service',
  repoTable: repoTable.table,
});

Per-repo configuration

Blueprints accept optional overrides to customize agent behavior per repository: which model to use, how many turns the agent gets, cost budget limits, extra system prompt instructions, and network egress rules. See the User guide - Per-repo overrides for the full list.

new Blueprint(this, 'CustomBlueprint', {
  repo: 'my-org/my-service',
  repoTable: repoTable.table,
  agent: {
    modelId: 'us.anthropic.claude-sonnet-4-6',
    maxTurns: 50,
    systemPromptOverrides: 'Always write tests. Use conventional commits.',
  },
});

Add a CLAUDE.md to your repository

The agent automatically loads project-level instructions from CLAUDE.md at the repository root (or .claude/CLAUDE.md). This is the most effective way to improve agent output for a specific repo - tell it your build commands, coding conventions, architecture boundaries, and constraints. See the Prompt guide for examples and best practices.

Set up webhook integrations

Webhooks let external systems (GitHub Actions, CI pipelines) create tasks without Cognito credentials, using HMAC-SHA256 authentication. This is useful for automating PR review on every PR, or triggering code changes from CI events. See the User guide - Webhooks for setup instructions.

Next steps

Run from the cli/ directory (cd cli from the repo root):

  • Try an issue-based task: node lib/bin/bgagent.js submit --repo owner/repo --issue 42
  • Iterate on a PR: node lib/bin/bgagent.js submit --repo owner/repo --pr 1
  • Review a PR: node lib/bin/bgagent.js submit --repo owner/repo --review-pr 1
  • Pick a workflow explicitly: node lib/bin/bgagent.js submit --repo owner/repo --task "..." --workflow coding/new-task-v1 — see User guide - Workflows
  • Watch a task live: node lib/bin/bgagent.js watch <TASK_ID> — stream progress events
  • Steer a running task: node lib/bin/bgagent.js nudge <TASK_ID> "focus on tests" — mid-run guidance
  • Enable tracing: node lib/bin/bgagent.js submit --repo owner/repo --issue 42 --trace then node lib/bin/bgagent.js trace download <TASK_ID>
  • Manage webhooks: node lib/bin/bgagent.js webhook create --name "My CI" — automate task submission from external systems
  • Run locally first: Test with ./agent/run.sh before deploying - see the Developer guide