AWS bedrock-agentcore documentation change
Summary
Major restructuring and simplification of the AgentCore CLI getting started guide, including reorganization of prerequisites, addition of preview channel information, consolidation of steps, and renaming 'Add resources' to 'Add capabilities' with updated content.
Security assessment
The changes are primarily structural and instructional improvements to the documentation. There is no evidence of addressing a specific security vulnerability, weakness, or incident. The update includes routine documentation improvements such as clarifying prerequisites, adding information about preview features, and streamlining instructions. The only security-related change is updating the IAM permissions link from a GitHub repository to an official AWS documentation page (security-iam.html), which is a routine documentation maintenance activity rather than addressing a security issue.
Diff
diff --git a/bedrock-agentcore/latest/devguide/agentcore-get-started-cli.md b/bedrock-agentcore/latest/devguide/agentcore-get-started-cli.md index 8b5d04fc2..1d3ac708c 100644 --- a//bedrock-agentcore/latest/devguide/agentcore-get-started-cli.md +++ b//bedrock-agentcore/latest/devguide/agentcore-get-started-cli.md @@ -7 +7 @@ -PrerequisitesStep 1: Install the AgentCore CLIStep 2: Create your projectStep 3: Test locallyStep 4: Deploy your agentStep 5: Invoke your deployed agentAdd resources to your projectView logs and tracesClean upNext steps +PrerequisitesStep 1: Install the AgentCore CLIStep 2: Create your projectStep 3: Test locallyStep 4: Deploy your agentStep 5: Invoke your deployed agentAdd capabilities to your projectView logs and tracesClean upNext steps @@ -11 +11 @@ PrerequisitesStep 1: Install the AgentCore CLIStep 2: Create your projectStep 3: -This quickstart gets you from zero to a running agent in under five minutes using the [AgentCore CLI](https://github.com/aws/agentcore-cli) . You will install the CLI, scaffold a project, test locally, deploy to AgentCore Runtime, and invoke your agent. +This quickstart gets you from zero to a running agent in a few minutes using the AgentCore CLI. You will install the CLI, scaffold a project, test locally, deploy to AWS, and invoke your agent. @@ -13,13 +13 @@ This quickstart gets you from zero to a running agent in under five minutes usin -## Prerequisites - -Before you begin, make sure you have the following: - - * **Node.js 20 or later** – The AgentCore CLI is distributed as an npm package and requires Node.js. Check your version: - - node --version - -If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/). - - * **npm** – Included with Node.js. Used to install the CLI globally. - - * **An AWS account with credentials configured** – The CLI uses your AWS credentials to deploy infrastructure and invoke agents. Configure credentials using the AWS CLI, environment variables, or an AWS profile. For more information, see [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). +Two ways to build an agent on AgentCore, same CLI: @@ -27 +15 @@ If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/ - * **Python 3.10 or later** (for agent code) – Agent code generated by the CLI is written in Python. Check your version: + * **Code-based agent** (default, GA). You write the agent loop in Python using a framework you already know (Strands, LangGraph, Google ADK, or OpenAI Agents), and deploy it to AgentCore Runtime. Full control over orchestration logic. @@ -29 +17 @@ If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/ - python3 --version + * **Managed harness** (preview). You declare the agent in a config file (model, prompt, tools, memory) and AgentCore runs the loop for you. No framework, no orchestration code. Good path when you want the fastest route from idea to a running agent. [Learn more](./harness.html). @@ -31 +18,0 @@ If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/ - * **IAM permissions** – Your AWS identity needs permissions to make AgentCore API calls and to assume the CDK bootstrap roles used during deployment. The CLI interacts with AWS in two ways: direct SDK calls (invoking agents, tailing logs, checking status) that use your credentials, and CDK deployments where assumes a separate execution role to provision infrastructure. For ready-to-use IAM policy documents covering both, see [AgentCore CLI IAM Permissions](https://github.com/aws/agentcore-cli/blob/main/docs/PERMISSIONS.md) . For general AgentCore permissions, see [IAM Permissions for AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html). @@ -34,0 +22 @@ If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/ +This page walks through the code-based flow. For harness, see [What is the AgentCore harness](./harness.html). @@ -36 +24 @@ If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/ -## Step 1: Install the AgentCore CLI +## Prerequisites @@ -38 +26 @@ If you need to install or update Node.js, visit [nodejs.org](https://nodejs.org/ -Install the CLI globally using npm: + * **Node.js 20 or later.** The AgentCore CLI is distributed as an npm package. Check with `node --version`. Install from [nodejs.org](https://nodejs.org) if needed. @@ -39,0 +28 @@ Install the CLI globally using npm: + * **npm.** Included with Node.js. @@ -41 +30 @@ Install the CLI globally using npm: - npm install -g @aws/agentcore + * **An AWS account with credentials configured.** Configure via AWS CLI, environment variables, or an AWS profile. See [Configuring the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html). @@ -43 +32 @@ Install the CLI globally using npm: -Verify the installation: + * **Python 3.10 or later** (for agent code). Check with `python3 --version`. @@ -44,0 +34 @@ Verify the installation: + * **IAM permissions.** Your identity needs permissions to make AgentCore API calls and to assume the CDK bootstrap roles used during deployment. See [AgentCore CLI IAM Permissions](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/security-iam.html). @@ -46 +35,0 @@ Verify the installation: - agentcore --version @@ -48 +36,0 @@ Verify the installation: -To update the CLI to the latest version later, run the same install command again or use: @@ -51,3 +39 @@ To update the CLI to the latest version later, run the same install command agai - agentcore update - -For the source code and to report issues, see the [agentcore-cli GitHub repository](https://github.com/aws/agentcore-cli). +## Step 1: Install the AgentCore CLI @@ -55 +40,0 @@ For the source code and to report issues, see the [agentcore-cli GitHub reposito -## Step 2: Create your project @@ -57 +42 @@ For the source code and to report issues, see the [agentcore-cli GitHub reposito -Create a new project using the `create` command. You can use command-line flags or the interactive wizard: + npm install -g @aws/agentcore @@ -59 +44 @@ Create a new project using the `create` command. You can use command-line flags -###### Example +Verify: @@ -61 +45,0 @@ Create a new project using the `create` command. You can use command-line flags -AgentCore CLI @@ -62,0 +47 @@ AgentCore CLI + agentcore --version @@ -64 +49 @@ AgentCore CLI - 1. Use the `--defaults` flag to generate a Python agent using the Strands Agents SDK with Amazon Bedrock as the model provider: +To update later, rerun the install command or `agentcore update`. Source and issues: [agentcore-cli on GitHub](https://github.com/aws/agentcore-cli). @@ -66 +51 @@ AgentCore CLI - agentcore create --name MyAgent --defaults +### Opt into the preview channel @@ -67,0 +53 @@ AgentCore CLI +To access preview capabilities (harness, config-based agents, in-progress features), install the preview channel: @@ -69,0 +56 @@ AgentCore CLI + npm install -g @aws/agentcore@preview @@ -71 +58 @@ AgentCore CLI -Interactive +The preview channel is the same CLI with preview features enabled. Stable commands behave identically. See [What is the AgentCore harness](./harness.html) for what the preview unlocks. @@ -72,0 +60 @@ Interactive +## Step 2: Create your project @@ -74 +61,0 @@ Interactive - 1. Run `agentcore create` without flags to launch the interactive wizard: @@ -78,9 +65 @@ Interactive - 2. Enter your project name: - - - - 3. Choose your agent framework and model provider: - - - - 4. Review your configuration and confirm: +The interactive wizard asks you for: @@ -88 +67 @@ Interactive - + * **Framework** \- Strands Agents (recommended), LangChain/LangGraph, Google Agent Development Kit, or OpenAI Agents SDK @@ -89,0 +69 @@ Interactive + * **Model provider** \- Amazon Bedrock, Anthropic, OpenAI, or Gemini @@ -90,0 +71 @@ Interactive + * **Memory** \- None, short-term only, or long-term and short-term @@ -91,0 +73 @@ Interactive + * **Build type** \- CodeZip (default) or Container @@ -93 +74,0 @@ Interactive -The interactive mode lets you choose from the following options: @@ -95 +75,0 @@ The interactive mode lets you choose from the following options: - * **Framework** – Strands Agents, LangChain/LangGraph, Google Agent Development Kit (ADK), or OpenAI Agents SDK @@ -97 +76,0 @@ The interactive mode lets you choose from the following options: - * **Model provider** – Amazon Bedrock, Anthropic, OpenAI, or Gemini @@ -99 +78 @@ The interactive mode lets you choose from the following options: - * **Memory** – None, short-term only, or long-term and short-term +You can also pass flags directly: @@ -101 +79,0 @@ The interactive mode lets you choose from the following options: - * **Build type** – CodeZip (default) or Container @@ -102,0 +81,6 @@ The interactive mode lets you choose from the following options: + agentcore create \ + --name MyAgent \ + --framework Strands \ + --model-provider Bedrock \ + --memory none \ + --build CodeZip @@ -103,0 +88 @@ The interactive mode lets you choose from the following options: +###### Note @@ -104,0 +90 @@ The interactive mode lets you choose from the following options: +**Preview alternative.** With the preview CLI installed, you can scaffold a config-based [harness](./harness.html) instead of a code-based agent. The CLI surfaces this as a choice in the wizard. Harness is the fastest path to a running agent because there is no framework or orchestration code to write. @@ -108 +94 @@ The interactive mode lets you choose from the following options: -After running `agentcore create` , the CLI generates the following project structure: +`agentcore create` generates: @@ -122,7 +108 @@ After running `agentcore create` , the CLI generates the following project struc -The key files are: - - * **agentcore/agentcore.json** – The main configuration file. It defines your agents, memory stores, and credentials. The CLI manages this file when you run `agentcore add` or `agentcore remove` commands. - - * **app/** – Contains your agent code. Each agent has its own subdirectory with a `main.py` entrypoint and a `pyproject.toml` for dependencies. - - * **agentcore/aws-targets.json** – Defines the AWS account and region for deployment. +Key files: @@ -129,0 +110 @@ The key files are: + * `agentcore/agentcore.json` \- the main config. Defines your agents, memory stores, gateways, credentials, and other resources. Managed by `agentcore add` and `agentcore remove`. @@ -130,0 +112 @@ The key files are: + * `app/` \- your agent code. Each agent gets its own subdirectory with an entrypoint and a `pyproject.toml`. @@ -131,0 +114 @@ The key files are: + * `agentcore/aws-targets.json` \- the AWS account and region for deployment. @@ -133 +115,0 @@ The key files are: -The following example shows a typical `agentcore.json` generated by the defaults: @@ -136,27 +117,0 @@ The following example shows a typical `agentcore.json` generated by the defaults - { - "name": "MyAgent", - "version": 1, - "tags": { - "agentcore:created-by": "agentcore-cli", - "agentcore:project-name": "MyAgent" - }, - "agents": [ - { - "type": "AgentCoreRuntime", - "name": "MyAgent", - "build": "CodeZip", - "entrypoint": "main.py", - "codeLocation": "app/MyAgent/", - "runtimeVersion": "PYTHON_3_13", - "networkMode": "PUBLIC", - "modelProvider": "Bedrock", - "protocol": "HTTP" - } - ], - "memories": [], - "credentials": [], - "evaluators": [], - "onlineEvalConfigs": [], - "agentCoreGateways": [], - "policyEngines": [] - } @@ -166 +120,0 @@ The following example shows a typical `agentcore.json` generated by the defaults -Before deploying, test your agent locally using the development server. Change into your project directory and start the dev server: @@ -168,6 +122 @@ Before deploying, test your agent locally using the development server. Change i -###### Example - -AgentCore CLI - - - 1. cd MyAgent + cd MyAgent @@ -175,0 +125 @@ AgentCore CLI +`agentcore dev` creates a Python virtual environment, installs dependencies, starts a local server with hot reload, and opens the **agent inspector** in your browser so you can chat with the agent, inspect traces, and browse project resources. Code changes are picked up automatically. @@ -176,0 +127 @@ AgentCore CLI +Useful flags: @@ -177,0 +129 @@ AgentCore CLI + * `--no-browser` \- use the terminal-based TUI instead of the browser inspector. @@ -179,39 +131 @@ AgentCore CLI -Interactive - - - 1. Run `agentcore` to open the TUI home screen, then select **dev** to start the local development server: