SDK Quickstart

DotCraft ships SDKs for TypeScript, .NET, and Python.

Install

TypeScript

npm install @dotcraft/sdk

.NET

dotnet add package DotCraft.Sdk

Python

pip install dotcraft

1. Connect

local discovers or starts the local Hub and ensures an AppServer for your workspace. Use remote to connect to a known AppServer WebSocket instead.

TypeScript

import { DotCraft } from "@dotcraft/sdk";

const dotcraft = await DotCraft.local({ workspacePath: "/path/to/workspace" });

.NET

using DotCraft.Sdk.AppServer;

await using var client = await DotCraftClient.ConnectLocalAsync(
    "/path/to/workspace",
    new DotCraftLocalClientOptions { ClientName = "my-app", ClientVersion = "0.1.0" });

Python

from dotcraft import DotCraft, LocalOptions

dotcraft = await DotCraft.connect_local(LocalOptions(workspace_path="/path/to/workspace"))

2. Start a thread

A thread is a persistent conversation. Start a fresh one, or reuse an existing one for an identity with getOrCreate / get_or_create.

TypeScript

const thread = await dotcraft.threads.start({ userId: "me" });

.NET

var thread = await client.Threads.StartAsync(
    new DotCraftThreadStartRequest(new SessionIdentity("my-app", Environment.UserName)));

Python

thread = await dotcraft.threads.start(user_id="me")

3. Run a turn

run submits input and waits for the turn to finish, returning the merged assistant reply.

TypeScript

const result = await thread.run("Summarize this project.");
console.log(result.text);

.NET

var result = await thread.RunAsync("Summarize this project.");
Console.WriteLine(result.Text);

Python

result = await thread.run("Summarize this project.")
print(result.text)

4. Stream events

runStreamed yields normalized events as they arrive — text deltas, item lifecycle, and the terminal turn.

TypeScript

for await (const event of thread.runStreamed("And list the open questions.")) {
  if (event.type === "agent_message_delta") {
    process.stdout.write(event.delta ?? "");
  }
}

.NET

await foreach (var runEvent in thread.RunStreamedAsync("And list the open questions."))
{
    if (runEvent.Type == DotCraftRunEventTypes.AgentMessageDelta)
    {
        Console.Write(runEvent.Params.GetProperty("delta").GetString());
    }
}

Python

async for event in thread.run_streamed("And list the open questions."):
    if event.type == "agent_message_delta":
        print(event.params["delta"], end="", flush=True)

Next steps

• Threads & runs — thread lifecycle, run options, and the normalized event model.
• Tools & approvals — runtime dynamic tools and approval / user-input callbacks.
• Channel adapters — build external channels (TypeScript and Python).
• Reference cards: TypeScript · .NET · Python.