tasks.md

import { CodeTabs } from '../views/docs/CodeTabs';
import { Callout, NextLink } from '../views/docs/prose';

export const SET_TASK_SIG_PY = `call.set_task(
    # Unique identifier for this task, used to bind on_task_complete handlers.
    task_id: str,

# High-level goal for the agent. Provides context when no checklist is given,
    # or alongside a checklist to frame the overall objective.
    objective: str = "",

# Ordered list of items for the agent to complete during the call.
    checklist: list[Field | Say | str] | None = None,

# Optional extra guidance on when to consider this task done. Useful for
    # open-ended tasks where the checklist alone doesn't define completion.
    completion_criteria: str = "",
)`;

export const SET_TASK_SIG_TS = `await call.setTask({
  // Unique identifier for this task, used to bind onTaskComplete handlers.
  taskId: string,

// High-level goal for the agent. Provides context when no checklist is given,
  // or alongside a checklist to frame the overall objective.
  objective?: string,

// Ordered list of items for the agent to complete during the call.
  checklist?: (FieldItem | SayItem | string)[],
})`;

## Task

A task is the unit of work your agent completes on a call. Call `call.set_task()` to direct the agent toward a new goal. You can invoke `call.set_task()` on one of your handler callbacks, or at any time (even on another thread).

<CodeTabs
  python={{ code: SET_TASK_SIG_PY, filename: "signature" }}
  typescript={{ code: SET_TASK_SIG_TS, filename: "signature" }}
/>

### Checklist items

The checklist drives the agent forward. Each item is one of three types:

| Type              | Purpose                                               |
|-------------------|------------------------------------------------------|
| `guava.Field`     | Collect structured data from the caller               |
| `guava.Say`      | Speak a verbatim statement                             |
| `str`            | Natural language instruction for the agent            |

<Callout>
  <span className="text-primary font-semibold">guava.Say</span> A <code>guava.Say</code> step is spoken verbatim — use it sparingly when exact wording matters.
</Callout>

### Example

export const SET_TASK_EX_PY = `@agent.on_call_start
def on_call_start(call: guava.Call):
    call.set_task(
        "waitlist",
        objective="You are a virtual assistant for Thai Palace. Add callers to the waitlist.",
        checklist=[
            guava.Field(key="caller_name", field_type="text", description="Name for the waitlist"),
            guava.Field(key="party_size", field_type="integer", description="Number of people"),
            guava.Field(
                key="phone_number",
                field_type="text",
                description="Phone number to text when the table is ready",
            ),
            "Read the phone number back to the caller to confirm.",
        ],
    )

@agent.on_task_complete("waitlist")
def on_waitlist_done(call: guava.Call):
    logger.info("Added %s, party of %d, to waitlist.",
        call.get_field("caller_name"), call.get_field("party_size"))
    call.hangup("Thank the caller and let them know we'll text when their table is ready.")`;

export const SET_TASK_EX_TS = `agent.onCallStart(async (call) => {
  await call.setTask({
    taskId: "waitlist",
    objective: "You are a virtual assistant for Thai Palace. Add callers to the waitlist.",
    checklist: [
      guava.Field({ key: "caller_name", fieldType: "text", description: "Name for the waitlist" }),
      guava.Field({ key: "party_size", fieldType: "integer", description: "Number of people" }),
      guava.Field({
        key: "phone_number",
        fieldType: "text",
        description: "Phone number to text when the table is ready",
      }),
      "Read the phone number back to the caller to confirm.",
    ],
  });
});

agent.onTaskComplete("waitlist", async (call) => {
  logger.info("Added %s, party of %d, to waitlist.",
    await call.getField("caller_name"), await call.getField("party_size"));
  await call.hangup("Thank the caller and let them know we'll text when their table is ready.");
});

<CodeTabs
  python={{ code: SET_TASK_EX_PY, filename: "example.py" }}
  typescript={{ code: SET_TASK_EX_TS, filename: "example.ts" }}
/>

<NextLink section="field" label="Fields" />