> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cominty.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Capping tool rounds

> Limit how many tool rounds an agent runs for one message with max_steps

An agent works in **tool rounds**. The model picks one or more tools (web
search, file write, and so on), the tools run, and the cycle repeats until the
agent can answer. Long tasks can chain many rounds, which costs time and money.
`max_steps` caps the number of rounds for **one message**.

Reaching the cap is **not an error**. The agent stops using tools, writes a
short recap, and asks whether it should continue. The message ends with
`status="success"`. You continue with a normal follow-up in the same thread.

For the HTTP contract, see
[Capping tool rounds](/api-reference#capping-tool-rounds) in the API reference.

## Quick start

```python theme={null}
from cominty_sdk import AsyncCominty

async with AsyncCominty(user_id="user_123") as client:
    run = await client.chat.start(
        agent_id="ag_abc123",
        message="Research X, then write it up.",
        max_steps=5,
    )
    print(await run.text())
```

## Arguments

`max_steps` is a keyword-only argument of both methods:

| Method | Signature |
| - | - |
| `client.chat.start(...)` | `max_steps: MaxSteps = SERVER_DEFAULT` |
| `client.chat.send(thread_id, ...)` | `max_steps: MaxSteps = SERVER_DEFAULT` |

`MaxSteps` is either an integer `>= 1` or the `SERVER_DEFAULT` sentinel. Import
them from `cominty_sdk`:

```python theme={null}
from cominty_sdk import SERVER_DEFAULT, MaxSteps
```

### Accepted values

| Value | Result |
| - | - |
| Not passed, or `SERVER_DEFAULT` | The field is left out of the request. The server applies its own default (60 today, and it may change). |
| Integer `>= 1` | Sent as `options.max_steps`. |
| `None`, `0`, a negative integer, a float, a bool, or a string | `InvalidParams` is raised before any request is sent. |

There is no "unlimited" value, and the API has no upper bound. Choose a
sensible maximum in your own application.

## Behavior to know

### The cap is per message, not per thread

A follow-up that does not pass `max_steps` runs with the server default,
whatever the first message used. Pass an integer on every call to keep a custom
cap.

```python theme={null}
run = await client.chat.start(
    agent_id=AGENT_ID,
    message="Research X, then write it up.",
    max_steps=5,
)
await run.text()

reply = await client.chat.send(
    run.thread.id,
    agent_id=AGENT_ID,
    message="Yes, continue.",
    max_steps=10,
)
print(await reply.text())
```

### Hitting the cap looks like a normal success

* The reply ends with `status="success"`.
* No field, event, or error code tells you the cap was reached.
* The recap is written by the model in the conversation language. Do not parse
  it.

### It is an order of magnitude, not an exact count

* The limit is checked after each round, so the agent can run up to
  `max_steps + 1` rounds.
* One round can contain several tool calls.
* Each sub-agent gets its own budget, so one message can exceed `max_steps`
  when sub-agents are involved.
* It limits rounds, not tokens, cost, or duration.

### The value is not readable afterwards

The value is neither stored nor returned for chats. Keep it on your side if you
need to display it.

## Errors

An invalid value raises `InvalidParams` before any request is sent:

```python theme={null}
from cominty_sdk import InvalidParams

try:
    await client.chat.start(agent_id=AGENT_ID, message="hi", max_steps=0)
except InvalidParams as exc:
    print(exc)
```

## Scope

* `max_steps` exists on `chat.start` and `chat.send` only.
* Routines also accept `max_steps` on the platform, but the SDK does not
  expose routines.
* Agents have no `max_steps` setting. Each message carries its own value.
* The default (60 today) is a server setting. Pass an integer if your
  integration depends on an exact value.

▶ [`examples/10_max_steps.py`](https://github.com/cominty/python-sdk/blob/main/examples/10_max_steps.py)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.