Capping tool rounds - Cominty Docs

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 in the API reference.

Quick start

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:

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.

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:

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

​Quick start

​Arguments

​Accepted values

​Behavior to know

​The cap is per message, not per thread

​Hitting the cap looks like a normal success

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

​The value is not readable afterwards

​Errors

​Scope