Bedrock AgentCore Starter Toolkit

Amazon Bedrock AgentCore is a modular platform for deploying and operating AI agents securely and at scale. It provides purpose-built infrastructure that works with popular open-source frameworks (like LangGraph, CrewAI, and Strands) and any model.

Core modular services include:

• Runtime: A secure, serverless runtime for deploying and scaling dynamic agents and tools.
• Memory: Provides short-term (multi-turn conversation) and long-term (shared across sessions) memory management.
• Gateway: A managed Model Context Protocol (MCP) server that converts APIs and Lambda functions into MCP tools.
• Code Interpreter: Enables secure code execution in isolated sandbox environments.
• Browser: A cloud-based browser runtime for agents to interact with websites.
• Observability: Provides OpenTelemetry-compatible telemetry and dashboards for tracing and debugging.
• Evaluation: Tools for assessing agent quality (helpfulness, correctness, etc.) via on-demand or continuous monitoring.
• Identity: Secure agent identity and access management compatible with existing identity providers.
• Policy: Real-time, deterministic control over agent actions using natural language or Cedar policy language.
• Import-Agent: Facilitates migrating existing Amazon Bedrock Agents to AgentCore frameworks (LangChain/LangGraph or Strands).

When using the import-agent utility to migrate from Amazon Bedrock Agents to AgentCore (using either Langchain or Strands), the following feature mappings apply:

Policies are written in the Cedar language to permit or forbid access to gateway tools. A policy consists of a Who (principal), What (action), Which (resource), and When (conditions).

Authorization Semantics

Cedar follows a forbid-overrides-permit model:

1. Default Deny: If no policies match, the result is DENY.
2. Forbid Wins: If any forbid policy matches, the result is DENY, even if a permit policy also matches.
3. At Least One Permit Required: If at least one permit policy matches and no forbid policies match, the result is ALLOW.

Policy Enforcement Modes

• LOG_ONLY: Evaluates and logs decisions without blocking actions (ideal for testing).
• ENFORCE: Actively allows or denies agent operations based on the decision.

permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"RefundTool__process_refund",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/refund-gateway"
)
when {
  principal.hasTag("username") &&
  principal.getTag("username") == "refund-agent" &&
  context.input.amount < 500
};

For long-running tasks, use AgentCore's asynchronous processing to avoid blocking the main response.

Key Features:

• Automatic Status Management: The agent status automatically switches to HealthyBusy during background processing and returns to Healthy upon completion.
• Session Termination: Sessions terminate after 15 minutes of inactivity.

Two Approaches:

1. Manual Task Management: Use app.add_async_task(name, payload) to get a task_id, then call app.complete_async_task(task_id) when finished.
2. Custom Ping Handler: Implement a @app.ping decorator that returns PingStatus.HEALTHY_BUSY if the system is currently processing data.

@app.entrypoint
def handler(event):
    task_id = app.add_async_task("data_processing", {"batch": 100})

    def background_work():
        import time
        time.sleep(30)
        app.complete_async_task(task_id)

    import threading
    threading.Thread(target=background_work, daemon=True).start()
    return {"task_id": task_id}

AgentCore Policy provides a deterministic authorization layer that sits outside of the agent's code. The core components are:

• Policy Engines: Containers used to organize and manage related Cedar policies. They act as the evaluation unit.
• Cedar Policies: Fine-grained authorization rules written in the Amazon Cedar language. They define who (principal) can perform what (action) on which resource under what when conditions.
• Gateway Integration: The AgentCore Gateway intercepts tool calls at runtime. When a Policy Engine is attached to a Gateway in ENFORCE mode, the Gateway evaluates every request against the engine's policies before allowing the tool execution.

Cedar Policy Syntax Example

To allow a specific tool call only if the input amount is below a threshold, use a statement like this:

permit(principal, 
  action == AgentCore::Action::"RefundTarget___process_refund", 
  resource == AgentCore::Gateway::"<gateway-arn>") 
when { context.input.amount < 1000 };

Enforcement Modes

When attaching a Policy Engine to a Gateway via update_gateway_policy_engine, you can specify a mode. In ENFORCE mode:

• Every tool call is intercepted.
• All actions are denied by default unless explicitly permitted.
• If any forbid policy matches, access is denied (forbid-wins semantics).
• Decisions are logged to CloudWatch.