Handle runtime results

A call to AGENTO can finish, ask a question, offer choices, or wait for approval. Your host must carry the same authorized session through those states. Rendering only result.message loses the control information needed to continue safely.

Start with the search tool from the quick start: completed displays returned data, needs_input requests missing input, and error requires inspecting its code. The optional booking exercise introduces selection and confirmation for more complex workflows.

Choose the right entry point

• Use invoke() when the server already knows the tool and arguments. It starts a new operation and replaces the pending flow.
• Use chat() for natural-language routing or a conversational answer to missing input. It requires a model except for certain built-in pending shortcuts.
• Use select() to continue a returned choice; pass its selection ID and selected option ID.
• Use confirm() only after the user approves the current preview.
• Use cancel() to clear pending execution and published references.

Do not call invoke() as a generic “next” button. A selection is not a new invocation.

Follow a booking from missing date to completion

1. Invoke book without a date. The result is needs_input; no availability call occurs.
2. Collect the date. With a form, start a new invoke() with the complete known user input. With chat, send the user's answer through chat() so the pending frame can be updated.
3. Availability returns several slots. Render selection.options; do not regenerate their IDs or let a model rewrite the option list.
4. The user selects a slot. Call select(); the runtime maps the server token and prepares the write.
5. Render confirmation.preview and expiry. The HTTP write has still not occurred.
6. After explicit approval, call confirm(). Render completion only when the returned status permits it.

Each continuation can return another intermediate status or an error. Do not hard-code “select always completes” or “confirm always succeeds.”

Route every result through one handler

This is host pseudocode: the render functions are application responsibilities.

function handleResult(result) {
  switch (result.status) {
    case "completed":
      renderCompleted({ message: result.message, data: result.data });
      break;
    case "needs_input":
      renderInputRequest({ fields: result.missing ?? [], message: result.message });
      break;
    case "needs_selection":
      renderChoices(result.selection);
      break;
    case "needs_confirmation":
      renderApproval(result.confirmation);
      break;
    case "error":
      renderRecoverableError(result.error);
      break;
  }
}

Keep IDs and expiry from the result in your application state. Authorize the caller on every server handler. A conversation ID is not proof of identity.

What the runtime does between states

load session inside a serialized transaction
  → check expiry, config identity, credential transport, and budgets
  → route a message or start a known tool
  → validate user-owned inputs
  → resolve read-only dependencies and choices
  → validate completed arguments
  → prepare a fixed HTTP request
  → wait for confirmation if required
  → execute, validate response, redact, and present

The internal state machine prevents unsupported transitions. Application code should rely on public result statuses and continuation IDs rather than editing stored state.

Conversation can detour without approving anything

While waiting for a date, the user might say “thanks.” With conversation enabled, AGENTO can answer and retain pending work. If the user asks for opening hours, that fact needs an appropriate API tool or trusted source; a conversational detour must not invent business data.

A recognized confirmation word returns the pending confirmation instead of executing it. A new routed intent can replace the old flow. A changed input can invalidate earlier dependency facts and require fresh choices.

Cancellation, expiry, and uncertain execution

Cancellation clears pending work, but does not undo a write already accepted by the API. Aborting a network request likewise cannot prove that the server did nothing.

An expired or configuration-incompatible session returns SESSION_EXPIRED and clears incompatible state. Start a fresh flow. A stored EXECUTING marker returns TOOL_EXECUTION_UNCERTAIN; reconcile with the API before clearing and retrying.

Test the host, not just the happy path

Exercise every status, a choice that expires while the screen is open, a double-click on confirmation, a changed authenticated user, and an API failure after approval. See errors for recovery decisions and Runtime API for method parameters.