> ## Documentation Index > Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt > Use this file to discover all available pages before exploring further. # Agents > An agent is your org's configuration for the AI: instructions, reasoning effort, a greeting, and what the customer sees, may answer and may approve. 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. ```json theme={null} { "object": "agent", "agent_id": "billing", "name": "Billing help", "instructions": "Our billing app is Acme Billing. Open it from the Dock before anything else.", "effort": "medium", "greeting": "Hi, this is Acme support. We will fix your billing settings together.", "display_name": "Acme Support", "narration": true, "customer_answers": true, "customer_approvals": true, "is_default": false, "invite_url_template": "https://guidinghand.ai/acme/billing/{code}", "created_at": "2026-09-26T15:03:36.037Z", "updated_at": "2026-09-26T15:03:36.037Z" } ``` | Field | What it does | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agent_id` | 2 to 40 lowercase letters, numbers and dashes. It appears in invite links. Made from `name` if you leave it out. It can't be changed later. | | `name` | Shown in the console. Up to 80 characters. Required when creating. | | `instructions` | Your instructions to the model, up to 20,000 characters. Added under GuidingHand's own rules (below). | | `effort` | `low`, `medium`, `high`, or `null` for GuidingHand's default. How much the model reasons per step. | | `greeting` | Shown to the customer on the invite page, up to 500 characters. | | `display_name` | What the GuidingHand app calls the agent on the customer's screen while it works ("Acme Support is typing"), up to 40 characters on one line. Empty (the default) shows "GuidingHand". | | `narration` | `true` (the default): the app shows the agent's thoughts and steps on the customer's screen as it works, and its summary when it finishes. `false`: no thoughts, steps or summary; they see the banner with the **Stop** button (and the agent's questions and approval requests, if `customer_answers` and `customer_approvals` are on). | | `customer_answers` | `true` (the default): the customer can answer the agent's questions in the app, as well as your team. `false`: only your team answers. See [below](#questions-the-customer-can-answer). | | `customer_approvals` | `true` (the default): the customer can approve or deny the agent's approval requests in the app, as well as your team. `false`: only your team decides. See [below](#approvals-the-customer-can-decide). | 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: ```text theme={null} Our desktop app is called Acme Billing. It is in the Dock or in /Applications. Customers mean "workspace" when they say "account". Never change the currency setting. If the task needs it, ask first. ``` ## 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`](/guides/webhooks#event-types) 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](/sdks/javascript) and [Python](/sdks/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`](/guides/webhooks#event-types) 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`. ## Invite links A session's `invite_url` names your org and, unless it is the default agent, the agent: | Agent | Invite link | | --------- | ------------------------------------------------ | | `default` | `https://guidinghand.ai/{org}/{CODE}` | | any other | `https://guidinghand.ai/{org}/{agent_id}/{CODE}` | 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`.