/agents-debug                      # interactive — describe what's wrong
/agents-debug traces               # read and explain recent traces
/agents-debug logs                 # search recent logs for errors
/agents-debug memory               # diagnose memory recall issues specifically
/agents-debug doctor               # check environment prerequisites

undefined

**Important:** CloudWatch put-to-get latency is **~10 seconds end-to-end** — that's the delay from when a span is emitted to when it's readable by `agentcore traces get` or `agentcore run eval`. There is **no separate "trace ingested but eval not ready yet" window**; the same ingestion step unlocks both paths. Older skills and docs said 30–60s for traces and 2–5 minutes for evals — both are stale. If you just invoked the agent, wait ~15 seconds and both trace reads and evals will work.

Read `agentcore/agentcore.json` to get the agent name if not provided.

aws iam simulate-principal-policy \
  --policy-source-arn $(agentcore status --json | jq -r '.runtimes[0].executionRoleArn') \
  --action-names bedrock:InvokeModel \
  --resource-arns "arn:aws:bedrock:*::foundation-model/*"

agentcore traces get <traceId> --runtime <AgentName>

agentcore status --type gateway
agentcore fetch access --name <AgentName> --type agent

agentcore logs --runtime <AgentName> --since 1h --query "auth"

aws logs tail /aws/lambda/<function-name> --since 1h

agentcore logs --runtime <AgentName> --since 1h --query "policy"
agentcore status --type policy-engine

agentcore traces get <traceId> --runtime <AgentName>

agentcore status --type memory --json | jq '.memories[].strategies'

agentcore status --type memory

agentcore status --type memory --json | jq '.memories[].id'

agentcore traces get <traceId> --runtime <AgentName>

agentcore logs --runtime <AgentName> --since 30m --level error

agentcore status --runtime <AgentName> --json

agentcore status --type memory

agentcore logs --runtime <AgentName> --since 1h --query "auth"
agentcore logs --runtime <AgentName> --since 1h --query "401"
agentcore logs --runtime <AgentName> --since 1h --query "403"

agentcore status --type credential
agentcore status --type gateway --json

undefined

**2. Your runtime IAM role needs CloudWatch and X-Ray permissions:**

If using the AgentCore CLI with CodeZip, the CDK scaffold adds these automatically. If using a custom role or Container build, verify they're present.

**3. Use Python's `logging` module, not `print()`.**

OTEL hooks into `logging` automatically — no custom handlers needed. `print()` statements won't appear in CloudWatch.

```python
import logging
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)

**Also verify:** CloudWatch Transaction Search is enabled in your account. Without it, traces and spans won't appear in the GenAI Observability dashboard.

{
  "Effect": "Allow",
  "Action": [
    "logs:DescribeLogGroups"
  ],
  "Resource": "*"
},
{
  "Effect": "Allow",
  "Action": [
    "logs:CreateLogGroup",
    "logs:CreateLogStream",
    "logs:PutLogEvents"
  ],
  "Resource": "arn:aws:logs:<REGION>:<ACCOUNT_ID>:log-group:/aws/bedrock-agentcore/runtimes/*:*"
}

import asyncio
import json
from bedrock_agentcore.runtime import BedrockAgentCoreApp

app = BedrockAgentCoreApp()

async def emit_keepalive(tool_task):
    """Yield heartbeat events every 30s while tool_task is running."""
    while not tool_task.done():
        yield f"data: {json.dumps({'type': 'heartbeat'})}\n\n"
        try:
            await asyncio.wait_for(asyncio.shield(tool_task), timeout=30)
        except asyncio.TimeoutError:
            continue  # tool still running, emit another heartbeat

@app.entrypoint
async def invoke(payload, context):
    async def stream():
        tool_task = asyncio.create_task(run_long_tool(payload))

        # Emit heartbeats while the tool runs
        async for event in emit_keepalive(tool_task):
            yield event

        # Tool completed — emit the real result
        result = await tool_task
        yield f"data: {json.dumps({'type': 'result', 'content': result})}\n\n"
        yield "data: [DONE]\n\n"

    return stream()

for chunk in response.iter_lines():
    if not chunk:
        continue
    data = json.loads(chunk.removeprefix(b"data: "))
    if data.get("type") == "heartbeat":
        continue  # ignore keepalives
    # process real events

aws lambda update-function-configuration \
  --function-name my-caller-function \
  --tracing-config Mode=Active

from aws_xray_sdk.core import xray_recorder, patch_all
patch_all()  # patches boto3, requests, etc.

OTEL_TRACES_SAMPLER=always_on

arn:aws:bedrock-agentcore:<region>:<account>:runtime/<runtime-name>

arn:aws:bedrock-agentcore:<region>:<account>:runtime/<runtime-name>/runtime-endpoint/DEFAULT

pip show langchain-aws | grep Version

undefined

Verify against the current langchain-aws release notes: https://github.com/langchain-ai/langchain-aws/releases — cross-region inference profile support has been evolving.

**Google ADK — Gemini only:**
ADK only works with Gemini models. If you're seeing model errors with ADK, check that `GEMINI_API_KEY` is set and you're using a `gemini-*` model ID.

**A2A agents — wrong port:**
A2A servers must run on port 9000. If your A2A agent isn't responding, check it's not accidentally running on 8080.

---

undefined

undefined