Get started with Instances using the AWS CLI or SDK

This tutorial walks through hosting an agent on the Instances compute type with the AWS Command Line Interface (AWS CLI) and SDKs. You first create a capacity provider that defines the Amazon Elastic Compute Cloud (Amazon EC2) infrastructure, then create an agent runtime that uses it, and finally invoke the agent.

For the prerequisites, see Get started with Instances.

Step 1: Create a capacity provider

Use the CreateCapacityProvider operation to define your EC2 infrastructure. The request takes a permissionsConfiguration (the IAM role AgentCore uses to operate the capacity provider) and a computeConfiguration that describes the EC2 instances through a launch template. The following example creates a Linux capacity provider with a single allowed instance type and a persistent EBS volume.

To run GPU workloads, include a supported GPU instance type in allowedInstanceTypes. AgentCore provisions the GPU drivers on the instance, so standard container images work without bundling drivers. The supported families are g4dn, g5, g6, g6e, gr6, g6f, gr6f, g7e, and inf2. If you include an accelerator instance type from an unsupported family, the request fails with a ValidationException. For more information, see Use GPU instance types.

Poll GetCapacityProvider until the status is READY before associating the capacity provider with a runtime. If the status becomes CREATE_FAILED, inspect statusCode and statusReason to determine the cause.

Step 2: Create an agent runtime on the capacity provider

Create an agent runtime with a capacityProviderConfiguration that references your capacity provider. To mount a volume defined on the capacity provider into the agent’s filesystem, add a capacityProviderVolume entry to filesystemConfigurations that references the volume by name. Mount paths must be under /mnt with a single subdirectory (for example, /mnt/scratch).

The agent runtime has its own lifecycleConfiguration.maxLifetime, which defaults to 28800 seconds (8 hours). This value must be less than or equal to the maxLifetime that the capacity provider sets in ec2Configuration.lifecycleConfiguration. The capacity provider in Step 1 sets that value to 3600 seconds (1 hour), so the runtime default of 8 hours would exceed it and CreateAgentRuntime would fail with a ValidationException. The following example therefore sets a runtime maxLifetime of 1800 seconds, which is within the capacity provider’s limit.

Do not pass networkConfiguration when you specify capacityProviderConfiguration. An Instances runtime inherits its networking from the capacity provider’s ec2Configuration.vpcConfiguration, so specifying both fails with a ValidationException.

Step 3: Invoke the agent

Invoke the runtime the same way you would a microVM-backed runtime. Reuse the same runtimeSessionId across invocations to keep the session on the same instance. This lets your agent access data from previous invocations. To co-locate collaborating agents, use the same runtimeSessionId across multiple runtimes that share a capacity provider.

The runtimeSessionId must be at least 33 characters.

The first invocation for a new session provisions an EC2 instance in your account and launches the agent, so it typically takes longer than later invocations. Subsequent invocations to the same session reuse the running instance and return much faster.

AgentCore provisions these instances as Amazon EC2 managed instances, which are hidden from DescribeInstances and your EC2 console views by default. A plain aws ec2 describe-instances call does not list them. To see them, include managed resources:

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id"

For more information about managing instance visibility, see the managed resource visibility setting.

Co-locate multiple agents on one instance

When two agent runtimes reference the same capacity provider and you invoke them with the same runtimeSessionId, both agents run on the same EC2 instance. There, they can share the volume configured in their filesystem configuration. Agents collaborate by reading and writing files on that shared volume — each agent is invoked independently and does not otherwise share state. For example, a test runner can write results to the volume, and a code analyzer invoked on the same session can then read them. For the boundary between agents on a shared instance, see Security model and permissions for Runtime Instances.

import boto3
import json

client = boto3.client("bedrock-agentcore", region_name="us-west-2")
session_id = "collab-session-000000000000000000000"

# Agent A — created on capacity provider "my_capacity_provider"
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/test-runner-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Run the test suite for project ABC"}).encode(),
    qualifier="DEFAULT",
)

# Agent B — a different runtime that shares the SAME capacity provider and session ID,
# so it runs on the same instance as Agent A and can read the files Agent A wrote to the shared volume.
client.invoke_agent_runtime(
    agentRuntimeArn="arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/code-analyzer-suffix",
    runtimeSessionId=session_id,
    payload=json.dumps({"prompt": "Analyze the code for project ABC"}).encode(),
    qualifier="DEFAULT",
)

Each agent runs with its own IAM credentials derived from its runtime’s execution role, so you can grant the collaborating agents different permissions although they share the same instance. However, because agents on the same instance are not isolated from each other, any agent can potentially read another agent’s credentials. Co-locate only agents that are mutually trusted. For more information, see Security model and permissions for Runtime Instances.

Clean up: stop and delete sessions

A session can host multiple agent runtimes on the same instance, so AgentCore provides two distinct operations:

To stop a specific agent runtime on a session, call the StopRuntimeSession operation with the runtime ARN and the session ID.

To delete a session and deprovision all of its resources — including any persistent EBS volumes — call DeleteCapacityProviderSession with the capacity provider ID and the session ID. The operation is idempotent and asynchronous: it returns immediately while AgentCore terminates the instance and deletes the volumes in the background.

Session IDs are values that you supply on invocation, and there is no operation that lists the sessions on a capacity provider. Keep a record of the runtimeSessionId values you use so that you can delete each session afterwards. If you no longer have them, you can find the instances that are still running, and then delete the capacity provider to deprovision all of its sessions:

aws ec2 describe-instances --include-managed-resources \
  --filters "Name=tag-key,Values=bedrock-agentcore:capacity-provider-id" \
  --query 'Reservations[].Instances[?State.Name!=`terminated`].[InstanceId,State.Name]'

Delete a capacity provider

When you no longer need a capacity provider, delete it with the DeleteCapacityProvider operation. Deleting a capacity provider stops and deletes all of its associated sessions and their persistent storage, so it also serves as a way to clean up sessions whose IDs you no longer have. You do not need to delete the sessions first. You do, however, need to remove the runtimes that reference the capacity provider: delete the associated versions, endpoints, or runtimes first, or the delete request fails with a ValidationException. The operation is asynchronous; identify the capacity provider by its ID.