调试托管智能体

#调试托管智能体

诊断并修复使用 azd ai agent 为 Microsoft Foundry 构建、运行和部署智能体时的常见问题。先从诊断命令开始。然后使用按症状划分的章节排查身份验证、本地开发、部署、直接命令、日志和例程。

先决条件

• 一个已初始化的托管智能体（Hosted agent）项目。要创建一个，请参阅初始化智能体项目。
• 已安装 azd Foundry 扩展。安装步骤请参阅安装 azd Foundry 扩展。
• 一个已认证的 Azure 开发者 CLI（Azure Developer CLI）会话。如有需要，运行 azd auth login。
• 对于部署和日志问题，需要一个已部署的托管智能体。要部署一个，请参阅部署托管智能体。

收集诊断上下文

在深入具体错误之前，使用这些命令收集上下文：

# Check extension version
azd ai agent version

# Verify Azure authentication
azd auth login

# Show current environment configuration
azd env get-values

# View agent details
azd ai agent show

# Show the resolved Foundry project endpoint and where it came from
azd ai project show

# Stream production logs
azd ai agent monitor --follow

要获得结构化健康报告，运行 azd ai agent doctor。更多信息请参阅用智能体医生诊断项目。

诊断调用延迟

使用延迟调试标头，判断一次缓慢的托管智能体请求是把时间花在平台上、预配基础设施、等待容器，还是在你的智能体中处理请求。这些标头是诊断信号，不是服务级别协议（Service Level Agreement，SLA）或计费指标。

在每个请求上设置 x-ms-debug-latency-enabled: true 以启用该诊断。如果请求不包含此标头，响应就不会包含 x-ms-debug-latency-* 标头。

1. 把延迟标头加到托管智能体的 Responses 或 Invocations 协议请求上。此示例使用 Responses 协议：

    ENDPOINT="https://{account}.services.ai.azure.com/api/projects/{project}"
    API_VERSION="v1"
    TOKEN=$(az account get-access-token \
      --resource https://ai.azure.com \
      --query accessToken -o tsv)
    AGENT="my-code-agent"
    
    curl --http2 -i -X POST \
      "$ENDPOINT/agents/$AGENT/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
      -H "Authorization: Bearer $TOKEN" \
      -H "Content-Type: application/json" \
      -H "x-ms-debug-latency-enabled: true" \
      -d '{"model":"gpt-5.4-mini","input":"Hello, agent!","stream":false}'

2. 检查响应标头。所有延迟值都是整数毫秒：

四个计时组成部分相加等于 x-ms-debug-latency-response-begin-ms。在冷启动或已恢复的请求上，如果平台无法捕获每一个预配边界，它会省略基础设施和就绪标头，并把那段时间计入平台预处理。

3. 用会话启动类型和最大的计时组成部分识别延迟的可能来源：

缩短容器就绪时间

容器就绪值包括启动进程、加载应用程序，以及从 /readiness 返回 HTTP 200 所需的时间。给启动日志加上时间戳，以识别缓慢的导入、依赖加载、网络调用和其他初始化工作。

对你识别出的缓慢步骤应用这些优化：

• 在构建镜像时安装依赖并编译代码。不要在容器启动时运行包安装、还原或编译。
• 使用多阶段构建，并把构建工具、包缓存、测试和其他开发文件排除在运行时镜像之外。
• 在就绪之前避免模型调用、迁移、工具发现和资产下载。把必须先完成的独立初始化并行化。
• 让 /readiness 专注于智能体能否接受请求。如果你推迟初始化，请测量第一个请求，以确保没有把启动延迟挪到请求处理中。

Python

在复制到运行时镜像的虚拟环境中安装依赖。尽力编译依赖，这样第三方包中无法解析的文件不会使构建失败。严格编译应用程序，使语法错误导致构建失败。

FROM python:3.13-slim AS build

WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q /opt/venv \
      || true; \
    PYTHONDONTWRITEBYTECODE= python -m compileall -q /app

FROM python:3.13-slim AS final

ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app

COPY --from=build /opt/venv /opt/venv
COPY --from=build /app /app

# Precompile the standard library in the runtime image.
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q \
    "$(python -c "import sysconfig; print(sysconfig.get_path('stdlib'))")" \
    || true

CMD ["python", "main.py"]

为此构建步骤清除 PYTHONDONTWRITEBYTECODE，允许 Python 把字节码写入镜像。该环境变量阻止的是字节码写入，而不是读取，因此正在运行的容器仍可使用已编译的文件。

参考：compileall：字节编译 Python 库

.NET

使用 ReadyToRun 发布，以便为目标运行时编译程序集，并减少即时编译器在启动期间执行的工作。此示例使用匹配的、基于 glibc 的 SDK 和运行时镜像，因此正确的 .NET 运行时标识符是 linux-x64。

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build

WORKDIR /src
COPY . .

RUN dotnet publish -c Release \
    -r linux-x64 \
    --self-contained false \
    -p:PublishReadyToRun=true \
    -o /app

FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final

WORKDIR /app
COPY --from=build /app .

ENTRYPOINT ["dotnet", "MyAgent.dll"]

把 MyAgent.dll 替换为你发布的程序集名称。把还原、构建和发布放在同一条命令中，以便 ReadyToRun 属性在还原期间生效。ReadyToRun 以更大的镜像和更长的构建为代价改善启动性能。

重要

运行时标识符必须与运行时镜像匹配。如果你使用 Alpine Linux，两个阶段请使用 sdk:10.0-alpine 和 aspnet:10.0-alpine，并使用 linux-musl-x64。不要把 linux-x64 用于 Alpine 镜像，也不要把 linux-musl-x64 用于基于 glibc 的镜像。不匹配可能导致还原、发布或运行时失败。

参考：ReadyToRun 部署

为托管智能体所要求的 x86-64 架构构建任一镜像：

docker build --platform linux/amd64 -t my-agent:latest .

这里，linux/amd64 是 Docker 平台，不是 .NET 运行时标识符。

参考：托管智能体容器要求

调查智能体和模型延迟

如果容器就绪很快，但容器响应或首字节时间很高，请把调查集中在转发开始之后的请求路径上。在复现请求时运行 azd ai agent monitor --follow，并在模型调用、工具调用、外部服务、重试和响应序列化周围添加跟踪。更多信息请参阅监视托管智能体日志。

对于调用大语言模型（Large Language Model，LLM）的智能体，在更改部署之前单独测量模型延迟。比较首令牌时间、令牌间隔时间、生成的令牌数、提示大小、部署利用率和限流。然后评估模型选择、输出令牌限制、流式传输和工作负载分离。请参阅改善 Azure OpenAI 性能。

如果测量显示可预测工作负载存在持续的容量压力，请评估预配部署，并按观察到的输入令牌、输出令牌和请求速率确定其规模。请参阅预配吞吐量。

检查完成计时

在 HTTP/2 或更高版本上，服务可以返回尽力而为的 x-ms-debug-latency-final 响应尾部。它重复响应标头中的值，并可以添加这些字段：

该尾部使用带版本的、以分号分隔的格式：

x-ms-debug-latency-final: v=1;start=cold;platform_pre_ms=...;
  infra_ms=...;ready_ms=...;container_response_ms=...;
  response_begin_ms=...;first_byte_ms=...;total_last_byte_ms=...

HTTP/1.1 响应不包含此尾部。在取消、客户端断开、中途错误，或网关或 SDK 不保留尾部时，尾部也可能缺失。把响应标头视为有保证的诊断契约。

检索已存储的延迟结果

服务把捕获的计时与响应或调用一起存储。稍后对同一响应或调用 ID 的 GET 请求会把原始请求的计时作为响应标头返回。该 GET 请求不要求延迟标头，也不测量 GET 请求本身。

GET 请求也可以把这些完成值作为普通标头返回：

存储是最终一致的，因此紧接在原始请求之后的 GET 请求可能还没有包含这些标头。对于异步响应或调用，只有平台开销值可用：会话启动类型、平台预处理、基础设施设置和容器就绪。失败的代理响应或 WebSocket（invocations_ws）请求不会发出延迟标头。

修复身份验证错误

修复 AuthenticationError

症状： 智能体无法在本地启动，或在调用 AI 模型时返回 401/403。

原因与修复：

• 凭据过期：运行 azd auth login 以刷新 Azure 会话。
• 订阅错误：用 azd env get-values | grep AZURE_SUBSCRIPTION_ID 验证，并与 Foundry 项目的订阅比较。
• 缺少 RBAC 角色：你的身份需要在 Foundry 项目上拥有 Foundry 用户（Foundry User）或等效访问权限。

重要

Foundry 的基于角色的访问控制（Role-Based Access Control，RBAC）角色最近已更名。Foundry 用户（Foundry User）、Foundry 所有者（Foundry Owner）、Foundry 账户所有者（Foundry Account Owner）和 Foundry 项目管理员（Foundry Project Manager）以前分别名为 Azure AI User、Azure AI Owner、Azure AI Account Owner 和 Azure AI Project Manager。在更名推广期间，你可能仍会在某些地方看到旧名称。角色 ID 和核心权限不因更名而改变。

你的身份还需要 认知服务 OpenAI 用户（Cognitive Services OpenAI User） 才能使用模型部署。

修复预配期间的 AuthorizationFailed

症状： azd up 或 azd provision 因权限错误而失败。

修复： 在 Azure 订阅上申请 参与者（Contributor） 角色。对于持续集成/持续交付（CI/CD），服务主体还需要 Foundry 所有者（Foundry Owner）。

修复 SubscriptionNotRegistered

症状： 预配失败，因为所需的资源提供程序未注册。

修复：

az provider register --namespace Microsoft.CognitiveServices
az provider register --namespace Microsoft.ContainerRegistry

修复本地开发问题

修复端口 8088 上的连接被拒绝

症状： azd ai agent invoke --local 无法连接。

原因与修复：

• 智能体未运行：在另一个终端用 azd ai agent run 启动它。
• 端口冲突：另一个进程正在使用端口 8088。停止它，或使用自定义端口：

    azd ai agent run --port 9090
    azd ai agent invoke --local --port 9090 "Hello!"

• 启动崩溃：检查运行 azd ai agent run 的终端中的错误输出。常见原因包括缺少依赖、导入错误，或 azure.yaml 中不正确的 startupCommand。

修复依赖安装失败

症状： azd ai agent run 在依赖安装期间失败。

原因与修复：

• 运行时版本错误：确保已安装 Python 3.10+ 或 .NET 8+。
• 缺少 requirements.txt 或 .csproj：CLI 根据这些文件自动检测项目类型。确认它们存在于智能体目录中。
• 网络问题：包注册表可能被公司代理阻止。检查 pip 或 dotnet 配置。

修复 ResourceNotFound 或 DeploymentNotFound

症状： 智能体已启动，但在尝试调用模型时失败。

原因与修复：

• 终结点不匹配：运行 azd env get-values，并确认 FOUNDRY_PROJECT_ENDPOINT 与 Foundry 门户中显示的终结点匹配。
• 模型部署名称不匹配：azure.yaml 中配置的模型部署名称必须与 Foundry 项目中的部署名称匹配。在门户的 部署（Deployments） 下检查。
• 资源未预配：如果你还没有运行 azd up，云资源就不会存在。先运行 azd up，再在本地测试。本地智能体仍然调用云上托管的模型。

修复部署问题

修复容器构建失败

症状： azd up 在 Docker 构建阶段失败。

原因与修复：

• 缺少 Dockerfile：确保智能体目录中有 Dockerfile。如果从模板初始化，它会自动生成。
• 构建上下文错误：Dockerfile 必须位于 azure.yaml 中服务 project 路径所指定的目录中。
• Docker 中的依赖安装：如果容器内的 pip/dotnet 还原失败，请检查 requirements.txt 或 .csproj 是否正确固定了所有依赖。

修复 azd up 挂起或超时

症状： 预配或部署花费的时间异常长。

原因与修复：

• 首次部署：第一次 azd up 会预配全部 Azure 资源，包括 Foundry 项目、容器注册表（Azure Container Registry，ACR）、托管标识和模型部署，可能需要 5 到 10 分钟。后续部署更快。
• 远程构建：默认情况下，容器镜像在 ACR 上远程构建。这可能更慢，但不需要本地 Docker。要改为本地构建，请在 azure.yaml 的服务配置中设置 docker.remoteBuild: false。
• 区域容量：某些区域对特定模型 SKU 的容量可能有限。如果预配持续失败，请尝试其他区域。

修复已部署但不响应的智能体

症状： 部署成功后，azd ai agent invoke 超时或返回错误。

原因与修复：

• 健康探测失败：容器必须在端口 8088 上对 GET /readiness 以 200 状态响应。用 azd ai agent monitor --follow 检查日志。
• 协议不匹配：确保 azure.yaml 中 azure.ai.agent 服务所定义的协议与代码实现的协议匹配。如果 azure.yaml 写的是 responses，但代码只处理 invocations，或相反，请求就会失败。
• 容器崩溃：检查系统日志中的重启事件：azd ai agent monitor --type system。常见原因包括未处理的异常和内存不足。如有需要，在 azure.yaml 中增加容器资源。

修复直接命令失败

这些错误来自针对 Foundry 项目运行的 azd ai 直接命令，例如 azd ai connection、azd ai toolbox 和 azd ai routine。

修复未解析的 Foundry 项目终结点

症状： 直接命令以 No Foundry project endpoint resolved. Run azd ai project set to set one, or pass --project-endpoint. 退出。

原因： CLI 无法在任何受支持的来源中找到 Foundry 项目终结点：--project-endpoint 标志、活动的 azd 环境、全局配置，或 FOUNDRY_PROJECT_ENDPOINT 环境变量。

修复：

• 运行 azd ai project set <endpoint>，把终结点存储在全局 azd 配置（~/.azd/config.json）中。
• 在每条命令上传递 --project-endpoint（-p）：azd ai connection list -p https://my-proj.services.ai.azure.com/api/projects/my-project。
• 在 shell 环境中设置 FOUNDRY_PROJECT_ENDPOINT。

完整的解析顺序以及每种来源何时生效，请参阅理解 azd 项目上下文。

修复已有资源的创建失败

症状： azd ai connection create、azd ai toolbox create、azd ai routine create 或 azd ai skill create 因“已经存在”错误而失败。

原因： 按照设计，create 不是更新插入。默认失败模式防止一名开发者在共享的 Foundry 项目上静默覆盖另一人的状态。

修复：

• 选择不同的名称并重新运行。
• 在 create 命令支持的地方传递 --force，通过 ARM PUT 替换现有资源。替换是破坏性的：它就地覆盖现有资源，来自门户手工编辑、元数据或凭据的任何偏差都会丢失。azd ai toolbox create 命令不支持 --force。请删除现有工具箱，或改用新名称。

修复 connection show 的凭据输出

症状： azd ai connection show <name> 返回连接的名称、种类、目标和身份验证类型，但没有 API 密钥或凭据值。

原因： 按照设计，默认绝不返回凭据值。它们需要显式的 --show-credentials 标志。

修复：

azd ai connection show tavily-conn --show-credentials

这会调用数据平面 API，并要求对 Foundry 项目拥有数据平面权限，例如 Foundry 用户或等效角色。如果你只有管理平面的 Reader 或 Contributor 访问权限，调用会以 403 失败。请向项目所有者申请数据平面角色。

读取智能体日志

使用 azd ai agent monitor 检查智能体行为：

# Stream all recent logs
azd ai agent monitor --follow

# View system-level events (container starts, crashes, restarts)
azd ai agent monitor --type system

# Filter to a specific session
azd ai agent monitor --session-id <session-id>

常见日志模式包括：

诊断例程失败

例程的失败方式与交互式 agent invoke 调用不同，因为没有调用方在场来呈现错误。例程是由计时器触发、重复触发、GitHub 议题触发或自定义事件触发的智能体运行。使用 azd ai routine run list 检查发生了什么。

检查过去的运行

# Recent runs of a routine: trigger time, agent input/output, status, trace link
azd ai routine run list daily-digest

筛选失败

# Failed runs only, with an OData filter
azd ai routine run list daily-digest --filter "status eq 'failed'"

与 --top 结合以扩大或缩小窗口。

深入单次运行

# Full detail for the most recent runs as JSON, then look up the run you care about
azd ai routine run list daily-digest --top 5 --output json

JSON 输出包括输入负载、智能体的响应，以及分布式跟踪的深层链接，与交互式调用中看到的跟踪相同。

手动重新触发例程

如果需要复现失败或测试修复，用 dispatch 按需触发例程：

azd ai routine dispatch daily-digest
azd ai routine dispatch triage-issues --input '{"issue":{"number":42}}'

dispatch 异步运行并打印一个调度 ID。用 azd ai routine run list <name> 检查结果。

修复失败的例程运行

azd ai routine run list 显示 status: failed 的运行。跟随跟踪链接查看底层智能体错误，例如模型错误、工具失败或超时。智能体侧的修复与交互式失败相同。请参阅“修复身份验证错误”和“读取智能体日志”。

修复从不触发的例程

如果 azd ai routine run list 完全不返回任何运行，则触发器本身没有触发：

1. 检查例程是否已启用：azd ai routine show <name>。查找 enabled: true。
2. 对于 timer 触发器，确认 --at 在未来，并且尚未触发。
3. 对于 recurring 触发器，确认 --cron 表达式有效，并且 --time-zone 是你期望的时区。
4. 对于 github-issue 触发器，确认 --connection-id 解析到一个健康的连接，并且 GitHub 存储库和 --issue-event 与该存储库发出的事件匹配。
5. 对于 custom 触发器，确认 --provider、--event-name 和 --parameters 范围与提供程序正在发布的事件匹配。

获取更多帮助

• 调试模式：给任何 azd 命令加上 --debug 以获得详细输出。
• Azure 门户：在 Azure 门户中检查 Foundry 项目的资源运行状况和诊断。
• 提交缺陷：在 https://github.com/Azure/azure-dev/issues 报告问题。

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/debug-hosted-agent