Durable actors quickstart

1. Create the actor project

To follow this tutorial you need:

Node.js 22.19 or later
A Terse account
An OpenAI API key

npx terse-cli install

Choose a language.

TypeScript
Python

terse init agent-chat
cd agent-chat
npm install ai@^6 @ai-sdk/openai@^3

terse init agent-chat --language python
cd agent-chat
uv add openai

Create .env in agent-chat/. Add your provider key:

.env

OPENAI_API_KEY=your-openai-api-key

2. Define the actor

TypeScript
Python

src/actor.ts

import { openai } from "@ai-sdk/openai"
import { streamText } from "ai"
import { Actor, Emittable, Persisted, type ActorSocket } from "terse-sdk/actor"

type Member = { name: string }
type Message = { role: "user" | "assistant"; content: string }

export class ChatHistory extends Actor<Member, string, Message[]> {
    // Save history and sync it to connected clients.
    @Persisted @Emittable messages: Message[] = []

    async onMessage(socket: ActorSocket<Member, Message[]>, text: string): Promise<void> {
        // Add the user's message to the conversation.
        const messages: Message[] = [
            ...this.messages,
            { role: "user", content: `${socket.metadata.name}: ${text}` },
        ]
        const reply: Message = { role: "assistant", content: "" }
        this.broadcast([...messages, reply])

        // Stream the growing reply to every connected client.
        const result = streamText({ model: openai("gpt-5-mini"), messages })
        for await (const chunk of result.textStream) {
            reply.content += chunk
            this.broadcast([...messages, reply])
        }

        // Save the completed conversation when this handler returns.
        this.messages = [...messages, reply]
    }
}

src/actor.py

from typing import Literal
from durable_actors import Actor, ActorSocket, emitted
from openai import OpenAI
from openai.types.responses import ResponseInputParam
from pydantic import BaseModel


class Member(BaseModel):
    name: str


class Message(BaseModel):
    role: Literal["user", "assistant"]
    content: str


class ChatHistory(Actor[Member, str, list[Message]]):
    # Save history and sync it to connected clients.
    messages: list[Message] = emitted(default_factory=list)

    def on_message(self, socket: ActorSocket[Member, list[Message]], text: str) -> None:
        # Add the user's message to the conversation.
        messages = [
            *self.messages,
            Message(role="user", content=f"{socket.metadata.name}: {text}"),
        ]
        reply = Message(role="assistant", content="")
        self.broadcast([*messages, reply])

        # Stream the growing reply to every connected client.
        inputs: ResponseInputParam = [{"role": m.role, "content": m.content} for m in messages]
        with OpenAI() as client:
            with client.responses.stream(model="gpt-5-mini", input=inputs) as stream:
                for event in stream:
                    if event.type == "response.output_text.delta":
                        reply.content += event.delta
                        self.broadcast([*messages, reply])

        # Save the completed conversation when this handler returns.
        self.messages = [*messages, reply]

3. Run locally and generate the client

Start the actor server:

terse actor dev

Keep it running. Open a second terminal in agent-chat/. Generate the backend client:

TypeScript
Python

terse actor generate --language typescript --out-dir generated

terse actor generate --language python --out-dir generated

Generated code points to http://127.0.0.1:7100/v1/projects/local/actors by default. Regenerate after making changes to actor code.

4. Add the application backend

TypeScript
Python

npm install express
npm install --save-dev @types/express

app.ts

import express from "express"
import { actors } from "./generated/index.js"

const app = express()

// Issue a socket grant for this conversation.
app.post("/socket", async (_req, res) => {
    const grant = await actors.ChatHistory.prepareWebsocket({
        actorId: "demo-chat",
        metadata: { name: "Local developer" },
    })
    res.set("Cache-Control", "no-store").json(grant)
})

app.listen(3000, "127.0.0.1")

uv add flask

app.py

from flask import Flask, Response, jsonify
from generated import ActorProxy, actors

app = Flask(__name__)


@app.post("/socket")
def connect() -> Response:
    # Issue a socket grant for this conversation.
    grant = ActorProxy.handle(actors.ChatHistory.Authorization(
        actor_id="demo-chat",
        metadata=actors.ChatHistory.Metadata(name="Local developer"),
    ))
    response = jsonify(websocketUrl=grant.websocket_url)
    response.headers["Cache-Control"] = "no-store"
    return response

5. Connect the browser

npm create vite@latest frontend -- --template react
cd frontend
npm install
cd ..

frontend/vite.config.js

import { defineConfig } from "vite"
import react from "@vitejs/plugin-react"

export default defineConfig({
  plugins: [react()],
  server: {
    proxy: { "/socket": "http://127.0.0.1:3000" },
  },
})

frontend/src/App.jsx

import { useEffect, useRef, useState } from "react"

export default function App() {
  const socket = useRef(null)
  const [messages, setMessages] = useState([])
  const [text, setText] = useState("")
  const [busy, setBusy] = useState(true)

  useEffect(() => {
    let connection
    let cancelled = false

    // Get a grant from the backend. Connect to the actor.
    async function connect() {
      const response = await fetch("/socket", { method: "POST" })
      const grant = await response.json()
      if (cancelled) return
      connection = new WebSocket(grant.websocketUrl)
      socket.current = connection

      connection.onmessage = event => {
        const data = JSON.parse(event.data)
        if (Array.isArray(data)) {
          // Replace the displayed reply as it streams.
          setMessages(data)
          setBusy(true)
        } else {
          // Restore saved history on connection and after each reply.
          if (data.type === "state") setMessages(data.state.messages)
          if (data.type === "state_update") setMessages(data.changes.messages)
          setBusy(false)
        }
      }
    }

    connect()
    // Close the socket when this component unmounts.
    return () => {
      cancelled = true
      connection?.close()
    }
  }, [])

  // Send the user's text to the actor.
  function send(event) {
    event.preventDefault()
    socket.current.send(JSON.stringify(text))
    setText("")
    setBusy(true)
  }

  return (
    <main>
      <h1>Agent chat</h1>
      <pre style={{ whiteSpace: "pre-wrap" }}>
        {messages.map(m => `${m.role}: ${m.content}`).join("\n\n")}
      </pre>
      <form onSubmit={send}>
        <input aria-label="Message" value={text} onChange={e => setText(e.target.value)} required />
        <button disabled={busy}>Send</button>
      </form>
    </main>
  )
}

6. Try streaming and persistence

Start the app:

TypeScript
Python

bun app.ts

uv run --env-file .env flask --app app run --port 3000

Open a third terminal in agent-chat/. Start React:

cd frontend
npm run dev

7. Deploy to Terse

From the actor project:

terse secrets add OPENAI_API_KEY
terse deploy

Open the Terse app. Open your profile menu. Select API tokens. Create a token and copy it.

Test the deployed actor locally

Keep React and your backend on your machine. Connect them to the actor running on Terse. Add these values to agent-chat/.env. Use the URL from terse deploy and your Terse API token:

TERSE_ACTOR_URL=https://api.useterse.ai/YOUR_PROJECT_ID/actors
TERSE_API_KEY=your-terse-api-key

Regenerate the client and restart the backend from agent-chat/:

TypeScript
Python

terse actor generate --language typescript --out-dir generated
bun app.ts

terse actor generate --language python --out-dir generated
uv run --env-file .env flask --app app run --port 3000

Open http://localhost:5173 to use the app.

Get started

Reference

Durable actors quickstart

1. Create the actor project

2. Define the actor

3. Run locally and generate the client

4. Add the application backend

5. Connect the browser

6. Try streaming and persistence

7. Deploy to Terse

Test the deployed actor locally

​1. Create the actor project

​2. Define the actor

​3. Run locally and generate the client

​4. Add the application backend

​5. Connect the browser

​6. Try streaming and persistence

​7. Deploy to Terse

​Test the deployed actor locally

1. Create the actor project

2. Define the actor

3. Run locally and generate the client

4. Add the application backend

5. Connect the browser

6. Try streaming and persistence

7. Deploy to Terse

Test the deployed actor locally