Autonomy Control

When to useCopy Anchor Link

• The user wants to change how independently the agent works: always ask, ask only for risky steps, or act and report.
• Before a long or recurring task, to agree how often the agent should check in.

When not to useCopy Anchor Link

• The agent needs access to specific tools or data. Use Permission Scope.
• The agent is about to take one specific action. Use an Approval Request.
• There is only one sensible way to work. Say how the agent will proceed in text.

How the agent should use itCopy Anchor Link

• Give two to five levels, least autonomy first, each with a short label and a one-line summary.
• Use details (up to three) for concrete consequences at that level: what still needs approval, caps, reports.
• Set levelId to the level in effect now, from the agent's settings. Mark at most one recommendedId.
• After a result, work at the returned level from then on and say so in one line.

InteractionCopy Anchor Link

• The levels are a radio group (arrow keys move between them). The selected level opens its details; a small meter in the header shows how far along the scale it sits.
• The level in effect is tagged Current (blue); the recommendedId level is tagged Recommended (green). Choosing a level above the one in effect adds "gives the agent more freedom" to the footer note ("Not saved yet"), so the extra room is visible before saving. Picking another enables Set to …, which sends the result; the footer then reads Saved.
• The control stays usable after saving, so the user can change the level again; each save sends a new result. A restored result never re-sends.
• While streaming, levels arrive one by one and the controls are disabled. Selection and saving are announced to screen readers.

InstallationCopy Anchor Link

npx shadcn@latest add https://your-site.com/r/autonomy-control.json

UsageCopy Anchor Link

import { tool } from "ai"
import { autonomyControlTool } from "@/components/genui/autonomy-control.schema"

const tools = {
  [autonomyControlTool.name]: tool({
    description: autonomyControlTool.description,
    inputSchema: autonomyControlTool.inputSchema,
  }),
}

import { AutonomyControl } from "@/components/genui/autonomy-control"

function ToolPart({ part, addToolResult }) {
  if (part.type !== "tool-set_autonomy") return null

  return (
    <AutonomyControl
      {...part.input}
      status={part.state === "input-streaming" ? "streaming" : undefined}
      result={part.state === "output-available" ? part.output : undefined}
      onResult={(result) =>
        addToolResult({
          tool: "set_autonomy",
          toolCallId: part.toolCallId,
          output: result,
        })
      }
    />
  )
}

The result tells the agent which level to work at:

{ action: "set", level: "risky" }

SchemaCopy Anchor Link

Host props: status (streaming, ready), onResult, result and className.

SourceCopy Anchor Link