Capstone: A Production-Grade Agent

Everything you have learned in this course converges on a single shape. A production AgentCore agent is a Runtime-hosted Python service that pulls in the other primitives as it needs them:

  Caller (app / another agent)
        |  inbound auth: JWT/OIDC  (or SigV4)
        v
  +-------------------- AgentCore Runtime (per-session microVM) --------------------+
  |  BedrockAgentCoreApp  ->  @app.entrypoint  ->  your framework agent             |
  |                                                                                  |
  |   Memory  <----- short-term events + long-term records (namespaced)             |
  |   Gateway --MCP--> tools (Lambda / OpenAPI / Smithy / MCP server / API GW)       |
  |   Identity ------> token vault (outbound 2LO/3LO to Google/GitHub/internal API)  |
  |   Guardrails ----> content filters / denied topics / PII on the model boundary   |
  +----------------------------------------------------------------------------------+
        |  every tool call intercepted by Policy (Cedar) ENFORCE/LOG
        |  OTEL traces/spans/metrics/logs -> CloudWatch (GenAI dashboard)
        v
  Observability + Evaluations

Map each box to its job:

The platform is composable: you do not have to use all of it. The all-in pattern is what we build here, but an a la carte deployment (your agent on EKS using only Gateway, or only Memory) is equally valid. What does not change is the invariant: a wrapped entrypoint, an inbound auth decision, durable state where you need it, governed tool access, and telemetry you can trust.

Build the agent in a deliberate order. Each step depends on the one before it, and getting the order wrong is how people end up with a tool-using agent that has no auth or an observable agent with no governance.

1. Wrap the agent. The bedrock-agentcore SDK turns any framework function into the Runtime HTTP contract. This is the 'four lines to deploy' core:

from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()  # model-agnostic; default model is configurable

@app.entrypoint
def invoke(payload, context):          # optional 2nd arg = RequestContext
    session_id = context.session_id     # echo this; >=33 chars
    result = agent(payload.get("prompt", ""))
    return {"result": result.message}

if __name__ == "__main__":
    app.run()   # local: http://localhost:8080 ; in container binds 0.0.0.0:8080

Test the exact cloud contract locally before you deploy anything:

curl -X POST http://localhost:8080/invocations \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"What is the weather?"}'

2. Deploy to Runtime. Use the new AgentCore CLI (@aws/agentcore, CDK -> CloudFormation) or the starter toolkit (bedrock-agentcore-starter-toolkit, CodeBuild). They expose the same agentcore binary with different verbs — pin which one your runbook assumes.

agentcore create --name SupportAgent --framework Strands \
  --protocol HTTP --model-provider Bedrock --memory none
cd SupportAgent
agentcore dev          # hot-reload + inspector on :8080
agentcore deploy       # package -> CDK synth -> CloudFormation; builds ARM64; pushes to ECR
agentcore status       # agent ARN, endpoint, log group

3. Attach Memory. Add short-term events plus the long-term strategies you actually need:

agentcore add memory --name SupportMem --strategies SUMMARIZATION,USER_PREFERENCE
agentcore deploy

4. Expose tools via Gateway. Aggregate your backends into one MCP endpoint:

agentcore add gateway --name SupportGW --authorizer-type NONE --runtimes SupportAgent
agentcore add gateway-target --name OrdersTarget --type lambda-function-arn \
  --lambda-arn <ARN> --tool-schema-file tools.json --gateway SupportGW
agentcore deploy

5. Wire inbound + outbound auth. Inbound: switch the runtime to JWT. Outbound: register a credential provider and decorate the function that touches the downstream API (Step covered in detail in the auth section below).

6. Instrument + evaluate. Runtime-hosted agents are auto-instrumented with OTEL; enable Transaction Search once, then read traces in the GenAI dashboard and turn on online Evaluations.

7. Govern. Attach a Cedar policy engine to the gateway and a Bedrock Guardrail to the model boundary — last, so you are governing a system that already works end to end.

Auth is where capstone builds most often go wrong, because the two halves are configured in completely different places.

Inbound (JWT/OIDC). A runtime supports either SigV4 or JWT, not both — they are mutually exclusive per version. To require a bearer token, attach a customJWTAuthorizer:

client.create_agent_runtime(
    agentRuntimeName='SupportAgent',
    agentRuntimeArtifact={'containerConfiguration': {'containerUri': '...ecr.../support:latest'}},
    authorizerConfiguration={"customJWTAuthorizer": {
        "discoveryUrl": 'https://cognito-idp.us-west-2.amazonaws.com/<pool>/.well-known/openid-configuration',
        "allowedClients": ['<COGNITO_CLIENT_ID>']}},
    networkConfiguration={"networkMode": "PUBLIC"},
    roleArn='arn:aws:iam::111122223333:role/AgentRuntimeRole',
    lifecycleConfiguration={'idleRuntimeSessionTimeout': 300, 'maxLifetime': 1800})

Once a runtime is JWT-protected, boto3 cannot invoke it — invoke_agent_runtime signs with SigV4. You must make a raw HTTPS request with Authorization: Bearer <token> (the ARN URL-encoded into the path). Cognito has no Dynamic Client Registration, so pre-register the OAuth client.

Outbound (token vault). To call a downstream API on the user's behalf, register a credential provider once, then decorate the function. The @requires_access_token decorator runs the full workload-identity -> vault -> consent flow and injects the credential as a kwarg — the raw token never touches your business logic or the LLM context:

from bedrock_agentcore.identity.auth import requires_access_token

@requires_access_token(
    provider_name="google-provider",
    scopes=["https://www.googleapis.com/auth/drive.metadata.readonly"],
    auth_flow="USER_FEDERATION",                  # 3LO; "M2M" for client-credentials
    on_auth_url=lambda url: print("Authorize:\n" + url),  # in prod, stream URL to the caller
    force_authentication=False)
async def read_from_google_drive(*, access_token: str):
    ...  # use access_token to call the Google Drive API

Under the hood the runtime exchanges the inbound token for a Workload Access Token (GetWorkloadAccessTokenForJWT), then the agent calls the vault (GetResourceOauth2Token) which mints the provider authorization URL for 3LO. The vault stores downstream tokens with strict per-(agent identity + user id) isolation — zero token sharing — encrypted at rest and in transit via KMS, and auto-refreshes them. For Google specifically, you need "access_type":"offline" in customParameters to get a refresh token (the gotchas differ per provider; verify the live resource-providers page).

Register the provider and its callback URL — forgetting the callback registration is the classic 3LO break:

aws bedrock-agentcore-control create-oauth2-credential-provider --region us-east-1 \
  --name "google-provider" --credential-provider-vendor "GoogleOauth2" \
  --oauth2-provider-config-input '{"googleOauth2ProviderConfig":{"clientId":"...","clientSecret":"..."}}'
# Register the returned callbackUrl in the provider's "Authorized redirect URIs"

A working agent is not a production agent until you can govern its actions and see what it did.

Govern with Policy (Cedar). The Cedar policy engine intercepts every tool call through the gateway. Attach it in ENFORCE (block) or LOG (observe-only) mode — start in LOG, watch what would be denied, then flip to ENFORCE:

client.create_gateway(
    name="SupportGW", roleArn="...", protocolType="MCP", authorizerType="CUSTOM_JWT",
    authorizerConfiguration={"customJWTAuthorizer": {"discoveryUrl": "...", "allowedClients": ["..."]}},
    policyEngineConfiguration={"mode": "LOG", "arn": "arn:aws:bedrock-agentcore:...:policy-engine/..."})

Govern the model boundary with Guardrails. Two ways: native (attach guardrail_id/guardrail_version to a Strands BedrockModel, detect firing via response.stop_reason == "guardrail_intervened") or the model-agnostic ApplyGuardrail API for OpenAI/Gemini/self-hosted models. Both cover content filters, denied topics, word filters, PII detection/redaction, and contextual grounding. Use shadow mode (log would-be blocks before enforcing) to tune thresholds without breaking users.

Observe. Runtime-hosted agents are auto-instrumented with OpenTelemetry — no extra libs for baseline traces/sessions/metrics (add aws-opentelemetry-distro to requirements.txt for completeness). The one mandatory one-time step is enabling CloudWatch Transaction Search before spans are searchable (~10 min to take effect; 1% indexing is free as of writing):

aws xray update-trace-segment-destination --destination CloudWatchLogs
aws xray update-indexing-rule ...

Then view everything in the GenAI Observability dashboard: CloudWatch -> #gen-ai-observability -> Bedrock AgentCore tab -> Agents View / Sessions View / Trace View. Pass the runtimeSessionId on every invoke so the Sessions view stitches a conversation together.

Evaluate. Evaluations ride the same OTEL traces. Online evaluation samples a configurable % of traces and scores them in the dashboard with no code changes, using built-in evaluators across three levels — Session (Goal Success Rate), Trace (Helpfulness, Correctness, Faithfulness, Harmfulness, Instruction Following, ...), and Tool (Tool Selection Accuracy, Tool Parameter Accuracy). The framing to keep straight: Observability = what happened / how fast / what cost / where it failed; Evaluation = was it correct / helpful / safe.

Run this list before you point real traffic at the agent. Each item maps to a failure you have already seen in this course.

Don't block the entrypoint. A blocking call inside @app.entrypoint starves the /ping thread and your session gets killed at the idle timeout during long work. Offload to threads/async and, for background work, use app.add_async_task(...) so /ping reports HealthyBusy. If you implement a custom /ping, time_of_last_update (Unix seconds) is required — omit it and the idle timeout fires even while busy.

@app.ping
def ping():
    return {"status": "Healthy", "time_of_last_update": int(time.time())}

Once live, operating the agent is a steady loop across three lenses you have already built:

• Monitor in the GenAI Observability dashboard. Watch the Runtime metrics by their exact names — Invocations, Throttles, System Errors, User Errors, Latency, Session Count — and drill into the Trace View when a session misbehaves. Resource-usage metrics (CPUUsed-vCPUHours, MemoryUsed-GBHours) can lag up to ~60 min and are not your bill.
• Evaluate quality continuously with online evaluation sampling a % of production traces. A drop in Goal Success Rate or a spike in Refusal is your early-warning signal — long before users complain.
• Manage cost against the consumption dimensions. The cheap-looking line items hide cost elsewhere: Observability and Payments are pass-through (you pay CloudWatch / the wallet provider), and Memory has several sub-dimensions (events, records-per-month, retrievals). Overrides and self-managed memory strategies also incur Bedrock model charges billed to your account.

The volatile-fact discipline, one last time. This course has tagged dozens of facts [VOLATILE] for a reason: AgentCore moves fast. Before you rely on any of the following, open the live AWS source and re-verify:

Never assert a price, a quota, a region count, a model ID, or a GA date as a timeless fact — frame it as 'as of writing, verify the live page.' Anything the docs leave ambiguous (for example the OTEL log-group suffix, or any number marked UNVERIFIED), hedge explicitly or leave it out. That habit is the difference between a runbook that ages gracefully and one that quietly becomes wrong.