Outcomes and errors¶

A turn ends with a typed outcome, refusals included; only real failures throw.

When the server refuses a prompt, stops an answer, or a tool is not allowed, the turn still ends normally: its outcome says what happened, and its notices say what to tell the user. The session goes on, and the user can send the next message. See Outcomes for why refusals are outcomes.

The result of a turn¶

session.send returns an AgentResult, and session.stream yields it in the turn_completed event:

Outcomes¶

When a turn has both a refusal and a denied tool call, prompt_blocked or response_blocked wins over tool_denied.

A refused prompt is never sent to the model again. Of an answer the server stopped, only the question stays in the history that later requests carry. A turn that was rate limited or over budget is left out of later requests as well, so the user can send the message again.

Notices¶

A notice tells the user about a refusal or a limit. Notices arrive as notice events during the turn and are collected in result.notices:

A round_limit notice means the agent stopped calling tools after the most model calls a turn may make (useMaxRounds). The turn's outcome is still completed or tool_denied.

const result = await session.send("Delete pages 3 to 5.");
if (result.outcome !== "completed") {
  for (const notice of result.notices) showNotice(notice.message, notice.decisionId);
}

Errors¶

Errors are thrown only when a turn cannot run or cannot finish: the server cannot be reached, the sign-in is gone, the server answered with an error that is not a refusal, or the answer broke off. A turn that fails is recorded with the status error and left out of later requests. stream yields no turn_completed for it.

All the SDK's errors derive from FadenError:

When you stop a turn with an AbortSignal, the signal's reason is thrown. isAbortError(error) from @fadenstack/client is true for it, so you can tell a stop from a failure.

Mistakes in your code throw the platform's errors: a TypeError for an address that is not an https:// URL (unless you allowed http://), and an Error for a second turn while one runs, an incomplete builder, or a session that is not on the device.

import {
  FadenApiError,
  FadenSignInRequiredError,
  FadenUnreachableError,
  isAbortError,
} from "@fadenstack/client";

async function ask(text: string): Promise<void> {
  try {
    showResult(await session.send(text));
  } catch (error) {
    if (isAbortError(error)) return; // the user stopped it
    if (error instanceof FadenSignInRequiredError) return showSignIn();
    if (error instanceof FadenUnreachableError) return showOffline();
    if (error instanceof FadenApiError) return showError(`${error.status}: ${error.message}`);
    throw error;
  }
}

Errors in your tools¶

An error thrown by your tool does not end the turn. The model gets Error: and the message as the tool's result, the tool_completed event has the outcome error, and the model decides what to do next. The same goes for a tool the model names that does not exist, and for arguments that fail the checks. See Tools and approvals.