Prerequisites Step 1: Create the project Step 2: Deploy Step 3: Run a session Step 4: Continue the session Step 5: (Optional) Add skills Step 6: View logs and traces Step 7: Update and redeploy Step 8: Clean up Related resources

Get started with Amazon Bedrock Managed Agents (with OpenAI) on AgentCore Runtime

Note

Amazon Bedrock Managed Agents (with OpenAI) is in preview. Features and APIs may change before general availability.

Amazon Bedrock Managed Agents runs the OpenAI Codex harness on AWS. The harness runs the loop between the model and the tools, keeps the session, and compacts context as the conversation grows. When the agent must run a command or work with files, Bedrock Managed Agents sends the work to an environment. You decide where that environment runs.

You can run the Codex exec-server on your own computer for local development. For other workloads, Bedrock Managed Agents invokes an AgentCore Runtime in your account. The Runtime gives each session its own microVM. The session runs under an execution role that you control, and the Runtime can connect to your VPC so that the agent can reach private resources. The model calls stay in Bedrock Managed Agents, so the container runs only the commands that the agent sends.

In this tutorial, you do these tasks:

Create and deploy the Runtime with the AgentCore CLI.
Start a session with the OpenAI SDK. The agent uses a sample skill in your Runtime.
(Optional) Add your own skills.

Steps 1 to 4 take about 15 minutes.

The AWS resources that you create in this tutorial might result in charges to your AWS account. These resources include the Runtime, the AWS CodeBuild image builds, and the Bedrock Managed Agents model calls. For more information, see AgentCore pricing. To stop the charges, remove the resources in Step 8: Clean up.

Prerequisites

Node.js 20 or later. The AgentCore CLI is distributed as an npm package. Check with node --version.
uv. The sample client uses uv to install its Python dependencies.
An AWS account with credentials configured. To create an account, see Getting started with an AWS account. To configure credentials, see Configuring the AWS CLI.
IAM permissions. Your identity needs permissions to make AgentCore API calls and to assume the CDK bootstrap roles used during deployment. See Use the AgentCore CLI. The sample client also needs IAM permissions. See The session role.
Model access. Your account needs access to the Bedrock Managed Agents model openai.gpt-5.6-luna.

The CLI builds the container image with AWS CodeBuild in your account.

Step 1: Create the project

Install the AgentCore CLI, and set your credentials and Region:


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

export AWS_PROFILE=your-profile
export AWS_REGION=us-east-1

Create the project with the BedrockManagedAgents framework. You can also run agentcore create with no flags. Select Agent, and then select Bedrock Managed Agents as the framework.


agentcore create --name MyManagedAgent --framework BedrockManagedAgents
cd MyManagedAgent

The project has the Runtime configuration in agentcore/agentcore.json and the container source in app/MyManagedAgent/. The container runs codex exec-server, which connects out to Bedrock Managed Agents and runs the commands of the agent.

The project configures the Runtime with these defaults:

A 30 minute idle timeout and an 8 hour maximum lifetime. See Configure lifecycle settings.
An execution role with the permissions in policies/bma-acr-policy.json.


MyManagedAgent/
├── agentcore/
│   ├── agentcore.json
│   └── cdk/
└── app/MyManagedAgent/
    ├── Dockerfile
    ├── lifecycle/server.py
    ├── otel/collector.yaml
    ├── plugins/acr-report/
    ├── policies/
    │   ├── bma-acr-policy.json
    │   ├── bma-session-trust.json
    │   └── bma-session-policy.json
    ├── pyproject.toml
    ├── client.py
    └── README.md

Key files:

lifecycle/server.py - The lifecycle server. Bedrock Managed Agents calls it to start codex exec-server in your Runtime session. Do not change this file.
Dockerfile - Installs Codex, the CloudWatch agent, and Python, and copies lifecycle/, otel/, and plugins/ to /opt/bma.
otel/collector.yaml - Sends the spans and logs of the exec-server to CloudWatch.
plugins/acr-report/ - A sample plugin with one skill. The skill saves acr-report.txt in the workspace.
policies/bma-acr-policy.json - The policy of the Runtime execution role. Allows bedrock-mantle:RegisterEnvironment and bedrock-mantle:ConnectEnvironment. To limit it to one project, change Resource to arn:aws:bedrock-mantle:<region>:<account-id>:project/<project-id>.
pyproject.toml - The Python dependencies. The dev group is for client.py only.
policies/bma-session-trust.json and policies/bma-session-policy.json - The trust policy and the permissions of the session role. See The session role.
client.py - A sample client that starts a session. You run it in Step 3.

Add the network options to agentcore create:


agentcore create --name MyManagedAgent --framework BedrockManagedAgents \
  --network-mode VPC --vpc-id <vpc-id> --subnets <subnet-ids> \
  --security-groups <security-group-ids>

The VPC must have a route to the Bedrock Managed Agents endpoint, because the exec-server connects out to it. The image build downloads Codex and Python, so it also needs a route to the internet. See Configure AgentCore for VPC.

The same project runs on the Instances compute type. Add a capacity provider to the project, and then add the agent with the capacity provider:


agentcore create --name MyManagedAgent --no-agent
cd MyManagedAgent
agentcore add capacity-provider --name MyCapacityProvider \
  --subnets <subnet-ids> --security-groups <security-group-ids> \
  --os LINUX_ARM64 --instance-types c7g.large
agentcore add agent --name MyManagedAgent --framework BedrockManagedAgents \
  --capacity-provider MyCapacityProvider

Then continue with Step 2: Deploy. agentcore deploy also creates the capacity provider and its operator role.

Use LINUX_ARM64 and Graviton instance types, because the image build makes an ARM64 image.
The capacity provider gives the network. The subnets must have a route to the Bedrock Managed Agents endpoint.

To attach a capacity provider that is not in the project, give its ARN to agentcore create --framework BedrockManagedAgents --capacity-provider <capacity-provider-arn>. See Runtime Instances and capacity providers.

Step 2: Deploy


agentcore deploy
agentcore status

The CLI builds the image with AWS CodeBuild in your account, and deploys the Runtime and its execution role. Bedrock Managed Agents invokes the Runtime for you.

Save the Runtime ARN from the output of agentcore status:


arn:aws:bedrock-agentcore:us-east-1:<account-id>:runtime/<runtime-id>

Step 3: Run a session

Bedrock Managed Agents uses a session role to call the model and to invoke your Runtime. The session role is not the Runtime execution role. When you run client.py, it creates the session role in your account. agentcore deploy does not create the session role, and agentcore remove does not delete it. See The session role.

Run the client from the agent directory:


cd app/MyManagedAgent
uv run client.py --runtime <runtime-arn>

The client creates a session and prints the session ID, each command with its output, and the answer of the agent. By default, the agent uses the acr-report skill to save acr-report.txt in the workspace.

The next section tells you how the client manages the session role, and which IAM permissions you need to run the client.

The session role is not the Runtime execution role. agentcore deploy creates the execution role with policies/bma-acr-policy.json. The client gives the session role to Bedrock Managed Agents in the role_arn field when it creates a session.

When you start a new session and do not give --role-arn, the client does these steps:

If the role BmaSessionRole-<region> does not exist, the client creates it.
The client compares the trust policy and the inline policy BmaSession of the role with policies/bma-session-trust.json and policies/bma-session-policy.json. If a policy is not the same, the client writes the file to the role. The files are limited to the account and the Region of the Runtime.
If the client changed the role, it waits 15 seconds. IAM needs this time before Bedrock Managed Agents can use the change.

To change the role, change the files. The client does not remove other policies that someone adds to the role. It does not check the role when you give --session-id, and it does not change a role that you give with --role-arn.

For production, give the client a role for one Runtime and one gateway with --role-arn. To make the role, use the two files in policies/. Put in your partition, Region, and account ID, and change the in runtime/ and gateway/* to your Runtime ID and gateway ID. Do not change the files in the project, because all the projects in the Region share BmaSessionRole-<region>.

The identity that runs the client needs the Bedrock Managed Agents client permissions, bedrock-mantle:CallWithBearerToken, and iam:PassRole on the session role. To let the client create and repair the role, also give iam:GetRole, iam:CreateRole, iam:UpdateAssumeRolePolicy, iam:GetRolePolicy, and iam:PutRolePolicy on arn:aws:iam::<account-id>:role/BmaSessionRole-*. If you give --role-arn, the client does not need these five permissions.

For the trust policy, the permissions of the session role, and the client permissions, see Security and IAM roles in the Amazon Bedrock User Guide.

The client uses the client.beta.agents resources of the openai package. Bedrock Managed Agents runs the agent loop.

When the client creates the session, it sets these values in environment:

type - aws_bedrock_agentcore, which tells Bedrock Managed Agents to use an AgentCore Runtime.
runtime_arn - Your Runtime. The session runs in the Region of the Runtime.
workspace_directory - The directory where the agent runs its commands. The client uses /home/app/workspace. The lifecycle server creates the directory.
runtime_qualifier - The endpoint of the Runtime. The client uses DEFAULT.
capability_directories - The directories where Bedrock Managed Agents finds skills. The client uses /opt/bma/plugins.

The client also sets role_arn in extra_body to the session role. The openai package does not have a parameter for this field.

The provide_token helper uses your AWS credentials to get a short-lived Amazon Bedrock bearer token for each request.

If you add a gateway to the project, give its ARN from the output of agentcore deploy with --gateway. Use the flag only for a new session. The client adds the gateway as an mcp tool with the ARN in connector_id. Bedrock Managed Agents calls the gateway with the session role. The gateway must support MCP version 2025-03-26. If it does not, the agent gets no gateway tools, and Bedrock Managed Agents does not show an error.


"""Send an input to a Bedrock Managed Agents session that uses this project's ACR."""

import argparse
import json
import time
from pathlib import Path
from typing import Any

import boto3
from aws_bedrock_token_generator import provide_token
from botocore.exceptions import ClientError
from openai import NotFoundError, OpenAI

BMA_MODEL_ID = "openai.gpt-5.6-luna"
# The agent runs its commands in this directory. The lifecycle server creates it.
WORKSPACE_DIRECTORY = "/home/app/workspace"
# Plugins and skills that the agent can use. The image has the acr-report plugin
# at this path. Add the path of an S3 Files mount to use the skills in a bucket.
CAPABILITY_DIRECTORIES = ["/opt/bma/plugins"]
TURN_END = ("completed", "failed", "cancelled")
TOOL_CALLS = ("mcp_call", "function_call", "web_search_call")
POLICIES = Path(__file__).parent / "policies"
SESSION_ROLE = "BmaSessionRole-{region}"
SESSION_POLICY = "BmaSession"


def show(data: dict[str, Any]) -> None:
    """Prints the session ID, the commands, the tool calls, and the answer."""
    kind = data["type"].removeprefix("agent.session.")
    item = data.get("item") or {}
    if kind == "created":
        print(f"Session {data['session']['id']}")
    elif kind == "turn.output_text.delta":
        print(data["delta"], end="", flush=True)
    elif kind == "turn.item.done" and item.get("type") == "command_execution":
        print(f"\n$ {item['command']}\n{item.get('output') or ''}".rstrip())
    elif kind == "turn.item.done" and item.get("type") in TOOL_CALLS:
        print(f"\nTool {item.get('name') or item['type']} {item.get('status')}")
    elif kind == "error" or kind.split(".")[-1] in TURN_END:
        source = data.get("turn") or data.get("environment") or data.get("session")
        print(f"\n{kind} {(source or data).get('error') or ''}".rstrip())


def load_policy(name: str, partition: str, region: str, account: str) -> str:
    """Reads a policy file and puts in the partition, the Region, and the account."""
    text = (POLICIES / name).read_text()
    for key, value in (("Partition", partition), ("Region", region), ("AccountId", account)):
        text = text.replace("${AWS::" + key + "}", value)
    return text


def session_role(runtime_arn: str) -> str:
    """Creates or repairs the session role, and returns its ARN.

    If the trust policy or the policy of the role is not the same as the file in `policies/`,
    the client writes the file to the role.
    """
    _, partition, _, region, account = runtime_arn.split(":")[:5]
    name = SESSION_ROLE.format(region=region)
    trust = load_policy("bma-session-trust.json", partition, region, account)
    policy = load_policy("bma-session-policy.json", partition, region, account)
    iam = boto3.client("iam")
    changed = False
    try:
        role = iam.get_role(RoleName=name)["Role"]
    except iam.exceptions.NoSuchEntityException:
        role = iam.create_role(RoleName=name, AssumeRolePolicyDocument=trust)["Role"]
        print(f"Created the session role {name}")
        changed = True
    else:
        if role["AssumeRolePolicyDocument"] != json.loads(trust):
            iam.update_assume_role_policy(RoleName=name, PolicyDocument=trust)
            print(f"Updated the trust policy of {name}")
            changed = True
    try:
        current = iam.get_role_policy(RoleName=name, PolicyName=SESSION_POLICY)["PolicyDocument"]
    except iam.exceptions.NoSuchEntityException:
        current = None
    if current != json.loads(policy):
        iam.put_role_policy(RoleName=name, PolicyName=SESSION_POLICY, PolicyDocument=policy)
        if not changed:
            print(f"Updated the policy of {name}")
        changed = True
    if changed:
        # IAM needs some seconds before Bedrock Managed Agents can use a new or changed role.
        time.sleep(15)
    return role["Arn"]


def main() -> None:
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--runtime", required=True, help="The ACR ARN.")
    parser.add_argument(
        "--session-id",
        help="The BMA session ID. If it does not exist, the client creates a session.",
    )
    parser.add_argument(
        "--input",
        default="Use the acr-report skill to save an ACR report in the workspace.",
    )
    parser.add_argument(
        "--gateway",
        help="The Gateway ARN from the output of `agentcore deploy`.",
    )
    parser.add_argument(
        "--role-arn",
        help="The session role that BMA assumes. If you do not give it, the client creates a role.",
    )
    parser.add_argument("--delete", action="store_true", help="Delete the session.")
    parser.add_argument("--raw", action="store_true", help="Print events as JSON.")
    args = parser.parse_args()
    # BMA must run in the Region of the ACR.
    region = args.runtime.split(":")[3]

    with OpenAI(
        api_key=lambda: provide_token(region=region),
        base_url=f"https://bedrock-mantle.{region}.api.aws/openai/v1",
    ) as client:
        sessions = client.beta.agents.sessions
        session_id = args.session_id
        if session_id:
            try:
                session = sessions.retrieve(session_id).model_dump(warnings=False)
            except NotFoundError:
                print(f"Session {session_id} does not exist.")
                session_id = None
            else:
                if session["environment"].get("runtime_arn") != args.runtime:
                    raise ValueError(f"Session {session_id} uses another ACR.")
        if not session_id and not args.role_arn:
            try:
                args.role_arn = session_role(args.runtime)
            except ClientError as error:
                parser.error(
                    f"The client cannot create or check the session role: {error}. "
                    "Get the IAM permissions in README.md, or give --role-arn."
                )
            print(f"Session role {args.role_arn}")

        if session_id:
            # BMA opens the stream only with stream=true, and the SDK does not send it.
            events = sessions.events.stream(session_id, extra_query={"stream": "true"})
            message = {
                "role": "user",
                "content": [{"type": "input_text", "text": args.input}],
            }
            sessions.events.create(
                session_id,
                events=[{"type": "agent.session.input.message", "input": [message]}],
            )
        else:
            agent: dict[str, Any] = {
                "model": BMA_MODEL_ID,
                "instructions": "Use the available tools to complete the task.",
            }
            if args.gateway:
                # Bedrock Managed Agents calls Gateway with the session role from the service side.
                agent["tools"] = [
                    {"type": "mcp", "server_label": "team_tools", "connector_id": args.gateway}
                ]
                args.input += " Then list the tools that the Gateway gives you."
            events = sessions.create(
                agent=agent,
                environment={
                    "type": "aws_bedrock_agentcore",
                    "runtime_arn": args.runtime,
                    "runtime_qualifier": "DEFAULT",
                    "workspace_directory": WORKSPACE_DIRECTORY,
                    "capability_directories": CAPABILITY_DIRECTORIES,
                },
                input=args.input,
                stream=True,
                # The SDK has no role_arn parameter. BMA assumes this role to call the ACR.
                extra_body={"role_arn": args.role_arn},
            )

        with events:
            for event in events:
                data = event.model_dump(mode="json", warnings=False)
                session_id = session_id or (data.get("session") or {}).get("id")
                if args.raw:
                    print(json.dumps(data), flush=True)
                else:
                    show(data)
                if data["type"].removeprefix("agent.session.turn.") in TURN_END:
                    break

        if args.delete:
            sessions.delete(session_id)
            print(f"\nDeleted session {session_id}")


if __name__ == "__main__":
    main()

Step 4: Continue the session

To send another input to the same session, add the session ID. The turn uses the same workspace. To keep the workspace after an idle stop, add session storage as in Keep files after an idle stop.


uv run client.py --runtime <runtime-arn> --session-id <session-id> \
  --input "Run cat acr-report.txt and show the output."

If the session does not exist, the client creates a new session. Add --delete to delete the session after the turn, or --raw to print each event as JSON.

On a microVM Runtime, put the home directory of the exec-server on session storage. Then the workspace, the connection state, and CODEX_HOME stay after an idle stop.

Instead of the command in Step 1, create the project with session storage:


agentcore create --name MyManagedAgent --framework BedrockManagedAgents \
  --session-storage-mount-path /mnt/home
cd MyManagedAgent

In agentcore/agentcore.json, add this variable to the entry for the Runtime:
```
"envVars": [{ "name": "BMA_HOME_DIR", "value": "/mnt/home" }]
```
In client.py, set WORKSPACE_DIRECTORY = "/mnt/home/workspace".
Deploy, and run the client.

For more information about session storage, see File system configurations for AgentCore Runtime.

Step 5: (Optional) Add skills

To add a skill to the image, add a plugin under plugins/ and deploy. A plugin has a .codex-plugin/plugin.json file and a skills/ directory. The skills/ directory has one subdirectory for each skill, with a SKILL.md file in it. The image copies it to /opt/bma/plugins, which the client already gives to Bedrock Managed Agents.

To start, copy plugins/acr-report/, and rename the plugin directory and skills/acr-report/ to the name of your plugin and your skill. In plugin.json, set name, version, description, and "skills": "./skills/". Each SKILL.md starts with front matter that has name and description. After the deploy, start a new session with --input "Use the <skill-name> skill to …".

Mount an S3 Files access point in the Runtime. Then the skills change when the bucket changes, and the image stays the same. For the S3 Files file system, the access point, and the security group rules, see File system configurations for AgentCore Runtime.

An S3 Files mount needs a Runtime in VPC network mode. Create the project with the network options in Deploy the Runtime in a VPC.

In the bucket, put each plugin in its own directory under the root directory of the access point. Use the same layout as plugins/acr-report/: <plugin>/.codex-plugin/plugin.json and <plugin>/skills/<skill>/SKILL.md.

Add the mount to the entry for the Runtime in agentcore/agentcore.json:


{
  "filesystemConfigurations": [
    {
      "s3FilesAccessPoint": {
        "accessPointArn": "arn:aws:s3files:us-east-1:111122223333:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0",
        "mountPath": "/mnt/skills"
      }
    }
  ]
}

Then set CAPABILITY_DIRECTORIES in client.py to ["/opt/bma/plugins", "/mnt/skills"], and deploy.

Step 6: View logs and traces


agentcore logs --since 15m

The first deploy turns on CloudWatch Transaction Search in your account. The traces show after about 10 minutes. To see the traces, open the CloudWatch console and choose GenAI Observability. Each call from Bedrock Managed Agents to the lifecycle server has one bma.invocation span. For more information, see View observability data for your Amazon Bedrock AgentCore agents.

Transaction Search settings apply to the entire account

Transaction Search and its span indexing apply to the entire account in the Region, and additional charges might apply. To keep your current settings, add "disableTransactionSearch": true to ~/.agentcore/config.json before you deploy.

Step 7: Update and redeploy

Change the Runtime settings in agentcore/agentcore.json, or the files of the image, and deploy again. For example, this setting stops an idle session after 10 minutes. The values are in seconds.


{
  "lifecycleConfiguration": {
    "idleRuntimeSessionTimeout": 600,
    "maxLifetime": 28800
  }
}


agentcore deploy

The changes apply to new sessions.

Add a variable to envVars in the entry for the Runtime, for example { "name": "DISABLE_ADOT_OBSERVABILITY", "value": "true" }.

Variable	Default	Description
`DISABLE_ADOT_OBSERVABILITY`	Not set	Set to `true` to turn off the traces and the exec-server logs. The lifecycle server still writes its own logs to the log group of the Runtime.
`BMA_HOME_DIR`	`/home/app`	`HOME` of the exec-server.
`BMA_STATE_DIR`	`.bma` in `BMA_HOME_DIR`	The directory of `state.json`, which keeps the connection state of the session.
`BMA_CODEX_HOME`	`.codex` in `BMA_HOME_DIR`	`CODEX_HOME` of the exec-server.
`BMA_CODEX_BINARY`	`/opt/bma/bin/codex`	The Codex binary.
`BMA_MAX_TURN_LEASE`	`300`	The longest turn lease, in seconds.

Each image build installs the latest Codex release. The lifecycle server needs Codex 0.154.0 or later. To pin a release, add CODEX_RELEASE=<version> next to CODEX_NON_INTERACTIVE=1 in the Dockerfile.

Step 8: Clean up

To delete a session, add --delete to the last run of the client for that session. Then remove the resources of the project, and deploy to delete the Runtime, its execution role, and the stack.


agentcore remove all
agentcore deploy

The deploy does not delete these resources:

The CloudWatch Logs log groups of the Runtime, of the CodeBuild project that builds the image, and of the Lambda function that starts the build.
The AWS KMS key of the Amazon ECR repository. The key stays in the Pending deletion state for 30 days, and then AWS KMS deletes it.
The CDKToolkit stack, if the first deploy bootstrapped the account and Region. Other AWS CDK apps can use this stack. Delete it only if no other app uses it.
The Transaction Search settings from Step 6.
The session role that client.py created in Step 3.

To delete the session role, run these commands:


aws iam delete-role-policy --role-name BmaSessionRole-<region> --policy-name BmaSession
aws iam delete-role --role-name BmaSessionRole-<region>

To find the log groups, run these commands. Then delete each log group.


aws logs describe-log-groups --log-group-name-prefix /aws/bedrock-agentcore/runtimes/<project-name>_<agent-name>- --query 'logGroups[].logGroupName'
aws logs describe-log-groups --log-group-name-prefix /aws/codebuild/AgentCore-<project-name>-<target-name>- --query 'logGroups[].logGroupName'
aws logs describe-log-groups --log-group-name-prefix /aws/lambda/AgentCore- --query 'logGroups[].logGroupName'
aws logs delete-log-group --log-group-name <log-group-name>

Replace these values:

<project-name> - The name of the project. In Step 1, it is MyManagedAgent.
<agent-name> - The name of the agent. In Step 1, it is also MyManagedAgent.
<target-name> - The name of the deploy target in agentcore/aws-targets.json. The default is default. In the CodeBuild names, each underscore (_) in the project name and the target name changes to a hyphen (-).

The name of the Lambda log group is shortened, as in this example:


/aws/lambda/AgentCore-MyManagedAgent--ApplicationAgentMyManage-<suffix>

The command lists the Lambda log groups of all AgentCore CLI projects in the Region. Delete only the log groups of your project.

If you added other resources to the project, such as a gateway or a memory, check that the deploy deleted them.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Get started with bidirectional streaming using WebSocket

Optimize your agent