gem-hunter

agentcore is a command-line tool and interactive terminal UI (TUI) for Amazon Bedrock AgentCore, the platform for building and running production AI agents (documentation).

It gives you two ways to work, from the same package:

• A scriptable CLI — flag-driven commands with JSON output (--json) for coding agents, scripts, and CI.
• An interactive TUI — guided flows for creating projects, browsing resources, and chatting with agents.

agentcore               # launch the interactive TUI
agentcore status --json # scriptable, machine-readable output

Using the AgentCore APIs directly means calling several services, setting up execution roles, and handling streamed responses. agentcore takes care of those details so you can create, deploy, and invoke agents from your terminal.

You need Node.js 20.12 or later and AWS credentials configured as for the AWS CLI. Python templates also need uv.

npm install -g @aws/agentcore

If the Python-based Bedrock AgentCore Starter Toolkit is installed, uninstall it: both provide an agentcore command.

A project holds either kind of agent, or both:

• A Harness is a managed agent you configure in YAML — model, system prompt, tools, skills — and AgentCore runs for you.
• A Runtime is agent code you own, scaffolded from a template and deployed for you.

Create a project, add a Harness to it, deploy it, and send a prompt:

agentcore create --name MyProject
cd MyProject
agentcore add harness --name MyAssistant
agentcore deploy
agentcore invoke --harness MyAssistant --prompt "Hey, what can you do for me?"

To start from code you own instead, pick a template (agentcore create --help lists them):

agentcore create --name MyAgent --template agent-python-strands

agentcore create --template scaffolds the template with its default model provider (Amazon Bedrock for the model-backed templates). To use another provider, run agentcore create with no flags: for templates that take a model provider (agent-python-strands and its -container variant, a2a-python-strands, agui-python-strands, agent-typescript-strands) the wizard asks for the provider (Amazon Bedrock, Anthropic, OpenAI, an OpenAI-compatible endpoint, Gemini, or LiteLLM, which is Python-only), the model id, and an API-key file. The API key is kept in agentcore/.env.local and provisioned as an AgentCore Identity credential on deploy.

To bring your own code into a project instead, add a runtime for it:

agentcore add runtime --name search --language python   # or --language typescript

add runtime doesn't generate code. It creates app/search/ with a README.md and an AGENTS.md describing what the code has to provide for the chosen --protocol (HTTP by default, or MCP, A2A, AGUI), and registers the runtime in agentcore.json with starting values (a CodeZip build on the latest Python or Node.js, entrypoint main.py or main.js). If app/search/ already exists, your files are left alone and only the missing docs are added.

agentcore dev, agentcore build, and agentcore deploy then update agentcore.json from the code and print what changed. Adding a Dockerfile to the folder switches the runtime to a container build. requires-python in pyproject.toml or engines.node in package.json constrains the runtime version: it changes only when the range excludes the current one, and then to the highest version the range allows. The Python entrypoint comes from [tool.agentcore] entrypoint in pyproject.toml; TypeScript is always bundled from main.ts (a package.json "main" of main.ts or main.js agrees with that, and any other value is ignored with a warning). Where the code doesn't say, the value in agentcore.json is kept.

Run agentcore create outside any existing project.

create makes a directory holding agentcore/agentcore.json, the spec that declares the project's resources, and agentcore/cdk/, the AWS CDK app that deploys them. Deployment targets — an account and region each — live in agentcore/aws-targets.json. Project commands find the project by walking up from the current directory.

agentcore dev runs runtimes locally or deploys harnesses and prints invoke guidance. Use --mode browser for Agent Inspector, --skip-deploy to reuse deployed harnesses, and --agent <name> to choose an agent in mixed projects.

In a terminal, a command run without flags opens its interactive flow; pass flags and it runs non-interactively. --help on any command lists its subcommands and flags, and the command reference has them all.

Global flags, available on every command:

agentcore/cdk/ has two source files. bin/cdk.ts reads the project once (readAgentCoreProject), makes one stack per deployment target (resolveTargetStacks) and turns agentcore.json into the application's props (transformAgentCoreJson). All three come from @aws/agentcore-cdk, so that logic is updated through the library rather than changes to your CDK app.

lib/cdk-stack.ts instantiates one AgentCoreApplication. This is the file you edit to add your own resources. Runtimes and harnesses implement iam.IGrantable, so you can pass them to a resource's CDK grant methods to give your agents access. Use addEnvironmentVariable to pass resource names, ARNs, or endpoints to your agent.

This example gives the generated runtime named agent access to a table:

import { AgentCoreApplication, type AgentCoreApplicationProps } from "@aws/agentcore-cdk";
import { Stack, type StackProps } from "aws-cdk-lib";
import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
import { Construct } from "constructs";

export interface AgentCoreStackProps extends StackProps {
  application: AgentCoreApplicationProps;
}

export class AgentCoreStack extends Stack {
  public readonly application: AgentCoreApplication;

  constructor(scope: Construct, id: string, props: AgentCoreStackProps) {
    super(scope, id, props);
    this.application = new AgentCoreApplication(this, "Application", props.application);

    const orders = new dynamodb.Table(this, "Orders", {
      partitionKey: { name: "pk", type: dynamodb.AttributeType.STRING },
    });
    const agent = this.application.runtime("agent");
    orders.grantReadWriteData(agent);
    agent.addEnvironmentVariable("ORDERS_TABLE", orders.tableName);
  }
}

For a Harness, use this.application.harness("<name>") instead.

Run agentcore deploy to apply your changes. The names passed to runtime() or harness() must match the names in your project.

If you use an existing execution role through executionRoleArn, CDK cannot change its permissions. You'll need to add the required permissions to that role yourself.

Note that agentcore status reports only the resources agentcore.json declares, not the ones you add in the stack.

• Command reference: every command and flag.
• Harness project configuration: Harness YAML, prompts, tools, skills, and environment settings.
• China regions: what is available there and how the restrictions are enforced.
• Amazon Bedrock AgentCore documentation: service guides and API references.
• Contributing: development, builds, architecture, and testing.
• Security · License: Apache-2.0.