Troubleshoot Agent Framework agents
Fixes for the build, deploy, hosting and reporting failures seen with Agent Framework agents and workflows on Foundry and AMC.
Before you startA hosted agent or workflow, and access to its Foundry logs.View as Markdown
Build and deploy
| Symptom | Cause and fix |
|---|---|
Remote build fails: Cannot install agent-framework-core ... hyperlight-sandbox-backend-wasm ... ResolutionImpossible | You depend on the agent-framework meta-package. Depend on agent-framework-core, agent-framework-foundry and agent-framework-foundry-hosting only. |
bad_request: Unsupported region for Foundry Hosted Agents | The account's region doesn't support hosted agents, and it can't be changed. Use a project in a supported region. |
azd: project ... not found or is not eligible for the current configuration | The same region problem, or a missing data-plane role such as Foundry User. |
ImportError for AzureAIAgentsProvider or agent_framework.azure | Older SDK surface. Use FoundryChatClient, FoundryAgent and to_prompt_agent from agent_framework.foundry; see the overview. |
| Agent fails at startup: running on protocol 1.0.0, but the agent requires protocol 2.0.0 | The responses 2.x runtime needs hosted-agent protocol 2.0.0. Set ProtocolVersionRecord(protocol="responses", version="2.0.0") and use an environment that supports it. |
TypeError on ResponsesServerOptions(resilient_background=True) | azure-ai-agentserver-responses is older than 2.x. Bump the four pins together; see Harden an agent or workflow for AMC. |
RuntimeError on resilient_background=True | You passed it for a single agent. It is workflow-only; build the job as a one-node workflow if it needs recovery. |
Hosting
| Symptom | Cause and fix |
|---|---|
Workflow.run() got an unexpected keyword argument 'messages' | ResponsesHostServer was given a raw Workflow. Wrap it: ResponsesHostServer(workflow.as_agent(name=...)). |
Workflow's start executor cannot handle list[Message] | Add a list[Message] handler to the start executor. |
@response_handler signature validation fails | Remove from __future__ import annotations from that module. |
Checkpoint deserialization blocked for type 'workflow:<Type>' | Add that type, and every other custom edge or request type, to CheckpointStoreProvider(allowed_checkpoint_types=[...]). |
| A human-input run never resumes | Without recovery the checkpoint is instance-local. Run one replica, or turn on resilient_background with the allow-list. |
Run stuck at in_progress after a deploy or a dropped connection; reconnect returns an empty stream | The run died with its process. Turn on resilient_background for workflows. |
Empty output_text from a smoke test | Expected when the terminal executor yields a dict rather than assistant text. The data is still in the response. |
| A message-less trigger does nothing, or ignores your schema | Add middleware that appends a kickoff message, and set response_format in default_options; the host doesn't forward a caller's. |
Reporting in AMC
| Symptom | Cause and fix |
|---|---|
| Every step shows zero tokens, or the run has no cost | usage_details was read with getattr. It is a dict; use .get("input_token_count"). Hosted run-level usage is always empty, so markers are the only source. |
| No steps appear, only the final result | Executors don't emit markers, or aren't in intermediate_output_from, so their markers aren't forwarded. |
| One step is missing although its executor emits a marker | The marker's call_id and name differ, so AMC treats it as a real tool call and ignores it. Set both to the step id. |
| Steps run but never show as failed | The executor re-raises without emitting failure_reason first. |
| Cost looks wrong for a step | No token rate is configured for that model in AMC, or a model_usage key isn't the pricing model id. |
| The human-input step has no question | The request_data dataclass has no question field. |
| A workflow was imported as an agent, or a helper is missing from the catalog | Name-based classification: agent in the name means a single agent, subagent means hidden. Rename, or register by hand with the right Kind. |
| Detail rows missing | activity_log is off (EMIT_STEP_ACTIVITY_LOG=false), the capture hit an error and fell back, or the model emitted no reasoning. |
For Foundry-side failures, Microsoft's hosted-agent troubleshooting guide is at aka.ms/hostedagents/tsg/code.
Related
Last updated 2026-10-21