Connect any agent
to any user.

// Controlled generative UI
useComponent({
  name: "showRefundStatus",
  description: "Show a refund status card.",
  parameters: z.object({
    orderId: z.string(),
    amount: z.number(),
    method: z.string(),
  }),
  // your component, your design system
  render: RefundStatusCard,
});

const RefundStatusCard = ({ orderId, amount }) => (
  <Card>…</Card>  // breakdown pie, your design system
);

useHumanInTheLoop({
  name: "chooseRefundMethod",
  parameters: z.object({ orderId: z.string() }),
  render: ({ respond }) => (
    <RefundMethodChoice
      options={["original card", "store credit"]}
      allowCustomAnswer
      onChoose={(answer) => respond?.(answer)}
    />
  ),
});

useFrontendTool({
  name: "selectOrder",
  description: "Open an order in the dashboard.",
  parameters: z.object({ orderId: z.string() }),
  handler: async ({ orderId }) => {
    openOrder(orderId);  // your app code
    return { status: "selected", orderId };
  },
});

const handler = createCopilotRuntimeHandler({
  runtime,
  hooks: {
    onRequest: ({ request }) => {
      const jwt = request.headers.get("authorization");
      const user = verifyJwt(jwt);
      if (!user)
        throw new Response(null, { status: 401 });
      // agent runs are tied to this user
    },
  },
});

const { agent } = useAgent({ agentId: "support" });

// read the agent's shared state
agent.state.focus  // "refunds"

// write it, the agent sees the change
agent.setState({ ...agent.state, focus: "returns" });