Actors

An Actor is anything that can execute a function. There are four types of actors in the system, each with different execution characteristics and capabilities.

The Actor Hierarchy

Actor
├── ServiceAccount  → executes Code functions
├── Model           → executes Generative functions
└── Worker
    ├── Agent       → executes Agentic functions
    └── Human       → executes Human functions

Workers are a special subset of actors - Agents and Humans - that "perform Tasks" rather than execute functions directly. Workers figure things out, while ServiceAccounts and Models execute deterministically.

ServiceAccount

A ServiceAccount is a non-human actor that executes deterministic code functions.

Characteristics

Execution style: Deterministic, synchronous
Function type: Code functions
Autonomy: None - runs predefined logic
Authentication: API keys, service tokens
Examples: API service accounts, background jobs, webhooks

Use Cases

Use Case	Example
Data transformation	Parse CSV, convert JSON to XML
Validation	Check email format, validate input
Integration	Sync with external APIs
Automation	Send notifications, process webhooks
Computation	Calculate totals, aggregate metrics

Example

interface ServiceAccount {
  id: string
  name: string
  type: 'ServiceAccount'
  apiKey: string
  permissions: string[]
}

const serviceAccount: ServiceAccount = {
  id: 'sa_123',
  name: 'Payment Processor',
  type: 'ServiceAccount',
  apiKey: 'sk_live_...',
  permissions: ['payments.read', 'payments.write']
}

// ServiceAccount executes Code function
async function processPayment(invoice: Invoice): Promise<Payment> {
  const result = await stripe.charges.create({
    amount: invoice.amount,
    currency: 'usd',
    customer: invoice.customerId,
  })
  return result
}

When to Use ServiceAccounts

Use ServiceAccounts when:

Logic is deterministic and predictable
No judgment or creativity required
Performance and speed are critical
You need reliable, repeatable execution
The function is pure transformation or I/O

Model

A Model is an LLM that executes generative functions through direct generation.

Characteristics

Execution style: LLM generation, synchronous
Function type: Generative functions
Autonomy: Limited - single-turn generation
Authentication: API keys for LLM providers
Examples: GPT-4, Claude, Gemini

Use Cases

Use Case	Example
Content generation	Write copy, generate descriptions
Summarization	Condense documents, extract key points
Classification	Categorize content, sentiment analysis
Extraction	Pull structured data from text
Translation	Convert between languages
Transformation	Rewrite tone, format conversion

Example

interface Model {
  id: string
  name: string
  type: 'Model'
  provider: 'openai' | 'anthropic' | 'google'
  model: string
  apiKey: string
}

const model: Model = {
  id: 'model_123',
  name: 'Claude Sonnet 4.5',
  type: 'Model',
  provider: 'anthropic',
  model: 'claude-sonnet-4-5',
  apiKey: 'sk_ant_...'
}

// Model executes Generative function
async function generateProductDescription(product: Product): Promise<string> {
  const prompt = `Generate a compelling product description for: ${product.name}`
  const response = await anthropic.messages.create({
    model: model.model,
    messages: [{ role: 'user', content: prompt }]
  })
  return response.content[0].text
}

When to Use Models

Use Models when:

You need creative or natural language output
The task involves understanding and generation
Rules-based logic is too rigid
You need human-like reasoning in a single turn
The function is classification, extraction, or transformation

Agent

An Agent is an AI that executes agentic functions by autonomously performing tasks.

Characteristics

Execution style: Autonomous, multi-step, asynchronous
Function type: Agentic functions
Autonomy: High - plans and executes multi-step workflows
Tools: Can use external tools and APIs
Examples: Research agents, coding agents, data analysis agents

Use Cases

Use Case	Example
Research	Gather information from multiple sources
Analysis	Analyze data and provide insights
Multi-step workflows	Complete complex tasks with multiple steps
Problem solving	Debug code, troubleshoot issues
Planning	Create implementation plans

Example

interface Agent {
  id: string
  name: string
  type: 'Agent'
  model: Model
  tools: Tool[]
  systemPrompt: string
}

const agent: Agent = {
  id: 'agent_123',
  name: 'Research Agent',
  type: 'Agent',
  model: model,
  tools: [webSearchTool, webScrapeTool, analyzeTool],
  systemPrompt: 'You are a research agent that gathers and analyzes information.'
}

// Agent implements Worker interface
class ResearchAgent implements Worker {
  async ask(prompt: string): Promise<Response> {
    // Single turn interaction
  }

  async do(task: Task): Promise<Result> {
    // Multi-step task execution
    // Agent autonomously plans and executes
    const plan = await this.createPlan(task)
    const results = await this.executePlan(plan)
    return this.synthesizeResults(results)
  }
}

Agent vs Model

Aspect	Model	Agent
Interaction	Single turn	Multi-turn
Planning	None	Creates and follows plans
Tool use	No	Yes
Autonomy	Low	High
Function type	Generative	Agentic
Best for	Direct generation	Complex tasks

When to Use Agents

Use Agents when:

The task requires multiple steps
Planning and decision-making are needed
You need to use external tools or APIs
The workflow is exploratory or research-oriented
Human-like reasoning over multiple turns is required

Human

A Human is a person that executes human functions by performing tasks.

Characteristics

Execution style: Manual, asynchronous, judgment-based
Function type: Human functions
Autonomy: Full - makes subjective decisions
Interface: UI, Slack, email, etc.
Examples: Approvers, reviewers, decision-makers

Use Cases

Use Case	Example
Approval	Approve invoices, sign contracts
Review	Code review, content review
Decision-making	Strategic decisions, edge cases
Creative work	Design, writing, strategy
Quality control	Final checks, validation

Example

interface Human {
  id: string
  name: string
  type: 'Human'
  email: string
  roles: string[]
  notificationChannels: ('email' | 'slack' | 'sms')[]
}

const human: Human = {
  id: 'human_123',
  name: 'Alice Johnson',
  type: 'Human',
  email: 'alice@example.com',
  roles: ['approver', 'reviewer'],
  notificationChannels: ['email', 'slack']
}

// Human implements Worker interface
class HumanWorker implements Worker {
  async ask(prompt: string): Promise<Response> {
    // Send prompt to human via Slack/email
    // Wait for response
  }

  async do(task: Task): Promise<Result> {
    // Create HumanTask
    const humanTask = await createHumanTask({
      assignee: this.id,
      description: task.description,
      data: task.data
    })

    // Notify human via Slack/email
    await notify(this, humanTask)

    // Wait for human to complete task
    return await waitForCompletion(humanTask)
  }
}

Human Tasks

Human functions create HumanTasks that render in human-friendly interfaces:

interface HumanTask {
  id: string
  type: 'approval' | 'review' | 'decision' | 'creative'
  assignee: Human
  status: 'pending' | 'in_progress' | 'completed' | 'rejected'
  data: any
  ui: 'slack' | 'email' | 'web'
}

The same MDXLD document renders differently based on the actor:

---
$type: Invoice
amount: 5000
customer: Acme Corp
---

# Invoice Approval

Please review and approve this invoice.

<InvoiceDetails />
<ApprovalButtons />

Renderers:

renderSlack() - Slack Block Kit with approve/reject buttons
renderEmail() - HTML email with clickable buttons
renderHTML() - Web UI with rich interface

When to Use Humans

Use Humans when:

The task requires judgment or subjective decision-making
Compliance or governance requires human oversight
The task is creative or strategic
AI cannot reliably handle edge cases
Legal or ethical considerations require human involvement

The Worker Interface

Workers are Agents and Humans that perform tasks rather than execute functions directly.

Worker Contract

interface Worker {
  ask(prompt: string): Promise<Response>
  do(task: Task): Promise<Result>
}

Both Agents and Humans implement this interface, making them interchangeable for task execution.

Worker vs Non-Worker Actors

Aspect	ServiceAccount/Model	Worker (Agent/Human)
Interface	Function call	Task assignment
Execution	Direct	Autonomous
Planning	None	Yes
Async	Synchronous	Asynchronous
Tools	No	Yes
Judgment	No	Yes

Example: Interchangeable Workers

async function performResearch(task: Task, worker: Worker): Promise<Result> {
  // Works with both Agent and Human
  return await worker.do(task)
}

// Can use Agent
const agentResult = await performResearch(task, researchAgent)

// Or Human
const humanResult = await performResearch(task, researcher)

This enables hybrid workflows where you can:

Start with an Agent for routine tasks
Escalate to Human for edge cases
Use Human for high-stakes decisions
Use Agent for scale and speed

How Actors Execute Functions

Each actor type executes a specific function type:

Actor	Executes	Style	Example
ServiceAccount	Code function	Deterministic	`processPayment(invoice)`
Model	Generative function	LLM generation	`generateDescription(product)`
Agent	Agentic function	Autonomous task	`researchCompetitor(company)`
Human	Human function	Manual task	`approveInvoice(invoice)`

Execution Flow

// 1. ServiceAccount executes Code function
const validatedInvoice = await validateInvoice(invoice) // Code function

// 2. Model executes Generative function
const summary = await summarizeInvoice(validatedInvoice) // Generative function

// 3. Agent performs Agentic task
const analysis = await analyzeInvoice(validatedInvoice) // Agentic function

// 4. Human performs Human task
const approved = await approveInvoice(validatedInvoice) // Human function

Actor Selection Guide

Choose the right actor for your function:

Decision Tree

Is the logic deterministic and rule-based?
├─ Yes → ServiceAccount (Code function)
└─ No → Does it require creativity/generation?
    ├─ Yes → Is it a single-turn generation?
    │   ├─ Yes → Model (Generative function)
    │   └─ No → Agent (Agentic function)
    └─ No → Does it require human judgment?
        ├─ Yes → Human (Human function)
        └─ No → Agent (Agentic function)

Quick Reference

Requirement	Actor
Rules-based logic	ServiceAccount
Generate text/content	Model
Multi-step research	Agent
Approval/decision	Human
Data transformation	ServiceAccount
Classification	Model
Problem-solving	Agent
Creative work	Human or Agent
Real-time processing	ServiceAccount
Complex reasoning	Agent
Legal compliance	Human

Authentication & Permissions

Each actor type has different authentication mechanisms:

ServiceAccount

interface ServiceAccount {
  apiKey: string
  permissions: string[]
  rateLimit?: number
}

Model

interface Model {
  provider: 'openai' | 'anthropic' | 'google'
  apiKey: string
  model: string
  maxTokens?: number
}

Agent

interface Agent {
  model: Model
  tools: Tool[]
  systemPrompt: string
  maxIterations?: number
}

Human

interface Human {
  email: string
  roles: string[]
  permissions: string[]
  notificationChannels: ('email' | 'slack' | 'sms')[]
}

Next Steps

Read Functions to understand what Actors execute
See Workflows for coordinating multiple Actors
Explore Verbs for action grammar used by Actors

Actors

On this page