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

export const ON_TASK_COMPLETE_SIG_PY = `# Per-task form (recommended)
@agent.on_task_complete("task_name")
def handler(call: guava.Call) -> None:
    ...

# Generic form — fires for all tasks
@agent.on_task_complete
def handler(call: guava.Call, task_id: str) -> None:
    ...`;

export const ON_TASK_COMPLETE_SIG_TS = `// Per-task form (recommended)
agent.onTaskComplete("task_name", async (call: guava.Call) => void);

// Generic form — fires for all tasks
agent.onTaskComplete(async (call: guava.Call, taskId: string) => void);`;

export const ON_TASK_COMPLETE_EX_PY = `import logging
import guava
from guava import Agent

logger = logging.getLogger(__name__)

agent = Agent(
    organization="Thai Palace",
    purpose="Add callers to the waitlist",
)

@agent.on_call_start
def on_call_start(call: guava.Call):
    call.set_task(
        "waitlist",
        objective="Add the caller 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 ready"),
            "Read the phone number back to the caller to confirm.",
        ],
    )

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

export const ON_TASK_COMPLETE_EX_TS = `import * as guava from "@guava-ai/guava-sdk";

const agent = new guava.Agent({
  organization: "Thai Palace",
  purpose: "Add callers to the waitlist",
});

agent.onCallStart(async (call) => {
  await call.setTask({
    taskId: "waitlist",
    objective: "Add the caller 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 ready" }),
      "Read the phone number back to the caller to confirm.",
    ],
  });
});

agent.onTaskComplete("waitlist", async (call) => {
  const name = await call.getField("caller_name");
  const size = await call.getField("party_size");
  console.log(\`Added \${name}, party of \${size}, to waitlist.\`);
  await call.hangup("Thank the caller and let them know we'll text when their table is ready.");
});`;

## on\_task\_complete()

`on_task_complete` is called when a [Task](./tasks) previously set with `call.set_task()` is completed by the agent. Use it to persist collected data, trigger downstream workflows, or move the call to the next stage.

### Signature

There are two forms:

<CodeTabs
  python={{ code: ON_TASK_COMPLETE_SIG_PY, filename: "signature" }}
  typescript={{ code: ON_TASK_COMPLETE_SIG_TS, filename: "signature" }}
/>

- **Per-task form** (recommended): `@agent.on_task_complete("task_name")` binds the handler to a specific `task_id`. The handler receives only the `Call` object.
- **Generic form**: `@agent.on_task_complete` (bare decorator) fires for every completed task. The handler receives the `Call` object and the `task_id` string, letting you dispatch on it manually.

<Callout>
  You cannot mix both forms on the same agent — using per-task handlers alongside a generic handler raises a <code>TypeError</code>.
</Callout>

- `on_task_complete` fires once all checklist items are resolved and the agent has signaled completion.
- Use [`call.get_field()`](./get-field) inside the handler to read values collected during the task.
- The call is still live when this handler runs — you can issue commands such as `call.set_task()`, `call.hangup()`, or `call.transfer()`.

### Example

<CodeTabs
  python={{ code: ON_TASK_COMPLETE_EX_PY, filename: "waitlist_controller.py" }}
  typescript={{ code: ON_TASK_COMPLETE_EX_TS, filename: "waitlist_controller.ts" }}
/>

<AutoNextLink currentSection="on-task-complete" />