- Python
- TypeScript
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).signature
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 = "",
)
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.signature
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,
})
Checklist items
The checklist drives the agent forward. Each item is one of three types:- Python
- TypeScript
| Type | Purpose |
|---|---|
guava.Field | Collect structured data from the caller |
guava.Say | Speak a verbatim statement |
str | Natural language instruction for the agent |
| Type | Purpose |
|---|---|
guava.Field | Collect structured data from the caller |
guava.Say | Speak a verbatim statement |
string | Natural language instruction for the agent |
A
guava.Say step is spoken verbatim — use it sparingly when exact wording matters.Example
- Python
- TypeScript
example.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.")
example.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.");
});