Python SDK: install, submit a Task, and validate results

Install dualeai, submit a Task, and validate its result. The package and import name are both dualeai.

Install the SDK

Use CPython 3.10–3.14 on Linux or macOS:

python -m pip install dualeai

Configure the first request

Ask your administrator for a provisioned Tenant, an Agent Identity API token, and an eligible model pool. The SDK creates none of these resources.

Set the token shown during provisioning:

export DUALEAI_TOKEN=dualeai_your_token_here

The SDK sends requests to https://api.beta.duale.ai by default. Set DUALEAI_ENDPOINT only when your access instructions name another environment.

Submit a typed Task request

Use synthetic, non-sensitive input: this example submits real work and can incur Platform and model-provider usage. Your agreement and the Privacy notice govern retention.

import asyncio

from pydantic import BaseModel

from dualeai 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=(
                "Synthetic support case: A customer asks to reset an account password, "
                "but identity verification has not been completed. Recommend the next "
                "safe step and explain why; do not change the account."
            ),
            res=SupportDecision,
            sdk=sdk,
        )
        print(response.task_id)
        decision = await response.model()
        print(decision.next_action)


asyncio.run(main())

Save the example as quickstart.py, then run it:

python quickstart.py

Verify the result

One possible successful run prints a Task identifier and the proposed next action:

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

The action text can vary. ask() returns an AgentResponse before Duale AI has necessarily accepted the request. Save response.task_id before waiting. You will need it to investigate the Task outcome if the connection fails.

await response.model() waits for the outcome and validates a completed result against SupportDecision. Your application must still decide whether the proposed step is right for the customer.

model() raises a typed exception for a stopped or failed Task, or ValidationError for a result that does not match the model. Troubleshoot the SDK shows what to do next, and SDK errors lists every exception and code.

Continue with How the SDK works for outcomes, routing, and continuations. Then choose the task you need:

• Show an answer while it is written: Stream an answer.
• Let Tasks call your Python functions: Authoring tools.
• Send files with a Task: Attach documents.
• Manage documents outside a Task: Manage a Library.
• Reuse the result of an expensive function: Activity caching.

SDK configuration covers environment variables, outbound network access, logging, and telemetry. The API reference covers every method. For application tests without Platform calls, start with MockSDK.