Amazon Bedrock Agents Core (AgentCore) — A Practical, End‑to‑End Guide

This guide shows how to design, build, deploy, and operate Amazon Bedrock Agents with practical CLI and code examples. It covers agent core concepts, IAM, action groups (tool/function calling), OpenAPI schemas, Lambda executors, knowledge bases, guardrails, invocation patterns, and production hardening.

Terminology:

• Control plane: bedrock-agent (create/configure agents, action groups, knowledge bases, aliases)
• Runtime: bedrock-agent-runtime (invoke an agent)

Table of Contents

1. What an Agent Is (and Isn’t)
2. Reference Architecture
3. IAM: Minimal Roles
4. Create an Agent via AWS CLI (Windows PowerShell)
5. Agent Runtime in Code (Python, Node.js)
6. Action Groups: OpenAPI vs Lambda
7. Knowledge Bases (RAG)
8. Guardrails
9. Prompting and Reasoning Strategy
10. Versioning, Aliases, Safe Releases
11. Observability and Debugging
12. Security and Networking
13. Quotas, Cost, and Performance
14. Common Failure Modes and Fixes
15. Local Development and Testing
16. Sample IAM Policy Snippets
17. Checklists
18. Quick Start Recap

1) What an Agent Is (and Isn’t)

• Agent: A managed orchestrator that uses a foundation model (FM) plus your instructions, tools (action groups), and knowledge bases to fulfill tasks.
• Agent Alias: A versioned, immutable pointer (e.g., “prod”) for safe traffic routing.
• Action Group: A set of callable tools backed by either an OpenAPI schema (Bedrock-managed HTTP calls) or a Lambda executor.
• Knowledge Base: Retrieval‑augmented generation (RAG) data sources searchable by the agent.
• Guardrails: Safety policies (content filters, PII handling, topic restrictions) applied at runtime.
• Foundation Model: Claude, Llama, Titan, etc., chosen per use case (reasoning depth, latency, token limits).

High‑level flow:

1. Client sends a prompt to the Agent Runtime (InvokeAgent).
2. Agent reasons with the chosen FM.
3. If needed, it calls a tool (action group) or searches a knowledge base.
4. The agent composes the final answer and streams it back.

2) Reference Architecture

• Client (Web/API) → Bedrock Agent (Runtime)
  • FM orchestration (prompt + plan + tool use)
  • Optional: Knowledge base search
  • Optional: Action group call(s)
    • HTTP tool (from OpenAPI schema)
    • or Lambda executor (custom code)
• Observability: CloudWatch Logs, Lambda logs, traces
• Security: IAM, KMS, VPC (for Lambda), private APIs, guardrails

3) IAM: Minimal Roles You’ll Need

• Agent Resource Role (used by the Agent service)

  • bedrock:InvokeModel
  • bedrock:Retrieve (knowledge bases), bedrock:RetrieveAndGenerate if used directly
  • lambda:InvokeFunction (for Lambda executor tools)
  • logs:CreateLogGroup/Stream/PutLogEvents
  • kms:Decrypt/Encrypt/GenerateDataKey (if encrypted)
  • s3:GetObject (for OpenAPI schema in S3) and any data references

• Lambda Execution Role (if using Lambda)

  • Permissions to reach downstream systems (DynamoDB/RDS/HTTP/VPC)
  • logs:CreateLogGroup/Stream/PutLogEvents
  • Any domain‑specific read/write permissions

Tip: Start least‑privileged; expand only when tool calls fail with AccessDenied.

4) Create an Agent via AWS CLI (Windows PowerShell)

Replace placeholders in ALL_CAPS.

# 4.1 Create the agent
aws bedrock-agent create-agent `
  --agent-name "orders-assistant" `
  --agent-resource-role-arn arn:aws:iam::ACCOUNT_ID:role/BedrockAgentRole `
  --foundation-model arn:aws:bedrock:REGION::foundation-model/anthropic.claude-3-5-sonnet-20240620-v1:0 `
  --instruction "You are a helpful assistant for customer orders. Always provide concise, factual answers." `
  --region REGION
 
# Capture AgentId
$agents = aws bedrock-agent list-agents --region REGION | ConvertFrom-Json
$agents.AgentSummaries | Format-Table
 
# 4.2 (Optional) Attach a knowledge base later (see section 7)
 
# 4.3 Create an action group with a Lambda executor
aws bedrock-agent create-agent-action-group `
  --agent-id AGENT_ID `
  --action-group-name "OrdersAPI" `
  --action-group-executor '{"lambda": {"lambdaArn":"arn:aws:lambda:REGION:ACCOUNT_ID:function:OrdersLambda"}}' `
  --region REGION
 
# 4.4 Alternatively, create an action group with an OpenAPI schema hosted in S3
aws bedrock-agent create-agent-action-group `
  --agent-id AGENT_ID `
  --action-group-name "OrdersHTTP" `
  --api-schema "s3://YOUR_BUCKET/openapi/orders.yaml" `
  --region REGION
 
# 4.5 Prepare the agent (builds internal artifacts)
aws bedrock-agent prepare-agent --agent-id AGENT_ID --region REGION
 
# 4.6 Create an alias for safe rollout
aws bedrock-agent create-agent-alias `
  --agent-id AGENT_ID `
  --agent-alias-name "prod" `
  --description "Production alias" `
  --region REGION

Invoke the agent:

aws bedrock-agent-runtime invoke-agent `
  --agent-id AGENT_ID `
  --agent-alias-id ALIAS_ID `
  --session-id "demo-$(Get-Date -Format yyyyMMddHHmmss)" `
  --input-text "Where is order 12345?" `
  --region REGION

For streaming responses, use SDK event streams or CLI streaming options supported by your version.

5) Agent Runtime in Code (Python and Node.js)

Python (boto3):

import boto3, json, uuid
 
agent_id = "AGENT_ID"
alias_id = "ALIAS_ID"
region   = "REGION"
 
runtime = boto3.client("bedrock-agent-runtime", region_name=region)
session_id = str(uuid.uuid4())
 
resp = runtime.invoke_agent(
    agentId=agent_id,
    agentAliasId=alias_id,
    sessionId=session_id,
    inputText="List my last 3 orders and their status."
)
 
# Non-streaming:
print(resp.get("outputText"))
 
# Streaming (if enabled on your SDK):
# for event in resp["completion"]:
#     print(event)

Node.js (AWS SDK v3):

import {
  BedrockAgentRuntimeClient,
  InvokeAgentCommand,
} from "@aws-sdk/client-bedrock-agent-runtime";
 
const client = new BedrockAgentRuntimeClient({ region: "REGION" });
 
const out = await client.send(
  new InvokeAgentCommand({
    agentId: "AGENT_ID",
    agentAliasId: "ALIAS_ID",
    sessionId: crypto.randomUUID(),
    inputText: "Cancel order 987 if it hasn't shipped yet.",
  })
);
 
console.log(out.outputText);
// For streaming, subscribe to the event stream on supported SDK versions.

6) Action Groups

Two main choices:

• OpenAPI‑backed HTTP tools: Provide an OpenAPI 3.0 schema; Bedrock calls HTTP endpoints directly.
• Lambda executor: Bedrock calls your Lambda; you implement any logic and call any systems.

6.1 OpenAPI Schema Example

openapi: 3.0.3
info:
  title: Orders API
  version: 1.0.0
paths:
  /orders/{orderId}:
    get:
      summary: Get order by ID
      operationId: getOrder
      parameters:
        - in: path
          name: orderId
          required: true
          schema: { type: string }
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId: { type: string }
                  status: { type: string }
                  eta: { type: string }
        "404":
          description: Not Found

Host this in S3 and reference it when creating the action group. Keep operations clear and bounded; prefer narrow, composable endpoints.

6.2 Lambda Executor Example (Python)

Event contracts evolve. Log the incoming event to understand the latest shape.

import json
import logging
logger = logging.getLogger()
logger.setLevel(logging.INFO)
 
def lambda_handler(event, context):
    # Typical keys (subject to change):
    # - actionGroup, apiPath, operation, httpMethod
    # - parameters (dict of name->value)
    # - sessionId, inputText, promptSessionAttributes
    logger.info("Event: %s", json.dumps(event))
 
    op = (event.get("operation") or "").lower()
    params = event.get("parameters") or {}
    order_id = params.get("orderId") or params.get("order_id")
 
    if op in ("getorder", "get_order"):
        # Simulate data lookup
        if order_id == "12345":
            result = {"orderId": "12345", "status": "Shipped", "eta": "2025-08-28"}
        else:
            result = {"message": f"Order {order_id} not found."}
 
        # Response for the agent
        return {
            "response": {
                "content": [
                    { "text": json.dumps(result) }
                ]
            },
            "isSuccess": True
        }
 
    return {
        "response": { "content": [ { "text": "Unsupported operation." } ] },
        "isSuccess": False
    }

Best practices:

• Validate and sanitize inputs.
• Return compact, JSON‑serializable objects.
• Include correlation IDs (e.g., sessionId) in logs.
• Minimize latency; small, atomic tools compose better.

7) Knowledge Bases (RAG)

Steps (CLI):

# 7.1 Create a Knowledge Base
aws bedrock-agent create-knowledge-base `
  --name "orders-kb" `
  --description "Order FAQs and SOPs" `
  --role-arn arn:aws:iam::ACCOUNT_ID:role/BedrockKbRole `
  --region REGION `
  --knowledge-base-configuration file://kb-config.json
# kb-config.json: embeddings model, vector store (e.g., OpenSearch Serverless), data sources (S3 URIs)
 
# 7.2 Associate KB with the agent
aws bedrock-agent associate-agent-knowledge-base `
  --agent-id AGENT_ID `
  --knowledge-base-id KB_ID `
  --description "RAG for orders" `
  --region REGION
 
# 7.3 Sync data sources
aws bedrock-agent start-ingestion-job `
  --knowledge-base-id KB_ID `
  --data-source-id DATA_SOURCE_ID `
  --region REGION

Prompt tip: Give clear retrieval guidance (“Use the knowledge base for policy answers. If uncertain, ask a clarifying question.”).

8) Guardrails

Create guardrails (e.g., block categories, PII handling) and attach to the agent or model invocations.

• Combine input and output policies.
• Test with adversarial prompts.
• Log guardrail blocks and tune exceptions.

9) Prompting and Reasoning Strategy

• Instruction: Crisp role, domain, and constraints.
• Tool usage: Add short, human‑readable descriptions in OpenAPI and Lambda op names.
• Output schemas: If downstream expects JSON, instruct the agent to return structured JSON.
• Memory: Use session attributes only when cross‑turn context truly helps.

Instruction snippet:

You are an Orders Assistant. When the user asks about an order:
1) If the orderId is provided, call getOrder to retrieve status.
2) If not provided, ask for orderId succinctly.
3) If no data is found, state that and offer next steps.
Return concise answers. Prefer bullet points for multi‑item lists.

10) Versioning, Aliases, and Safe Releases

• Use agent aliases (e.g., dev, staging, prod).
• After adding/changing action groups or instructions, run prepare-agent and test via a non‑prod alias.
• Promote by updating the alias to the new agent version. Keep old alias during canary.

11) Observability and Debugging

• Enable CloudWatch logs for both Agent and Lambda.
• Log the full action event (redact secrets/PII).
• Track latency percentiles for:
  • FM inference
  • Tool latency (per operation)
  • Knowledge base retrieval
• Add business metrics (orders_found, not_found) to CloudWatch Metrics.
• For intermittent 5xx from tools, implement retries with jitter in Lambda/tooling.

12) Security and Networking

• Keep PII out of prompts unless necessary; use guardrails and redaction.
• Put sensitive tools behind private networking:
  • Lambda in VPC with interface endpoints (PrivateLink) for downstream.
• Sign outbound HTTP requests (SigV4) where applicable.
• Encrypt data at rest (S3/KMS, vector store) and in transit (TLS).
• Use least privilege on Agent Resource and Lambda Execution roles.

13) Quotas, Cost, and Performance

• Choose FMs that balance accuracy and cost. Start with Claude 3.5 Sonnet; test smaller models for cost.
• Constrain tool use: prefer atomic, fast operations.
• Cache frequent answers (e.g., order status snapshots) if staleness is acceptable.
• Monitor token usage; cap input/output lengths where possible.

14) Common Failure Modes and Fixes

• AccessDenied on tool call → Expand Agent Resource Role (lambda:InvokeFunction or s3:GetObject).
• Agent never calls the tool → Improve operation descriptions; ensure clear parameter names; add few‑shot examples.
• Streaming fails in client → Update SDK/CLI; handle event streams correctly.
• Knowledge base irrelevant results → Tune chunking, embeddings model, topK; improve doc quality; add a “don’t know” instruction.
• Timeouts → Reduce tool latency, split operations, raise timeouts cautiously.

15) Local Development and Testing

• Unit test Lambda tool logic independently.
• Contract test the action event; log the shape during dev and fix parameter mapping.
• Use Postman/curl against your HTTP tools; ensure CORS for browser clients.
• Record test conversations per agent version; regression test before alias promotion.

16) Sample IAM Policy Snippets

Agent Resource Role (adjust to fit your environment):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["bedrock:InvokeModel", "bedrock:Retrieve"],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["lambda:InvokeFunction"],
      "Resource": "arn:aws:lambda:REGION:ACCOUNT_ID:function:OrdersLambda"
    },
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["s3:GetObject"],
      "Resource": "arn:aws:s3:::YOUR_BUCKET/*"
    },
    {
      "Effect": "Allow",
      "Action": ["kms:Decrypt", "kms:Encrypt", "kms:GenerateDataKey"],
      "Resource": "arn:aws:kms:REGION:ACCOUNT_ID:key/YOUR_KEY_ID"
    }
  ]
}

Lambda Execution Role basics:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "logs:CreateLogGroup",
        "logs:CreateLogStream",
        "logs:PutLogEvents"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": ["dynamodb:GetItem", "dynamodb:Query"],
      "Resource": "arn:aws:dynamodb:REGION:ACCOUNT_ID:table/Orders"
    }
  ]
}

17) Checklists

Before first prod call:

• Agent has instruction, FM, and at least one tested tool or KB
• prepare-agent completed successfully
• Alias created and pointing to intended version
• IAM permissions verified; logs visible
• Guardrails configured and validated

Ongoing:

• Monitor latency/cost dashboards
• Rotate keys/secrets
• Update KB ingestion on schedule
• Regular prompt and tool usability reviews

18) Quick Start Recap

1. Create IAM roles (Agent Resource Role, Lambda Execution Role).
2. Create the Agent (instruction, FM).
3. Add action group(s): OpenAPI or Lambda executor.
4. (Optional) Attach knowledge base(s) and ingest content.
5. Prepare the agent; create an alias.
6. Invoke via CLI/SDK; iterate on prompts and tools.
7. Add observability, guardrails, and release via aliases.