feat/rate limit implementation

[sujal12344]

PR Checklist

Please check if your PR fulfills the following requirements:

• The commit message follows our guidelines: https://voltagent.dev/docs/community/contributing/#commit-convention

Bugs / Features

• Related issue linked Rate Limiting #5
• Tests for the changes have been added (36 test cases)
• Docs have been added / updated (added example in example/with-rate-limiting)
• Changesets have been added https://voltagent.dev/docs/community/contributing/#creating-a-changeset

What is the current behavior?

Currently, VoltAgent has no built-in mechanism to control the frequency of LLM calls and tool executions. This can lead to:

• Exceeding API rate limits from LLM providers (OpenAI, Anthropic, Google, etc.)
• Unexpected API throttling or account suspension
• Uncontrolled costs in production environments
• Poor resource management in multi-tenant scenarios
• No way to implement custom usage quotas

Users must implement rate limiting manually in their application code, which is:

• Error-prone and inconsistent across different agents
• Difficult to test and maintain
• Not integrated with VoltAgent's observability features

What is the new behavior?

1. Configurable Rate Limiting

   • Control LLM calls globally or per provider
   • Limit tool executions individually
   • Support for requests-per-minute constraints

2. Flexible Strategies

   • Fixed Window Counter (MVP)
   • Option to throw error immediately or delay until quota resets

3. Multi-Scope Support

   • Global LLM limits
   • Provider-specific limits (OpenAI, Anthropic, etc.)
   • Tool-specific limits

Example Project (examples/with-rate-limiting/)

• 6 working examples demonstrating all features:
  1. Basic LLM rate limiting (throw strategy)
  2. Delay strategy (auto-wait behavior)
  3. Provider-specific limits
  4. Tool-specific limits
  5. Combined LLM + tool limits
  6. Monitoring and statistics
• Ready-to-run with Google Gemini API

fixes (issue) #5

Screenshots with running project with rate limiting

[changeset-bot]

⚠️ No Changeset found

Latest commit: 8de4af4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[sujal12344]

Hey @omeraplak @marinoska @necatiozmen , I’ve submitted a PR — #742
Could you please review it and share your feedback when you get a chance?

[omeraplak]

Hey @sujal12344 ,
Thank you! I'll review it soon

[omeraplak]

Hey @sujal12344 , thanks a lot for the PR! 🔥

I have a couple of questions:

1. Since we define rateLimits on the Agents and each agent has only one model, how does the providers field under rateLimits work?

rateLimits: {
  providers: {
    openai: {
      maxRequestsPerMinute: 5,
      onExceeded: "throw"
    },
    anthropic: {
      maxRequestsPerMinute: 3,
      onExceeded: "delay"
    }
  }
}

Is this meant for future support when dynamic providers are added?

2. When defining rate limits for tools, is there a way to add IntelliSense support? That way, tool names could be resolved dynamically.
3. It would be nice if the user could be notified via a hook when a rate limit is reached.
   Right now, onExceeded returns a decision, but maybe there could also be a hook with the same name?
4. What do you think about defining a global rate limit through the new VoltAgent() instance itself?