- Duale AI
- Documentation
- Python SDK
- SDK limits
Python SDK client limits: harness, streams, and caching
Lists Python SDK client limits for harness requests, stream idle timeouts, failure recovery, and activity caching, with actions for each.
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 gives the limits of attachments and Library calls,
and Tool limits gives the limits of the Tools that sdk.serve()
publishes.
Submit, continue, and stop a Task
Agent harness limits gives the limits of the instruction, the
task_id, the response-format description, and the request size. Plan around the
deadline gives the default deadline. The SDK checks these
limits before it sends a request:
ask()andnext()raisepydantic.ValidationErrorfor an instruction or atask_idoutside its limit, and send nothing. AJsonSchemaResponseFormatwith a description over its limit raises the same exception when you create it.- A request over the size limit reaches
model()asBusinessErrorwithREQUEST_BODY_TOO_LARGE, and no Task starts. stop()andstop_task()raiseValueErrorfor an empty reason or a reason with only spaces, andpydantic.ValidationErrorfor a reason over its limit. 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. |
- Limit
- Idle time on a Task stream
- Value
- Duale AI sends data at regular intervals, even while the Task writes no answer
- What happens
- A proxy that closes or buffers a quiet connection breaks the stream. The SDK reconnects, but repeated breaks make
model()raiseDualeAIConnectionErrorwhile the Task keeps running. - Your action
- 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.
- Limit
- Failures before the SDK blocks submissions
- Value
- 10 consecutive retryable failures of Tasks or of their streams;
failure_threshold, 1 to 100 - What happens
- New submissions in this process raise
RuntimeError. - Your action
- Find the cause of the failures, then wait for the recovery delay.
- Limit
- Recovery delay
- Value
- 30 seconds;
recovery_timeout_seconds, above 0 and at most 300 - What happens
- The SDK then allows one submission. If that Task completes, submissions resume. If it fails, the SDK blocks them for another delay.
- Your action
- Submit one Task to check that the cause is gone.
Set failure_threshold and recovery_timeout_seconds in a
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 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. |
- Limit
- Entry lifetime
- Value
- 1 hour, when you omit
cache_ttl - What happens
- The entry expires, and the next call runs the function again.
- Your action
- Pass
cache_ttlto@activity.
- Limit
- Lifetime variation
- Value
- Up to 10% earlier or later than the lifetime;
CacheConfig.ttl_jitter_factor, 0 to 0.5 - What happens
- An entry can expire early, or stay after its lifetime.
- Your action
- For exact lifetimes, set
ttl_jitter_enabled=False, as Choose the storage shows.
- Limit
- Attempts per call
- Value
- 1 plus
max_retries, which is 3 by default - What happens
- After the last attempt, the call raises the last exception.
- Your action
- Set
max_retries=0for an operation that is not safe to repeat.
- Limit
- Time per call
- Value
- 1,800 seconds, set by
job_timeout, for the wait, the run, and every retry - What happens
- The call raises the built-in
TimeoutError. The function can already have run, and the timeout does not undo what it changed. - Your action
- Pass a larger
job_timeouttoDualeAISDK, or make the function faster.
- Limit
- Activities that run at once
- Value
- 100;
max_concurrent_activities, 1 to 10,000 - What happens
- Further calls wait to run, and that wait counts against
job_timeout. - Your action
- Raise the limit in a
BackpressureConfig.
- Limit
- Activities that wait to run
- Value
- 500;
max_pending_activities, 1 to 50,000 - What happens
- Further calls wait, with no time limit, until a waiting place is free.
job_timeoutstarts after that. - Your action
- 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.