Documentation / @agentick/kernel / KernelContext

Interface: KernelContext

Execution context that flows through all async operations via AsyncLocalStorage.

The KernelContext contains all state needed during execution:

Identity and tracing (requestId, traceId, user)
Event buses (events, executionHandle)
Cancellation (signal)
Communication (channels)
Execution tracking (procedureGraph, procedurePid, origin)
Extensible storage (metadata, metrics)

Access the current context with Context.get() from anywhere in your code - no need to pass it explicitly through function calls.

Examples

typescript

const ctx = Context.create({
  user: { id: 'user-1' },
  metadata: { conversationId: 'conv-123' }
});

await Context.run(ctx, async () => {
  // Context is available here and in all async calls
  const current = Context.get();
  console.log(current.user?.id); // 'user-1'
});

typescript

interface AppContext extends KernelContext {
  customHandle?: MyCustomHandle;
  appMetadata: AppSpecificMetadata;
}

See

Context - Static methods to create/access context
UserContext - User information structure

Properties

[KERNEL_CONTEXT_SYMBOL]?

optional [KERNEL_CONTEXT_SYMBOL]: boolean

Defined in: kernel/src/context.ts:298

Type brand for context detection

activeSpan?

optional activeSpan: Span

Defined in: kernel/src/context.ts:269

Active telemetry span for the currently-executing procedure.

Set by ExecutionTracker when forking the per-procedure context. Inside a procedure body (or any middleware/hook running within it), reading Context.get().activeSpan returns the span the engine started for that procedure — letting middleware enrich it with setAttribute, addEvent, etc., without needing a parallel ALS or a getActiveSpan() accessor.

Undefined outside of any procedure execution.

baggage?

optional baggage: Record<string, AttributeValue>

Defined in: kernel/src/context.ts:293

Ambient attributes auto-stamped onto every span started within this context's lifetime. Conceptually equivalent to OpenTelemetry baggage: key-value pairs that propagate through the execution context and end up on each span automatically, without callers needing to set them.

Set via Context.withBaggage(attrs, fn) (key-level merge with parent) or proc.withBaggage(attrs) (procedure variant). Telemetry.startSpan reads this field and applies the keys via setAttributes before returning the span.

Child contexts inherit baggage and can override individual keys without affecting the parent — last writer wins per key.

Example

typescript

await Context.withBaggage({ "app.location": "ernesto" }, async () => {
  // every span started here (and downstream) carries app.location=ernesto
  await runAgent();
});

channels?

optional channels: ChannelServiceInterface

Defined in: kernel/src/context.ts:194

Channel service for bidirectional communication (optional). Injected by Engine when channels are configured. Tools and components can access channels via this service.

events

events: EventEmitter

Defined in: kernel/src/context.ts:184

Global request event bus for subscribing to all events

executionHandle?

optional executionHandle: EventEmitter<any>

Defined in: kernel/src/context.ts:188

Operation-specific event emitter (from .withHandle())

executionId?

optional executionId: string

Defined in: kernel/src/context.ts:223

Current execution ID. Set when entering an execution boundary. All procedures within this execution share this ID.

executionType?

optional executionType: string

Defined in: kernel/src/context.ts:229

Type of execution at this boundary (e.g., 'engine', 'model', 'component_tool', 'fork', 'spawn'). Only meaningful at execution boundaries.

metadata

metadata: ContextMetadata

Defined in: kernel/src/context.ts:180

Application-specific metadata

metrics

metrics: ContextMetrics

Defined in: kernel/src/context.ts:182

Accumulated execution metrics

middleware?

optional middleware: object

Defined in: kernel/src/context.ts:254

Middleware registry for procedure execution. Procedures read this at execution time to get instance-level middleware. Typically set by createApp() from the Agentick instance.

getMiddlewareFor()

getMiddlewareFor(procedureName): Middleware[]

Parameters

procedureName

string

Returns

Middleware[]

origin?

optional origin: ProcedureNode

Defined in: kernel/src/context.ts:211

Origin procedure node - the root procedure that initiated this execution chain. Undefined for the root procedure itself (since it IS the origin). Set automatically by ExecutionTracker when procedures are executed.