SDK Quickstart

Connect to a workspace and run your first turn with the DotCraft SDK. This tutorial covers all three SDKs — TypeScript, .NET, and Python — and takes you from install to a streamed reply. Pick your language in each tab.

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 — pass the workspace path. Use remote instead to connect to a known AppServer WebSocket URL (ws://host:port/...) when the workspace runs elsewhere.

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.