zeitlich开源AI工作流

Requirements

• Node.js >= 18
• Temporal server
• Redis

Installation

npm install zeitlich ioredis \
  @temporalio/workflow @temporalio/common

Peer dependencies:

• @temporalio/workflow >=1.16.0 <2.0.0 (required)
• @temporalio/common >=1.16.0 <2.0.0 (required)
• @temporalio/worker >=1.16.0 <2.0.0 (optional — only when running a worker)
• @temporalio/envconfig >=1.16.0 <2.0.0 (optional — only when using envconfig)
• ioredis >= 5.0.0
• @langchain/core >= 1.0.0 (optional — only when using the LangChain adapter)
• @google/genai >= 1.0.0 (optional — only when using the Google GenAI adapter)
• @aws-sdk/client-bedrock-agentcore >= 3.900.0 (optional — only when using the Bedrock adapter)
• @aws-sdk/client-s3 >= 3.700.0 (optional — only when using the built-in S3 cold thread tier)

Why peer deps? Zeitlich's public API surfaces @temporalio/* types (UpdateDefinition, ChildWorkflowOptions, Duration, etc.) directly. Peer deps guarantee a single resolved copy of each @temporalio/* package in the consumer's tree, eliminating brand-symbol skew between zeitlich's types and the consumer's own.

Required infrastructure:

• Temporal server (local dev: temporal server start-dev)
• Redis instance

Example: LangChain Adapter

import { ChatAnthropic } from "@langchain/anthropic";
import { createLangChainAdapter } from "zeitlich/adapters/thread/langchain";
import { createRunAgentActivity } from "zeitlich";

const adapter = createLangChainAdapter({
  redis,
  model: new ChatAnthropic({ model: "claude-sonnet-4-20250514" }),
});

export function createActivities(client: WorkflowClient) {
  return {
    ...adapter.createActivities("myAgentWorkflow"),
    ...createRunAgentActivity(client, adapter.invoker, "myAgentWorkflow"),
  };
}

All adapters follow the same pattern — createActivities(scope) for worker registration and invoker for model calls.

Examples

Runnable examples (worker, client, workflows) are in a separate repo: zeitlich-examples.

Quick Start

API Reference

LLM Integration

Zeitlich's core is framework-agnostic — it defines generic interfaces (ModelInvoker, ThreadOps, MessageContent) that work with any LLM SDK. You choose a thread adapter (for conversation storage and model invocation) and a sandbox adapter (for filesystem operations), then wire them together.

2. Create the Workflow

The workflow wires together a thread adapter (for conversation storage / model calls) and a sandbox adapter (for filesystem tools). Both are pluggable — swap the proxy import to switch providers.

import { proxyActivities, workflowInfo } from "@temporalio/workflow";
import {
  createAgentStateManager,
  createSession,
  defineWorkflow,
  proxyRunAgent,
  askUserQuestionTool,
  bashTool,
  defineTool,
} from "zeitlich/workflow";
import { searchTool } from "./tools";
import type { MyActivities } from "./activities";
import type { StoredMessage } from "@langchain/core/messages";

import { proxyLangChainThreadOps } from "zeitlich/adapters/thread/langchain/workflow";
import { proxyInMemorySandboxOps } from "zeitlich/adapters/sandbox/inmemory/workflow";

const runAgentActivity = proxyRunAgent<StoredMessage>();

const {
  searchHandlerActivity,
  bashHandlerActivity,
  askUserQuestionHandlerActivity,
} = proxyActivities<MyActivities>({
  startToCloseTimeout: "30m",
  retry: {
    maximumAttempts: 6,
    initialInterval: "5s",
    maximumInterval: "15m",
    backoffCoefficient: 4,
  },
});

export const myAgentWorkflow = defineWorkflow(
  { name: "myAgentWorkflow" },
  async ({ prompt }: { prompt: string }, sessionInput) => {
    const { runId } = workflowInfo();

    const stateManager = createAgentStateManager({
      initialState: {
        systemPrompt: "You are a helpful assistant.",
      },
      agentName: "my-agent",
    });

    const session = await createSession({
      agentName: "my-agent",
      maxTurns: 20,
      thread: { mode: "new", threadId: runId },
      threadOps: proxyLangChainThreadOps(),
      sandboxOps: proxyInMemorySandboxOps(),
      runAgent: runAgentActivity,
      buildContextMessage: () => [{ type: "text", text: prompt }],
      tools: {
        Search: defineTool({
          ...searchTool,
          handler: searchHandlerActivity,
        }),
        AskUserQuestion: defineTool({
          ...askUserQuestionTool,
          handler: askUserQuestionHandlerActivity,
          hooks: {
            onPostToolUse: () => {
              stateManager.waitForInput();
            },
          },
        }),
        Bash: defineTool({
          ...bashTool,
          handler: bashHandlerActivity,
        }),
      },
      ...sessionInput,
    });

    const result = await session.runSession({ stateManager });
    return result;
  }
);

Workflow Entry Point (`zeitlich/workflow`)

Safe for use in Temporal workflow files: