Python SDK for bounded agent work with typed results

Submit bounded agent work from Python and get a typed result back. Install the dualeai package, set one environment variable, and run a first task in a few lines.

Before you install the SDK

Meet these requirements before installation:

• Python 3.10 or newer.
• A DUALE_TOKEN for one agent in your tenant. The platform binds each token to a single agent, shows it once, at creation, and starts it with duale_.
• A centrally provisioned DUALE_AGENT_ID for hosted tools or task-scoped attachments. A first task that only calls ask() does not need one. Agents and access defines the agent and tenant boundaries.

Installation adds the Python package. It does not create or grant any platform resource.

Provision access

Every resource below is provisioned before your first task. The Python SDK creates none of them.

If one is missing, ask the workspace administrator or use pricing and access. A Library you create later is granted to your agent automatically; Library actions states who grants access to one you did not create. Libraries explains what an agent can read after it has that grant. For reusable documents, start with Manage a Library. Use task attachments when only one task needs the file.

Install

The package is published as dualeai; the import name is duale.

pip install dualeai

Authenticate

The SDK reads configuration from DUALE_ environment variables. Set your token:

export DUALE_TOKEN=duale_your_token_here

Requests go to https://api.duale.ai by default. Set DUALE_ENDPOINT to target another environment.

Submit your first task

Ask for work, request a typed result with a Pydantic model, and await the validated response:

import asyncio

from pydantic import BaseModel

from duale import ask, create_sdk


class SupportDecision(BaseModel):
    next_action: str
    reason: str


async def main() -> None:
    async with create_sdk() as sdk:
        response = await ask(
            action="Review this support case and return the next safe action.",
            res=SupportDecision,
            sdk=sdk,
        )
        decision = await response.model()
        print(response.task_id, decision.next_action)


asyncio.run(main())

ask() submits one task and returns an AgentResponse. await response.model() blocks until the task reaches a terminal state, then validates the result against SupportDecision. response.task_id is the durable identifier—store it to correlate everything your application later logs about this task.

Verify the typed result

A successful run prints the task identifier and the model’s chosen action:

0192f7c1-6e2a-7c31-9a4d-2b6f8c1d4e90 hold_for_review

The result matches SupportDecision because the runtime validated it against the schema you passed. If it cannot, model() raises ValidationError. If the platform ends the task with a failure, model() raises DualeError carrying the failure detail—see Errors and reliability.

You did not name a model. How the SDK works explains how the platform chose one, and how a routing policy changes that choice.