Agent Commands

The agent command group contains all commands related to managing agent runtimes, including creation, updates, invocation, and deletion.

Overview

Agent commands provide complete lifecycle management for your agents on Amazon Bedrock AgentCore Runtime. Each agent represents a containerized AI application that can be deployed, versioned, and invoked through endpoints.

• create

  Create and deploy a new agent runtime.

• update

  Update an existing agent with a new version.

• invoke

  Invoke an agent runtime with a prompt or payload.

• list

  List all deployed agent runtimes.

• status

  Show detailed status of an agent runtime.

• delete

  Delete an agent runtime and associated resources.

agent create

Create and deploy a new agent runtime.

agentcore-cli agent create <name> [options]

Arguments

Argument	Description
name	The name of the agent to create (required)

Options

Option	Description
--dockerfile PATH	Path to the Dockerfile (default: Dockerfile)
--context PATH	Docker build context (default: current directory)
--build-args KEY=VALUE	Build arguments for Docker build (can be used multiple times)
--image-tag TAG	Tag for the container image (default: latest)
--environment ENV	Environment to deploy to (default: current environment)
--region REGION	AWS region for deployment
--no-deploy	Build the container but don't deploy the agent runtime
--role-prefix PREFIX	IAM role name prefix (default: agentcore)
--memory MB	Memory allocation in MB (default: 2048)
--timeout SEC	Function timeout in seconds (default: 900)
--concurrency NUM	Maximum concurrent executions (default: 10)
--environment-vars KEY=VALUE	Environment variables for the agent (can be used multiple times)

Examples

Basic CreationCustom DockerfileBuild ArgumentsEnvironment VariablesProduction DeploymentBuild Only

# Create an agent with default settings
agentcore-cli agent create my-agent

# Create an agent with a custom Dockerfile
agentcore-cli agent create my-agent --dockerfile ./path/to/Dockerfile

# Create an agent with build arguments
agentcore-cli agent create my-agent \
  --build-args API_KEY=secret123 \
  --build-args DEBUG=true

# Create an agent with environment variables
agentcore-cli agent create my-agent \
  --environment-vars MODEL=anthropic.claude-3-sonnet-20240229-v1:0 \
  --environment-vars MAX_TOKENS=4096

# Create an agent in production environment
agentcore-cli agent create my-agent \
  --environment prod \
  --memory 4096 \
  --timeout 1800 \
  --concurrency 25

# Build the container without deploying
agentcore-cli agent create my-agent --no-deploy

agent update

Update an existing agent with a new version.

agentcore-cli agent update <name> [options]

Arguments

Argument	Description
name	The name of the agent to update (required)

Options

Option	Description
--dockerfile PATH	Path to the Dockerfile (default: Dockerfile)
--context PATH	Docker build context (default: current directory)
--build-args KEY=VALUE	Build arguments for Docker build (can be used multiple times)
--image-tag TAG	Tag for the container image (default: autogenerated)
--environment ENV	Environment to deploy to (default: current environment)
--region REGION	AWS region for deployment
--no-deploy	Build the container but don't deploy the agent runtime
--endpoint NAME	Endpoint to update (default: DEFAULT)
--memory MB	Memory allocation in MB
--timeout SEC	Function timeout in seconds
--concurrency NUM	Maximum concurrent executions
--environment-vars KEY=VALUE	Environment variables for the agent (can be used multiple times)

Examples

Basic UpdateUpdate with Custom TagUpdate ConfigurationUpdate Endpoint

# Update an agent with a new version
agentcore-cli agent update my-agent

# Update an agent with a specific tag
agentcore-cli agent update my-agent --image-tag v2.0.0

# Update an agent's configuration
agentcore-cli agent update my-agent \
  --memory 4096 \
  --timeout 1800

# Update a specific endpoint
agentcore-cli agent update my-agent \
  --endpoint production \
  --image-tag stable-v1

agent invoke

Invoke an agent runtime with a prompt or payload.

agentcore-cli agent invoke <name> [options]

Arguments

Argument	Description
name	The name of the agent to invoke (required)

Options

Option	Description
--prompt TEXT	Text prompt to send to the agent
--file PATH	Path to a file containing the prompt
--payload JSON	Raw JSON payload to send to the agent
--payload-file PATH	Path to a JSON file containing the payload
--endpoint NAME	Endpoint to invoke (default: DEFAULT)
--environment ENV	Environment to use (default: current environment)
--output FILE	Save the response to a file
--raw	Output raw response without formatting
--timeout SEC	Request timeout in seconds (default: 30)

Examples

Text PromptFrom FileCustom JSON PayloadSave OutputSpecific Endpoint

# Invoke an agent with a text prompt
agentcore-cli agent invoke my-agent \
  --prompt "Tell me about AWS Bedrock"

# Invoke an agent with a prompt from a file
agentcore-cli agent invoke my-agent \
  --file ./prompt.txt

# Invoke an agent with a custom JSON payload
agentcore-cli agent invoke my-agent \
  --payload '{"query": "What is AWS Bedrock?", "max_tokens": 500}'

# Save the agent's response to a file
agentcore-cli agent invoke my-agent \
  --prompt "Generate a report" \
  --output ./report.txt

# Invoke a specific endpoint
agentcore-cli agent invoke my-agent \
  --prompt "Hello" \
  --endpoint production

agent list

List all deployed agent runtimes.

agentcore-cli agent list [options]

Options

Option	Description
--environment ENV	Environment to list agents from (default: current environment)
--region REGION	AWS region to list agents from
--verbose, -v	Show detailed information for each agent

Examples

# List all agents in the current environment
agentcore-cli agent list

# List all agents in production with details
agentcore-cli agent list --environment prod --verbose

agent status

Show detailed status of an agent runtime.

agentcore-cli agent status <name> [options]

Arguments

Argument	Description
name	The name of the agent to show status for (required)

Options

Option	Description
--environment ENV	Environment to use (default: current environment)
--region REGION	AWS region to use

Examples

# Show status of an agent
agentcore-cli agent status my-agent

# Show status in a specific environment
agentcore-cli agent status my-agent --environment prod

agent delete

Delete an agent runtime and associated resources.

agentcore-cli agent delete <name> [options]

Arguments

Argument	Description
name	The name of the agent to delete (required)

Options

Option	Description
--environment ENV	Environment to delete from (default: current environment)
--region REGION	AWS region to delete from
--force	Skip confirmation prompt
--keep-ecr	Keep the ECR repository and images
--keep-iam	Keep the IAM role

Examples

Basic DeletionForce DeleteKeep Resources

# Delete an agent (with confirmation)
agentcore-cli agent delete my-agent

# Force delete without confirmation
agentcore-cli agent delete my-agent --force

# Delete agent but keep ECR repository
agentcore-cli agent delete my-agent --keep-ecr

Next Steps

Now that you understand the agent commands, you might want to explore:

• Environment Commands to manage your environments
• Container Commands to work directly with Docker containers
• Configuration Commands to manage your AgentCore configuration