Skip to content
Submit, continue, and stop a Task
Public Preview

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() 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. They send nothing.

Watch a Task and recover from failures

LimitValueWhat happensYour action
Idle time on a Task streamDuale AI sends data at regular intervals, even while the Task writes no answerA 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 submissions10 consecutive retryable failures of Tasks or of their streams; failure_threshold, 1 to 100New submissions in this process raise RuntimeError.Find the cause of the failures, then wait for the recovery delay.
Recovery delay30 seconds; recovery_timeout_seconds, above 0 and at most 300The 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() raise DualeAIConnectionError while 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

LimitValueWhat happensYour action
Entry lifetime1 hour, when you omit cache_ttlThe entry expires, and the next call runs the function again.Pass cache_ttl to @activity.
Lifetime variationUp to 10% earlier or later than the lifetime; CacheConfig.ttl_jitter_factor, 0 to 0.5An entry can expire early, or stay after its lifetime.For exact lifetimes, set ttl_jitter_enabled=False, as Choose the storage shows.
Attempts per call1 plus max_retries, which is 3 by defaultAfter the last attempt, the call raises the last exception.Set max_retries=0 for an operation that is not safe to repeat.
Time per call1,800 seconds, set by job_timeout, for the wait, the run, and every retryThe 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 once100; max_concurrent_activities, 1 to 10,000Further calls wait to run, and that wait counts against job_timeout.Raise the limit in a BackpressureConfig.
Activities that wait to run500; max_pending_activities, 1 to 50,000Further 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_ttl to @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=0 for 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_timeout to DualeAISDK, 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_timeout starts 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.