> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goguava.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Task

> The unit of work your agent completes on a call

<Tabs>
  <Tab title="Python">
    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).

    ```python signature theme={null}
    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 = "",
    )
    ```
  </Tab>

  <Tab title="TypeScript">
    A task is the unit of work your agent completes on a call. Call `call.setTask()` to direct the agent toward a new goal. You can invoke `call.setTask()` on one of your handler callbacks, or at any time.

    ```typescript signature theme={null}
    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)[],

      // Optional extra guidance on when to consider this task done. Useful for
      // open-ended tasks where the checklist alone doesn't define completion.
      completionCriteria?: string,
    })
    ```
  </Tab>
</Tabs>

## Checklist items

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

<Tabs>
  <Tab title="Python">
    | Type | Purpose |
    | - | - |
    | [`guava.Field`](/sdk-reference/field) | Collect structured data from the caller |
    | `guava.Say` | Speak a verbatim statement |
    | `str` | Natural language instruction for the agent |
  </Tab>

  <Tab title="TypeScript">
    | Type | Purpose |
    | - | - |
    | [`guava.Field`](/sdk-reference/field) | Collect structured data from the caller |
    | `guava.Say` | Speak a verbatim statement |
    | `string` | Natural language instruction for the agent |
  </Tab>
</Tabs>

<Note>
  A `guava.Say` step is spoken verbatim — use it sparingly when exact wording matters.
</Note>

## Example

<Tabs>
  <Tab title="Python">
    ```python example.py theme={null}
    @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.")
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript example.ts theme={null}
    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.");
    });
    ```
  </Tab>
</Tabs>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.