@aws/agentcore 1.0.0-preview.9 → 1.0.0-rc.1

package/dist/assets/evaluators/python-lambda/README.md

@@ -0,0 +1,28 @@
+# {{ Name }}
+
+An AgentCore **code-based evaluator** — a Lambda that scores an agent session
+with your own logic.
+
+## What's here
+
+- `lambda_function.py` — the evaluator. The `@custom_code_based_evaluator()`
+  handler receives an `EvaluatorInput` (the session / trace / tool-call to
+  grade) and returns an `EvaluatorOutput` (`value` + `label`, or an error). It
+  ships as a stub that returns `Pass` for everything — replace the `TODO` with
+  your scoring logic.
+- `pyproject.toml` — Python dependencies, managed with
+  [uv](https://docs.astral.sh/uv/).
+- `execution-role-policy.json` — extra IAM the evaluator Lambda gets at runtime.
+  Add statements here for anything your logic calls (DynamoDB, S3, …).
+
+## Write your evaluator
+
+```python
+@custom_code_based_evaluator()
+def handler(input: EvaluatorInput, context) -> EvaluatorOutput:
+    # inspect input.session_spans / input.target_trace_id / input.target_span_id
+    return EvaluatorOutput(value=1.0, label="Pass", explanation="…")
+```
+
+Then `agentcore project deploy` packages this directory into the evaluator
+Lambda and registers the evaluator.

package/dist/assets/evaluators/python-lambda/pyproject.toml

@@ -8,7 +8,7 @@ version = "0.1.0"
 description = "AgentCore Code-Based Evaluator"
 requires-python = ">=3.10"
 dependencies = [
-    "bedrock-agentcore>=1.6.0",
+    "bedrock-agentcore>=1.6.0,<2.0.0",
 ]
 
 [tool.hatch.build.targets.wheel]

package/dist/assets/templates/a2a-python-strands/README.md

@@ -0,0 +1,31 @@
+# {{ name }}
+
+An A2A (Agent-to-Agent) agent deployed on Amazon Bedrock AgentCore using the Strands SDK.
+
+## Overview
+
+This agent speaks the A2A protocol. Other agents discover it via its agent card at
+`/.well-known/agent-card.json` and invoke it with JSON-RPC (`message/send`, `message/stream`)
+at the server root, matching the AgentCore Runtime A2A service contract.
+
+## Adding Tools
+
+Define tools with the `@tool` decorator in `main.py` and add them to the `tools` list:
+
+```python
+@tool
+def my_tool(param: str) -> str:
+    """Description of what the tool does."""
+    return f"Result: {param}"
+```
+
+## Developing locally
+
+`agentcore project dev` starts the agent locally on `0.0.0.0:9000`. Fetch its agent card at
+`http://127.0.0.1:9000/.well-known/agent-card.json` and send it messages by posting A2A
+JSON-RPC to `http://127.0.0.1:9000/`.
+
+## Deployment
+
+`agentcore project deploy` deploys the agent into Amazon Bedrock AgentCore. Invoke it with the
+AWS CLI (`bedrock-agentcore invoke-agent-runtime`) using an A2A JSON-RPC payload.

package/dist/assets/templates/a2a-python-strands/main.py

@@ -0,0 +1,100 @@
+from strands import Agent, tool
+from strands.multiagent.a2a.executor import StrandsA2AExecutor
+from bedrock_agentcore.runtime import serve_a2a
+from model.load import load_model
+from memory.session import get_memory_session_manager
+{{#if needsOs}}
+import os
+{{/if}}
+
+
+@tool
+def add_numbers(a: int, b: int) -> int:
+    """Return the sum of two numbers."""
+    return a + b
+
+
+tools = [add_numbers]
+
+{{#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
+
+@tool
+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}"
+
+@tool
+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}"
+
+@tool
+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([file_read, file_write, list_files])
+{{/if}}
+
+SYSTEM_PROMPT = """
+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}}
+"""
+
+# serve_a2a serves one agent instance, so it is bound to a fixed session and
+# actor; get_memory_session_manager returns None (in-process history only) until
+# the deployed MEMORY_ID env var is set by the CDK.
+agent = Agent(
+    name="{{ name }}",
+    model=load_model(),
+    session_manager=get_memory_session_manager("default-session", "default-user"),
+    system_prompt=SYSTEM_PROMPT,
+    tools=tools,
+)
+
+# serve_a2a binds 0.0.0.0:9000 in the container (the AgentCore A2A service
+# contract) and publishes the agent card at /.well-known/agent-card.json. The
+# card is derived by introspecting the executor's agent.
+if __name__ == "__main__":
+    serve_a2a(StrandsA2AExecutor(agent))

package/dist/assets/templates/a2a-python-strands/memory/session.py

@@ -0,0 +1,35 @@
+import os
+import uuid
+from typing import Optional
+
+from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig, RetrievalConfig
+from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager
+
+MEMORY_ID = os.getenv("{{memoryEnvVarName}}")
+REGION = os.getenv("AWS_REGION")
+
+
+def get_memory_session_manager(
+    session_id: Optional[str], actor_id: str
+) -> Optional[AgentCoreMemorySessionManager]:
+    if not MEMORY_ID:
+        return None
+
+    session_id = session_id or uuid.uuid4().hex
+
+    retrieval_config = {
+        f"/users/{actor_id}/facts": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/users/{actor_id}/preferences": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/episodes/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),
+        f"/summaries/{actor_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+    }
+
+    return AgentCoreMemorySessionManager(
+        AgentCoreMemoryConfig(
+            memory_id=MEMORY_ID,
+            session_id=session_id,
+            actor_id=actor_id,
+            retrieval_config=retrieval_config,
+        ),
+        REGION,
+    )

package/dist/assets/templates/a2a-python-strands/model/load.py

@@ -0,0 +1,6 @@
+from strands.models.bedrock import BedrockModel
+
+
+def load_model() -> BedrockModel:
+    """Get Bedrock model client using IAM credentials."""
+    return BedrockModel(model_id="global.anthropic.claude-sonnet-4-5-20250929-v1:0")

package/dist/assets/templates/a2a-python-strands/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling ~= 1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "AgentCore A2A Agent using Strands SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "a2a-sdk[all] ~= 0.3.0",
+    "aws-opentelemetry-distro ~= 0.17.0",
+    "bedrock-agentcore[a2a] ~= 1.9.1",
+    "botocore[crt] ~= 1.43.0",
+    "strands-agents ~= 1.15.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

package/dist/assets/templates/agent-python-langchain/README.md

@@ -0,0 +1,55 @@
+# agent-python-langchain
+
+A LangChain agent on AgentCore Runtime, calling Claude through Amazon Bedrock.
+The agent is built with `create_agent`, keeps conversation history per Runtime
+session, and streams its response.
+
+## What's here
+
+- `main.py`: the agent. A `BedrockAgentCoreApp` wraps an async entrypoint
+  that reads `prompt` from the payload, runs the agent, and streams each model
+  chunk back as a JSON event of content blocks. An `InMemorySaver` checkpointer
+  keyed on the Runtime session id carries history between turns.
+- `model/load.py`: creates the Bedrock chat model with `init_chat_model`.
+- `pyproject.toml`: Python dependencies, managed with
+  [uv](https://docs.astral.sh/uv/). `agentcore project create` has already run
+  `uv sync` for you (unless you passed `--skip-install`), so `.venv/` is ready.
+
+## Develop
+
+Run the agent locally from the project root:
+
+```bash
+agentcore project dev
+agentcore project invoke runtime --local --payload '{"prompt":"What is 2 plus 3?"}'
+```
+
+Environment variables for local development go in `agentcore/.env.local`
+(gitignored).
+
+## Deploy
+
+```bash
+agentcore project deploy
+agentcore project invoke runtime --payload '{"prompt":"Hello!"}'
+```
+
+Traces are collected automatically: AgentCore Runtime starts the agent under
+`opentelemetry-instrument`, which picks up `opentelemetry-instrumentation-langchain`
+from the dependencies.
+
+## Extending
+
+Everything hangs off the `create_agent` call in `main.py`.
+
+- **Tools.** Add a function decorated with `@tool` and append it to `tools`.
+- **Middleware.** Hook the agent loop with `langchain.agents.middleware`, for
+  example a `@before_model` function passed as `middleware=[...]`.
+- **Durable memory.** Replace `InMemorySaver()` with `AgentCoreMemorySaver`
+  from `langgraph-checkpoint-aws` and add `actor_id` next to `thread_id` in the
+  `configurable` config to persist history in AgentCore Memory.
+- **Structured output.** Pass a Pydantic model as `response_format=` and read
+  `structured_response` from the final state.
+
+See the [LangChain agents documentation](https://docs.langchain.com/oss/python/langchain/agents)
+for the full `create_agent` surface.

package/dist/assets/{python/a2a/googleadk/base → templates/agent-python-langchain}/gitignore.template

@@ -38,4 +38,4 @@ env/
 
 # OS
 .DS_Store
-Thumbs.db
+Thumbs.db

package/dist/assets/templates/agent-python-langchain/main.py

@@ -0,0 +1,54 @@
+from langchain.agents import create_agent
+from langchain.tools import tool
+from langchain_core.messages import AIMessageChunk
+from langgraph.checkpoint.memory import InMemorySaver
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+from model.load import load_model
+
+app = BedrockAgentCoreApp()
+
+SYSTEM_PROMPT = "You are a helpful assistant. Use tools when appropriate."
+
+
+@tool
+def add_numbers(a: int, b: int) -> int:
+    """Return the sum of two numbers"""
+    return a + b
+
+
+tools = [add_numbers]
+
+agent = create_agent(
+    model=load_model(),
+    tools=tools,
+    system_prompt=SYSTEM_PROMPT,
+    checkpointer=InMemorySaver(),
+)
+
+
+@app.entrypoint
+async def invoke(payload, context):
+    prompt = payload.get("prompt") if isinstance(payload, dict) else None
+    if not isinstance(prompt, str) or not prompt:
+        yield {"error": "payload must be a JSON object with a non-empty string 'prompt'"}
+        return
+
+    session_id = context.session_id or "default-session"
+    config = {"configurable": {"thread_id": session_id}}
+
+    async for event in agent.astream(
+        {"messages": [{"role": "user", "content": prompt}]},
+        config,
+        stream_mode="messages",
+        version="v2",
+    ):
+        message, metadata = event["data"]
+        if not isinstance(message, AIMessageChunk):
+            continue
+        blocks = message.content_blocks
+        if blocks:
+            yield {"node": metadata["langgraph_node"], "content": blocks}
+
+
+if __name__ == "__main__":
+    app.run()

package/dist/assets/templates/agent-python-langchain/model/load.py

@@ -0,0 +1,9 @@
+from langchain.chat_models import init_chat_model
+from langchain_core.language_models import BaseChatModel
+
+MODEL_ID = "global.anthropic.claude-sonnet-4-5-20250929-v1:0"
+
+
+def load_model() -> BaseChatModel:
+    """Get a Bedrock chat model using IAM credentials."""
+    return init_chat_model(MODEL_ID, model_provider="bedrock_converse")

package/dist/assets/templates/agent-python-langchain/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling ~= 1.27.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "AgentCore Runtime Application using LangChain"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "aws-opentelemetry-distro ~= 0.19.0",
+    "bedrock-agentcore ~= 1.22.0",
+    "langchain ~= 1.4.0",
+    "langchain-aws ~= 1.7.5",
+    "langgraph ~= 1.2.11",
+    "opentelemetry-instrumentation-langchain ~= 0.62.3",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

package/dist/assets/templates/agent-python-minimal/README.md

@@ -0,0 +1,31 @@
+# agent-python-minimal
+
+A minimal AgentCore Runtime HTTP agent with no agent framework. Its
+`@app.entrypoint` returns a fixed `Hello, world!` message for every
+invocation — a starting point you own and grow into a real agent.
+
+## What's here
+
+- `main.py` — the agent. A `BedrockAgentCoreApp` wraps the entrypoint that
+  receives each invocation payload and returns the response.
+- `pyproject.toml` — Python dependencies, managed with
+  [uv](https://docs.astral.sh/uv/). `agentcore project create` has already run
+  `uv sync` for you (unless you passed `--skip-install`), so `.venv/` is ready.
+
+## Develop
+
+Run the agent locally from the project root:
+
+```bash
+agentcore project dev
+```
+
+Environment variables for local development go in `agentcore/.env.local`
+(gitignored).
+
+## Deploy
+
+```bash
+agentcore project deploy
+agentcore project invoke runtime --payload '{"prompt":"Hello!"}'
+```

package/dist/assets/templates/agent-python-minimal/main.py

@@ -0,0 +1,13 @@
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+
+app = BedrockAgentCoreApp()
+
+
+@app.entrypoint
+def invoke(payload, context):
+    """Add agent logic here"""
+    return {"message": "Hello, world!"}
+
+
+if __name__ == "__main__":
+    app.run()

package/dist/assets/templates/agent-python-minimal/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-python-minimal"
+version = "0.1.0"
+description = "Minimal AgentCore Runtime HTTP agent"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "aws-opentelemetry-distro ~= 0.18.0",
+    "bedrock-agentcore ~= 1.9.1",
+    "botocore[crt] ~= 1.43.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

package/dist/assets/{container/python/Dockerfile → templates/agent-python-strands/Dockerfile.template}

@@ -1,4 +1,6 @@
-FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
+FROM public.ecr.aws/docker/library/python:3.12-slim-trixie
+
+RUN pip install --no-cache-dir uv
 
 ARG UV_DEFAULT_INDEX
 ARG UV_INDEX

package/dist/assets/templates/agent-python-strands/README.md

@@ -0,0 +1,46 @@
+This is a project generated by the AgentCore CLI!
+
+# 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 Strands Agent SDK running within.
+
+`model/load.py` instantiates the chosen model provider.
+
+## Input Validation
+
+Validate invocation input before forwarding it to Strands. Keep plain prompts typed as strings. If the app accepts a
+caller-supplied message history, retain `strip_trailing_tool_use()`, which normalizes the history tail before
+invoking the agent.
+
+## Environment Variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+{{#if identityProviders.[0]}}| `{{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 project dev` will start a local server on 0.0.0.0:8080.
+
+# Deployment
+
+After providing credentials, `agentcore project deploy` will deploy your project into Amazon Bedrock AgentCore.
+
+Invoke the deployed Runtime with its native payload:
+
+```bash
+agentcore project invoke runtime --payload '{"prompt":"Hello!"}'
+```

package/dist/assets/{python/a2a/langchain_langgraph/base → templates/agent-python-strands}/gitignore.template

@@ -38,4 +38,4 @@ env/
 
 # OS
 .DS_Store
-Thumbs.db
+Thumbs.db

package/dist/assets/templates/agent-python-strands/main.py

@@ -0,0 +1,106 @@
+from typing import Any
+
+from strands import Agent, tool
+from strands.agent.conversation_manager.null_conversation_manager import NullConversationManager
+from bedrock_agentcore.runtime import BedrockAgentCoreApp
+from model.load import load_model
+from memory.session import get_memory_session_manager
+
+app = BedrockAgentCoreApp()
+log = app.logger
+
+DEFAULT_SYSTEM_PROMPT = "You are a helpful assistant. Use tools when appropriate."
+
+# Define a collection of tools used by the model
+tools = []
+
+
+# Define a simple function tool
+@tool
+def add_numbers(a: int, b: int) -> int:
+    """Return the sum of two numbers"""
+    return a + b
+
+
+tools.append(add_numbers)
+
+
+def _make_conversation_manager():
+    return NullConversationManager()
+
+
+def agent_factory():
+    cache = {}
+    def get_or_create_agent(session_id, user_id):
+        key = f"{session_id}/{user_id}"
+        if key not in cache:
+            cache[key] = Agent(
+                model=load_model(),
+                session_manager=get_memory_session_manager(session_id, user_id),
+                conversation_manager=_make_conversation_manager(),
+                system_prompt=DEFAULT_SYSTEM_PROMPT,
+                tools=tools,
+            )
+        return cache[key]
+    return get_or_create_agent
+get_or_create_agent = agent_factory()
+
+
+def strip_trailing_tool_use(messages: Any) -> list[dict]:
+    """Strip toolUse blocks from the tail until the last message has none."""
+    if not isinstance(messages, list):
+        raise ValueError("messages must be a list")
+
+    messages = list(messages)
+    while messages:
+        last = messages[-1]
+        if not isinstance(last, dict):
+            raise ValueError("each message must be an object")
+        original_content = last.get("content", [])
+        if not isinstance(original_content, list) or not all(isinstance(block, dict) for block in original_content):
+            raise ValueError("each message content value must be a list of content blocks")
+
+        content = [block for block in original_content if "toolUse" not in block]
+        if len(content) == len(original_content):
+            break
+        if content:
+            messages[-1] = {**last, "content": content}
+            break
+        messages.pop()
+
+    return messages
+
+
+def _extract_prompt(payload: dict):
+    """Accept a caller-supplied message history or a plain prompt string."""
+    if not isinstance(payload, dict):
+        raise ValueError("payload must be a JSON object")
+    if "messages" in payload:
+        return strip_trailing_tool_use(payload["messages"])
+    prompt = payload.get("prompt", "")
+    if not isinstance(prompt, str):
+        raise ValueError("prompt must be a string")
+    return prompt
+
+
+@app.entrypoint
+async def invoke(payload, context):
+    log.info("Invoking Agent.....")
+
+    session_id = getattr(context, "session_id", "default-session")
+    user_id = getattr(context, "user_id", "default-user")
+    agent = get_or_create_agent(session_id, user_id)
+
+    prompt = _extract_prompt(payload)
+
+    async for event in agent.stream_async(prompt):
+        if not isinstance(event, dict) or "event" not in event:
+            continue
+        cbs = event["event"].get("contentBlockStart")
+        if cbs is not None and not cbs.get("start"):
+            continue
+        yield event
+
+
+if __name__ == "__main__":
+    app.run()

package/dist/assets/templates/agent-python-strands/memory/session.py

@@ -0,0 +1,35 @@
+import os
+import uuid
+from typing import Optional
+
+from bedrock_agentcore.memory.integrations.strands.config import AgentCoreMemoryConfig, RetrievalConfig
+from bedrock_agentcore.memory.integrations.strands.session_manager import AgentCoreMemorySessionManager
+
+MEMORY_ID = os.getenv("{{memoryEnvVarName}}")
+REGION = os.getenv("AWS_REGION")
+
+
+def get_memory_session_manager(
+    session_id: Optional[str], actor_id: str
+) -> Optional[AgentCoreMemorySessionManager]:
+    if not MEMORY_ID:
+        return None
+
+    session_id = session_id or uuid.uuid4().hex
+
+    retrieval_config = {
+        f"/users/{actor_id}/facts": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/users/{actor_id}/preferences": RetrievalConfig(top_k=3, relevance_score=0.5),
+        f"/episodes/{actor_id}/{session_id}": RetrievalConfig(top_k=5, relevance_score=0.5),
+        f"/summaries/{actor_id}": RetrievalConfig(top_k=3, relevance_score=0.5),
+    }
+
+    return AgentCoreMemorySessionManager(
+        AgentCoreMemoryConfig(
+            memory_id=MEMORY_ID,
+            session_id=session_id,
+            actor_id=actor_id,
+            retrieval_config=retrieval_config,
+        ),
+        REGION,
+    )