Skip to main content
Last updated on
Tags:
Options
Open in ChatGPTAsk ChatGPT about this pageOpen in ClaudeAsk Claude about this page

Temporal Integration Guide (Python)

This is the end-to-end guide for integrating OpenBox with a Temporal AI agent. You'll set up the demo repo, register your agent, run it with governance enabled, then walk through the integration architecture, available scenarios, human-in-the-loop approvals, and configuration options.

Skip ahead

Prerequisites​

  • Tools & dependencies — Python 3.11+, Node.js, uv, make, and the Temporal CLI

  • OpenBox Account — Sign up at platform.openbox.ai

  • LLM API Key — The demo uses LiteLLM for model routing. Set LLM_MODEL using the format provider/model-name:

    • openai/gpt-4o
    • anthropic/claude-sonnet-4-5-20250929
    • gemini/gemini-2.0-flash

    See LiteLLM Supported Providers for the full list.

Part 1: Clone and Set Up the Demo​

This guide uses the public demo repo:

git clone https://github.com/OpenBox-AI/poc-temporal-agent
cd poc-temporal-agent

Install Dependencies​

From the repo root:

make setup

Part 2: Register Your Agent in OpenBox​

  1. Log in to the OpenBox Dashboard
  2. Navigate to Agents → Click Add Agent
  3. Configure the agent:
    • Workflow Engine: Temporal
    • Agent Name: Temporal AI Agent
    • Agent ID: Auto-generated
    • Description (optional): Temporal AI agent demo
    • Teams (optional): assign the agent to one or more teams
    • Icon (optional): select an icon
  4. API Key Generation:
    • Click Generate API Key
    • Copy and store the key (shown only once)
  5. Configure platform settings:
  6. Click Add Agent

See Registering Agents for a field-by-field walkthrough of the form.

Part 3: Configure Environment​

  1. Copy .env.example to .env
  2. Open .env in your editor and set your LLM and OpenBox values:
# LLM — use the format provider/model-name
LLM_MODEL=openai/gpt-4o
LLM_KEY=your-llm-api-key

# Temporal
TEMPORAL_ADDRESS=localhost:7233

# OpenBox (use the API key from Part 2)
OPENBOX_URL=https://core.openbox.ai
OPENBOX_API_KEY=your-openbox-api-key
OPENBOX_GOVERNANCE_ENABLED=true
OPENBOX_GOVERNANCE_TIMEOUT=30.0
OPENBOX_GOVERNANCE_MAX_RETRIES=1
OPENBOX_GOVERNANCE_POLICY=fail_open

Part 4: Run the Demo​

Start the Temporal development server:

temporal server start-dev
tip

Check the startup output for the Temporal Web UI URL — you can use it to verify the server is running and monitor workflows.

In separate terminals, start each process:

make run-worker
make run-api
make run-frontend

You should see OpenBox SDK initialized successfully in the worker terminal.

Open the UI at http://localhost:5173:

  1. Send a message to the agent — the default scenario is a travel booking assistant
  2. Let it run through the workflow
  3. Once it completes, move on to See It in Action

See It in Action​

  1. Open the OpenBox Dashboard
  2. Navigate to Agents → Click your agent (the one you created in Part 2)
  3. On the Overview tab, find the session that corresponds to your workflow run
  4. Click Details to open it — you'll land on the Overview tab which shows the Event Log Timeline
  5. Scroll through the timeline — you'll see every event the trust layer captured: workflow start/complete, each activity with its inputs and outputs, the HTTP requests to your LLM, and the governance decision OpenBox made for each one
  6. Switch to the Tree View to see the same data as a hierarchy — workflows at the top, activities nested underneath, tool calls within those
  7. Click Watch Replay to open Session Replay — this plays back the entire session step-by-step, showing exactly what the agent did and how OpenBox evaluated it

What Just Happened?​

When you ran the demo, the OpenBox trust layer:

  1. Intercepted workflow and activity events — every workflow start, activity execution, and signal was captured and sent to OpenBox for governance evaluation
  2. Captured HTTP calls automatically — OpenTelemetry instrumentation recorded all outbound HTTP requests (LLM calls, external APIs) with full request/response bodies
  3. Evaluated governance policies — each captured event was evaluated against your agent's configured governance policies in real-time
  4. Recorded a governance decision for every event — approved, blocked, or flagged — giving you a complete audit trail
  5. Captured database operations and file I/O — the demo configures instrument_databases=True and instrument_file_io=True, so SQL queries, NoSQL operations, and file read/write operations were also recorded

How the Integration Works​

The OpenBox integration point is the worker bootstrap script: scripts/run_worker.py. The only change is replacing Worker with create_openbox_worker and adding the OpenBox configuration:

worker.py
import os
import asyncio
from temporalio.client import Client
from openbox import create_openbox_worker  # Changed import
from your_workflows import YourWorkflow
from your_activities import your_activity

async def main():
    client = await Client.connect("localhost:7233")

    # Replace Worker with create_openbox_worker
    worker = create_openbox_worker(
        client=client,
        task_queue="agent-task-queue",
        workflows=[YourWorkflow],
        activities=[your_activity],

        # Add OpenBox configuration
        openbox_url=os.getenv("OPENBOX_URL"),
        openbox_api_key=os.getenv("OPENBOX_API_KEY"),
    )

    await worker.run()

asyncio.run(main())

The agent's Temporal code is organized in:

  • workflows/ — Workflows define the high-level orchestration logic. In this demo, AgentGoalWorkflow is the main workflow that coordinates the agent's execution — it receives a goal, plans a sequence of steps, and executes them. OpenBox intercepts workflow started, completed, and failed events for governance evaluation.
  • activities/ — Activities are the individual units of work that a workflow executes — things like calling an LLM, querying a database, or making an API request. OpenBox captures each activity's inputs, outputs, and duration, and evaluates them against your governance policies.
  • tools/ — Tools are the capabilities available to the agent (e.g., search flights, check balances, process payments). Each tool is implemented as a Temporal activity, so OpenBox automatically captures and governs tool usage.
  • goals/ — Goals define the scenarios the agent can handle (e.g., travel booking, banking assistant). Each goal configures the system prompt, available tools, and expected behavior for a specific use case.

See Extending the Demo Agent for a step-by-step guide to adding your own goals and tools to this structure, or the Demo Architecture Reference for a full breakdown of signals, activities, endpoints, and message flow.

Explore Different Scenarios​

The demo ships with a default travel booking scenario, but you can switch to other domains by changing AGENT_GOAL in your .env file. For example, to try the finance banking assistant:

AGENT_GOAL=goal_fin_banking_assistant

After changing the goal, restart the worker (make run-worker) to pick up the new value.

Available Goals​

  • HR
    • goal_hr_check_pto — Check your available PTO
    • goal_hr_check_paycheck_bank_integration_status — Check employer/financial institution integration
    • goal_hr_schedule_pto — Schedule PTO based on your available balance
  • E-commerce
    • goal_ecomm_order_status — Check order status
    • goal_ecomm_list_orders — List all orders for a user
  • Finance
    • goal_fin_check_account_balances — Check balances across accounts
    • goal_fin_loan_application — Start a loan application
    • goal_fin_move_money — Initiate a money transfer
    • goal_fin_banking_assistant — Full-service banking (combines balances, transfers, and loans)
  • Travel
    • goal_event_flight_invoice — Book a trip to Australia or New Zealand around local events (default)
    • goal_match_train_invoice — Book a trip to a UK city around Premier League match dates
  • Food ordering
    • goal_food_ordering — Order food with Stripe payment processing
  • MCP Integrations
    • goal_mcp_stripe — Manage Stripe customer and product data
Add Your Own

These are the built-in scenarios. You can create your own goals with custom tools — see Extending the Demo Agent.

Human-in-the-Loop Approvals​

Some operations are too sensitive to run without a human sign-off — for example, initiating a money transfer, processing a payment, or modifying a customer's account. You can configure governance policies in OpenBox to require approval for these kinds of activities. See Authorize to set up guardrails, policies, and behavioral rules.

When governance requires approval:

  1. OpenBox creates an approval request
  2. Approval request appears in the OpenBox dashboard
  3. Human approves/rejects
  4. Temporal proceeds or fails based on the decision

While waiting for a human to approve or reject, the Temporal activity will retry. Set longer timeouts and more retries than usual to allow time for the decision:

result = await workflow.execute_activity(
    sensitive_operation,
    data,
    start_to_close_timeout=timedelta(minutes=10),
    retry_policy=RetryPolicy(
        initial_interval=timedelta(seconds=10),
        maximum_interval=timedelta(minutes=5),
        maximum_attempts=20,  # Allow time for approval
    ),
)

Configuration Options​

Governance Settings​

OptionDefaultDescription
governance_timeout30.0Max seconds to wait for governance evaluation
governance_policyfail_openfail_open = continue on API error, fail_closed = stop on API error

Event Filtering​

Skip governance for specific workflows or activities:

worker = create_openbox_worker(
    client=temporal_client,
    task_queue="my-task-queue",
    workflows=[AgentGoalWorkflow, UtilityWorkflow],
    activities=[...],

    # Skip these from governance
    skip_workflow_types={"UtilityWorkflow"},
    skip_activity_types={"internal_activity"},
    skip_signals={"heartbeat"},
)

Optional Instrumentation​

Enable additional telemetry capture:

worker = create_openbox_worker(
    client=temporal_client,
    task_queue="my-task-queue",
    workflows=[AgentGoalWorkflow],
    activities=[...],

    # Optional: Capture database operations
    instrument_databases=True,
    db_libraries={"psycopg2", "redis"},  # Or None for all

    # Optional: Capture file I/O
    instrument_file_io=True,
)

See SDK Configuration for the full list of options.

Error Handling​

In this demo, the SDK's role is to connect your Temporal worker to OpenBox and emit the events OpenBox needs to evaluate policies and record sessions. The recommended way to understand and respond to blocks, approvals, and validation failures is through the OpenBox dashboard UI.

To investigate failures, open a session in the dashboard using the same steps from See It in Action and look for governance decisions that were blocked or flagged, failed activity outputs, and approval requests that were rejected.

Next Steps​

  1. Extending the Demo Agent - Add your own goals, native tools, and MCP integrations
  2. SDK Configuration - Fine-tune timeouts, fail policies, and filtering
  3. Error Handling - Handle governance decisions in your code
  4. Set Up Approvals - Add human-in-the-loop for sensitive operations
  5. Demo Architecture Reference - Signals, activities, endpoints, and message flow

Having issues? See the Troubleshooting guide for common problems and solutions.