# Get started with Amazon Bedrock AgentCore
<a name="agentcore-get-started-cli"></a>

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.

## Prerequisites
<a name="agentcore-cli-prerequisites"></a>

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).
+  **Python 3.10 or later** (for agent code) – Agent code generated by the CLI is written in Python. Check your version:

  ```
  python3 --version
  ```
+  **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).

## Step 1: Install the AgentCore CLI
<a name="agentcore-cli-install"></a>

Install the CLI globally using npm:

```
npm install -g @aws/agentcore
```

Verify the installation:

```
agentcore --version
```

To update the CLI to the latest version later, run the same install command again or use:

```
agentcore update
```

For the source code and to report issues, see the [agentcore-cli GitHub repository](https://github.com/aws/agentcore-cli).

## Step 2: Create your project
<a name="agentcore-cli-create-project"></a>

Create a new project using the `create` command. You can use command-line flags or the interactive wizard:

**Example**  

1. Use the `--defaults` flag to generate a Python agent using the Strands Agents SDK with Amazon Bedrock as the model provider:

   ```
   agentcore create --name MyAgent --defaults
   ```

1. Run `agentcore create` without flags to launch the interactive wizard:

   ```
   agentcore create
   ```

1. Enter your project name:  
![\[Create wizard: enter project name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-create-name.png)

1. Choose your agent framework and model provider:  
![\[Create wizard: select framework\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-create-framework.png)

1. Review your configuration and confirm:  
![\[Create wizard: review and confirm\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-create-confirm.png)

The interactive mode lets you choose from the following options:
+  **Framework** – Strands Agents, LangChain/LangGraph, Google Agent Development Kit (ADK), or OpenAI Agents SDK
+  **Model provider** – Amazon Bedrock, Anthropic, OpenAI, or Gemini
+  **Memory** – None, short-term only, or long-term and short-term
+  **Build type** – CodeZip (default) or Container

### Project structure
<a name="agentcore-cli-project-structure"></a>

After running `agentcore create` , the CLI generates the following project structure:

```
MyAgent/
├── agentcore/
│   ├── agentcore.json      # Project and resource configuration
│   ├── aws-targets.json    # Deployment target (account and region)
│   └── cdk/                # CDK infrastructure (auto-managed)
└── app/
    └── MyAgent/            # Your agent code
        ├── main.py         # Agent entrypoint
        ├── pyproject.toml  # Python dependencies
        └── ...
```

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.

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": []
}
```

## Step 3: Test locally
<a name="agentcore-cli-local-dev"></a>

Before deploying, test your agent locally using the development server. Change into your project directory and start the dev server:

**Example**  

1. 

   ```
   cd MyAgent
   agentcore dev
   ```

1. Run `agentcore` to open the TUI home screen, then select **dev** to start the local development server with an inline chat prompt:

   ```
   agentcore
   ```  
![\[AgentCore CLI TUI dev server with inline chat prompt\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-dev-server.png)

The dev server automatically creates a Python virtual environment, installs dependencies, and starts a local server with hot-reload on port 8080. Any changes you make to your agent code are picked up automatically.

To view server logs in real time, use the `--logs` flag:

```
agentcore dev --logs
```

Dev server logs are stored in `agentcore/.cli/logs/dev` in your project directory.

In a separate terminal, invoke your local agent:

**Example**  

1. 

   ```
   agentcore dev "Hello, what can you do?"
   ```

   You can also stream the response in real time:

   ```
   agentcore dev "Tell me a joke" --stream
   ```

1. Run `agentcore dev` without a prompt to open the interactive chat TUI, which streams responses by default and maintains your session automatically:

   ```
   agentcore dev
   ```  
![\[AgentCore CLI TUI interactive invoke chat interface\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-invoke-chat.png)

**Note**  
Local development does not require deployment. However, Amazon Bedrock AgentCore Memory is not available during local development because memory stores require deployed AWS infrastructure. To use memory, deploy your project first with `agentcore deploy` . For more information, see [Add memory to your Amazon Bedrock AgentCore agent](memory.md).

## Step 4: Deploy your agent
<a name="agentcore-cli-deploy-step"></a>

When you are ready, deploy your agent to Amazon Bedrock AgentCore Runtime:

**Example**  

1. 

   ```
   agentcore deploy
   ```

1. From the AgentCore CLI home screen, select `deploy` to launch the interactive deployment flow:  
![\[Deploy progress: CloudFormation resource creation and deployment status\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-deploy-progress.png)

The `deploy` command:
+ Packages your Python agent code into a zip artifact
+ Uses the AWS CDK under the hood to synthesize and deploy resources
+ Creates an AgentCore Runtime endpoint for your agent
+ Configures Amazon CloudWatch logging and observability

The first deployment takes a few minutes while the CDK bootstraps your account and provisions resources. Subsequent deployments are faster.

To preview what will be deployed without making changes, use:

```
agentcore deploy --plan
```

After deployment completes, check the status of your resources:

**Example**  

1. 

   ```
   agentcore status
   ```

1. Run `agentcore` and select **status** to view a live dashboard of all deployed resources:

   ```
   agentcore
   ```  
![\[AgentCore CLI TUI status dashboard showing deployed resources\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-status-dashboard.png)

## Step 5: Invoke your deployed agent
<a name="agentcore-cli-invoke"></a>

After deployment, invoke your agent with a prompt:

**Example**  

1. 

   ```
   agentcore invoke --runtime MyAgent "Hello, what can you do?"
   ```
**Note**  
If your project contains a single runtime, the `--runtime` flag is optional. For multi-runtime projects, specify which runtime to invoke.

   You can also stream responses, continue sessions, or use JSON output:

   ```
   # Stream the response in real time
   agentcore invoke --runtime MyAgent "Tell me a joke" --stream
   
   # Continue a previous conversation session
   agentcore invoke --runtime MyAgent "Tell me another" --session-id my-session
   
   # Get JSON output for scripting
   agentcore invoke --runtime MyAgent "Hello" --json
   ```

   To start a new session, run the invoke command without specifying a `--session-id` . The CLI generates a new session automatically.

1. Run `agentcore invoke` without a prompt to open the interactive chat TUI, which streams responses by default and maintains your session automatically:

   ```
   agentcore invoke
   ```  
![\[AgentCore CLI TUI interactive chat interface for deployed agent\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-invoke-chat.png)

**Note**  
Congratulations\$1 You created, tested, and deployed your first agent using the AgentCore CLI.

## Add resources to your project
<a name="agentcore-cli-add-resources"></a>

After creating your initial project, you can add more resources using `agentcore add` . Run the command without arguments to launch the interactive menu, or specify the resource type directly.

### Add memory
<a name="agentcore-cli-add-memory"></a>

Add a memory store with one or more strategies:

**Example**  

1. 

   ```
   agentcore add memory \
     --name SharedMemory \
     --strategies SEMANTIC,SUMMARIZATION
   ```

1. Run `agentcore add` and select **Memory** to launch the wizard:

1. Enter a name for the memory store:  
![\[Add memory wizard: enter name\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-add-memory-name.png)

1. Select memory strategies:  
![\[Add memory wizard: select strategies\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-add-memory-strategies.png)

After adding memory, deploy to provision it:

**Example**  

1. 

   ```
   agentcore deploy
   ```

1. From the AgentCore CLI home screen, select `deploy` to launch the interactive deployment flow:  
![\[Deploy progress: CloudFormation resource creation and deployment status\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-deploy-progress.png)

Available memory strategies are `SEMANTIC` , `SUMMARIZATION` , and `USER_PREFERENCE` . For more information, see [Add memory to your Amazon Bedrock AgentCore agent](memory.md).

### Add agents to your project
<a name="agentcore-cli-add-agent"></a>

The AgentCore CLI supports multiple agents in a single project. Each agent gets its own code directory under `app/` and shares the project’s deployment infrastructure.

Add a second agent to the same project:

**Example**  

1. 

   ```
   agentcore add agent \
     --name ResearchAgent \
     --language Python \
     --framework Strands \
     --model-provider Bedrock \
     --memory shortTerm
   ```

   You can also bring your own agent code:

   ```
   agentcore add agent \
     --name MyCustomAgent \
     --type byo \
     --code-location ./my-custom-agent \
     --entrypoint main.py \
     --language Python \
     --framework Strands \
     --model-provider Bedrock
   ```

1. Run `agentcore add` and select **Agent** to launch the wizard:

1. Choose the agent type and framework:  
![\[Add agent wizard: select agent type\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-create-agent-type.png)

1. Select the framework and model provider:  
![\[Add agent wizard: select framework\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-create-framework.png)

1. Review the configuration and confirm:  
![\[Add agent wizard: review and confirm\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-create-confirm.png)

### Add credentials
<a name="agentcore-cli-add-identity"></a>

If you use a non-Bedrock model provider, add credentials for it:

**Note**  
When you add an agent with a non-Bedrock model provider using `agentcore add agent` , the CLI prompts you for credentials automatically. Use this command to add credentials separately if you skipped the prompt or need to update them later.

**Example**  

1. 

   ```
   # API key credential
   agentcore add credential --name OpenAI --api-key sk-...
   
   # OAuth credential
   agentcore add credential \
     --name MyOAuthProvider \
     --type oauth \
     --discovery-url https://idp.example.com/.well-known/openid-configuration \
     --client-id my-client-id \
     --client-secret my-secret
   ```

1. Run `agentcore add` and select **Identity** to launch the wizard:

1. Choose the credential type (API Key or OAuth):  
![\[Add identity wizard: select credential type\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-add-identity-type.png)

1. Enter the credential name and value, then confirm.

## View logs and traces
<a name="agentcore-cli-observability"></a>

After deploying, you can stream logs from your agent:

```
# Stream recent logs
agentcore logs

# Filter by time range and level
agentcore logs --since 30m --level error

# Search logs
agentcore logs --query "timeout"
```

You can also view distributed traces:

```
# List recent traces
agentcore traces list

# Get details for a specific trace
agentcore traces get <trace-id>
```

## Clean up
<a name="agentcore-cli-cleanup"></a>

To tear down all AWS resources created by the CLI, first remove all resources from the configuration, then deploy the empty state:

**Example**  

1. 

   ```
   agentcore remove all
   agentcore deploy
   ```

   To preview what will be removed before taking action:

   ```
   agentcore remove all --dry-run
   ```

1. Run `agentcore` and select **remove** to interactively choose which resources to remove:

   ```
   agentcore
   ```  
![\[AgentCore CLI TUI remove resource selection screen\]](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/images/tui/common-remove-resource.png)

The `remove all` command resets the configuration files. The subsequent `deploy` detects that resources have been removed and tears them down from your AWS account.

## Next steps
<a name="agentcore-cli-next-steps"></a>

After building your first agent with the AgentCore CLI, explore the following topics:
+  [Add memory to your Amazon Bedrock AgentCore agent](memory.md) – Store conversation context with long-term and short-term memory
+  [Browser](browser-tool.md) – Browse the web with the built-in browser tool
+  [Gateway](gateway.md) – Connect external tools and services through a secure gateway
+  [Observability](observability.md) – Monitor and debug agents with logs and traces
+  [Code samples](https://github.com/awslabs/amazon-bedrock-agentcore-samples/) – Explore additional examples and patterns
+  [AgentCore CLI source](https://github.com/aws/agentcore-cli) – View the CLI source code and report issues