Amazon Bedrock AgentCore Python SDK

Warnings

• breaking Version 1.5.1 reverted the feature to emit OTEL (OpenTelemetry) attributes for AgentCore Evaluation support. If your application relies on these specific OTEL attributes for observability, this change will break that integration.
  Fix: Review your observability setup if you were leveraging OTEL attributes from AgentCore Evaluation. You may need to adjust your tracing configuration or find alternative metrics.
• gotcha AccessDeniedException is a common issue due to insufficient IAM permissions for the caller or the agent's execution role. This can occur during agent creation or runtime invocation.
  Fix: Ensure your AWS identity has `bedrock-agentcore:CreateAgentRuntime` and other necessary permissions. Verify the agent's execution role grants required permissions to interact with Bedrock services and any tools it uses. Consult AWS IAM documentation for Bedrock AgentCore specific policies.
• gotcha Using outdated `boto3` or `botocore` libraries can lead to `Unknown service: 'bedrock-agent-core-runtime'` errors when attempting to interact with Bedrock AgentCore APIs.
  Fix: Regularly update `boto3` and `botocore` to their latest versions: `pip install --upgrade boto3 botocore`. Ensure both are at or above the minimum required versions (boto3 1.39.8+, botocore 1.33.8+).
• gotcha The AWS region resolution order can be complex. If not explicitly passed as a parameter to SDK clients, the region is determined by `boto3_session`, `AWS_REGION` environment variable, `AWS_DEFAULT_REGION`, or falls back to `us-west-2`. Inconsistent region configuration can lead to resources not found or `AccessDeniedException` if the agent attempts to operate in an unintended region.
  Fix: Always explicitly specify the `region_name` when initializing SDK clients, or consistently set the `AWS_REGION` environment variable in your deployment environment to avoid ambiguity.

Install

• pip install bedrock-agentcore Install latest version

Imports

• BedrockAgentCoreApp

  from bedrock_agentcore.agent import BedrockAgentCoreApp

• entrypoint

  from bedrock_agentcore.agent import entrypoint

• MemorySessionManager

  from bedrock_agentcore.memory import MemorySessionManager

Quickstart

This quickstart demonstrates how to define a simple AI agent using the `bedrock-agentcore` SDK. It initializes a `BedrockAgentCoreApp` and registers a handler function with the `@entrypoint` decorator. The agent echoes back the received prompt. The `app.run()` method allows for local testing by starting an HTTP server. Remember to set your AWS region and configure AWS credentials for local execution.

import os
from bedrock_agentcore.agent import BedrockAgentCoreApp, entrypoint

# Initialize the AgentCore application
app = BedrockAgentCoreApp(
    region_name=os.environ.get('AWS_REGION', 'us-east-1')
)

# Define your agent's entrypoint
@app.entrypoint()
def handler(event):
    """Handles incoming agent invocations."""
    prompt = event.prompt
    # In a real agent, you would process the prompt, use tools, or interact with memory.
    response_content = f"Hello from your AgentCore agent! You said: {prompt}"
    
    # The response must be a dictionary with a 'response' key for simple text responses
    return {"response": response_content}

# To run the agent locally (for development and testing)
# Make sure to set AWS_REGION and have AWS credentials configured.
# The `app.run()` method starts a local HTTP server on port 8080.
# You can test it with `curl -X POST http://localhost:8080/invocations -H "Content-Type: application/json" -d '{"prompt": "What's up?"}'`
if __name__ == "__main__":
    print("Starting Bedrock AgentCore agent locally. Access at http://localhost:8080/invocations")
    print("Ensure AWS_REGION environment variable is set and AWS credentials are configured.")
    app.run()