Jobs

A job is the unit of automation in Terse: a trigger and a handler that runs every time the trigger fires.

A job is the core building block in Terse. It connects an event (the trigger) to the code that should run when that event happens (the handler). When you deploy a Terse project, you’re deploying one or more jobs.

In the SDK, you define jobs with createJob(). Across these docs, we sometimes call them workflows, and the Terse app surfaces them as agents. Same thing, different names.

Anatomy of a job

Every job has four parts:

createJob({
    name: "new-deal-enrichment",
    triggers: [Triggers.attio.onRecordCreated({ object: AttioObject.Deal })],
    filter: (event) => event.record.values.stage === "contract-sent",
    onTrigger: async (event) => {
        // your logic here
    }
})

Name

A unique string identifier. Terse uses this to match the job across deploys, so if you rename it, the platform treats it as a new job. Keep names stable and descriptive.

Triggers

The event that starts the job. A trigger is always tied to an integration (Attio record created, Slack message received, GitHub PR opened) or to the system (cron schedule, webhook). A job can have multiple triggers, but each execution is started by exactly one event.

Filter (optional)

Runs a closure when the event fires and you can decide to skip this particular event.

Handler

The function that runs when the trigger fires. Inside the handler, you can make deterministic tool calls, use the TerseAgent, parse structured output, or combine all three.

What happens when a job runs

Trigger fires → Filter (optional) → Handler executes → Run recorded in Activity

1. Trigger fires. An event arrives from the connected integration or on the configured schedule.
2. Filter evaluates. If you defined a filter function, Terse calls it with the event. Return false to skip the run entirely. No tokens spent, no side effects.
3. Handler executes. Your onTrigger runs with the event payload.
4. Run is recorded. Every execution, whether it succeeds or fails, is logged in Activity with the full action trace so you can inspect what happened.

Deterministic vs. agentic

Inside a handler, you have two ways to get things done:

Approach	How	When to use
Deterministic	toolbox.*	You know exactly which tool to call and with what parameters
Agentic	generateText({ prompt, skills })	You need the model to reason, summarize, classify, or decide

Most production jobs combine both. Use deterministic calls for predictable operations (fetch data, update a record, send a message) and agentic calls when the model adds value (scoring, summarizing, routing).

onTrigger: async (event) => {
    // Agentic: let the model research and summarize
    const summary = await generateText({
        prompt: `Research ${event.record.values.company_name} and summarize what they do for the account owner.`,
        skills: [Skills.attio({ object: AttioObject.Deal }), Skills.web()]
    })

    // Deterministic: always write the result back
    await toolbox.attio.upsertRecord({
        object: AttioObject.Deal,
        matchingAttribute: "record_id",
        records: [{ record_id: event.record.id, research_summary: summary }]
    })
}

Filtering events

Not every event needs a full run. Use filter to skip events that don’t match your criteria before the handler executes.

createJob({
    name: "contract-alerts",
    triggers: [Triggers.attio.onRecordUpdated({ object: AttioObject.Deal })],
    filter: (event) => event.record.values.stage === "contract-sent",
    onTrigger: async (event) => {
        // Fully deterministic — no agent needed
        await toolbox.slack.sendMessage({
            channelId: SlackChannel.DealDesk.channelId,
            message: `Contract sent for ${event.record.values.company_name}.`
        })
    }
})

Tool approvals

For jobs that write to production systems, you can require human approval before specific tools execute. List the tool names in toolApprovals on generateText (or TerseAgent.create()). During local testing, the CLI prompts in your terminal. In production, approval requests appear in the Terse app under Notifications.

Lifecycle

Jobs follow a straightforward path from code to production:

1. Define. Register workflows with top-level createJob() in src/terse.jobs.ts (or split across files and import them for side effects).
2. Generate. Run terse generate to get typed helpers for your integrations.
3. Test. Run terse test to execute against real sample events locally.
4. Deploy. Run terse deploy to package and host serverlessly. New jobs are created, existing jobs are updated, and removed jobs are cleaned up.
5. Monitor. View runs, actions, and failures in the Activity tab.

Where to go next

Deterministic tool calls

Call integration tools directly from code, no LLM in the loop.

Triggers reference

Every available trigger and its event payload.