Skip to content

docs: distinguish task completion from business outcomes #52

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JJasonSun merged 1 commit into from
Sep 9, 2026
Merged

docs: distinguish task completion from business outcomes #52

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions content/guides/calls.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -475,13 +475,46 @@ a clear end state for the user. `completion_confidence` is confidence in that
judgment, and `evidence` supports it. These fields do not require a custom
result schema.

Read execution, task completion, and the business answer separately:

| Field | Question it answers | How to use it |
| --- | --- | --- |
| `status` | Has the call task finished executing? | Use the [lifecycle states](#call-status) to decide whether to keep waiting. `completed` alone does not establish task or business success. |
| `task_completed` | Did CALL-E judge that the requested task reached a clear end state? | Read it with `completion_confidence` and `evidence`. Confidence applies to this judgment, not to the likelihood of a favorable business answer. |
| `structured_result` | What business answer was extracted? | Check the fields defined by your result schema and the supporting transcript before taking a business action. |

A `true` value or high confidence does not establish that a person answered
or that your business objective was met. Check the business answer in
`structured_result` against the call transcript. Use the
[custom answered_by example](#classify-the-final-endpoint) to extract an
endpoint classification alongside your business result. Keep `unknown`
answers unresolved.

### Example: an answered question with an unfavorable result

Suppose the task is: "Ask whether a table for two is available at 7 p.m.
Do not make a reservation." The restaurant says no tables are available.
With a caller-defined `table_available` result field, an illustrative terminal
response excerpt is:

```json
{
"status": "completed",
"task_completed": true,
"evidence": ["The restaurant confirmed that no table for two is available at 7 p.m."],
"structured_result": {
"table_available": "no"
}
}
```

The availability question reached a clear answer, even though the answer was
unfavorable. The application should report "No table available", not
"Reservation successful". If the requested task were to make a reservation,
the application would need evidence of a confirmed booking; this example does
not establish that outcome. A `null` result or an `unknown` answer must remain
unresolved rather than becoming a yes or no from `status` alone.

## Polling and events

Use `waitForResult` or `wait_for_result` for simple server-side polling. Use events when you need a developer-facing trace of the call lifecycle.
Expand Down