Skip to main content
Outcomes let you give an Agent an explicit success criterion (a Rubric). The Agent iterates against the Rubric until the work meets the criteria.

​
Core concepts

TermDescription
OutcomeThe expected final result of a task
RubricThe success-criteria text the Agent uses to judge its own output
When you want the Agent to deliver work to a specific quality bar, send the Rubric to the Session via a user.define_outcome event. The Agent will keep referring to the criteria as it works.

​
Event format

{
  "events": [
    {
      "type": "user.define_outcome",
      "rubric": "The generated report must include: 1) an executive summary under 200 words, 2) at least 3 actionable recommendations, 3) sources cited."
    }
  ]
}

​
Field reference

FieldTypeRequiredDescription
typestringYesFixed value user.define_outcome
rubricstringYesSuccess criteria text

​
Typical usage

  1. Create a Session and send the initial message.
  2. Send user.define_outcome with the Rubric to define success.
  3. The Agent iterates against the Rubric.
  4. Inspect the output once you receive session.status_idle.
Make Rubrics specific and measurable. Avoid vague language like “make it better”; use criteria like “code coverage no less than 80%“.

​
curl example

# Send an Outcome definition to an existing Session
curl -X POST https://api.qoder.com/api/v1/cloud/sessions/sess_019e392c0d1e74e095d21ea4c6b41def/events \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.define_outcome",
        "rubric": "Refactored function: 1) all unit tests pass, 2) cyclomatic complexity <= 10, 3) no lint warnings."
      }
    ]
  }'

​
Successful response (202 Accepted)

{
  "data": [
    {
      "id": "evt_019e4a1b2c3d4e5f6a7b8c9d0e1f2a3b",
      "type": "user.define_outcome",
      "rubric": "Refactored function: 1) all unit tests pass, 2) cyclomatic complexity <= 10, 3) no lint warnings.",
      "session_id": "sess_019e392c0d1e74e095d21ea4c6b41def",
      "schema_version": "1.0",
      "created_at": "2026-05-18T16:00:00.000Z",
      "processed_at": "2026-05-18T16:00:00.000Z"
    }
  ]
}

​
Outcomes vs. regular messages

Dimensionuser.messageuser.define_outcome
PurposeSend a conversational messageDefine success criteria
Triggered behaviorThe Agent repliesThe Agent iterates against the criteria
Key fieldcontentrubric
TimingAny timeTypically before or alongside the initial task

​
Best practices

  • Send the Outcome before or alongside the task instructions (user.message).
  • Use a numbered list in the Rubric so the Agent can verify items individually.
  • For complex tasks, break the Rubric into multiple measurable acceptance criteria.
  • Keep the Rubric under 500 words.

​
Next steps

Start a session

Run an agent against an environment.

Session event stream

Stream agent thinking, messages, and tool calls over SSE.

Agent setup

Review Agent configuration.

Tools

Equip your agent with built-in, MCP, and custom tools.