agents-debug

debug

诊断 AgentCore Agent 或环境无法正常工作的原因。

使用场景

• Agent 返回错误答案或报错
• 工具调用失败或超时
• Agent 在本地运行正常，但部署后失败
• CloudWatch 中没有显示日志
• AgentCore CLI 无法运行，或环境似乎已损坏
• 找不到 agentcore 命令，或缺少先决条件

请勿用于：

• 部署失败（CDK 错误、部署期间的 IAM 问题）→ 使用 agents-deploy
• 搭建新项目 → 使用 agents-get-started
• 衡量质量或设置监控 → 使用 agents-optimize

输入

$ARGUMENTS 为可选参数：

/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

流程

步骤 0：确定问题类型

如果开发者遇到的问题与 CLI 本身有关（找不到命令、先决条件、环境设置），请加载 references/doctor.md，并按照其中的诊断检查清单操作。

如果问题与 Agent 行为有关（错误答案、报错、超时、工具故障），请继续执行下面的步骤 1。

步骤 1：验证 CLI 版本

运行 agentcore --version。此技能要求版本为 v0.9.0 或更高。如果版本较旧，请告知开发者先运行 agentcore update。

步骤 2：了解症状

询问（或根据上下文推断）：

“发生了什么情况？

1. Agent 返回了错误消息
2. Agent 返回了错误或无用的答案
3. 某个特定工具调用失败
4. 记忆功能无法正常工作（Agent 记不住事情）
5. Agent 响应缓慢或超时
6. 我想了解 Agent 在某个特定会话中执行了什么操作”

步骤 3：自动读取跟踪记录和日志

不要让开发者粘贴日志——直接读取。

# List recent traces
agentcore traces list --runtime <AgentName> --since 1h

# Get the most recent trace ID
agentcore traces list --runtime <AgentName> --since 1h --limit 1

# Download and read the trace
agentcore traces get <traceId> --runtime <AgentName>

# Search logs for errors
agentcore logs --runtime <AgentName> --since 1h --level error

# Search logs for a specific pattern
agentcore logs --runtime <AgentName> --since 2h --query "timeout"
agentcore logs --runtime <AgentName> --since 2h --query "model access"

重要： CloudWatch 从写入到读取的延迟为 端到端约 10 秒——也就是从 span 发出到可以通过 agentcore traces get 或 agentcore run eval 读取之间的延迟。不存在单独的“跟踪记录已摄取但评估尚未就绪”时间窗口；同一个摄取步骤会同时启用这两种读取方式。旧版技能和文档曾注明跟踪记录需要 30–60 秒、评估需要 2–5 分钟——这些说法都已过时。如果刚调用了 Agent，请等待约 15 秒，之后即可读取跟踪记录并运行评估。

如果未提供 Agent 名称，请读取 agentcore/agentcore.json 获取名称。

步骤 4：按症状诊断

---

症状：“model access denied”或模型错误

最常见原因： 在所在区域的 Bedrock 控制台中未启用该模型。

解决方法：

1. 前往 AWS Console → Amazon Bedrock → Model access
2. 启用 Agent 使用的模型
3. 等待 1–2 分钟，让访问权限生效

第二种原因： 执行角色缺少 bedrock:InvokeModel 权限。

检查：

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/*"

第三种原因： 跨区域推理配置文件要求在所有区域启用模型访问权限。

以地理前缀开头的模型 ID 是跨区域推理配置文件，会在相应地理区域内路由请求：

前缀	地理区域	目标区域示例
us.	美国	us-east-1、us-east-2、us-west-2
eu.	欧洲	eu-central-1、eu-west-1、eu-west-2、eu-west-3
apac.	亚太地区	ap-northeast-1、ap-southeast-1、ap-southeast-2、ap-south-1
global.	全球所有商业区域	所有支持的区域

AgentCore CLI 默认使用 global. 前缀搭建项目（例如，global.anthropic.claude-sonnet-4-5-20250929-v1:0）。所有前缀都要求在配置文件覆盖的每个目标区域启用模型访问权限。对于 us. 配置文件，请在所有美国区域启用；对于 eu.，请在所有欧盟区域启用；对于 global.，请在所有支持的区域启用。并非所有模型都支持所有前缀——目前只有部分模型支持 global.。如果可用，请使用 global. 以获得最高吞吐量；如果数据驻留要求限制了推理运行区域，则使用地理前缀。请查阅 Bedrock 推理配置文件文档，了解当前支持的模型与前缀组合。

---

症状：工具调用失败

步骤 1： 在跟踪记录中找到失败的工具调用：

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

查找状态为错误的工具调用条目。

步骤 2： 检查网关状态：

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

步骤 3： 常见的工具调用失败原因：

未设置网关 URL（本地开发）： AGENTCORE_GATEWAY_*_URL 环境变量仅在部署后设置。在 agentcore dev 中，网关工具不可用。这是预期行为——Agent 应妥善处理这种情况。

工具调用身份验证失败：

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

检查凭据配置是否正确：agentcore status --type credential

Lambda 函数错误： Lambda 本身出现故障。直接检查 Lambda 日志：

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

策略拒绝： 如果附加了策略引擎，请检查策略决策日志：

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

---

症状：回答错误或没有帮助

步骤 1： 阅读跟踪记录，了解 Agent 的推理过程：

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

跟踪记录会显示模型的推理步骤、发起的工具调用以及最终回答。请检查：

• Agent 是否使用了正确的工具？
• 工具调用是否返回了预期数据？
• 系统提示词是否提供了正确的上下文？

步骤 2： 检查是否涉及记忆： 如果 Agent 应该使用记忆上下文却没有使用，请参阅本技能后面的“症状：记忆未持久化”部分；如果这是环境问题，请加载 references/doctor.md。

步骤 3： 常见原因：

• 系统提示词过于含糊，或缺少关键信息
• Agent 没有调用正确的工具（需要改进工具描述）
• 工具返回了意外的数据格式
• 模型 ID 不适用于该任务（例如，使用较小的模型处理复杂推理）

---

症状：记忆无法正常工作

记忆未能跨会话持久化（LTM）：

1. 确认已配置 LTM 策略（SEMANTIC 或 USER_PREFERENCE）：

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

1. 会话结束后等待 5–30 秒——LTM 提取是异步的。必须先结束 Agent 的会话，才能提取事实。

2. 使用 UUID（v4）作为会话 ID——平台要求其长度至少为 33 个字符。像 "session-1" 这样的短 ID 会导致 LTM 静默失败。agentcore invoke 默认会生成符合要求的 ID。

3. 确认记忆资源处于 ACTIVE 状态：

agentcore status --type memory

会话开始时未加载记忆：

1. 检查是否设置了 MEMORY_*_ID 环境变量：

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

1. 确认各会话中的 actor_id 一致——记忆按 actor 隔离。

2. 检查检索配置中的命名空间路径是否与写入时使用的命名空间一致。

---

症状：Agent 超时

步骤 1： 检查跟踪记录，找出耗时所在：

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

查找运行时间较长的步骤，例如模型调用、工具调用和记忆操作。

步骤 2： 常见的超时原因：

Agent 初始化缓慢： 如果空闲一段时间后的首次调用很慢，而后续请求很快，则 Agent 初始化耗时过长。检查模块级别是否有繁重的导入、全局作用域中的数据库连接，或启动期间的 MCP 客户端初始化。将耗时较长的设置移至请求处理程序中，或采用延迟初始化。有关优化指导，请参阅 agents-harden 技能。

模型调用超时： 模型耗时过长。对于对时间敏感的操作，可考虑使用更快的模型（例如，简单任务使用 Haiku 而非 Sonnet）。

工具调用超时： Lambda 或外部 API 响应缓慢。检查工具自身的日志。

记忆检索超时： 对于大型记忆存储，语义搜索可能较慢。可考虑在检索配置中减小 top_k。

VPC 连接问题： 如果 Agent 位于 VPC 中，请检查安全组规则和路由表。有关 VPC 专属调试，请参阅 agents-build（加载 references/vpc.md）。

---

症状：ServiceQuotaExceededException: maxVms limit exceeded（尽管观测到的并发量较低）

CloudWatch 的“并发会话”指标显示的数值不高（可能是 30–50），但 InvokeAgentRuntime 调用却返回 ServiceQuotaExceededException: maxVms limit exceeded。

实际情况： CloudWatch 的并发会话指标不等同于运行中的微型 VM 数量。maxVms 配额统计的是账户中所有处于活动状态的环境，包括已完成调用但尚未回收的环境。在 idleRuntimeSessionTimeout 到期（默认 900 秒 / 15 分钟）或你主动停止环境之前，空闲但尚未回收的环境仍会计入配额。

如果你的代码每次请求都使用新的会话 ID，且不调用 StopRuntimeSession，那么每个请求都会留下一个空闲环境，在 15 分钟内持续占用配额。

修复顺序（申请提高配额前，按此顺序尝试）：

1. 每次逻辑请求完成后调用 StopRuntimeSession。 如果你不会在此会话上发送更多请求，请显式停止它。

   client.stop_runtime_session(
       agentRuntimeArn=runtime_arn,
       runtimeSessionId=session_id,
   )
   

2. 在相关请求之间复用会话 ID。 如果一次用户交互会产生多个后端调用，请将这些调用路由到同一会话，而不是为每次调用生成新的会话 ID。

3. 缩短 idleRuntimeSessionTimeout。 如果你的会话生命周期较短，且无法在所有位置添加 StopRuntimeSession，请编辑 agentcore/agentcore.json 中运行时的 lifecycleConfiguration，然后运行 agentcore deploy。

4. 仅在完成上述操作后申请提高配额。 请参阅 agents-harden（加载 references/limits.md）——通过 Service Quotas 控制台（Amazon Bedrock AgentCore）提交申请，而不是直接创建支持工单。

完整模式请参阅 agents-harden 的会话生命周期管理部分。

---

症状：invoke 时出现 424 Failed Dependency

这通常表示 Agent 容器启动失败，或在初始化期间崩溃。

步骤 1： 检查 Agent 日志中的启动错误：

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

步骤 2： 常见原因：

缺少 Python 依赖项： Agent 代码导入了 pyproject.toml 中未列出的程序包。容器可以启动，但会在首次请求时崩溃。修复方法：添加该依赖项并重新部署。

入口点崩溃： main.py 在导入期间或 app.run() 执行时抛出异常。检查日志中的回溯信息。

容器镜像拉取失败： 如果使用 Container 构建，ECR 镜像可能不存在，或执行角色缺少 ecr:BatchGetImage 权限。请检查：

agentcore status --runtime <AgentName> --json

内存资源未处于 ACTIVE 状态： 如果 Agent 代码假定内存已可用，但内存资源仍处于 CREATING 状态，入口点可能会失败。请检查：

agentcore status --type memory

初始化超时： Agent 无法及时准备好处理第一个请求——在模块级别导入繁重依赖、同步建立数据库连接，或在启动期间初始化 MCP 客户端，都可能超出服务的运行状况检查时限。表现为首次调用时出现 424，但后续调用正常。修复方法：将耗时的设置操作移出模块级代码，使用延迟初始化，或在生产流量到来前预热 Agent。相关模式请参阅 agents-harden 的初始化耗时部分。

---

症状：本地调用失败，出现 connection-refused / 退出代码 7

这通常不是 Agent 的问题，而是开发服务器运行在与预期不同的端口上。

agentcore dev 绑定的默认端口：

协议	默认值
HTTP	8080
MCP	8000
A2A	9000

默认端口被占用时（第二个开发会话、上次运行遗留的进程，或运行在 8080 上的其他服务），CLI 会静默地自动递增端口号：8080 → 8081 → 8082。测试框架或将端口写死为 8080 的 curl 脚本会收到 Connection refused（curl 退出代码 7），但 Agent 实际上在 8082 上正常运行。

请按以下顺序排查：

1. 查看 agentcore dev 打印的 CLI 横幅，其中会显示实际绑定的端口和 URL。这始终是准确信息的来源。

2. 如果横幅已不可见（终端内容已清除，或进程在后台运行），请检查日志文件：

   tail -20 agentcore/.cli/logs/dev/*.log
   

3. 或者直接查找进程：

   # macOS / Linux
   ps aux | grep -E 'agentcore dev|uvicorn' | grep -v grep
   lsof -iTCP -sTCP:LISTEN -n -P | grep -E '8080|8081|8082|8000|9000'
   

解决方案：

• 明确指定端口：agentcore dev --port 8080
• 终止占用默认端口的进程：lsof -tiTCP:8080 -sTCP:LISTEN | xargs kill
• 更新测试框架中的硬编码端口，使其从 CLI 输出或环境变量读取

这也是“有时本地运行正常，有时又失败”问题的常见原因之一——端口在不同运行之间发生了变化。

---

症状：网关工具调用因身份验证错误而失败

步骤 1： 确认身份验证类型与目标类型匹配。这是最常见的网关错误：为目标使用了错误的出站身份验证方式：

目标类型	有效的出站身份验证方式
mcp-server	none、oauth 或 IAM（通过 API 使用 SigV4）
lambda-function-arn	仅 IAM（自动）
open-api-schema	oauth 或 api-key（必需）
api-gateway	none、api-key 或 IAM
smithy-model	IAM 或 oauth

步骤 2： 检查 OAuth 令牌是否已过期。如果网关目标使用 OAuth，访问令牌可能已经过期。请查找与身份验证相关的错误：

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

如果令牌即将过期，请确认 OAuth 凭证提供程序的令牌端点可访问，并且客户端凭证仍然有效。对于使用 OAuth 的 MCP 服务目标，网关会自动处理令牌刷新；如果刷新失败，凭证提供程序配置可能有误。

步骤 3： 检查凭证是否已配置：

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

---

症状：没有显示跟踪记录

等待约 15 秒——调用后通常需要约 10 秒，跟踪记录才会显示。

如果约 30 秒后仍没有跟踪记录：

1. 确认部署 Agent 时已启用可观测性
2. 检查 Agent 是否确实已被调用：agentcore logs --runtime <AgentName> --since 1h
3. 检查执行角色的 CloudWatch 权限

---

症状：没有显示 CloudWatch 日志

这是最常见的可观测性问题，尤其是在 Container/Docker 构建中。

AgentCore 不会采集原始 stdout，而是使用 OpenTelemetry 将日志发送到 CloudWatch。以下三点必须全部满足：

1. 入口点必须使用 opentelemetry-instrument 包装。

CodeZip 构建会自动完成此操作。Docker/Container 构建则需要手动添加——这是人们最常遗漏的一点。

在 Dockerfile 的 CMD 中：

# ✅ Correct — wrapped with opentelemetry-instrument
CMD ["opentelemetry-instrument", "python", "main.py"]

# ❌ Wrong — no OTEL wrapper, logs won't appear
CMD ["python", "main.py"]

2. 运行时 IAM 角色需要具备 CloudWatch 和 X-Ray 权限：

logs:CreateLogGroup
logs:CreateLogStream
logs:PutLogEvents    → scoped to /aws/bedrock-agentcore/runtimes/*
xray:PutTelemetryRecords
xray:PutTraceSegments → scoped to *

如果使用 AgentCore CLI 和 CodeZip，CDK 脚手架会自动添加这些权限。如果使用自定义角色或 Container 构建，请确认这些权限已配置。

3. 使用 Python 的 logging 模块，而不是 print()。

OTEL 会自动接入 logging，无需自定义处理程序。print() 语句不会显示在 CloudWatch 中。

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

# ✅ This appears in CloudWatch
logger.info("Processing request")

# ❌ This does NOT appear in CloudWatch
print("Processing request")

还需确认： 账户中已启用 CloudWatch Transaction Search。否则，跟踪记录和跨度不会显示在 GenAI Observability 控制面板中。

Terraform/CDK/IaC 部署的运行时缺少日志

一种常见情况：通过 Terraform、CDK 或自定义 IAM 角色部署的运行时可以正常工作（返回响应），但 CloudWatch 中没有日志流出现；而通过 AgentCore 控制台部署的相同 Agent 代码则能正常记录日志。

这几乎总是 IAM 权限范围配置问题。通过控制台部署运行时的执行角色默认拥有广泛的 CloudWatch 权限。IaC 模板通常会将这些权限限制在 /aws/bedrock-agentcore/runtimes/*，导致无法创建日志流。

解决方法：logs:DescribeLogGroups 的 Resource 必须为 "*"，不能是受限资源。其他日志操作可以限制在运行时的日志组范围内。

{
  "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/*:*"
}

更新执行角色的 IAM 策略后，使用 agentcore deploy 重新部署运行时，以应用新权限。

---

症状：流式连接在响应中途断开

Agent 使用 SSE 或长轮询响应，但连接在流式传输过程中断开。客户端代码中的症状：

• RemoteProtocolError: peer closed connection without sending complete message body
• 迭代流时出现 IncompleteRead 异常
• 静默断开——没有错误，也没有 [DONE] 事件，响应直接停止
• 在多工具调用对话中发生（5 次或更多连续工具调用）
• 远未达到任何客户端超时时间就失败

**根本原因：**流式连接的基础设施层空闲超时。如果响应流数分钟内没有数据传输（例如，工具执行期间的静默时段），运行时前方的负载均衡器就会终止 TCP 连接。

超时针对的是流中传输的数据，而非请求的总耗时。只要定期发送字节，连接就会保持打开。

解决方法：在长时间运行的工具执行期间发送 keepalive 事件。

流式入口点的 Python 模式：

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()

建议将心跳间隔设为约 30 秒。间隔过长可能触发空闲超时；间隔过短则会浪费带宽。

在客户端过滤心跳事件，再将字节传递给用户：

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

**替代方案：对即发即弃模式使用 SDK 的异步任务 API。**如果客户端无需等待结果，请通过 add_async_task / complete_async_task 注册任务，并立即返回调用结果。请参阅 agents-harden 中的 Long-running background tasks 部分。

---

症状：并发 Agent 调用的跟踪记录似乎被合并

你使用唯一的 runtimeSessionId 值并行运行多个 Agent 调用，但 AI Observability 控制面板将它们归为同一个会话，因而无法单独查看某次运行。数据平面日志显示，会话 ID 与请求 ID 一一对应且各不相同，但跟踪视图仍将它们合并。

最常见原因：调用方未启用主动跟踪（Active Tracing），因此上游跨度会以 Sampled=0 到达。AgentCore 默认遵循上游的跟踪采样决策。如果父级上下文指示“不要采样”，跨度就会被丢弃，并发调用也可能在控制面板中显示为合并状态。

按调用方类型解决：

**Lambda 调用方：**为 Lambda 函数启用主动跟踪。

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

也可以在 Lambda 控制台中选择：Configuration → Monitoring and operations tools → AWS X-Ray → Active tracing。

**ECS / EC2 / 容器调用方：**初始化 AWS X-Ray SDK，并确保对 AgentCore 的出站调用经过检测。对于 Python，请使用 aws-xray-sdk 并为 SDK 添加补丁：

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

**不使用 X-Ray 的直接 SDK 调用方：**如果无法启用上游跟踪，可在 Agent 上设置环境变量，强制运行时进行采样：

OTEL_TRACES_SAMPLER=always_on

这会使运行时对每条跟踪都进行采样，而不考虑父级上下文的采样决策。取舍：跟踪成本更高，但跟踪记录会正确显示。

另请检查：是否使用终端节点 ARN 而非 Agent ARN 调用

如果跟踪记录中只有一个顶层 AgentCore.Runtime.Invoke span，且没有子 span，请检查调用方使用的 ARN。调用目标应为 Agent 运行时 ARN：

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

而非终端节点 ARN：

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

使用终端节点 ARN 调用可能会绕过完整的跟踪插桩路径。这是一个隐蔽的陷阱——两个 ARN 都会返回成功响应，但只有 Agent ARN 能生成完整跟踪记录。

---

症状：运行时卡在 DELETING 状态数小时

你调用了 DeleteAgentRuntime，收到成功响应，状态为 status: DELETING，但运行时卡在该状态已超过 30 分钟。尝试单独删除默认终端节点时，会返回 ConflictException: Default endpoints are removed when you delete the agent.

**发生了什么：**删除工作流卡在服务端了。重试 DeleteAgentRuntime 没有帮助——调用会立即成功（返回 DELETING），但卡住的是后端工作流。客户侧工具无法强制完成该流程。

处理方法：

1. **不要继续重试。**这无法让工作流恢复。
2. **在 https://console.aws.amazon.com/support 提交 AWS Support 案例。**请提供：
   • AWS 账户 ID
   • 区域
   • 运行时 ARN（或 agentRuntimeId）
   • 原始 DeleteAgentRuntime 调用的 requestId 和时间戳（来自 CloudTrail）
   • 运行时处于 DELETING 状态的时长
3. **同时采用临时变通方案。**如果需要继续发布，请使用不同的名称部署新的运行时。不要让卡住的资源阻碍工作。

卡在删除流程中的孤立资源（ENI、工作负载身份）可能需要服务团队在同一个案例中手动清理。

---

特定框架的问题

LangGraph — 模型格式： 较旧版本的 langchain-aws 要求模型 ID 不带跨区域前缀。近期版本可能支持跨区域推理配置文件，请检查你安装的版本：

pip show langchain-aws | grep Version

如果 LangGraph 出现模型错误，请尝试使用不带前缀的 ID：

# If cross-region prefix errors in your langchain-aws version:
llm = init_chat_model("anthropic.claude-sonnet-4-5-20250929-v1:0", model_provider="bedrock_converse")

# If your version supports cross-region profiles (us. = US, eu. = Europe, apac. = Asia Pacific, global. = worldwide):
llm = init_chat_model("global.anthropic.claude-sonnet-4-5-20250929-v1:0", ...)

请对照当前 langchain-aws 版本说明进行核实：https://github.com/langchain-ai/langchain-aws/releases — 跨区域推理配置文件支持一直在演进。

Google ADK — 仅支持 Gemini： ADK 仅适用于 Gemini 模型。如果 ADK 出现模型错误，请检查是否已设置 GEMINI_API_KEY，并且使用的是 gemini-* 模型 ID。

A2A Agent — 端口错误： A2A 服务必须运行在端口 9000 上。如果 A2A Agent 没有响应，请检查它是否误在端口 8080 上运行。

---

阅读跟踪记录

跟踪记录会显示一次 Agent 调用的完整执行路径。主要部分包括：

• 模型调用 — 向模型提出了什么请求，以及模型返回了什么
• 工具调用 — 调用了哪些工具、使用了哪些输入，以及工具返回了什么
• 内存操作 — 从内存中读取了什么，以及向内存中写入了什么
• 策略决策 — 哪些操作被允许或拒绝（如果附加了策略引擎）
• 延迟细分 — 各组件耗费的时间

# Download trace to a file for detailed inspection
agentcore traces get <traceId> --runtime <AgentName> --output trace.json
cat trace.json | jq '.trace.orchestrationTrace.modelInvocationOutput'

输出

• 对具体故障的诊断及根本原因
• 具体的修复命令或代码更改
• 对跟踪记录内容的说明（如果正在读取跟踪记录）
• 如果修复超出 debug 的范围，则转交给相应的技能

诊断后 — 移交

确定根本原因后，请移交给负责修复的技能：

根本原因	移交给	详情
内存配置错误（策略、命名空间或连接方式不正确）	agents-build	加载 references/memory.md
应用无法调用 Agent（身份验证、URL、流式传输）	agents-build	加载 references/integrate.md
VPC 连接问题（无法连接到 RDS、没有互联网、AZ 错误）	agents-build	加载 references/vpc.md
多 Agent 委派无法正常工作	agents-build	加载 references/multi-agent.md
自定义请求标头未传递到 Agent 代码	agents-build	加载 references/request-headers.md
从其他账户中的应用跨账户调用	agents-build	加载 references/integrate.md（跨账户部分）
Gateway 身份验证配置错误（401、身份验证类型错误）	agents-connect	Gateway 身份验证矩阵
Gateway 目标类型问题（Lambda、OpenAPI、MCP 还是 API Gateway）	agents-connect	“Gateway 是什么，不是什么”部分
策略意外拒绝访问（Cedar、工具访问被拒绝）	agents-connect	加载 references/policy.md
未设置可观测性（没有日志、没有跟踪记录）	agents-optimize	加载 references/observability.md
冷启动／初始化过慢	agents-harden	初始化时间部分
会话生命周期／maxVms／StopRuntimeSession	agents-harden	会话生命周期管理部分
长时间运行的后台任务被回收	agents-harden	长时间运行的后台任务部分
JWT 入站身份验证失败（403、allowedClients／allowedAudience、颁发者不匹配）	agents-harden	入站身份验证部分
限流／配额错误／请求提高限额	agents-harden	加载 references/limits.md
部署制品过期或版本错误	agents-deploy	重新部署工作流
环境异常（CLI、凭据、Node、uv）	加载 references/doctor.md	此技能中包含完整处理说明

清楚说明诊断结果，然后告知开发者下一步应使用哪个技能。如果 Agent 能在同一会话中加载所引用的技能，请直接加载。