timestep 2026.0.48

Timestep AI - Durable agent execution framework with DBOS workflows, cross-language state persistence, and multi-model support for OpenAI Agents

Timestep (Python)

Python bindings for the Timestep Agents SDK. See the root README.md for the full story; this file highlights Python-specific setup.

Install

pip install timestep

Prerequisites (Python)

• OPENAI_API_KEY
• PostgreSQL: Set PG_CONNECTION_URI=postgresql://user:pass@host/db

Quick start

from timestep import run_agent, RunStateStore
from agents import Agent, Session

agent = Agent(model="gpt-4.1")
session = Session()
state_store = RunStateStore(agent=agent, session_id=await session._get_session_id())

result = await run_agent(agent, input_items, session, stream=False)

if result.interruptions:
    await state_store.save(result.to_state())

Cross-language resume

Save in Python, load in TypeScript with the same session_id and RunStateStore.load().

Model routing

Use MultiModelProvider if you need OpenAI + Ollama routing:

from timestep import MultiModelProvider, MultiModelProviderMap, OllamaModelProvider

provider_map = MultiModelProviderMap()
provider_map.add_provider("ollama", OllamaModelProvider())
model_provider = MultiModelProvider(provider_map=provider_map)

DBOS Workflows

Timestep supports durable agent execution via DBOS workflows. Run agents in workflows that automatically recover from crashes.

Durable Execution

from timestep import run_agent_workflow, configure_dbos, ensure_dbos_launched
from agents import Agent, OpenAIConversationsSession

configure_dbos()
ensure_dbos_launched()

agent = Agent(model="gpt-4.1")
session = OpenAIConversationsSession()

# Run in a durable workflow
result = await run_agent_workflow(
    agent=agent,
    input_items=input_items,
    session=session,
    stream=False,
    workflow_id="unique-id"
)

Queued Execution

from timestep import queue_agent_workflow

handle = await queue_agent_workflow(
    agent=agent,
    input_items=input_items,
    session=session,
    priority=1,
    deduplication_id="unique-id"
)

result = await handle.get_result()

Scheduled Execution

from timestep import create_scheduled_agent_workflow

await create_scheduled_agent_workflow(
    crontab="0 */6 * * *",  # Every 6 hours
    agent=agent,
    input_items=input_items,
    session=session
)

Package Structure

The Python package is organized into clear modules:

• core/: Core agent execution functions (run_agent, default_result_processor)
• core/agent_workflow.py: DBOS workflows for durable agent execution
• config/: Configuration utilities (dbos_config, app_dir)
• stores/: Data access layer
  • agent_store/: Agent configuration persistence
  • session_store/: Session data persistence
  • run_state_store/: Run state persistence
  • shared/: Shared database utilities (db_connection, schema)
  • guardrail_registry.py: Guardrail registration
  • tool_registry.py: Tool registration
• tools/: Agent tools (e.g., web_search)
• model_providers/: Model provider implementations (OllamaModelProvider, MultiModelProvider)
• models/: Model implementations (OllamaModel)

Documentation

Full docs: https://timestep-ai.github.io/timestep/