Rate the agent
rate_agent_resultRecord what a person thought of something the agent produced — a reply, an export, a report, an email. Send it as soon as they press the thumb: the reason and their words are optional and may follow in a second call, which replaces the first. Pick reason_code from get_feedback_reasons; an unknown code is dropped and the rating is still saved (reason_dropped: true). For target_kind: "report" the target_ref is the view_key, NOT the report_key — one report is read by many country pages and only the view_key tells them apart. target_ref is verified against your own message log: the answer carries ref_check saying whether it matched (verified), did not (mismatch), could not be checked (unchecked) or was never sent (absent). A rating is never dropped because the check failed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | No | Which model produced the rated answer. | |
| probe | No | True when the call comes from a test run rather than a person. 🔴 Derive it from the process you run in — do not set it by hand: a flag someone has to remember is a flag someone forgets. The rating is still STORED; it is hidden behind a switch on the triage screen, because dropping it on arrival would lose what later needs explaining. Omit the field when you cannot tell — absent means "not stated", never "a person". | |
| topic | No | What the exchange was about, one short phrase. | |
| signal | No | thumb (default) for a pressed thumb; undone when they cancelled the result; rephrased or left for the quiet signals. The weight is set by the platform, not by you. | |
| comment | No | Their own words. Optional. Trimmed at 2000 characters. | |
| surface | Yes | Where it happened, e.g. widget. | |
| verdict | Yes | The thumb the person pressed. Send "retracted" (or an empty string) when they pressed the same thumb again and took the rating back — it then stops counting and leaves the triage queue. Retracting needs the same target_ref as the rating it undoes. | |
| target_ref | No | Your identifier of the rated work: the message id for an answer, the view_key for a report. Omit it only when the kind has none. | |
| reason_code | No | A code from get_feedback_reasons. | |
| target_kind | Yes | What was rated: answer | export | report | email | any future kind. | |
| knowledge_ids | No | Ids of the platform rules that were in the prompt for this answer, up to 50. This is how a harmful rule gets noticed from a single complaint. | |
| reason_shown_lang | No | Language the person actually SAW the reason card in — send it together with `reason_code`, never alone. It exists so that "they picked this reason" can be told apart from "they tapped something they could not read": when the card had not been translated yet, the language differs from the visitor locale. Omit the field entirely rather than sending an empty string — absent means "not stated", which is a different answer from "in their own language". |