Skip to main content
An agent is a configuration object, not a running process. It says how the AI should work for one kind of support case: which app to open first, how your product names things, what to avoid. Sessions and tasks run with an agent.
Create agents with POST /v1/agents, change them with PATCH /v1/agents/{agent_id} (send only the fields to change; narration, customer_answers and customer_approvals take true or false, anything else is a 400), and delete them with DELETE /v1/agents/{agent_id}. Anyone in the org can read agents; creating, changing and deleting them needs the admin role or an API key. You can also manage them in the console under Agents.

​
Instructions and the rules that always win

The model gets GuidingHand’s rules first and your instructions after them, with an explicit note that GuidingHand’s rules win where the two conflict. The rules are the same for every org and every agent, so the person at the computer gets the same protections whichever agent runs:
  • If it needs something only the person can tell it (which account, which file, a preference), it asks a question.
  • Before anything consequential or irreversible (purchases, sending messages, deleting data, submitting forms, changing settings, entering personal data), it asks for an approval that says exactly what it is about to do, and only goes ahead if approved.
  • It never types passwords, one-time codes, card numbers or other secrets, and never asks for them in a question (answers are recorded and your team sees them). It asks the person to type them on screen themselves, and carries on once they say it’s done.
  • When it finishes, it replies with a short summary of what it did. That summary is the task’s result.
So you can’t instruct an agent to skip approvals or type a password. You can make it more careful: “Ask before closing any window” works, because it adds a question or an approval rather than removing one. Good instructions are short and specific to your product:

​
Effort

effort trades speed for care. low is fast and fine for simple settings changes. medium and high think more per step, which helps with unfamiliar apps and long tasks, and makes each step slower. Leave it null to use GuidingHand’s default.

​
Greeting

The greeting is the first thing the customer reads on the invite page, above the install steps. Use it to say who is helping and why, in your own voice. It’s plain text.

​
On the customer’s screen

While a task runs, the GuidingHand app shows a banner with a Stop button. With narration on, it also shows what the agent is thinking, saying and doing, step by step, as it happens, and its summary when it finishes. display_name puts your name on it (“Acme Support is typing…”) instead of GuidingHand’s. Turn narration off if you’d rather the customer only sees that the agent is working (and its questions and approval requests, when customer_answers and customer_approvals are on). Narration is the agent’s own words, so it can repeat what it was told: after your team answers a question, the agent’s next thought or message, or its summary, may restate that answer. Turn narration off for flows where your team’s answers must stay off the customer’s screen.

​
Questions the customer can answer

When the agent asks a question, the customer often knows the answer best: which account, which printer, which file. With customer_answers on (the default), the question also appears in the app on their screen, with the agent’s suggested options, and they can answer it right there. Your team can still answer it at the same time, from the console or with POST /v1/tasks/{task_id}/respond.
  • The first answer is used. The other gets 409 conflict with error.code: "already_answered" and error.answered_by (customer or operator), so nobody’s answer is applied twice.
  • You can tell who answered. The task’s answer event has data.answered_by, and the task.question_answered webhook carries the answer and who gave it. When your team answers, the customer’s screen shows that the question was answered, not your team’s answer itself (though with narration on, the agent may repeat it in its own words, as described under “On the customer’s screen” above).
  • pending.customer_can_answer says whether the customer can answer the question that is open now: the agent allows it and their GuidingHand app is recent enough to take answers.
  • Secrets never go through questions. The agent never asks for a password, code or card number in a question. It asks the customer to type it on screen themselves.
Turn it off ("customer_answers": false, or the switch in the console under Agents) when your team should answer every question, for example when the answer depends on your records rather than the customer’s. The question then isn’t shown on the customer’s screen at all: the app only says the agent asked your team a question. The setting is read when a task starts: changing it affects the next task, not one already running. With the SDKs, tasks.run() leaves questions the customer can answer to them when you don’t pass a question handler, and keeps following the task. See JavaScript and Python.

​
Approvals the customer can decide

Before anything consequential, the agent asks for an approval that says exactly what it is about to do. It’s the customer’s computer, so with customer_approvals on (the default), the request also appears in the app on their screen, and they can allow it or not right there. Your team can still decide it at the same time, from the console or with POST /v1/tasks/{task_id}/respond. It works like questions:
  • The first decision is used. The other gets 409 conflict with error.code: "already_answered" and error.answered_by.
  • You can tell who decided. The task’s approved and denied events have data.answered_by, and the task.approval_decided webhook carries the decision and who made it. Only your team can add a note for the agent.
  • pending.customer_can_approve says whether the customer can decide the approval that is open now: the agent allows it and their GuidingHand app is recent enough to show approvals (1.0.16 or later).
Turn it off ("customer_approvals": false, or the switch in the console under Agents) when your team should decide every approval, for example when a policy says who may sign off. The request then isn’t shown on the customer’s screen: the app only says the agent is waiting for your team. Like customer_answers, it is read when a task starts. Without an approval handler, the SDKs’ tasks.run() leaves approvals the customer can decide to them, and keeps following the task.

​
The default agent

Every org has an agent with agent_id: "default" and is_default: true. It exists before you set anything up: with no instructions, it runs on GuidingHand’s rules alone. Sessions and tasks that don’t name an agent use it.
  • PATCH /v1/agents/default gives it your own instructions, effort, greeting and the settings above. Until then it has narration, customer_answers and customer_approvals on and no display_name.
  • DELETE /v1/agents/default resets it to GuidingHand’s own instructions. It doesn’t go away. (If it was never customized, this returns 404.)
Deleting any other agent switches the sessions made with it to default. A session’s invite_url names your org and, unless it is the default agent, the agent: For example https://guidinghand.ai/acme/K7QM-24XP or https://guidinghand.ai/acme/billing/K7QM-24XP. {org} is your org’s address (its slug), which the org owner can change in the console. Each agent’s invite_url_template is the same link with {code} in place of the code. Links in the older /join/CODE?t=… form still work.

​
Choosing an agent per session or task

  • POST /v1/sessions takes agent_id. The session’s tasks run that agent, and its invite link and greeting belong to it.
  • POST /v1/sessions/{session_id}/tasks also takes agent_id, to run one task with a different agent than the session’s. An unknown agent_id returns 404 not_found.