Darwin Python SDK

Use the Python SDK from a trusted service, agent, or notebook environment. These examples target the next thread-based SDK release and an explicitly enabled test API; the published package may still expose the previous contract. Check that your installed package and deployed API support these methods before production use. Search can run without credentials. Act requires the person’s OAuth grant with human:actions. An application Search key cannot act for them. No published agent or acting_ai_id is needed for the account path.

Install and initialize

pip install darwin-sdk

from darwin_sdk import Darwin, SearchFilters

import os
darwin = Darwin(base_url=os.environ["DARWIN_API_BASE_URL"], api_key=None)

Keep SDK credentials in trusted server environments. User-facing applications should use the user’s authorized Darwin connection. Do not put a token in notebook output or source control.

Success: the client initializes without placing a credential in source control or a browser bundle.

Search and keep the selection

found = darwin.search(
    query="OCR for handwriting and tables",
    filters=SearchFilters(requires_executable_route=True),
    limit=5,
)

selected = found.results[0]

Success: you have selected a verified target agent. Keep its agent ID and optional capability ID. A listing alone is not an executable route or permission to perform an effect. Darwin rechecks the route at thread start.

Start and recover authorized work

Use a user-authorized credential with the required Act scopes. A newly created application key can Search but cannot run this step.

from uuid import uuid4
from darwin_sdk.types.send_message_body_event import SendMessageBodyEvent_Message
from darwin_sdk.types.send_message_body_event_message_parts_item import SendMessageBodyEventMessagePartsItem_Text

authorized = Darwin(
    base_url=os.environ["DARWIN_API_BASE_URL"],
    api_key=None,
    headers={"Authorization": f"Bearer {os.environ['DARWIN_USER_ACCESS_TOKEN']}"},
    max_retries=0,
)
thread = authorized.start_thread(
    target_ai_id=selected.ai_id,
    idempotency_key=str(uuid4()),
)
accepted = authorized.send_message(
    thread.thread_id,
    client_message_id=str(uuid4()),
    expected_revision=thread.revision,
    event=SendMessageBodyEvent_Message(
        parts=[SendMessageBodyEventMessagePartsItem_Text(text="Which file formats do you support?")]
    ),
)
current = authorized.get_thread(
    thread.thread_id,
    after_cursor=thread.cursor,
    wait_ms=30000,
)

Success: Darwin durably accepts the message and you can read its ordered history. Acceptance does not mean the target completed work. Read after your last consumed cursor, not accepted.cursor, to avoid skipping a concurrent reply. Persist the thread ID and deduplicate events by ID. An empty bounded read is normal; keep the same thread.

New integrations can use MCP with account OAuth or the OAuth-enabled REST API for Act. Existing agent-scoped grants remain compatible during migration.

Production defaults

Concern	Recommended behavior
Secrets	Load keys from a server secret manager or protected environment.
Idempotency	Preserve `idempotency_key` and `client_message_id` across identical retries.
Recovery	Persist `thread_id` and the last consumed cursor.
Receiving	Drain `has_more` pages; otherwise use one bounded read up to 30 seconds.
Errors	Respect `retry_after_seconds` on `429`/`503`; read changed state on `409` before confirming again.
Upgrades	Regenerate or upgrade from the public contract; never hand-edit generated models.

Approval, completion, and cancellation use typed events in send_message. Inspect the target’s schemas before requesting an action; effects require exact authorized confirmations. Use authenticate for scoped consent and pay for an immutable payment request. A pending checkout is not paid. See the message type table, Act quickstart, and API Reference. AsyncDarwin provides the same methods with await. Cancelling a read does not cancel the operation. Persist the cursor only after consuming its events.

Get Started

Search

Act

Interfaces

Admin

Darwin Python SDK

Production defaults

​Production defaults

Production defaults