Azure / Azure/azure-functions-agents-runtime

Fail fast on malformed agent and MCP configuration by default

Open
#37 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
9
Forks
7
Avg merge
1d 21h
Merged PRs (30d)
20

Description

## Problem

Some configuration errors are currently fail-soft during startup. For a programming model, this can make mistakes look like missing agents or missing tools instead of clear configuration failures.

Examples:

- Malformed `*.agent.md` files are skipped with a warning when agent specs are loaded with `strict=False`.
- Invalid or partially invalid `mcp.json` entries are skipped with warnings.
- MCP auth configuration problems can be deferred until the first tool call.
- Tool/skill/MCP references can be hard to diagnose from logs alone.

In local development and production, warnings are easy to miss in Functions host logs. Users may see that an agent did not register, or that a tool is unavailable, without an obvious startup failure pointing to the exact file and field.

## Proposal

Make startup validation stricter by default before public preview.

Recommended behavior:

- Fail fast on malformed `.agent.md` frontmatter instead of silently skipping the file.
- Fail fast on invalid `agents.config.yaml` and invalid `mcp.json` structure.
- Treat unresolved required configuration for enabled capabilities as startup errors where possible.
- Keep errors file/field-specific and link to the relevant docs anchor.
- Consider an explicit opt-out for advanced/dev scenarios, for example `AZURE_FUNCTIONS_AGENTS_STRICT=0`.

## Interaction with configuration overhaul work

This should be reconciled with PR #15 and any other configuration-shape changes. Regardless of whether provider configuration remains env-driven or moves into `agent_configuration`, the final public-preview behavior should avoid silently skipping user-authored agents or capability config.

## Required docs and sample updates

- Update README quickstart/troubleshooting to explain that invalid agent/config files fail startup.
- Update `docs/front-matter-spec.md` validation behavior.
- Update samples only if any current sample relies on unresolved placeholders or optional config that would become a startup error.
- Update tests and fixtures that currently expect malformed files to be skipped.

## Acceptance criteria

- Malformed agent files fail startup by default with a clear file/field error.
- Invalid `mcp.json` fails startup by default when present and malformed.
- Any opt-out is explicit, documented, and not the default.
- The validation behavior is covered in tests.
- README/docs describe how to diagnose and fix startup validation errors.

Contributor guide

Open the contributing guide

Research direction

Review the current agent and MCP validation tests and fixtures, then read README quickstart/troubleshooting and docs/front-matter-spec.md alongside configuration overhaul PR #15. Trace how malformed .agent.md, agents.config.yaml, and mcp.json files are handled. Done means default startup failures are file/field-specific, any opt-out is explicit and documented, and tests and documentation cover the behavior.

Written by the indexing model from the issue text.

Assessment

Tech stack
azure, python
Domain
backend, cloud, documentation, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.