Agent Limits

Limits cap how much one background agent can do in a period of time. They protect against an agent that gets triggered far more than expected, for example a busy Slack channel or a webhook stuck in a retry loop, and against an agent that calls an expensive or sensitive tool too often.

Each agent has its own limits, separate from the organization's rate-limit policies:

Limit	Counts	Set it in
New sessions	Conversations the agent starts.	The agent's Settings tab, Limits section.
Messages	Every message the agent receives, including the one that starts a session.	The agent's Settings tab, Limits section.
Tool rate limit	Calls the agent makes to one tool.	The menu on the tool's row in the Tools tab.

Every limit is a number per minute, hour, or day.

Limit sessions and messages

1. Open the agent and select the Settings tab.
2. Open the Limits section.
3. Turn on New sessions, Messages, or both, and set Allow N per minute, hour, or day.
4. Select Save.

A session starts with the first message for a new session key: a new Slack thread, a new webhook or API conversation, or a new test in the Test Agent panel. Every later message in that conversation counts as a message, not a session.

Both limits count everything that reaches the agent: Slack messages and workflow steps, API and webhook triggers, scheduled triggers, the invoke API, and the Test Agent panel. Follow-ups you send from the Sessions tab don't count.

Limit a tool

1. Open the agent and select the Tools tab.
2. On the tool's row, open the menu (the three dots) and select Add rate limit.
3. Set Allow N calls per minute, hour, or day, and select Save.

The row then shows the limit as a badge, for example 20/hour. Select the badge, or Edit rate limit in the menu, to change it. Remove rate limit takes it off.

A tool limit counts every call this agent makes to the tool, whoever triggered the run. It is checked together with the organization's rate-limit policies, and a call has to pass both.

See how much is used

The agent's Overview tab has a Limits card listing every limit the agent has, with how much of it the current period has used, for example 3 / 20 per hour. A limit that has been reached turns red. Hover a row to see the exact count and when the period resets. Manage opens the Limits section of the Settings tab.

When a limit is reached

The count starts with the first message (or call) and resets when the period ends. Once the count goes past the limit, Willow stops until then:

What was blocked	What happens
A Slack message	The agent's bot replies in the thread with the reason, when to try again, and who can raise the limit.
An API, webhook, or invoke call	The call fails with status 429 and a Retry-After header holding the seconds to wait.
A test in the Test Agent panel	The panel shows the same message.
A scheduled trigger	The run is skipped. The trigger fires again at its next scheduled time.
A tool call	The call fails, and the agent is told the limit and when to try again. The call shows in the logs as rate limited.

The message for a session or message limit reads like this:

This agent has reached its limit of 20 new sessions per hour. Try again in 12 minutes, or ask the agent's owner (Dana Levi) or a Willow admin to raise the limit.

A blocked message is not queued. Send it again once the period ends.

Get past a limit

Way	Who can do it
Wait until the period ends. The message says how long.	Anyone.
Raise or remove the limit. A higher limit applies right away to the current period. Changing the period starts a new count.	The agent's owners, and admins who can edit background agents.

Related

• Rate Limits: per-user caps on tool calls across the organization
• Assign Tools to an Agent
• Background Agents reference