Azure / Azure/azure-functions-agents-runtime

Expose agent tool-loop limits in configuration

Open
#49 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

The runtime currently exposes a wall-clock `timeout`, but it does not expose Microsoft Agent Framework's function/tool-loop limits. Apps inherit the MAF defaults, currently `max_iterations=40` and `max_function_calls=None`.

For agents with tools, MCP servers, or code execution, app authors need a simple way to prevent runaway loops and control tool execution cost without relying only on wall-clock timeout.

## Upstream Agent Framework knobs

Agent Framework configures these values on the chat client through `function_invocation_configuration`:

```python
client.function_invocation_configuration["max_iterations"] = 5
client.function_invocation_configuration["max_function_calls"] = 20
```

Semantics:

- `max_iterations`: caps LLM roundtrips in the tool loop. Each roundtrip may call one or more tools.
- `max_function_calls`: caps the total individual tool/function invocations across a request. This is a best-effort cap checked between batches; a single parallel batch can overshoot.

The OpenAI and Foundry chat clients used by this runtime accept `function_invocation_configuration` in their constructors.

## Proposed runtime config

Expose these as product-level runtime settings, parallel to `model` and `timeout`.

Global config:

```yaml
# agents.config.yaml
model: $FOUNDRY_MODEL
timeout: 900
max_iterations: 10
max_function_calls: 20
```

Agent frontmatter override:

```yaml
---
name: Daily Azure Report
description: Lists changed resources and emails a report.

timeout: 900
max_iterations: 8
max_function_calls: 25

trigger:
type: timer_trigger
args:
schedule: "0 0 7 * * *"
---
```

Environment variable overrides:

```text
AZURE_FUNCTIONS_AGENTS_MAX_ITERATIONS
AZURE_FUNCTIONS_AGENTS_MAX_FUNCTION_CALLS
```

Suggested precedence, mirroring `timeout`:

```text
agent frontmatter > agents.config.yaml > env var > MAF default
```

## Design notes

- Prefer top-level `max_iterations` and `max_function_calls` over an SDK-shaped `function_invocation_configuration` block.
- Avoid nesting under `system_tools`; these limits apply to the whole tool loop, including custom tools and MCP tools, not only runtime-provided system tools.
- Avoid leaking `agent_framework` as a public configuration section name.
- Consider whether `max_function_calls: null` should be supported explicitly to mean unlimited, matching MAF.

## Acceptance criteria

- `GlobalConfig`, `AgentSpec`, and `ResolvedAgent` include optional `max_iterations` and `max_function_calls` fields.
- Merge logic resolves both values with the agreed precedence.
- Env vars are parsed and invalid values fall back or fail consistently with existing timeout behavior.
- `MAFClientManager` passes `function_invocation_configuration` into OpenAI, Azure OpenAI, and Foundry clients when either value is configured.
- Docs describe the difference between wall-clock `timeout`, `max_iterations`, and `max_function_calls`.
- Tests cover global defaults, per-agent overrides, env var fallback, invalid env values, and provider client construction.

Contributor guide

Open the contributing guide

Research direction

Locate GlobalConfig, AgentSpec, ResolvedAgent, and MAFClientManager, then trace the existing timeout merge and environment-variable handling. Inspect provider client construction and related tests before adding coverage for precedence, invalid values, and configured limits. Done means both limits resolve correctly, reach OpenAI, Azure OpenAI, and Foundry clients, and are documented alongside timeout.

Written by the indexing model from the issue text.

Assessment

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.