agentcore-cli 0.31.1__py3-none-any.whl

agentcore/assets/python/http/autogen/base/README.md

@@ -0,0 +1,45 @@
+This is a project generated by the agentcore create CLI tool!
+
+# Layout
+
+The generated application code lives at the agent root directory. At the root, there is a `.gitignore` file, an
+`agentcore/` folder which represents the configurations and state associated with this project. Other `agentcore`
+commands like `deploy`, `dev`, and `invoke` rely on the configuration stored here.
+
+## Agent Root
+
+The main entrypoint to your app is defined in `main.py`. Using the AgentCore SDK `@app.entrypoint` decorator, this
+file defines a Starlette ASGI app with the AutoGen framework running within.
+
+`model/load.py` instantiates your chosen model provider.
+
+## Input Validation
+
+Validate invocation input before forwarding it to the agent framework. Keep plain prompts typed as strings and pass
+only prompt text to the agent.
+
+## Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+{{#if hasIdentity}}| `{{identityProviders.[0].envVarName}}` | Yes | {{modelProvider}} API key (local) or Identity provider name (deployed) |
+{{/if}}| `LOCAL_DEV` | No | Set to `1` to use `.env.local` instead of AgentCore Identity |
+
+# Developing locally
+
+If installation was successful, a virtual environment is already created with dependencies installed.
+
+Activate the environment with `source .venv/bin/activate` on macOS/Linux, `.venv\Scripts\activate.bat` in Windows
+Command Prompt, or `.\.venv\Scripts\activate.ps1` in Windows PowerShell.
+
+`agentcore dev` will start a local server on 0.0.0.0:8080.
+
+In a new terminal, you can invoke that server with:
+
+`agentcore invoke --dev "What can you do"`
+
+# Deployment
+
+After providing credentials, `agentcore deploy` will deploy your project into Amazon Bedrock AgentCore.
+
+Use `agentcore invoke` to invoke your deployed agent.

agentcore/assets/python/http/autogen/base/gitignore.template

@@ -0,0 +1,41 @@
+# Environment variables
+.env
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

agentcore/assets/python/http/autogen/base/main.py

@@ -0,0 +1,145 @@
+{{#if needsOs}}
+import os
+{{/if}}
+from collections import OrderedDict
+from autogen_agentchat.agents import AssistantAgent
+from autogen_core.tools import FunctionTool
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+from model.load import load_model
+from mcp_client.client import get_streamable_http_mcp_tools
+
+app = BedrockAgentCoreApp()
+log = app.logger
+
+
+# Define a simple function tool
+def add_numbers(a: int, b: int) -> int:
+    """Return the sum of two numbers"""
+    return a + b
+
+
+add_numbers_tool = FunctionTool(
+    add_numbers, description="Return the sum of two numbers"
+)
+
+# Define a collection of tools used by the model
+tools = [add_numbers_tool]
+
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
+
+def _safe_resolve(path: str) -> str:
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
+    return resolved
+
+def file_read(path: str) -> str:
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        with open(full_path) as f:
+            return f.read()
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error reading '{path}': {e.strerror}"
+
+def file_write(path: str, content: str) -> str:
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        parent = os.path.dirname(full_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(full_path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error writing '{path}': {e.strerror}"
+
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
+    try:
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{path}': {e.strerror}"
+
+tools.extend([
+    FunctionTool(file_read, description="Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."),
+    FunctionTool(file_write, description="Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."),
+    FunctionTool(list_files, description="List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."),
+])
+{{/if}}
+
+SYSTEM_MESSAGE = """
+You are a helpful assistant. Use tools when appropriate.
+{{#if needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}
+"""
+
+# Reuses one AssistantAgent per session_id so each session keeps its own
+# in-process conversation history (best-effort; resets on cold start). Caches up
+# to 128 active sessions with LRU eviction (least-recently-used is dropped and
+# its history reset).
+_agents = OrderedDict()
+
+
+async def get_or_create_agent(session_id):
+    if session_id in _agents:
+        _agents.move_to_end(session_id)
+        return _agents[session_id]
+    if len(_agents) >= 128:
+        _agents.popitem(last=False)
+    # Get MCP Tools
+    mcp_tools = await get_streamable_http_mcp_tools()
+    # Re-check after the await: a concurrent first-invocation for the same
+    # session_id may have built and stored the agent while we were awaiting.
+    # Don't overwrite it (that would orphan the agent the other request is using).
+    if session_id not in _agents:
+        _agents[session_id] = AssistantAgent(
+            name="{{ name }}",
+            model_client=load_model(),
+            tools=tools + mcp_tools,
+            system_message=SYSTEM_MESSAGE,
+        )
+    _agents.move_to_end(session_id)
+    return _agents[session_id]
+
+
+@app.entrypoint
+async def invoke(payload, context):
+    log.info("Invoking Agent.....")
+
+    # Process the user prompt
+    prompt = payload.get("prompt", "What can you help me with?")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
+    session_id = getattr(context, "session_id", "default-session")
+
+    # Reuse the per-session agent (preserves conversation history)
+    agent = await get_or_create_agent(session_id)
+
+    # Run the agent
+    result = await agent.run(task=prompt)
+
+    # Return result
+    return {"result": result.messages[-1].content}
+
+
+if __name__ == "__main__":
+    app.run()

agentcore/assets/python/http/autogen/base/mcp_client/__init__.py

@@ -0,0 +1 @@
+# Package marker

agentcore/assets/python/http/autogen/base/mcp_client/client.py

@@ -0,0 +1,28 @@
+from typing import List
+{{#if isVpc}}
+# VPC mode: external MCP endpoints are not reachable without a NAT gateway.
+# Add an AgentCore Gateway with `agentcore add gateway`, or configure your own endpoint below.
+
+
+async def get_streamable_http_mcp_tools() -> List:
+    """No MCP server configured. Add a gateway with `agentcore add gateway`."""
+    return []
+{{else}}
+from autogen_ext.tools.mcp import (
+    StreamableHttpMcpToolAdapter,
+    StreamableHttpServerParams,
+    mcp_server_tools,
+)
+
+# ExaAI provides information about code through web searches, crawling and code context searches through their platform. Requires no authentication
+EXAMPLE_MCP_ENDPOINT = "https://mcp.exa.ai/mcp"
+
+
+async def get_streamable_http_mcp_tools() -> List[StreamableHttpMcpToolAdapter]:
+    """
+    Returns MCP Tools compatible with AutoGen.
+    """
+    # to use an MCP server that supports bearer authentication, add headers={"Authorization": f"Bearer {access_token}"}
+    server_params = StreamableHttpServerParams(url=EXAMPLE_MCP_ENDPOINT)
+    return await mcp_server_tools(server_params)
+{{/if}}

agentcore/assets/python/http/autogen/base/model/__init__.py

@@ -0,0 +1 @@
+# Package marker

agentcore/assets/python/http/autogen/base/model/load.py

@@ -0,0 +1,136 @@
+{{#if (eq modelProvider "Bedrock")}}
+import os
+from autogen_ext.models.anthropic import AnthropicBedrockChatCompletionClient
+from autogen_core.models import ModelInfo, ModelFamily
+
+# Uses global inference profile for Claude Sonnet 4.5
+# https://docs.aws.amazon.com/bedrock/latest/userguide/inference-profiles-support.html
+MODEL_ID = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
+
+
+def load_model() -> AnthropicBedrockChatCompletionClient:
+    """Get Bedrock model client using IAM credentials."""
+    return AnthropicBedrockChatCompletionClient(
+        model=MODEL_ID,
+        model_info=ModelInfo(
+            vision=False,
+            function_calling=True,
+            json_output=False,
+            family=ModelFamily.CLAUDE_4_SONNET,
+            structured_output=True
+        ),
+        bedrock_info={"aws_region": os.environ.get("AWS_REGION", "us-east-1")}
+    )
+{{/if}}
+{{#if (eq modelProvider "Anthropic")}}
+import os
+from autogen_ext.models.anthropic import AnthropicChatCompletionClient
+from bedrock_agentcore.identity.auth import requires_api_key
+
+IDENTITY_PROVIDER_NAME = "{{identityProviders.[0].name}}"
+IDENTITY_ENV_VAR = "{{identityProviders.[0].envVarName}}"
+
+
+@requires_api_key(provider_name=IDENTITY_PROVIDER_NAME)
+def _agentcore_identity_api_key_provider(api_key: str) -> str:
+    """Fetch API key from AgentCore Identity."""
+    return api_key
+
+
+def _get_api_key() -> str:
+    """
+    Uses AgentCore Identity for API key management in deployed environments.
+    For local development, run via 'agentcore dev' which loads agentcore/.env.
+    """
+    if os.getenv("LOCAL_DEV") == "1":
+        api_key = os.getenv(IDENTITY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
+            )
+        return api_key
+    return _agentcore_identity_api_key_provider()
+
+
+def load_model() -> AnthropicChatCompletionClient:
+    """Get authenticated Anthropic model client."""
+    return AnthropicChatCompletionClient(
+        model="claude-sonnet-4-5-20250929",
+        api_key=_get_api_key()
+    )
+{{/if}}
+{{#if (eq modelProvider "OpenAI")}}
+import os
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from bedrock_agentcore.identity.auth import requires_api_key
+
+IDENTITY_PROVIDER_NAME = "{{identityProviders.[0].name}}"
+IDENTITY_ENV_VAR = "{{identityProviders.[0].envVarName}}"
+
+
+@requires_api_key(provider_name=IDENTITY_PROVIDER_NAME)
+def _agentcore_identity_api_key_provider(api_key: str) -> str:
+    """Fetch API key from AgentCore Identity."""
+    return api_key
+
+
+def _get_api_key() -> str:
+    """
+    Uses AgentCore Identity for API key management in deployed environments.
+    For local development, run via 'agentcore dev' which loads agentcore/.env.
+    """
+    if os.getenv("LOCAL_DEV") == "1":
+        api_key = os.getenv(IDENTITY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
+            )
+        return api_key
+    return _agentcore_identity_api_key_provider()
+
+
+def load_model() -> OpenAIChatCompletionClient:
+    """Get authenticated OpenAI model client."""
+    return OpenAIChatCompletionClient(
+        model="gpt-4o",
+        api_key=_get_api_key()
+    )
+{{/if}}
+{{#if (eq modelProvider "Gemini")}}
+import os
+from autogen_ext.models.openai import OpenAIChatCompletionClient
+from bedrock_agentcore.identity.auth import requires_api_key
+
+IDENTITY_PROVIDER_NAME = "{{identityProviders.[0].name}}"
+IDENTITY_ENV_VAR = "{{identityProviders.[0].envVarName}}"
+
+
+@requires_api_key(provider_name=IDENTITY_PROVIDER_NAME)
+def _agentcore_identity_api_key_provider(api_key: str) -> str:
+    """Fetch API key from AgentCore Identity."""
+    return api_key
+
+
+def _get_api_key() -> str:
+    """
+    Uses AgentCore Identity for API key management in deployed environments.
+    For local development, run via 'agentcore dev' which loads agentcore/.env.
+    """
+    if os.getenv("LOCAL_DEV") == "1":
+        api_key = os.getenv(IDENTITY_ENV_VAR)
+        if not api_key:
+            raise RuntimeError(
+                f"{IDENTITY_ENV_VAR} not found. Add {IDENTITY_ENV_VAR}=your-key to .env.local"
+            )
+        return api_key
+    return _agentcore_identity_api_key_provider()
+
+
+def load_model() -> OpenAIChatCompletionClient:
+    """Get authenticated Gemini model client via OpenAI-compatible API."""
+    return OpenAIChatCompletionClient(
+        model="gemini-2.0-flash",
+        api_key=_get_api_key(),
+        base_url="https://generativelanguage.googleapis.com/v1beta/openai/"
+    )
+{{/if}}

agentcore/assets/python/http/autogen/base/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "AgentCore Runtime Application using AutoGen SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "autogen-agentchat >= 0.7.5",
+    "autogen-ext[mcp] >= 0.7.5",
+    "opentelemetry-distro",
+    "opentelemetry-exporter-otlp",
+    "bedrock-agentcore >= 1.18.1",
+    "botocore[crt] >= 1.35.0",
+    "tiktoken",
+{{#if (eq modelProvider "Bedrock")}}
+    "autogen-ext[anthropic] >= 0.7.5",
+{{/if}}
+{{#if (eq modelProvider "Anthropic")}}
+    "autogen-ext[anthropic] >= 0.7.5",
+{{/if}}
+{{#if (eq modelProvider "OpenAI")}}
+    "autogen-ext[openai] >= 0.7.5",
+{{/if}}
+{{#if (eq modelProvider "Gemini")}}
+    "autogen-ext[openai] >= 0.7.5",
+{{/if}}
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

agentcore/assets/python/http/bma/base/Dockerfile

@@ -0,0 +1,41 @@
+FROM public.ecr.aws/lambda/microvms:al2023-minimal
+
+# OS setup
+RUN dnf install -y tar gzip findutils shadow-utils ca-certificates \
+ && dnf clean all \
+ && useradd -m -u 1000 app
+
+# Codex
+RUN curl -fsSL https://chatgpt.com/codex/install.sh -o /tmp/install-codex.sh \
+ && CODEX_NON_INTERACTIVE=1 CODEX_INSTALL_DIR=/opt/bma/bin CODEX_HOME=/opt/bma/codex \
+    sh /tmp/install-codex.sh \
+ && chmod -R a+rX /opt/bma \
+ && rm /tmp/install-codex.sh
+
+# CloudWatch agent
+RUN arch=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/') \
+ && curl -fsSL -o /tmp/cwagent.rpm \
+    https://amazoncloudwatch-agent.s3.amazonaws.com/amazon_linux/${arch}/latest/amazon-cloudwatch-agent.rpm \
+ && rpm -i /tmp/cwagent.rpm \
+ && rm /tmp/cwagent.rpm
+
+# uv and Python
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/
+ARG UV_DEFAULT_INDEX
+ARG UV_INDEX
+ENV UV_PYTHON_INSTALL_DIR=/opt/python UV_PYTHON_BIN_DIR=/usr/local/bin
+RUN uv python install --default
+
+# Application. The layout of /opt/bma is the same as the layout of this directory.
+WORKDIR /opt/bma
+ENV UV_COMPILE_BYTECODE=1 UV_NO_PROGRESS=1 \
+    UV_DEFAULT_INDEX=${UV_DEFAULT_INDEX} UV_INDEX=${UV_INDEX}
+COPY pyproject.toml uv.lock* ./
+RUN uv sync --no-dev
+COPY lifecycle/ lifecycle/
+COPY otel/ otel/
+COPY plugins/ plugins/
+USER app
+
+EXPOSE 8080
+CMD ["uv", "run", "--no-sync", "opentelemetry-instrument", "python", "-u", "lifecycle/server.py"]

agentcore/assets/python/http/bma/base/README.md

@@ -0,0 +1,178 @@
+This is a Bedrock Managed Agents (BMA) environment generated by the AgentCore CLI.
+
+# Layout
+
+BMA runs the agent loop (Codex) in the Bedrock Managed Agents service. This AgentCore Runtime (ACR) is the customer
+environment where BMA runs commands. The ACR has no model code.
+
+| Path | Description |
+| --- | --- |
+| `Dockerfile` | The ACR image. It installs the Codex CLI with OpenAI's installer, the CloudWatch agent, Python with uv, and the dependencies in `pyproject.toml`. It copies `lifecycle/`, `otel/`, and `plugins/` to the same paths under `/opt/bma`, the working directory of the image. |
+| `lifecycle/server.py` | The environment lifecycle server, `bma-acr-lifecycle`. It handles the lifecycle calls from BMA and starts `codex exec-server`. |
+| `otel/collector.yaml` | The configuration of the CloudWatch agent. The agent gets the spans and logs of `codex exec-server`, puts the session ID on them, and sends them to X-Ray and CloudWatch Logs with the ACR role. To turn off observability, add `DISABLE_ADOT_OBSERVABILITY` with the value `true` to `envVars`. |
+| `plugins/acr-report` | A Codex plugin with the `acr-report` skill. The skill saves the Python version, the user ID, and the working directory in `acr-report.txt`. |
+| `policies/bma-acr-policy.json` | Lets the ACR role call `bedrock-mantle:RegisterEnvironment` and `bedrock-mantle:ConnectEnvironment` on every Mantle project. To limit the role to your projects, change `Resource` to `arn:aws:bedrock-mantle:<region>:<account-id>:project/<project-id>`. |
+| `policies/bma-session-trust.json` | The trust policy of the session role. BMA assumes the session role to call the ACR. The conditions let only BMA sessions and projects in the account and the Region of the ACR assume the role. `client.py` changes `${AWS::Partition}`, `${AWS::Region}`, and `${AWS::AccountId}` to the values of the ACR ARN. |
+| `policies/bma-session-policy.json` | The policy of the session role. It lets BMA call the model with `bedrock-mantle:CreateInference`, and call and stop the ACRs and the Gateways in the account and the Region of the ACR. |
+| `pyproject.toml` | The Python dependencies. `aws-opentelemetry-distro` sends a span for each call from BMA and a child span for each step of the call, for example the state load or the exec-server start. `bedrock-agentcore` is the AgentCore SDK. The `dev` group has the dependencies of `client.py`, and the image does not install it. Each image build installs the latest Python and the latest releases. To pin them, run `uv lock` and keep `uv.lock` next to this file. `requires-python` sets only a minimum, 3.12, so that `uv run client.py` does not use an older system Python. |
+| `client.py` | A sample OpenAI SDK client. It creates the session role if necessary, and it creates a session in BMA. BMA sends the session's commands to this ACR. |
+
+Do not change `lifecycle/server.py`. It must match the lifecycle calls that BMA makes.
+
+The server always sends HTTP 200, because the Runtime changes any other status to 424 and drops the body. If a call
+fails, the body has the HTTP status code of the failure in `status_code` and the reason in `error`, for example
+`{"error": "the exec-server did not start", "status_code": 503}`.
+
+# Codex version
+
+The image build installs the latest Codex release. The server needs Codex 0.154.0 or newer because it runs
+`codex exec-server`. To pin a release, set `CODEX_RELEASE` next to `CODEX_NON_INTERACTIVE` in the `Dockerfile`. The
+image build downloads Codex and Python from the internet, so a build in VPC mode needs a route to the internet.
+
+# ACR settings
+
+`agentcore create` writes these settings to `agentcore/agentcore.json`:
+
+- `policies/bma-acr-policy.json` in `additionalPolicies`. The ACR role gets this policy.
+- An idle timeout of 1800 seconds (30 minutes) and a maximum lifetime of 28800
+  seconds (8 hours).
+- No session storage. Session storage is only for a microVM Runtime, so without it the same settings work on a
+  capacity provider.
+
+A value that you give to `agentcore create` replaces the value above.
+
+The server keeps the connection state in `state.json` in `BMA_STATE_DIR`. The default is `/home/app/.bma`. The client
+sets the workspace in `workspace_directory` when it creates the session. `client.py` uses `/home/app/workspace`. The
+server creates that directory and runs the agent commands in it. If the activate call has no workspace directory, the
+server returns status 400. If the server cannot create the directory, it returns status 503, logs
+`workspace_unavailable`, and does not start the exec-server.
+
+Files in the home directory do not stay after an idle stop. On a microVM Runtime, to keep the files and the connection
+state after an idle stop, put the home directory on session storage:
+
+1. Add session storage with `--session-storage-mount-path /mnt/home`.
+2. Set `BMA_HOME_DIR` to `/mnt/home` in `envVars`. Then `state.json` is in `/mnt/home/.bma`, and `CODEX_HOME` is
+   `/mnt/home/.codex`.
+3. Set `WORKSPACE_DIRECTORY` in `client.py` to `/mnt/home/workspace`.
+
+If you set `WORKSPACE_DIRECTORY` to a path on session storage, the Runtime must have session storage. If not, the
+server cannot create the workspace, and the session fails. If `BMA_STATE_DIR` is not on a mounted path, or the server
+cannot create it, the server keeps `state.json` in `.bma` in `BMA_HOME_DIR`.
+
+# Environment variables
+
+To change a setting of the server, add the variable to `envVars` of the agent in `agentcore/agentcore.json`. Then run
+`agentcore deploy`. For example:
+
+```json
+"envVars": [
+  { "name": "BMA_MAX_TURN_LEASE", "value": "600" },
+  { "name": "BMA_CODEX_BINARY", "value": "/opt/bma/bin/codex" }
+]
+```
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `DISABLE_ADOT_OBSERVABILITY` | Not set | Set to `true` to turn off the traces and the exec-server logs. The server still writes its own logs. |
+| `BMA_STATE_DIR` | `.bma` in `BMA_HOME_DIR` | The directory of `state.json`. |
+| `BMA_HOME_DIR` | The home directory of the image user | `HOME` of the exec-server. |
+| `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. The server changes a longer request to this value. |
+
+
+# Skills and plugins
+
+BMA finds skills and plugins in the directories that the client gives in `capability_directories`. A directory can be
+at any absolute path in the ACR. BMA does not need a copy in the workspace.
+
+- To add a skill to the image, put a plugin under `plugins/` and add its path under `/opt/bma/plugins` to
+  `CAPABILITY_DIRECTORIES` in `client.py`. A plugin has a `.codex-plugin/plugin.json` file and a `skills/` directory
+  with one directory for each skill. Each skill directory has a `SKILL.md` file.
+- To share skills from an S3 bucket, mount an S3 Files access point, for example at `/mnt/skills`, and add that
+  path to `CAPABILITY_DIRECTORIES`. Add the mount to `filesystemConfigurations` in `agentcore/agentcore.json` as an
+  `s3FilesAccessPoint` entry. An S3 Files mount needs VPC network mode.
+
+# Deploy
+
+```bash
+agentcore deploy
+```
+
+Give the ACR ARN to BMA when you create the BMA environment.
+
+# Session role
+
+BMA needs two IAM roles in your account:
+
+| Role | Who uses it | Who creates it |
+| --- | --- | --- |
+| The ACR role | The ACR, to connect to BMA. | `agentcore deploy`, with `policies/bma-acr-policy.json`. |
+| The session role | BMA, to call the model and to call and stop this ACR. | `client.py`, with `policies/bma-session-trust.json` and `policies/bma-session-policy.json`. |
+
+**`client.py` creates an IAM role in your account.** `agentcore deploy` does not create the session role, and
+`agentcore remove` does not delete it. The client always gives the session role to BMA, so you do not need the role
+`BedrockManagedAgentsPreviewInferenceServiceRole`.
+
+When the client creates a session and you do not give `--role-arn`, the client does these steps:
+
+1. It gets the partition, the Region, and the account from the ACR ARN, and it puts them in the two files.
+2. If the role `BmaSessionRole-<region>` does not exist, the client creates it.
+3. If the trust policy of the role is not the same as `policies/bma-session-trust.json`, the client writes the file to
+   the role.
+4. If the inline policy `BmaSession` of the role is not the same as `policies/bma-session-policy.json`, the client
+   writes the file to the role.
+5. If it changed the role, the client waits 15 seconds, because IAM needs this time before BMA can use the change.
+
+Thus, if you or another person changes the trust policy or the policy `BmaSession`, the next new session puts the
+files back. To change the role, change the files. Then run the client.
+
+The client does not change these items:
+
+- Other policies on the role. For example, a `Deny` policy that someone adds stays on the role, and the session fails.
+- A role that you give with `--role-arn`.
+- The role, when you give `--session-id` for a session that exists. BMA assumes the role again at each turn. If the role
+  is broken, the turn fails until a new session puts the files back.
+
+To use a role that you created, add `--role-arn <session role ARN>`. The trust policy must let
+`bedrock-mantle.amazonaws.com` assume the role, and the role needs the permissions in
+`policies/bma-session-policy.json`.
+
+To delete the session role:
+
+```bash
+aws iam delete-role-policy --role-name BmaSessionRole-<region> --policy-name BmaSession
+aws iam delete-role --role-name BmaSessionRole-<region>
+```
+
+# Run the client
+
+Run the client from this directory with the ACR ARN from `agentcore status`:
+
+```bash
+uv run client.py --runtime <ACR ARN>
+```
+
+The identity that runs the client needs these permissions:
+
+- `bedrock-mantle` permissions for the BMA sessions, for example `bedrock-mantle:CreateAgentSession`.
+- `bedrock-mantle:CallWithBearerToken`, because the client signs in with a bearer token.
+- `iam:PassRole` on the session role, with the condition `iam:PassedToService` set to `bedrock-mantle.amazonaws.com`.
+- `iam:GetRole`, `iam:CreateRole`, `iam:UpdateAssumeRolePolicy`, `iam:GetRolePolicy`, and `iam:PutRolePolicy` on
+  `arn:aws:iam::<account-id>:role/BmaSessionRole-*`. The client does not need these permissions if you give
+  `--role-arn`. Without them, the client stops and tells you to give `--role-arn`.
+
+`uv run` installs the dependencies and the `dev` group from `pyproject.toml` in `.venv`. The client creates a BMA
+session and prints the session ID, each command with its output, and the answer of the agent as it streams.
+
+To send another input to the same session, add the BMA session ID. If the session does not exist, the client creates a
+new session and prints its ID.
+
+```bash
+uv run client.py --runtime <ACR ARN> --session-id <BMA session ID> --input "List the files in the workspace."
+```
+
+If you add a Gateway, add `--gateway <Gateway MCP URL>` with the URL from the output of `agentcore deploy`. BMA adds
+the Gateway tools when it creates the session, so the flag has no effect on a session that exists.
+
+To delete the session after the turn, add `--delete`. To print each stream event as JSON, add `--raw`.