Threads

A thread is the record of one run: one order, one refund, one agent session. It can span several services, and each of them can add steps to it. Keep a thread’s scope focused. “Refund approval” is a good thread; “everything that ever happens to a customer” isn’t. Use references and entity profiles to connect related threads.

Create or resume a thread

You identify a thread with a thread key: a string your application already uses for that run, such as order:ORD-123 or an agent session ID. The first call with a key creates the thread. Later calls with the same key, from any service or worker, return the same thread.

const thread = await connection.thread('order:ORD-123', {
  label: 'Order ORD-123',
  refs: { order_id: 'ORD-123', customer_id: 'CUST-001' },
  tags: ['web'],
});

thread, err := conn.Thread(ctx, "order:ORD-123", threadify.ThreadOptions{
    Label: "Order ORD-123",
    Refs:  map[string]string{"order_id": "ORD-123", "customer_id": "CUST-001"},
    Tags:  []string{"web"},
})
if err != nil {
    return err
}

thread = await connection.thread("order:ORD-123", {
    "label": "Order ORD-123",
    "refs": {"order_id": "ORD-123", "customer_id": "CUST-001"},
    "tags": ["web"],
})

The options only apply when the thread is created:

Option	Meaning
`label`	A human-readable name for the dashboard
`contract`	The contract to follow, as `name` or `name:version`
`refs`	References. Values must be strings.
`tags`	Labels for filtering. They can’t be changed later.
`serviceName`	Overrides the connection’s service name for this thread
`role`	Your contract role on this thread

In Python use service_name. In Go use the threadify.ThreadOptions fields of the same names. When you resume a thread, Threadify ignores the label, refs and tags you pass and keeps the stored ones. To add references later, use addRefs().

Thread key rules

A key identifies one thread within your Engine.
Keys are trimmed and must be non-empty, up to 1024 bytes (UTF-8).
Two services calling thread() with the same new key at the same moment get the same thread.
Once a thread is completed or cancelled it can’t be reopened or receive more steps. Use a new key for the next run, such as order:ORD-123:retry-1.

Threadify gives each thread its own internal ID too (thread.id). You only need it for the GraphQL API and for joining by ID.

Contracted sessions

If a thread should follow a contract, pass contract the first time you call thread(). After that, any service can resume it with just the key and the contract comes with it:

// When the session starts
await connection.thread(sessionId, { contract: 'agent_session:3', label: 'Agent session' });

// In any later request or worker
const thread = await connection.thread(sessionId);
await thread.step('tool_call').idempotencyKey(toolCallId).success();

// When the session starts
if _, err := conn.Thread(ctx, sessionID, threadify.ThreadOptions{Contract: "agent_session:3", Label: "Agent session"}); err != nil {
    return err
}

// In any later request or worker
thread, err := conn.Thread(ctx, sessionID)
if err != nil {
    return err
}
_, err = thread.Step("tool_call").IdempotencyKey(toolCallID).Success(ctx)

# When the session starts
await connection.thread(session_id, {"contract": "agent_session:3", "label": "Agent session"})

# In any later request or worker
thread = await connection.thread(session_id)
await thread.step("tool_call").idempotency_key(tool_call_id).success()

Set the contract when the thread is created. You can’t add a contract to a thread that was created without one, and passing a different contract when resuming is rejected.

Finishing a thread

A thread with a contract completes by itself when its terminal step passes validation. A thread without one stays active until you complete or cancel it.

Get started

Concepts

Contracts

SDKs

Integrations

Operate

GraphQL API

Create or resume a thread

Thread key rules

Contracted sessions

Finishing a thread