Drive GuidingHand from your AI agent

const BASE = 'https://guidinghand.ai';
const manifest = await (await fetch(`${BASE}/tools.json`)).json();

// Tool definitions to pass to your model.
const tools = manifest.endpoints
  .filter((e) => e.input_schema)
  .map((e) => ({ name: e.name, description: e.description, input_schema: e.input_schema }));
const byName = Object.fromEntries(manifest.endpoints.map((e) => [e.name, e]));

// Runs one tool call from the model, on this conversation's session.
async function runTool(name, input, sessionToken) {
  const e = byName[name];
  const res = await fetch(BASE + e.path, {
    method: e.method,
    headers: { Authorization: `Bearer ${sessionToken}`, 'Content-Type': 'application/json' },
    body: e.method === 'POST' ? JSON.stringify(input) : undefined,
  });
  return res.json(); // errors too: the model can read { "error": "..." } and adjust
}

{
  "id": "task_RMW0Ke37PoUW",
  "request_id": "T-1042-dark-mode",
  "status": "waiting_for_user",
  "done": false,
  "cursor": 4,
  "events": [
    { "cursor": 4, "type": "question", "message": "Which account?", "ts": "2026-09-26T15:05:41.593Z",
      "data": { "question_id": "q_nh8TwFRVQMs", "question": "Which account?", "options": ["Work", "Home"] } }
  ],
  "update": { "cursor": 4, "type": "question", "message": "Which account?", "ts": "2026-09-26T15:05:41.593Z" },
  "question": { "question_id": "q_nh8TwFRVQMs", "question": "Which account?", "options": ["Work", "Home"], "customer_can_answer": true }
}

You can operate the customer's computer with the computer-task tools, once they have connected.
- Describe the outcome in start_computer_task, not the clicks: "Turn on Dark Mode", not "click the Apple menu".
- Keep calling wait_for_computer_task with the latest cursor until done is true.
- When the task has a question, answer it if the conversation already tells you the answer. Otherwise ask the customer, in their words, and pass their answer on. If question.customer_can_answer is true, they can also answer it on their screen: tell them so, and keep waiting.
- If an answer or decision comes back with code "already_answered" or "not_pending", the customer answered first (or it already closed). That's fine: keep waiting.
- When the task asks for approval, tell the customer exactly what will happen and approve only if they agree. If approval.customer_can_approve is true, they can also allow it on their screen: tell them so, and keep waiting.
- Never ask the customer for passwords, codes or card numbers to pass on. The computer agent never types them or asks for them; when a step needs one, its question asks the customer to type it on their own computer. Relay that, then answer the question once they have.
- If the customer wants it to stop, call stop_computer_task.