feat(agents): add max_tool_calls budget to ChatAgent

[anupamkr1708]

Summary

Adds an optional max_tool_calls budget to ChatAgent, independent of
max_iteration, to limit cumulative internal tool executions within a
single step() or astep() call.

Changes

• Add max_tool_calls: Optional[int] = None to ChatAgent.
• Validate configured values as positive integers or None.
• Reject bool values explicitly.
• Track tool executions as per-step local state so the budget resets for
  each new step() / astep() call.
• Enforce the remaining budget before dispatching tool calls from a model
  response, so a batch cannot execute more calls than allowed.
• Record valid tool-role rejection messages for calls beyond the remaining
  budget, preserving OpenAI-compatible message history.
• Stop providing tool schemas once the budget is exhausted so the model can
  continue to a final textual response.
• Preserve max_tool_calls when cloning a ChatAgent.
• Keep max_tool_calls independent from max_iteration.

Tests

Added focused coverage for:

• synchronous tool-call limiting;
• per-step budget reset;
• partial tool-call batches and rejected-call history;
• tool disabling after exhaustion;
• asynchronous execution;
• clone behavior;
• valid and invalid configuration values;
• independence from max_iteration.

Validation performed locally:

• python -m pytest test/agents/test_chat_agent_max_tool_calls.py -q — 17 passed
• python -m pytest test/agents/test_chat_agent_clone.py -q — 3 passed
• python -m pytest test/agents/test_chat_agent_tool_log.py -q — 24 passed
• ruff check --no-fix camel/agents/chat_agent.py — passed
• git diff --cached --check — passed

Streaming tool-execution paths are intentionally unchanged in this PR.

Fixes #4278

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: 5022f4a1-8fe3-4f41-9a64-596bc183ca17

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[anupamkr1708]

I investigated the current CI failures. The PR Label Automation job is failing with a 403 Resource not accessible by integration while trying to add the Review Required label, so that appears to be a workflow-token permission issue rather than a code failure.

The pytest-related jobs are currently failing during test collection with ImportError: cannot import name 'FastMCP' from 'mcp.server', before the affected tests execute. I have since checked the base branch locally; the direct FastMCP import succeeds there, although the corresponding app test cannot be reproduced locally because that environment is missing gradio. So I have not yet confirmed that this CI dependency/import failure is pre-existing.

The feature validation remains green locally: 17 focused max_tool_calls tests, 3 clone tests, and 24 tool-log tests passed; Ruff and git diff --check also passed.

I’ll continue checking the failing jobs against the base branch to confirm whether the dependency/import failure is pre-existing.

[anupamkr1708]

I also addressed the mypy failure reported by CI in the new regression test. The ChatCompletion helper now uses the typed Choice model with a Literal finish-reason type, matching the existing test conventions. The focused max_tool_calls tests, related regression tests, Ruff/pre-commit checks, and scoped mypy check are passing locally. The PR has been updated with follow-up commit 82b2b0b.