---
title: "Python SDK client limits: harness, streams, and caching"
description: "Lists Python SDK client limits for harness requests, stream idle timeouts, failure recovery, and activity caching, with actions for each."
lang: en
status: public-preview
lastUpdated: 2026-11-11
url: https://duale.ai/en/docs/sdk/limits
---

## AI-generated summary

This page covers Python SDK limits for submitting and stopping Tasks, watching Task streams with failure recovery, and caching activity results.

- Task submission, continuation, and stop limits.
- Task stream idle time and failure recovery.
- Activity cache lifetime, retries, and concurrency limits.

Summaries were generated by AI.

---

Plan your application around these limits of the Python SDK client: each row states what happens when you reach one
and what to do next. [Library limits](https://duale.ai/en/docs/libraries/limits.md) gives the limits of attachments and Library calls,
and [Tool limits](https://duale.ai/en/docs/tools/limits.md#declare-and-serve-sdk-tools) gives the limits of the Tools that `sdk.serve()`
publishes.

## Submit, continue, and stop a Task

[Agent harness limits](https://duale.ai/en/docs/agent-harness/limits.md#submit-a-task) gives the limits of the instruction, the
`task_id`, the response-format description, and the request size. [Plan around the
deadline](https://duale.ai/en/docs/agent-harness/limits.md#plan-around-the-deadline) gives the default deadline. The SDK checks these
limits before it sends a request:

- `ask()` and `next()` raise `pydantic.ValidationError` for an instruction or a `task_id` outside its limit, and send
  nothing. A `JsonSchemaResponseFormat` with a description over its limit raises the same exception when you create it.
- A request over the size limit reaches `model()` as `BusinessError` with `REQUEST_BODY_TOO_LARGE`, and no Task starts.
- `stop()` and `stop_task()` raise `ValueError` for an empty reason or a reason with only spaces, and
  `pydantic.ValidationError` for a reason over its [limit](https://duale.ai/en/docs/agent-harness/limits.md#stop-a-task). They send
  nothing.

## Watch a Task and recover from failures

| Limit                                      | Value                                                                                         | What happens                                                                                                                                                                             | Your action                                                                                                                                         |
| ------------------------------------------ | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Idle time on a Task stream                 | Duale AI sends data at regular intervals, even while the Task writes no answer                | A proxy that closes or buffers a quiet connection breaks the stream. The SDK reconnects, but repeated breaks make `model()` raise `DualeAIConnectionError` while the Task keeps running. | Set the idle timeout of your egress proxy to at least one minute, let one connection stay open for the whole Task, and turn off response buffering. |
| Failures before the SDK blocks submissions | 10 consecutive retryable failures of Tasks or of their streams; `failure_threshold`, 1 to 100 | New submissions in this process raise `RuntimeError`.                                                                                                                                    | Find the cause of the failures, then wait for the recovery delay.                                                                                   |
| Recovery delay                             | 30 seconds; `recovery_timeout_seconds`, above 0 and at most 300                               | The SDK then allows one submission. If that Task completes, submissions resume. If it fails, the SDK blocks them for another delay.                                                      | Submit one Task to check that the cause is gone.                                                                                                    |

Set `failure_threshold` and `recovery_timeout_seconds` in a
[BackpressureConfig](https://duale.ai/en/docs/sdk/reference.md#backpressureconfig). A value outside its range raises
`pydantic.ValidationError`.

## Cache activity results

| Limit                       | Value                                                                                   | What happens                                                                                                                   | Your action                                                                                                                            |
| --------------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Entry lifetime              | 1 hour, when you omit `cache_ttl`                                                       | The entry expires, and the next call runs the function again.                                                                  | Pass `cache_ttl` to `@activity`.                                                                                                       |
| Lifetime variation          | Up to 10% earlier or later than the lifetime; `CacheConfig.ttl_jitter_factor`, 0 to 0.5 | An entry can expire early, or stay after its lifetime.                                                                         | For exact lifetimes, set `ttl_jitter_enabled=False`, as [Choose the storage](https://duale.ai/en/docs/sdk/activity-caching.md#choose-the-storage) shows. |
| Attempts per call           | 1 plus `max_retries`, which is 3 by default                                             | After the last attempt, the call raises the last exception.                                                                    | Set `max_retries=0` for an operation that is not safe to repeat.                                                                       |
| Time per call               | 1,800 seconds, set by `job_timeout`, for the wait, the run, and every retry             | The call raises the built-in `TimeoutError`. The function can already have run, and the timeout does not undo what it changed. | Pass a larger `job_timeout` to `DualeAISDK`, or make the function faster.                                                              |
| Activities that run at once | 100; `max_concurrent_activities`, 1 to 10,000                                           | Further calls wait to run, and that wait counts against `job_timeout`.                                                         | Raise the limit in a `BackpressureConfig`.                                                                                             |
| Activities that wait to run | 500; `max_pending_activities`, 1 to 50,000                                              | Further calls wait, with no time limit, until a waiting place is free. `job_timeout` starts after that.                        | Raise the limit in a `BackpressureConfig`.                                                                                             |

Without a `BackpressureConfig`, `max_jobs` activities run at once, and five times as many wait. A value outside these
ranges, including a `max_jobs` above 10,000, raises `pydantic.ValidationError`.

## Related content

- [Tool limits for SDK Tools, MCP Connections, and Tool Calls](https://duale.ai/en/docs/tools/limits.md)
- [Python SDK reference: ask, AgentResponse, and task controls](https://duale.ai/en/docs/sdk/reference.md)
- [Troubleshoot the SDK: symptoms and fixes](https://duale.ai/en/docs/sdk/troubleshooting.md)
- [SDK Task lifecycle: requests, outcomes, and continuations](https://duale.ai/en/docs/sdk/concepts.md)
- [SDK errors: exceptions, problem details, and error codes](https://duale.ai/en/docs/sdk/errors.md)
- [Publish and operate an SDK Tool Host](https://duale.ai/en/docs/sdk/tools.md)

---

## Sitemap

See the full [Markdown sitemap](https://duale.ai/sitemap.md) for all pages.
