@aws/agentcore 0.3.0-preview.1.0

package/dist/assets/mcp/python/server.py

@@ -0,0 +1,117 @@
+"""
+MCP Server demonstrating HTTP tool patterns.
+
+This template shows:
+- Async HTTP boundaries with proper error handling
+- Retry logic and partial failure
+- Response parsing and validation
+
+Run with: uv run server.py
+"""
+
+import logging
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+logging.basicConfig(level=logging.INFO, format="%(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP("tools")
+
+HTTP_TIMEOUT = 10.0
+MAX_RETRIES = 2
+
+
+async def fetch_json(url: str, headers: dict[str, str] | None = None) -> dict[str, Any] | None:
+    """Make an HTTP GET request with retry logic."""
+    async with httpx.AsyncClient() as client:
+        for attempt in range(MAX_RETRIES):
+            try:
+                response = await client.get(url, headers=headers, timeout=HTTP_TIMEOUT)
+                response.raise_for_status()
+                return response.json()
+            except httpx.TimeoutException:
+                logger.warning(f"Timeout on attempt {attempt + 1} for {url}")
+            except httpx.HTTPStatusError as e:
+                logger.error(f"HTTP {e.response.status_code} for {url}")
+                return None
+            except httpx.RequestError as e:
+                logger.error(f"Request failed: {e}")
+                return None
+    return None
+
+
+@mcp.tool()
+async def lookup_ip(ip_address: str) -> str:
+    """Look up geolocation and network info for an IP address.
+
+    Args:
+        ip_address: IPv4 or IPv6 address to look up
+    """
+    data = await fetch_json(f"http://ip-api.com/json/{ip_address}")
+
+    if not data:
+        return f"Failed to look up IP: {ip_address}"
+
+    if data.get("status") == "fail":
+        return f"Lookup failed: {data.get('message', 'unknown error')}"
+
+    return (
+        f"IP: {data['query']}\n"
+        f"Location: {data['city']}, {data['regionName']}, {data['country']}\n"
+        f"ISP: {data['isp']}\n"
+        f"Organization: {data['org']}\n"
+        f"Timezone: {data['timezone']}"
+    )
+
+
+@mcp.tool()
+async def get_random_user() -> str:
+    """Generate a random user profile for testing or mock data."""
+    data = await fetch_json("https://randomuser.me/api/")
+
+    if not data or "results" not in data:
+        return "Failed to generate random user."
+
+    user = data["results"][0]
+    name = user["name"]
+    location = user["location"]
+
+    return (
+        f"Name: {name['first']} {name['last']}\n"
+        f"Email: {user['email']}\n"
+        f"Location: {location['city']}, {location['country']}\n"
+        f"Phone: {user['phone']}"
+    )
+
+
+@mcp.tool()
+async def fetch_post(post_id: int) -> str:
+    """Fetch a post by ID from JSONPlaceholder API.
+
+    Args:
+        post_id: The post ID (1-100)
+    """
+    if not 1 <= post_id <= 100:
+        return "Post ID must be between 1 and 100."
+
+    data = await fetch_json(f"https://jsonplaceholder.typicode.com/posts/{post_id}")
+
+    if not data:
+        return f"Failed to fetch post {post_id}."
+
+    return (
+        f"Post #{data['id']}\n"
+        f"Title: {data['title']}\n\n"
+        f"{data['body']}"
+    )
+
+
+def main():
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,22 @@
+# {{ Name }}
+
+Lambda-based tools for AgentCore Gateway.
+
+## Tools
+
+- `lookup_ip` - Look up geolocation for an IP address
+- `get_random_user` - Generate random user profile
+- `fetch_post` - Fetch a post by ID
+
+## Gateway Integration
+
+Tools are invoked via AgentCore Gateway. The tool name is passed in:
+`context.client_context.custom["bedrockAgentCoreToolName"]`
+
+Format: `{target_name}___{tool_name}`
+
+## Adding New Tools
+
+1. Define the tool function with the `@tool("tool_name")` decorator
+2. Add the tool definition to `mcp-defs.json` in your agentcore project
+3. The tool will be automatically routed by the handler

package/dist/assets/mcp/python-lambda/handler.py

@@ -0,0 +1,144 @@
+"""
+Lambda handler for AgentCore Gateway tools.
+
+This template mirrors the FastMCP server tools but runs as a Lambda function
+behind an AgentCore Gateway.
+
+Tool routing uses bedrockAgentCoreToolName from client context:
+  Format: {target_name}___{tool_name}
+"""
+import json
+import logging
+import urllib.request
+import urllib.error
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger()
+logger.setLevel(logging.INFO)
+
+HTTP_TIMEOUT = 10
+TOOLS = {}
+
+
+def tool(name: str):
+    """Decorator to register a tool handler."""
+    def decorator(func):
+        TOOLS[name] = func
+        return func
+    return decorator
+
+
+def lambda_handler(event: Dict[str, Any], context) -> Dict[str, Any]:
+    """Route incoming gateway requests to the appropriate tool."""
+    try:
+        extended_name = context.client_context.custom.get("bedrockAgentCoreToolName", "")
+        tool_name = None
+
+        if "___" in extended_name:
+            tool_name = extended_name.split("___", 1)[1]
+
+        if not tool_name:
+            return _response(400, {"error": "Missing tool name in bedrockAgentCoreToolName"})
+
+        handler = TOOLS.get(tool_name)
+        if not handler:
+            return _response(400, {"error": f"Unknown tool: {tool_name}"})
+
+        result = handler(event)
+        return _response(200, {"result": result})
+
+    except Exception as e:
+        logger.exception("Tool execution failed")
+        return _response(500, {"error": str(e)})
+
+
+def _response(status_code: int, body: Dict[str, Any]) -> Dict[str, Any]:
+    """Consistent JSON response wrapper."""
+    return {"statusCode": status_code, "body": json.dumps(body)}
+
+
+def _fetch_json(url: str) -> Optional[Dict[str, Any]]:
+    """Fetch JSON from URL with error handling."""
+    try:
+        req = urllib.request.Request(url, headers={"User-Agent": "AgentCore-Tool/1.0"})
+        with urllib.request.urlopen(req, timeout=HTTP_TIMEOUT) as resp:
+            return json.loads(resp.read().decode())
+    except (urllib.error.URLError, json.JSONDecodeError) as e:
+        logger.warning(f"Failed to fetch {url}: {e}")
+        return None
+
+
+@tool("{{Name}}_lookup_ip")
+def lookup_ip(event: Dict[str, Any]) -> str:
+    """Look up geolocation and network info for an IP address.
+
+    Args:
+        ip_address: IPv4 or IPv6 address to look up
+    """
+    ip_address = event.get("ip_address", "")
+    if not ip_address:
+        return "Missing required parameter: ip_address"
+
+    data = _fetch_json(f"http://ip-api.com/json/{ip_address}")
+    if not data:
+        return f"Failed to look up IP: {ip_address}"
+
+    if data.get("status") == "fail":
+        return f"Lookup failed: {data.get('message', 'unknown error')}"
+
+    return (
+        f"IP: {data['query']}\n"
+        f"Location: {data['city']}, {data['regionName']}, {data['country']}\n"
+        f"ISP: {data['isp']}\n"
+        f"Organization: {data['org']}\n"
+        f"Timezone: {data['timezone']}"
+    )
+
+
+@tool("{{Name}}_get_random_user")
+def get_random_user(event: Dict[str, Any]) -> str:
+    """Generate a random user profile for testing or mock data."""
+    data = _fetch_json("https://randomuser.me/api/")
+    if not data or "results" not in data:
+        return "Failed to generate random user."
+
+    user = data["results"][0]
+    name = user["name"]
+    location = user["location"]
+
+    return (
+        f"Name: {name['first']} {name['last']}\n"
+        f"Email: {user['email']}\n"
+        f"Location: {location['city']}, {location['country']}\n"
+        f"Phone: {user['phone']}"
+    )
+
+
+@tool("{{Name}}_fetch_post")
+def fetch_post(event: Dict[str, Any]) -> str:
+    """Fetch a post by ID from JSONPlaceholder API.
+
+    Args:
+        post_id: The post ID (1-100)
+    """
+    post_id = event.get("post_id")
+    if post_id is None:
+        return "Missing required parameter: post_id"
+
+    try:
+        post_id = int(post_id)
+    except (TypeError, ValueError):
+        return "post_id must be an integer"
+
+    if not 1 <= post_id <= 100:
+        return "Post ID must be between 1 and 100."
+
+    data = _fetch_json(f"https://jsonplaceholder.typicode.com/posts/{post_id}")
+    if not data:
+        return f"Failed to fetch post {post_id}."
+
+    return (
+        f"Post #{data['id']}\n"
+        f"Title: {data['title']}\n\n"
+        f"{data['body']}"
+    )

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

@@ -0,0 +1,15 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "{{ name }}"
+version = "0.1.0"
+description = "Lambda tools for AgentCore Gateway"
+readme = "README.md"
+requires-python = ">=3.10"
+# No external dependencies - uses stdlib only
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]

package/dist/assets/python/autogen/base/README.md

@@ -0,0 +1,41 @@
+This is a project generated by the agentcore create CLI tool!
+
+# Layout
+
+There is one directory with generated application code, `src/` . At the root, there is a `.gitignore` file, a
+`.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.
+
+## src/
+
+The main entrypoint to your app is defined in `src/main.py`. Using the AgentCore SDK `@app.entrypoint` decorator, this
+file defines a Starlette ASGI app with the AutoGen framework running within.
+
+`src/model/load.py` instantiates your chosen model provider.
+
+## Environment Variables
+
+| Variable                       | Required        | Description                                                      |
+| ------------------------------ | --------------- | ---------------------------------------------------------------- |
+| `AGENTCORE_IDENTITY_OPENAI`    | Yes (OpenAI)    | OpenAI API key (local) or Identity provider name (deployed)      |
+| `AGENTCORE_IDENTITY_ANTHROPIC` | Yes (Anthropic) | Anthropic API key (local) or Identity provider name (deployed)   |
+| `AGENTCORE_IDENTITY_GEMINI`    | Yes (Gemini)    | Gemini API key (local) or Identity provider name (deployed)      |
+| `LOCAL_DEV`                    | No              | Set to `1` to use `agentcore/.env` instead of AgentCore Identity |
+
+# Developing locally
+
+If installation was successful, a virtual environment is already created with dependencies installed.
+
+Run `source .venv/bin/activate` before developing.
+
+`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.

package/dist/assets/python/autogen/base/gitignore.template

@@ -0,0 +1,40 @@
+# 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/
+ENV/
+env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db

package/dist/assets/python/autogen/base/main.py

@@ -0,0 +1,52 @@
+import os
+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]
+
+
+@app.entrypoint
+async def invoke(payload, context):
+    log.info("Invoking Agent.....")
+
+    # Get MCP Tools
+    mcp_tools = await get_streamable_http_mcp_tools()
+
+    # Define an AssistantAgent with the model and tools
+    agent = AssistantAgent(
+        name="{{ name }}",
+        model_client=load_model(),
+        tools=tools + mcp_tools,
+        system_message="You are a helpful assistant. Use tools when appropriate.",
+    )
+
+    # Process the user prompt
+    prompt = payload.get("prompt", "What can you help me with?")
+
+    # Run the agent
+    result = await agent.run(task=prompt)
+
+    # Return result
+    return {"result": result.messages[-1].content}
+
+
+if __name__ == "__main__":
+    app.run()

package/dist/assets/python/autogen/base/mcp_client/client.py

@@ -0,0 +1,18 @@
+from typing import List
+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)

package/dist/assets/python/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}}

package/dist/assets/python/autogen/base/pyproject.toml

@@ -0,0 +1,35 @@
+[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.0.3",
+    "botocore[crt] >= 1.35.0",
+    "python-dotenv >= 1.0.1",
+    "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 = ["."]

package/dist/assets/python/crewai/base/README.md

@@ -0,0 +1,41 @@
+This is a project generated by the agentcore create CLI tool!
+
+# Layout
+
+There is one directory with generated application code, `src/` . At the root, there is a `.gitignore` file, a
+`.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.
+
+## src/
+
+The main entrypoint to your app is defined in `src/main.py`. Using the AgentCore SDK `@app.entrypoint` decorator, this
+file defines a Starlette ASGI app with the CrewAI framework running within.
+
+`src/model/load.py` instantiates your chosen model provider.
+
+## Environment Variables
+
+| Variable                       | Required        | Description                                                      |
+| ------------------------------ | --------------- | ---------------------------------------------------------------- |
+| `AGENTCORE_IDENTITY_OPENAI`    | Yes (OpenAI)    | OpenAI API key (local) or Identity provider name (deployed)      |
+| `AGENTCORE_IDENTITY_ANTHROPIC` | Yes (Anthropic) | Anthropic API key (local) or Identity provider name (deployed)   |
+| `AGENTCORE_IDENTITY_GEMINI`    | Yes (Gemini)    | Gemini API key (local) or Identity provider name (deployed)      |
+| `LOCAL_DEV`                    | No              | Set to `1` to use `agentcore/.env` instead of AgentCore Identity |
+
+# Developing locally
+
+If installation was successful, a virtual environment is already created with dependencies installed.
+
+Run `source .venv/bin/activate` before developing.
+
+`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.