# Troubleshoot Agent Framework agents

Agent Mission Control developer docs > Microsoft Agent Framework (Python)

> Fixes for the build, deploy, hosting and reporting failures seen with Agent Framework agents and workflows on Foundry and AMC.

**Before you start:** A hosted agent or workflow, and access to its Foundry logs.

## 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](https://www.agentmissioncontrol.ai/developers/af-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](https://www.agentmissioncontrol.ai/developers/af-amc-hardening/). |
| `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](https://aka.ms/hostedagents/tsg/code).

## Related

- [Harden an agent or workflow for AMC](https://www.agentmissioncontrol.ai/developers/af-amc-hardening/)
- [Host and deploy on Foundry](https://www.agentmissioncontrol.ai/developers/af-host-and-deploy/)
- [Register and test in AMC](https://www.agentmissioncontrol.ai/developers/af-register-and-test/)

---
Source: https://www.agentmissioncontrol.ai/developers/af-troubleshooting/ · Last updated 2026-10-21 · Full index: https://www.agentmissioncontrol.ai/llms.txt