agentcore

Files (38)

• SKILL.md
• README.md · assets/iam-policies/
• agentcore-runtime-execution-role-permissions.json · assets/iam-policies/
• agentcore-runtime-execution-role-trust.json · assets/iam-policies/
• VERIFIED.md · assets/poc-cve-verify/
• agentcore-commands.sh · assets/poc-cve-verify/
• agentcore.json · assets/poc-cve-verify/
• harness.json · assets/poc-cve-verify/app/cve_triage/
• SKILL.md · assets/poc-cve-verify/app/cve_triage/skills/cve-triage/
• system-prompt.md · assets/poc-cve-verify/app/cve_triage/
• Dockerfile · assets/poc-cve-verify/app/cve_verify/
• main.py · assets/poc-cve-verify/app/cve_verify/
• __init__.py · assets/poc-cve-verify/app/cve_verify/model/
• load.py · assets/poc-cve-verify/app/cve_verify/model/
• pyproject.toml · assets/poc-cve-verify/app/cve_verify/
• runtime-metadata.json · assets/poc-cve-verify/app/cve_verify/
• query-cve-agent.sh · assets/poc-cve-verify/app/cve_verify/scripts/
• migration-report.md · assets/poc-cve-verify/
• cve_triage.json · assets/poc-cve-verify/registry/
• cve_verify.json · assets/poc-cve-verify/registry/
• evals.json · evals/
• agentcore-mappings.md · references/
• deployment-checklist.md · references/
• harness.md · references/
• migration-modes.md · references/
• migration.md · references/
• security-iam.md · references/
• source-formats.md · references/
• Dockerfile.tmpl · references/templates/
• agentcore.json.tmpl · references/templates/
• harness.json.tmpl · references/templates/
• registry-record.json.tmpl · references/templates/
• runtime-metadata.json.tmpl · references/templates/
• generate_project.py · scripts/
• invoke_harness.py · scripts/
• preflight_check.py · scripts/
• scan_configs.py · scripts/
• test_prompt_promotion.py · scripts/

SKILL.md (first lines)

# AgentCore

Build, deploy, operate, and migrate AI agents on Amazon Bedrock AgentCore. The `agentcore` CLI (npm `@aws/agentcore`) manages the full lifecycle via CDK/CloudFormation.

There are **two ways to run an agent**:

| Mode | What it is | When |
|---|---|---|
| **Harness** (default since GA, June 2026) | Declarative managed agent: `harness.json` = model + tools + skills + memory + limits. No agent code, no container. `agentcore create --defaults` creates one. | Persona + skills + standard tools cover the need |
| **Runtime** (code agent) | Your code (Strands/LangChain/ADK/OpenAI/VercelAI) deployed as CodeZip or Container | Custom orchestration, custom tool logic, middleware |

Start with a harness; `agentcore export harness` converts it to editable Strands code later if you outgrow the config (one-way door: code, unlike config, is yours to maintain).

## Key Concepts

| Term | Meaning |
|---|---|
| **Harness** | First-class AWS resource (`CreateHarness`/`UpdateHarness`/`InvokeHarness`): a fully managed agent defined by config. In a CLI project: `agentcore.json → harnesses[]` + `app/<name>/harness.json` + `system-prompt.md` |
| **Runtime** | A deployed code agent — `agentcore.json → runtimes[]`, code in `app/<name>/` |
| **Gateway** | MCP tool router — routes agent tool calls to MCP servers, Lambda, API Gateway, HTTP passthrough, inference providers, web-search connector |
| **Identity** | Secret vault — API keys and OAuth credentials; can reference existing AWS Secrets Manager ARNs |
| **Memory** | Managed memory — strategies: SEMANTIC, SUMMARIZATION, USER_PREFERENCE, EPISODIC |
| **Registry** | Private catalog of agents/tools/skills with approval workflow |

## Prerequisites

Run the bundled preflight before any workflow:

```bash
python3 scripts/preflight_check.py
```

Checks: Python ≥ 3.10, Node.js ≥ 20, **uv** (required for Python agents), AWS CLI + credentials, `agentcore` CLI ≥ 0.22 (`npm install -g @aws/agentcore`; upgrade with `agentcore update`), `bedrock-agentcore-control` namespace. Docker only for Container builds.

## Core Lifecycle

```bash
agentcore create --defaults        # New project with a default harness (interactive wizard without flags)
agentcore dev                      # Local dev server + browser-based agent inspector
agentcore validate                 # Validate agentcore/ config files
agentcore deploy                   # Deploy via CDK → CloudFormation stack AgentCore-<project>-default
agentcore invoke --harness <name> "test"    # or --runtime <name> for code agents
agentcore logs / traces / status   # Observability
agentcore exec -- <cmd>            # Shell into a deployed agent container
```

Non-interactive create (all flags marked `[non-interactive]` in `--help`):

```bash
agentcore create --name <harness> --project-name <proj> --defaults \
  --skip-git --output-dir <dir>
```

Project layout (ground truth, CLI 0.22.0):

```
<project>/
├── AGENTS.md                 # AI-assistant context written by the CLI
├── agentcore/
│   ├── agentcore.json        # Flat resource arrays: runtimes[], harnesses[], memories[], credentials[], agentCoreGateways[], ...
│   ├── aws-targets.json      # ARRAY of {name, account (12-digit string), region}
│   ├── .env.local            # Gitignored secrets
│   ├── .llm-context/         # TypeScript schema types — the schema authority; read these before editing JSON by hand
│   └── cdk/                  # CDK project (deps installed by create unless --skip-install)
└── app/
    ├── <harness>/            # harness.json + system-prompt.md (no code)
    └── <agent>/              # main.py, pyproject.toml, model/, skills/, mcp_client/ (code agent)
```

## Harness Workflows

Add/manage harnesses, tools, skills, memory; export to code. See `references/harness.md` for commands, `harness.json` schema, and skill sources (`--path`/`--s3`/`--git`/`--aws-skills`).

```bash
agentcore add harness --name <n> --system-prompt "<text>" [--tools ...] [--memory-mode managed ...]
agentcore add skill --harness <n> --path <dir>        # skill dir with SKILL.md
agentcore add tool  --harness <n> --type remote_mcp --name <t> --url <mcp-url>
agentcore export harness --name <n> | --arn <arn>     # → editable Strands agent under app/
```

## Migration from coding assistants

Migrate agents/skills/MCP/hooks from 15 assistant formats (Claude Code, Copilot, Cursor, …) to AgentCore. **REQUIRED:** follow `references/migration.md` — discovery scan, mapping rules, harness-first generation, deploy. Supporting docs: `references/source-formats.md` (detection), `references/agentcore-mappings.md` (mapping rules), `references/migration-modes.md` (deploy/teardown/errors).

```bash
python3 scripts/scan_configs.py --repo-root <path> --format json   # → migration-inventory.json
python3 scripts/generate_project.py --inventory migration-inventory.json --output-dir ./agentcore-project --region us-east-1
```

## Key Rules

- **Harness-first** — agents that are persona + skills + standard tools become harnesses (config), not code. Generate code runtimes only for custom logic.
- **`.llm-context/` is the schema authority** — when editing `agentcore.json`/`harness.json` by hand, conform to the TypeScript types there, then `agentcore validate`.
- **Never put secrets in generated files** — API keys → Identity credentials (`agentcore add credential`), or reference an existing Secrets Manager ARN. Non-secrets → `envVars`.
- **Renaming a resource destroys and recreates it** — the `name` field is the CloudFormation logical ID.
- **`agentcore create` makes a NESTED `./<project-name>/` scaffold** — it does not initialize in place. For pre-generated configs: create with `--no-agent`, then copy `agentcore.json`/`aws-targets.json`/`app/` into the scaffold. The scaffold includes CDK `node_modules` (unless `--skip-install`); if deploy fails with `tsc: not found`, run `npm install` in `agentcore/cdk/`.
- **Don't `add agent` for runtimes already in `agentcore.json`** — fails with "already exists". `add` commands are for adding NEW resources.
- **aws-targets.json is a JSON array** — `[{"name","account","region"}]`, `account` is the 12-digit ID string (not `accountId`).
- **Naming**: harness/agent names alphanumeric+underscores, start with letter, ≤48 chars; project names alphanumeric only, ≤23 chars; gateway names alphanumeric+hyphens.
- **Default model is Claude** — harness default `global.anthropic.claude-sonnet-4-6`; code-agent template uses `global.anthropic.claude-sonnet-4-5-20250929-v1:0`. Nova (`amazon.nova-lite-v1:0`) remains a fallback if Anthropic model access isn't enabled in the account.
- **Streaming is the default entrypoint pattern** — `async for event in agent.stream_async(...): yield event` (the CLI's own template). The old "non-streaming only" workaround is obsolete.
- **Read EXPORT_NOTES.md after `export harness`** — it lists manual follow-ups the exporter couldn't automate.
- **Test with simple prompts first** — verify deploy works before complex prompts.

## Resolved Blockers (May → July 2026)

Limitations documented by earlier migrations that AWS has since fixed — do not re-apply old workarounds:

| Old blocker | Current state |
|---|---|
| Console-created harnesses locked (no `update-harness` API) | Harness GA: `UpdateHarness` API exists; `agentcore export harness --arn <arn>` converts any harness (incl. Console-created) to a CLI-managed code agent |
| Skills mountable only via Console UI | `agentcore add skill --harness <n> --path/--s3/--git/--aws-skills` |
| HITL gates had no mechanism | Gateway **elicitation pass-through** (form/URL modes); Step Functions harness integration with approval steps |
| Claude required use-case form; Nova Lite forced default | Claude Sonnet is the CLI default; LiteLLM + Bedrock Mantle add more providers |
| Streaming `yield` broke CLI display | Fixed — streaming is the default template pattern |
| Secrets had to be copied into Identity vault | Identity credential providers can reference existing Secrets Manager ARNs |

## Error Handling

From LeonMelamud/agentcore-toolkit, MIT.

More from LeonMelamud/agentcore-toolkit