|
1 | 1 | --- |
2 | 2 | name: onboard-repo |
3 | 3 | description: >- |
4 | | - Onboard a new GitHub repository to the ABCA platform by adding a Blueprint CDK |
5 | | - construct. Use when the user says "onboard a repo", "add a repository", |
6 | | - "register a repo", "new repo", "Blueprint construct", "REPO_NOT_ONBOARDED error", |
7 | | - or gets a 422 error about an unregistered repository. |
| 4 | + Onboard a new GitHub repository to the ABCA platform so the agent can target it. |
| 5 | + Use when the user says "onboard a repo", "add a repository", "register a repo", |
| 6 | + "new repo", or gets a `REPO_NOT_ONBOARDED` / 422 error about an unregistered |
| 7 | + repository. |
8 | 8 | --- |
9 | 9 |
|
10 | 10 | # Repository Onboarding |
11 | 11 |
|
12 | | -You are guiding the user through onboarding a new GitHub repository to ABCA. Repositories must be registered as `Blueprint` constructs in the CDK stack before tasks can target them. |
| 12 | +You are helping an **operator** register a GitHub repository with their running ABCA |
| 13 | +deployment so tasks can target it. |
13 | 14 |
|
14 | | -## Step 1: Gather Repository Details |
| 15 | +There are two paths. |
15 | 16 |
|
16 | | -Use AskUserQuestion to collect: |
17 | | -- **Repository**: GitHub `owner/repo` format |
18 | | -- **Compute type**: `agentcore` (default) or `ecs` |
19 | | -- **Model preference**: Claude Sonnet 4 (default), Claude Opus 4 (complex repos), or Claude Haiku (lightweight). **Important:** Models must be specified using their cross-region inference profile ID (e.g. `us.anthropic.claude-opus-4-20250514-v1:0`), not the raw foundation model ID. On-demand invocation of raw model IDs is not supported for most models. |
20 | | -- **Max turns**: Default 100 (range: 1-500) |
21 | | -- **Max budget**: USD cost ceiling per task (optional) |
22 | | -- **Custom GitHub PAT**: If this repo needs a different token than the platform default |
| 17 | +**Prefer the CLI operator path (Path A)** when the repo can run on the |
| 18 | +**platform/default-blueprint** setup — the default GitHub token secret, a model |
| 19 | +already granted to the runtime, and the default egress allowlist. It's a single |
| 20 | +runtime command against the deployed stack: no code change, no redeploy. |
23 | 21 |
|
24 | | -## Step 2: Read the Current Stack |
| 22 | +**Use the CDK Blueprint path (Path B)** when the repo needs its **own** config that |
| 23 | +the CLI can't provision at runtime — a per-repo GitHub token, a model not yet |
| 24 | +granted to the runtime, custom egress domains, Cedar HITL policies, or |
| 25 | +system-prompt overrides. These are baked into infrastructure and require a redeploy |
| 26 | +(with the correct permissions). When in doubt, start with Path A; if a task later |
| 27 | +fails on a missing token / model grant / blocked egress, promote the repo to a |
| 28 | +Blueprint. |
25 | 29 |
|
26 | | -Read the CDK stack file to understand existing Blueprint definitions: |
| 30 | +> **This is an operation, not a contribution.** Onboarding a repo into your own |
| 31 | +> deployment writes a record to the platform's RepoTable — it is **not** a change to |
| 32 | +> the `aws-samples` codebase, so the ADR-003 contribution flow (GitHub issue → |
| 33 | +> approval → feature branch) does **not** apply. Only invoke ADR-003 if the user is |
| 34 | +> actually changing the platform source (e.g. wiring a brand-new Bedrock model into |
| 35 | +> the stack — see "Model not yet wired into the runtime" below). |
27 | 36 |
|
28 | | -``` |
29 | | -Read cdk/src/stacks/agent.ts |
30 | | -``` |
| 37 | +## Gather repository details |
31 | 38 |
|
32 | | -Identify: |
33 | | -- Where existing Blueprint constructs are defined |
34 | | -- The `repoTable` reference used |
35 | | -- Any patterns for compute/model overrides |
| 39 | +Use AskUserQuestion to collect (only the repository is required — the rest fall back to platform defaults): |
36 | 40 |
|
37 | | -### Sample blueprint repo without a code change |
| 41 | +- **Repository** — GitHub `owner/repo`. Must match exactly what's passed to `bgagent submit --repo` later. |
| 42 | +- **Compute type** — `agentcore` (default) or `ecs`. |
| 43 | +- **Model** — default is the platform model (Sonnet 4.6). If overriding, it must be a model **already granted to the runtime** (see "Model not yet wired into the runtime"), specified as a cross-Region **inference-profile ID** (e.g. `us.anthropic.claude-sonnet-4-6`), not a raw `anthropic.*` foundation-model ID. |
| 44 | +- **Max turns** — default 100 (range 1–500). |
| 45 | +- **Per-repo GitHub token** — only if this repo needs a different token than the platform default (provide its Secrets Manager ARN). |
38 | 46 |
|
39 | | -The stack’s **AgentPlugins** blueprint uses a `repo` value resolved in this order: **`BLUEPRINT_REPO`** (environment variable) → CDK context **`blueprintRepo`** → default `awslabs/agent-plugins` (see `blueprintRepo` in `cdk/src/stacks/agent.ts`). If the user only needs to target a fork of the sample repo, they can set `export BLUEPRINT_REPO=owner/repo` or pass `-c blueprintRepo=owner/repo` (or set `"context": { "blueprintRepo": "..." }` in `cdk/cdk.json`) and redeploy, instead of adding a new `Blueprint` construct. |
| 47 | +> **Per-task cost limits aren't set here.** `max_budget` / `max_turns` *per task* are flags on `bgagent submit` (the `submit-task` skill), not repo-onboarding fields. Onboarding sets only the per-repo **default** `max_turns`. |
40 | 48 |
|
41 | | -## Step 3: Add the Blueprint Construct |
| 49 | +If the repo needs config the CLI can't provision (per-repo egress, Cedar policies, system-prompt overrides, or a not-yet-granted model), use **Path B** instead. |
42 | 50 |
|
43 | | -Add a new `Blueprint` construct instance to the stack. Follow the existing pattern. Example: |
| 51 | +## Path A — CLI operator onboarding (default) |
44 | 52 |
|
45 | | -```typescript |
46 | | -new Blueprint(this, 'MyRepoBlueprint', { |
47 | | - repo: 'owner/repo', |
48 | | - repoTable: repoTable.table, |
49 | | - // Optional overrides: |
50 | | - // computeType: 'agentcore', |
51 | | - // modelId: 'us.anthropic.claude-sonnet-4-20250514-v1:0', |
52 | | - // maxTurns: 100, |
53 | | - // maxBudgetUsd: 50, |
54 | | - // runtimeArn: runtime.runtimeArn, |
55 | | - // githubTokenSecretArn: 'arn:aws:secretsmanager:...', |
56 | | -}); |
| 53 | +`bgagent repo onboard` writes (or re-activates) the repository's `RepoConfig` row in |
| 54 | +the deployed RepoTable directly. It takes effect immediately — **no `agent.ts` edit, |
| 55 | +no `cdk deploy`.** |
| 56 | + |
| 57 | +```bash |
| 58 | +bgagent repo onboard <owner/repo> |
| 59 | +# common overrides: |
| 60 | +# --model <inference-profile-id> e.g. us.anthropic.claude-sonnet-4-6 (must be runtime-granted) |
| 61 | +# --compute-type <agentcore|ecs> |
| 62 | +# --max-turns <n> per-repo default turn limit |
| 63 | +# --token-secret-arn <arn> per-repo GitHub token (else platform default) |
| 64 | +# --runtime-arn <arn> override AgentCore runtime ARN (agentcore only) |
| 65 | +# --poll-interval <ms> agent completion poll interval |
57 | 66 | ``` |
58 | 67 |
|
59 | | -Use a descriptive construct ID derived from the repo name. |
| 68 | +Then confirm it landed: |
60 | 69 |
|
61 | | -### Model ID and IAM Permissions |
| 70 | +```bash |
| 71 | +bgagent repo list # status should be "active" |
| 72 | +bgagent repo show <owner/repo> # full resolved config (secret ARNs redacted) |
| 73 | +``` |
62 | 74 |
|
63 | | -When specifying a non-default model via `agent.modelId`, three things are required: |
| 75 | +That's it — the repo is onboarded. Submit a task with the `submit-task` skill. |
64 | 76 |
|
65 | | -1. **Use the inference profile ID, not the raw model ID, when Bedrock requires it.** For `InvokeModel` / streaming, specify the cross-Region **inference profile** identifier (or ARN) where the Bedrock User Guide calls for it — not only the bare `anthropic.*` foundation model ID. Examples: |
66 | | - - Sonnet 4.6 (US geography profile): `us.anthropic.claude-sonnet-4-6` |
67 | | - - Sonnet 4: `us.anthropic.claude-sonnet-4-20250514-v1:0` |
68 | | - - Opus 4: `us.anthropic.claude-opus-4-20250514-v1:0` |
69 | | - - Haiku 4.5: `us.anthropic.claude-haiku-4-5-20251001-v1:0` |
| 77 | +**Pick a model that is already wired into the runtime.** With no `--model`, the repo |
| 78 | +uses the platform default (Sonnet 4.6). If you pass `--model`, use a cross-Region |
| 79 | +**inference profile ID** (e.g. `us.anthropic.claude-sonnet-4-6`), not a raw |
| 80 | +`anthropic.*` foundation-model ID. Only models the stack has granted the runtime can |
| 81 | +be invoked — see "Model not yet wired into the runtime" before choosing a model the |
| 82 | +deployment doesn't already support. |
70 | 83 |
|
71 | | - See [Use an inference profile in model invocation](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-use.html). |
| 84 | +## Path B — CDK Blueprint (declarative / canonical) |
72 | 85 |
|
73 | | -2. **Grant the runtime IAM permissions for the model.** The Blueprint construct does not automatically grant `bedrock:InvokeModel*` — this is by design (least privilege). You must add a `grantInvoke` block in the stack for each model used: |
74 | | - ```typescript |
75 | | - const opusModel = new bedrock.BedrockFoundationModel('anthropic.claude-opus-4-20250514-v1:0', { |
76 | | - supportsAgents: true, |
77 | | - supportsCrossRegion: true, |
78 | | - }); |
79 | | - opusModel.grantInvoke(runtime); |
| 86 | +Use this when the operator wants the repo committed to infrastructure-as-code (so a |
| 87 | +fresh deploy re-creates it) rather than set as a runtime record. This **does** require |
| 88 | +editing the stack and redeploying. |
80 | 89 |
|
81 | | - const opusProfile = bedrock.CrossRegionInferenceProfile.fromConfig({ |
82 | | - geoRegion: bedrock.CrossRegionInferenceProfileRegion.US, |
83 | | - model: opusModel, |
| 90 | +1. Read `cdk/src/stacks/agent.ts` to find where `Blueprint` constructs are defined and |
| 91 | + the `repoTable` reference. |
| 92 | +2. Add a construct following the existing pattern: |
| 93 | + |
| 94 | + ```typescript |
| 95 | + new Blueprint(this, 'MyRepoBlueprint', { |
| 96 | + repo: 'owner/repo', |
| 97 | + repoTable: repoTable.table, |
| 98 | + // Optional overrides: |
| 99 | + // computeType: 'agentcore', |
| 100 | + // modelId: 'us.anthropic.claude-sonnet-4-6', |
| 101 | + // maxTurns: 100, |
| 102 | + // maxBudgetUsd: 50, |
| 103 | + // githubTokenSecretArn: 'arn:aws:secretsmanager:...', |
84 | 104 | }); |
85 | | - opusProfile.grantInvoke(runtime); |
86 | 105 | ``` |
87 | 106 |
|
88 | | -3. **Account-level Bedrock model access (separate from IAM).** The runtime role must be allowed to invoke the model, and the **AWS account** must be able to use that model in Bedrock: complete [model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) prerequisites (AWS Marketplace actions on first serverless use where applicable, Anthropic first-time use / `PutUseCaseForModelAccess` for Anthropic models, valid payment method for Marketplace-backed models). For geographic cross-Region inference profiles, IAM and SCPs must allow Bedrock in **source and destination** Regions per [Supported Regions and models for inference profiles](https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html). |
89 | | - |
90 | | -## Step 4: Deploy |
| 107 | +3. Redeploy: `mise //cdk:compile` → `mise //cdk:diff` (show the diff) → `mise //cdk:deploy -- --require-approval never`. |
91 | 108 |
|
92 | | -After adding the Blueprint, the stack must be redeployed: |
| 109 | +> **Sample-repo shortcut:** the stack's AgentPlugins blueprint resolves its `repo` from |
| 110 | +> `BLUEPRINT_REPO` (env) → CDK context `blueprintRepo` → default `awslabs/agent-plugins`. |
| 111 | +> To target a fork of the sample without adding a construct, set |
| 112 | +> `export BLUEPRINT_REPO=owner/repo` (or `cdk.json` context) and redeploy. |
93 | 113 |
|
94 | | -```bash |
95 | | -export MISE_EXPERIMENTAL=1 |
96 | | -mise //cdk:compile # Verify TypeScript compiles |
97 | | -mise //cdk:test # Run tests |
98 | | -mise //cdk:diff # Preview changes |
99 | | -``` |
| 114 | +## Model not yet wired into the runtime (the one real code change) |
100 | 115 |
|
101 | | -Show the diff to the user. If it looks correct, ask if they want to deploy now. |
| 116 | +A repo can only use a model the **runtime IAM role has `grantInvoke` for**. As of now |
| 117 | +the stack wires **Sonnet 4.6, Opus 4 (`claude-opus-4-20250514`), and Haiku 4.5** (see |
| 118 | +the `grantInvoke` block in `agent.ts`). Onboarding a repo pinned to any **other** model |
| 119 | +(e.g. Opus 4.8 / `us.anthropic.claude-opus-4-8`) will fail at invoke with a 403 — the |
| 120 | +CLI onboard succeeds, but tasks can't run. |
102 | 121 |
|
103 | | -```bash |
104 | | -mise //cdk:deploy |
105 | | -``` |
| 122 | +Adding a new model **is** a platform source change, so it follows ADR-003 (issue → |
| 123 | +approval → feature branch) and requires: |
106 | 124 |
|
107 | | -## Step 5: Verify |
108 | | - |
109 | | -After deployment, verify the repo config was written to DynamoDB: |
| 125 | +1. **Wire the model + inference profile and grant the runtime**, in `agent.ts`: |
| 126 | + ```typescript |
| 127 | + const model = new bedrock.BedrockFoundationModel('anthropic.claude-opus-4-8', { |
| 128 | + supportsAgents: true, |
| 129 | + supportsCrossRegion: true, |
| 130 | + }); |
| 131 | + model.grantInvoke(runtime); |
| 132 | + const profile = bedrock.CrossRegionInferenceProfile.fromConfig({ |
| 133 | + geoRegion: bedrock.CrossRegionInferenceProfileRegion.US, |
| 134 | + model, |
| 135 | + }); |
| 136 | + profile.grantInvoke(runtime); |
| 137 | + ``` |
| 138 | + then redeploy. |
| 139 | +2. **Account-level Bedrock model access** (separate from IAM): the account must have the |
| 140 | + model enabled for the Region — complete [model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) |
| 141 | + prerequisites (Marketplace actions / Anthropic first-time use where applicable). For |
| 142 | + cross-Region profiles, IAM and SCPs must allow Bedrock in source **and** destination |
| 143 | + Regions. |
110 | 144 |
|
111 | | -```bash |
112 | | -aws dynamodb scan --table-name <RepoTableName> \ |
113 | | - --filter-expression "repo = :r" \ |
114 | | - --expression-attribute-values '{":r":{"S":"owner/repo"}}' \ |
115 | | - --output json |
116 | | -``` |
| 145 | +If the user just wants the agent working now, steer them to a wired model (Sonnet 4.6) |
| 146 | +via Path A and treat "add model X" as a separate, later change. |
117 | 147 |
|
118 | | -## Per-Repository Configuration Reference |
| 148 | +## Per-repository configuration reference |
119 | 149 |
|
120 | 150 | | Setting | Purpose | Default | |
121 | 151 | |---------|---------|---------| |
122 | 152 | | `compute_type` | Execution strategy | `agentcore` | |
123 | 153 | | `runtime_arn` | AgentCore runtime override | Platform default | |
124 | | -| `model_id` | AI model for tasks | Platform default (Sonnet 4) | |
| 154 | +| `model_id` | AI model for tasks (inference profile ID) | Platform default (Sonnet 4.6) | |
125 | 155 | | `max_turns` | Turn limit per task | 100 | |
126 | 156 | | `max_budget_usd` | Cost ceiling per task | Unlimited | |
127 | 157 | | `system_prompt_overrides` | Custom system instructions | None | |
128 | 158 | | `github_token_secret_arn` | Repo-specific GitHub token | Platform default | |
129 | 159 | | `poll_interval_ms` | Completion polling frequency | 30000ms | |
130 | 160 |
|
131 | | -Task-level parameters override Blueprint defaults. If neither specifies a value, platform defaults apply. |
| 161 | +Task-level parameters override per-repo defaults; if neither specifies a value, platform defaults apply. |
132 | 162 |
|
133 | | -## Common Issues |
| 163 | +## Common issues |
134 | 164 |
|
135 | | -- **422 "Repository not onboarded"** — Blueprint hasn't been deployed yet. Add the construct and redeploy. |
136 | | -- **Preflight failures after onboarding** — GitHub PAT may lack permissions for the new repo. Check the PAT's fine-grained access includes the target repository with Contents (read/write) and Pull requests (read/write) permissions. |
137 | | -- **400 "Invocation with on-demand throughput isn't supported"** — The Blueprint `modelId` is using a raw foundation model ID instead of an inference profile ID. Change e.g. `anthropic.claude-opus-4-20250514-v1:0` to `us.anthropic.claude-opus-4-20250514-v1:0`. |
138 | | -- **403 "not authorized to perform bedrock:InvokeModelWithResponseStream"** — The runtime IAM role lacks permissions for the model specified in the Blueprint. Add `grantInvoke` for both the model and its cross-region inference profile in `agent.ts`. |
139 | | -- **Model not available / "not available on your Bedrock deployment"** — IAM is not the whole story: the account must meet [Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html) for that model family and Region, and `modelId` should be an **enabled** inference profile ID (for example `us.anthropic.claude-sonnet-4-6`) where Bedrock requires it. After fixing access in the console, align Blueprint / DynamoDB `model_id` and redeploy if you change IAM grants. |
| 165 | +- **`REPO_NOT_ONBOARDED` / 422** — the repo isn't registered. Run `bgagent repo onboard <owner/repo>` (Path A). Confirm the `owner/repo` matches exactly what you pass to `bgagent submit --repo`. |
| 166 | +- **Preflight failure after onboarding** — the GitHub PAT lacks access to the new repo. Ensure the token has Contents (read/write) + Pull requests (read/write) on it, or onboard with a repo-specific `--token-secret-arn`. |
| 167 | +- **400 "Invocation with on-demand throughput isn't supported"** — `model_id` is a raw foundation-model ID; use the inference-profile ID (e.g. `us.anthropic.claude-sonnet-4-6`). |
| 168 | +- **403 "not authorized to perform bedrock:InvokeModelWithResponseStream"** — the repo's model isn't wired into the runtime. See "Model not yet wired into the runtime." |
| 169 | +- **Model not available / "not available on your Bedrock deployment"** — account-level Bedrock access isn't enabled for that model/Region (separate from IAM); complete [model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html), then use an enabled inference-profile ID. |
0 commit comments