Skip to main content

Temporal Integration

AgentVisor™ uses Temporal for durable execution, ensuring agents survive crashes and enabling human-in-the-loop patterns.

Configuration Guide

For step-by-step configuration instructions, see the Temporal Configuration Guide. This page focuses on concepts and architecture.

Overview​

Temporal provides:

  • Durability: Workflow state survives process crashes
  • Reliability: Automatic retries and failure handling
  • Visibility: Workflow history and state inspection
  • Signals: Async communication with running workflows

How AgentVisor Uses Temporal​

Threads as Workflows​

Each conversation thread is backed by a long-lived Temporal workflow. Creating a thread starts the workflow; deleting a thread cancels it (not terminates — cancellation lets the workflow observe the request and wind down cooperatively, including waiting for an in-flight activity's cancellation handling, rather than being killed outright). Run creation, checkpoint saves, and state queries are all routed through the workflow via Temporal's update and query primitives, so they are durable and ordered.

Runs as Activities​

Each agent run is a Temporal activity. The host runtime starts the activity in response to a run-create update; the activity invokes the agent inside the guest sandbox; the result is recorded back in workflow state. Activities are the right Temporal primitive here because they isolate non-deterministic, side-effecting work (the actual agent invocation) from the deterministic workflow.

Workflow Lifecycle​

Checkpointing​

Agent state is stored in the workflow. Saves route through Temporal workflow updates, so checkpoints are durably persisted in the workflow's event history before the save call returns.

For the user-facing API, see Checkpointing → AgentVisorCheckpointer.

Interrupt/Resume​

LangGraph's interrupt() API integrates with Temporal. When the graph raises GraphInterrupt:

  1. AgentVisor returns status: interrupted to the API caller
  2. Workflow state is checkpointed durably
  3. The workflow waits for the next run

When the caller resumes:

  1. A new run is created on the same thread
  2. The graph resumes from the latest checkpoint
  3. Command(resume=input) provides the user response back to the graph

For the user-facing API and a sequence diagram, see Checkpointing → Interrupt/Resume Pattern.

Continue-As-New​

Long-running threads can accumulate large workflow histories. AgentVisor uses Temporal's Continue-As-New mechanism to manage this:

  1. After each run, workflow checks history size
  2. If threshold reached, workflow continues-as-new
  3. State is pruned to configured limits
  4. Thread ID remains the same

This happens transparently—the thread ID remains stable for API clients while workflow history stays bounded.

For configuration of history limits, see the Temporal Configuration Guide.

Search Attributes​

Threads use Temporal search attributes for discovery:

AttributeTypeDescription
MavSystemMetadataKeywordListInternal: Principal, GraphName, Ephemeral
MavMetadataKeywordListUser-defined key:value pairs
MavThreadStatusKeywordidle, busy, interrupted, error

These enable efficient thread filtering and discovery via the API.

For setup instructions, see the Temporal Configuration Guide.

Payload Encryption​

AgentVisor supports encrypting Temporal workflow payloads at rest using AES-256-GCM encryption. This protects sensitive data (agent inputs, outputs, checkpoints) stored in Temporal.

When encryption is enabled:

  • All payloads are encrypted before storage in Temporal
  • The Temporal server stores only ciphertext
  • A codec server can be enabled for decrypting payloads in the Temporal Web UI

For encryption algorithm details, see Payload Encryption. For configuration instructions, see the Temporal Configuration Guide.

Observability​

Workflow History​

View workflow history in the Temporal UI or via CLI:

temporal workflow show -w thread-12345

Metrics​

Temporal exposes Prometheus metrics:

# Workflow execution latency
temporal_workflow_execute_latency_bucket

# Activity execution count
temporal_activity_execution_total

Best Practices​

  1. Keep activities short: Long activities should heartbeat
  2. Use deterministic workflows: No random, time, or external calls in workflow code
  3. Handle failures: Configure retry policies for activities
  4. Monitor history size: Use Continue-As-New for long-running threads
  5. Use search attributes: Enable efficient thread discovery
  6. Enable encryption: Use payload codec for sensitive data at rest

See Also​