Agent SDK · Start here

Configuration.

Configure the shared default client, or isolate a Runner with its own client and auth.

`configure_default_client(client)`

Installs the shared default MatildaClient used by the module-level convenience functions (run, stream, stream_text, run_text, run_object, stream_object) and their shared default Runner. Returns nothing.

Python

import os

from matilda_agent_sdk import MatildaClient, configure_default_client

configure_default_client(
    MatildaClient(
        base_url="https://matilda.maincode.com/api",
        token=os.environ["MATILDA_ACCESS_TOKEN"],
    )
)

The client derives its base URL, static token, and async get_token provider from MatildaConfig — see the client SDK docs for the full field list.

`MatildaClient`

The underlying API client, re-exported from matilda-client. Each Runner can hold its own MatildaClient instance for isolation, or share the module-level default.

Python

import os

from matilda_agent_sdk import MatildaClient, Runner

client = MatildaClient(
    base_url="https://matilda.maincode.com/api",
    token=os.environ["MATILDA_ACCESS_TOKEN"],
)

runner = Runner(client)

`Runner`

The main agent execution class. Optionally accepts an explicit MatildaClient for isolation.

Python

from matilda_agent_sdk import MatildaClient, Runner

# Uses the shared default client (materialised lazily, or installed
# via configure_default_client)
default_runner = Runner()

# Uses an isolated client — independent config, auth, and token lifecycle
isolated_runner = Runner(MatildaClient(base_url="https://matilda.maincode.com/api"))

Field	type	description
client	MatildaClient \| None	Optional explicit client. If omitted, the shared default is used (created on first use if none was configured).

Environment URLs

Environment	Base URL
Production	`https://matilda.maincode.com/api`

Instance isolation

Each Runner holds its own MatildaClient (either explicit or the shared default). The auth, files, conversations, and feedback resources resolve their client lazily, so a client installed via configure_default_client() is picked up correctly.

Python

from matilda_agent_sdk import MatildaClient, Runner

runner_a = Runner(MatildaClient(base_url="https://matilda.maincode.com/api"))
runner_b = Runner(MatildaClient(base_url="https://matilda.maincode.com/api"))

# Each runner is fully isolated — independent auth, config, and token lifecycle
await runner_a.auth.login_with_device_flow(client_id="matilda-code")
await runner_b.auth.login_with_browser(client_id="matilda-code")

Other configuration utilities

Export	Description
`MatildaConfig`	Client configuration dataclass (re-exported from `matilda-client`).
`MATILDA_API_VERSION_HEADER` / `MATILDA_CURRENT_API_VERSION`	API version constants, importable from `matilda_client`.