Temporal

If your agents run on Temporal, KeletPlugin propagates session context across start_workflow → workflow → child workflow → activity so traces and signals are linked end-to-end. Register on the client (Python: workers inherit automatically; TypeScript: also pass to Worker.create).

How it works

KeletPlugin registers Kelet’s client + worker interceptors via Temporal’s Plugin API. On start_workflow, the current agentic_session() is stamped into Temporal headers (x-kelet-session-id, x-kelet-user-id, x-kelet-metadata) using Temporal’s default PayloadConverter. The worker side reads them back, restoring session context (Python contextvars / TS AsyncLocalStorage) so kelet.signal() and auto-instrumentation resolve the session without arg-threading.

Kelet bundles Temporal’s own OpenTelemetryPlugin by default so OTel trace context links workflow + activity spans automatically — auto-skipped when you’ve already registered OTel yourself.

Install

Python

uv add "kelet[temporal]"
# or: pip install "kelet[temporal]"

TypeScript

npm install kelet @temporalio/plugin @temporalio/interceptors-opentelemetry

Register the plugin

Configure Kelet once at process start, then register KeletPlugin on the Temporal client.

• Python: Plugin registered on the client automatically applies to every Worker constructed from that client — you don’t need to pass it again.
• TypeScript: pass the plugin to both new Client(...) and Worker.create(...). The TypeScript SDK doesn’t auto-propagate plugins from client to worker.

Python

import kelet
from kelet.temporal import KeletPlugin
from temporalio.client import Client
from temporalio.worker import Worker

kelet.configure(api_key="...", project="my-agent")

client = await Client.connect("localhost:7233", plugins=[KeletPlugin()])
worker = Worker(client, task_queue="ai", workflows=[MyWorkflow], activities=[my_activity])

TypeScript

import { configure } from 'kelet';
import { KeletPlugin } from 'kelet/temporal';
import { Client } from '@temporalio/client';
import { Worker } from '@temporalio/worker';

configure({ apiKey: process.env.KELET_API_KEY!, project: 'my-agent' });

const plugin = new KeletPlugin({ otelPluginOptions: { resource, spanProcessor } });
const client = new Client({ /* ...connection... */, plugins: [plugin] });
const worker = await Worker.create({
  workflowsPath: require.resolve('./workflows'),
  activities,
  taskQueue: 'ai',
  plugins: [plugin],
});

Plugin propagation differs between SDKs

Python: Temporal’s Plugin API automatically applies to every Worker constructed from that client — registering on the client means workers don’t need their own plugins=[...] line.

TypeScript: the TS SDK doesn’t auto-propagate. You must register KeletPlugin on Worker.create explicitly (as shown above). The same plugin instance can be reused across Client and Worker.

Wrap workflow starts in agentic_session()

When you start a workflow, wrap the call in agentic_session() (or agenticSession() in TS). The session ID, user ID, and metadata propagate into the workflow run and every activity it schedules.

Python

async with kelet.agentic_session(session_id="conv-42", user_id="user-7"):
    await client.execute_workflow(MyWorkflow.run, ..., id="wf-1", task_queue="ai")

TypeScript

import { agenticSession } from 'kelet';

await agenticSession({ sessionId: 'conv-42', userId: 'user-7' }, async () => {
  await client.workflow.execute(MyWorkflow, {
    args: [...],
    workflowId: 'wf-1',
    taskQueue: 'ai',
  });
});

Verify

Run a workflow that calls an activity. In the Kelet console, the workflow span and every activity / child-workflow span should share one gen_ai.conversation.id. If kelet.signal() is called from inside an activity, it should attach to the same session.

KeletPlugin() options

Option (Python / TS)	Type	Default	Behavior
auto_session / autoSession	bool | Callable[[Info], str?]	False / false	Auto-derive a session when no agentic_session is set. True extracts the segment after /session/ in the workflow ID; otherwise pass a callable. Must be deterministic for workflow replay.
activityAutoSession (TS only)	bool | (Info) => string?	false	Activity-side fallback for workflows started outside the TS client (CLI, schedules, other-language clients). See the inline note below.
include_otel_plugin / includeOtelPlugin	bool / boolean	True / true	Bundle Temporal’s OpenTelemetryPlugin so workflow + activity OTel spans link into one trace. Auto-skipped if a prior plugin in the plugins=[...] list already registered an OTel interceptor.
otelPluginOptions (TS only, required when bundling)	OpenTelemetryPluginOptions	—	Forwarded verbatim to OpenTelemetryPlugin (resource + spanProcessor).

Python: kelet.configure() option that affects Temporal behavior:

Option	Type	Default	Behavior
signal_failure_mode	"swallow" | "raise"	"swallow"	When kelet.signal() is called from workflow code it dispatches through a Temporal activity (HTTP from workflows is non-deterministic). After Temporal exhausts retries, this controls failure behavior. "swallow" logs + drops; "raise" surfaces an ApplicationError to the workflow.

Why bundle OTel by default?

Without OTel trace propagation, Temporal-emitted spans (RunWorkflow:*, RunActivity:*) become orphans of the spans Kelet records. Bundling Temporal’s OpenTelemetryPlugin is the cheapest way to keep traces linked.

If you already register OpenTelemetryPlugin yourself, put it before KeletPlugin — Kelet detects it and skips its bundled OTel:

plugins=[OpenTelemetryPlugin(), KeletPlugin()]                          # ✅
plugins=[KeletPlugin(include_otel_plugin=False), OpenTelemetryPlugin()] # ✅ explicit

Determinism — workflow replay safety

The auto_session callable runs on the workflow side and is invoked during both initial execution and replay. If it returns different values for the same WorkflowInfo, Temporal will fail with a non-determinism error and your workflow will block. Keep it pure and side-effect free.

TypeScript: client-side vs activity-side derivation

In TypeScript, autoSession runs client-side at start_workflow time — so workflows started outside the TS client (Temporal CLI, schedules, other-language clients) won’t get a session header. Use activityAutoSession as a worker-side backstop in those cases. Python’s auto_session runs on the workflow inbound side, so it covers all start paths uniformly.

Propagated headers

Encoded via PayloadConverter.default, so any custom payload converter / encryption you already use Just Works.

Header	Source
x-kelet-session-id	agentic_session(session_id=...)
x-kelet-user-id	agentic_session(user_id=...)
x-kelet-metadata	agentic_session(**metadata_kwargs) (Py) / agenticSession({ metadata }) (TS)

Outbound calls that propagate the session from workflow code:

start_activity, start_local_activity, start_child_workflow, signal_child_workflow, signal_external_workflow, continue_as_new.

kelet.signal() and agentic_session() inside workflow code

kelet.signal() from workflow code

Workflow code can’t make HTTP calls directly (non-deterministic). When kelet.signal() is called from a workflow, the SDK transparently dispatches it through _kelet_signal — a Temporal activity registered automatically by KeletPlugin, retried up to 3 times. On final failure, behavior is controlled by kelet.configure(signal_failure_mode=...). Activities and orchestrator code call signal() directly with no dispatch.

agentic_session() inside workflow code

agentic_session() works in workflow code too. It detects the workflow sandbox and runs in lite mode: contextvars only, no OTel baggage attach, no background drain (both non-deterministic). Behavior outside workflows is unchanged.

Notes

• On worker shutdown, KeletPlugin flushes Kelet’s span processor with a 10-second timeout. If the Kelet API is slow or unreachable, shutdown proceeds anyway with a warning log — your worker won’t hang.
• The Python plugin requires temporalio>=1.7.0. The TypeScript plugin requires @temporalio/plugin (the Plugin API was added in @temporalio/* 1.17).

See also

• Python SDK reference — kelet.configure(), kelet.agentic_session(), kelet.signal()
• TypeScript SDK reference — same for TypeScript
• Temporal docs: Python observability, TypeScript observability