curl --request POST \
--url https://guidinghand.ai/v1/agents/{agent_id}/procedures \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
"<string>"
],
"checks": "<string>",
"body": "<string>",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: '<string>',
use_when: '<string>',
inputs: [
{
name: '<string>',
type: 'text',
description: '<string>',
required: true,
options: ['<string>'],
example: '<string>'
}
],
goal: '<string>',
context: '<string>',
instructions: '<string>',
steps: ['<string>'],
checks: '<string>',
body: JSON.stringify('<string>'),
tools: ['<string>'],
approval: {required: true, by: 'anyone', who: '', covers: [], note: ''},
category: '<string>'
})
};
fetch('https://guidinghand.ai/v1/agents/{agent_id}/procedures', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://guidinghand.ai/v1/agents/{agent_id}/procedures"
payload = {
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": True,
"options": ["<string>"],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": ["<string>"],
"checks": "<string>",
"body": "<string>",
"tools": ["<string>"],
"approval": {
"required": True,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "procedure",
"id": "prc_…",
"agent_id": "<string>",
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
{
"id": "<string>",
"text": "<string>",
"subprocedure": {
"id": "<string>",
"title": "<string>",
"missing": true
}
}
],
"checks": "<string>",
"body": "<string>",
"status": "active",
"kind": "browser",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"model": "claude-haiku-5-5",
"plan_mode": "off",
"plan": {
"mode": "off",
"status": "off",
"revision": 123,
"compiled_at": "2023-11-07T05:31:56Z",
"error": "<string>",
"steps_count": 123,
"vars": [
{
"name": "<string>",
"description": "<string>",
"list": true
}
],
"steps": [
{
"id": "<string>",
"kind": "ask",
"text": "<string>",
"inputs": [
"<string>"
],
"tool": "<string>",
"args": [
{
"name": "<string>",
"value": "<string>"
}
],
"options": [
{
"when": "<string>",
"next": "<string>"
}
],
"procedure": "<string>",
"next": "<string>",
"type": "open",
"url": "<string>",
"page": "<string>",
"keys": [
"<string>"
],
"target": {
"role": "<string>",
"label": "<string>"
},
"focus": {
"role": "<string>",
"label": "<string>"
}
}
],
"recorded_from": "<string>"
},
"category": "<string>",
"written_by": "person",
"source_task_id": "<string>",
"revision": 123,
"uses_30d": 123,
"last_used_at": "2023-11-07T05:31:56Z",
"avg_run_cents_30d": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"evals": {
"test_cases": 4,
"last_run": {
"test_run_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"tries": 123,
"passed": 123,
"pass_rate": 123,
"found": 123,
"revision": 123,
"current": true
}
},
"references": [
{
"type": "tool",
"id": "<string>",
"name": "<string>",
"title": "<string>",
"missing": true
}
],
"file_access": "read_only"
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}Add a procedure
curl --request POST \
--url https://guidinghand.ai/v1/agents/{agent_id}/procedures \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
"<string>"
],
"checks": "<string>",
"body": "<string>",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
title: '<string>',
use_when: '<string>',
inputs: [
{
name: '<string>',
type: 'text',
description: '<string>',
required: true,
options: ['<string>'],
example: '<string>'
}
],
goal: '<string>',
context: '<string>',
instructions: '<string>',
steps: ['<string>'],
checks: '<string>',
body: JSON.stringify('<string>'),
tools: ['<string>'],
approval: {required: true, by: 'anyone', who: '', covers: [], note: ''},
category: '<string>'
})
};
fetch('https://guidinghand.ai/v1/agents/{agent_id}/procedures', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://guidinghand.ai/v1/agents/{agent_id}/procedures"
payload = {
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": True,
"options": ["<string>"],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": ["<string>"],
"checks": "<string>",
"body": "<string>",
"tools": ["<string>"],
"approval": {
"required": True,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"category": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text){
"object": "procedure",
"id": "prc_…",
"agent_id": "<string>",
"title": "<string>",
"use_when": "<string>",
"inputs": [
{
"name": "<string>",
"type": "text",
"description": "<string>",
"required": true,
"options": [
"<string>"
],
"example": "<string>"
}
],
"goal": "<string>",
"context": "<string>",
"instructions": "<string>",
"steps": [
{
"id": "<string>",
"text": "<string>",
"subprocedure": {
"id": "<string>",
"title": "<string>",
"missing": true
}
}
],
"checks": "<string>",
"body": "<string>",
"status": "active",
"kind": "browser",
"tools": [
"<string>"
],
"approval": {
"required": true,
"by": "anyone",
"who": "",
"covers": [],
"note": ""
},
"model": "claude-haiku-5-5",
"plan_mode": "off",
"plan": {
"mode": "off",
"status": "off",
"revision": 123,
"compiled_at": "2023-11-07T05:31:56Z",
"error": "<string>",
"steps_count": 123,
"vars": [
{
"name": "<string>",
"description": "<string>",
"list": true
}
],
"steps": [
{
"id": "<string>",
"kind": "ask",
"text": "<string>",
"inputs": [
"<string>"
],
"tool": "<string>",
"args": [
{
"name": "<string>",
"value": "<string>"
}
],
"options": [
{
"when": "<string>",
"next": "<string>"
}
],
"procedure": "<string>",
"next": "<string>",
"type": "open",
"url": "<string>",
"page": "<string>",
"keys": [
"<string>"
],
"target": {
"role": "<string>",
"label": "<string>"
},
"focus": {
"role": "<string>",
"label": "<string>"
}
}
],
"recorded_from": "<string>"
},
"category": "<string>",
"written_by": "person",
"source_task_id": "<string>",
"revision": 123,
"uses_30d": 123,
"last_used_at": "2023-11-07T05:31:56Z",
"avg_run_cents_30d": 123,
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"evals": {
"test_cases": 4,
"last_run": {
"test_run_id": "<string>",
"at": "2023-11-07T05:31:56Z",
"tries": 123,
"passed": 123,
"pass_rate": 123,
"found": 123,
"revision": 123,
"current": true
}
},
"references": [
{
"type": "tool",
"id": "<string>",
"name": "<string>",
"title": "<string>",
"missing": true
}
],
"file_access": "read_only"
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}{
"error": {
"type": "invalid_request",
"message": "<string>",
"code": "<string>",
"test_case_ids": [
"<string>"
],
"decided_by": {
"type": "person",
"email": "<string>",
"key_id": "<string>"
},
"conversation_id": "<string>",
"agent_id": "<string>",
"approval_id": "<string>",
"question_id": "<string>"
}
}Authorizations
An org API key (gh_live_…) from Settings → API keys in the console.
Path Parameters
The agent’s id.
Body
A new procedure needs instructions (or body).
20Show child attributes
Show child attributes
What done looks like. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}.
Background, policy, definitions and notes the steps rely on that aren’t steps themselves; the model reads it before the steps. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}.
10000The steps as one numbered Markdown list (steps is the same as a list). Sent instead of steps, it’s read into steps: one per item, sub-points under their step; prose before step 1 or after the last one joins context. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}.
The steps, in order: each its text, or { id, text } to keep a step’s id (as the procedure gives them back). A step sent as text keeps the id of a step it had with the same text, or of the step it replaces. Not with instructions or body. A step that links another procedure ([[procedure:<id or title>]]) calls it as a subprocedure.
100The step’s text (Markdown).
What to confirm before answering, as a list. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}.
The whole text instead of its parts (not with them): split into them by its ## Inputs, ## Goal, ## Context, ## Instructions and ## Checks headings (or its trailing “Check:” lines), with tool names and quoted procedure titles linked. The parts together are up to 20,000 characters.
active, draft browser, desktop, chat Up to 10 of the agent’s HTTP tools, by name (of its published version). Each stays locked in a task until the agent reads this procedure. The whole list: [] detaches them all.
10Ask a person in the conversation before a task follows this procedure. null or { "required": false } turns it off. The whole setting: fields left out take their defaults.
Show child attributes
Show child attributes
The model this procedure runs on instead of the agent's (one of the agent model values), or null for the agent's own. Once a chat reads the procedure, the rest of the conversation runs on this model; a browser or computer task that follows it does too. An eval run that tries the agent on models it picked keeps those. Changing it makes a new revision.
claude-haiku-5-5, claude-sonnet-5-5, claude-opus-5-5, claude-fable-5-1, gpt-6-luna, gpt-6.1-sol, gpt-6-astra, gemini-3.8-flash, gemini-4-argon, null Whether Eager runs this procedure without the agent's model: off (the model follows it), test (only in evals and test chats) or live (every conversation). A chat procedure is compiled into steps in the background when it's turned on or a new revision is saved; a browser procedure is recorded from the next run of it that works (its pages, clicks and typing, the procedure's inputs as blanks) and replayed after that, a small model reading the answer off the last screen. A step that needs judgement, or that can't be done for sure, hands the conversation (or the task) to the model from where it got to. Changing it doesn't make a new revision.
off, test, live The kind of request it's for, from the same set as the test cases' category (the eval charts group pass rates by it), or null for none. Spelled as a test case or procedure in the org already has it, whatever its capitals. Its test cases are always in it (a category sent for one is ignored), and move with it when it changes. Changing only the category makes no new revision. Up to 100 characters.
100Whether the agent may create, change and delete its own files (write_file, edit_file, delete_file, and with Run code save_sandbox_file, which keeps a file its code made) while a conversation follows this procedure: the one it last read, found or ran on its steps, or a schedule's. read_only (the default) keeps them read-only, as everywhere else. Checked on every change, so turning it off holds at once. A test chat's or an eval's changes go to that conversation's own copy, never the real files. Every change keeps the version it replaced (GET /v1/agents/{agent_id}/file_revisions). Changing it doesn't make a new revision.
read_only, read_write Response
The procedure.
"prc_…"
120500Left out of lists.
20Show child attributes
Show child attributes
What done looks like. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}. Left out of lists.
Background, policy, definitions and notes the steps rely on that aren’t steps themselves; the model reads it before the steps. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}. Left out of lists.
10000The steps as one numbered Markdown list (steps is the same as a list). Sent instead of steps, it’s read into steps: one per item, sub-points under their step; prose before step 1 or after the last one joins context. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}. Left out of lists.
The steps, in order, each with an id that stays with it when steps are added, moved or edited. A step that links another procedure calls it: a subprocedure, which runs as it’s set up (its own steps, model and Steps without AI) before the next step. Left out of lists.
Show child attributes
Show child attributes
What to confirm before answering, as a list. Markdown. Links the agent’s tools as [[tool:<id or name>]] and its other procedures as [[procedure:<id or title>]] (kept by id, so renaming either keeps the link; a tool a procedure links is unlocked with it), and uses an input as {name}. Left out of lists.
The whole text as the agent reads it: its parts under ## headings, links as the tool’s name and the procedure’s title. Left out of lists.
20000active, draft, archived What it needs to run: a browser, a computer, or nothing beyond the chat.
browser, desktop, chat The agent’s HTTP tools it unlocks, by name: each stays locked in a task until the agent reads this procedure. Kept when the agent no longer has one.
Whether a person must approve in the conversation before a task follows this procedure; null when not. Changing it makes a new revision.
Show child attributes
Show child attributes
The model this procedure runs on instead of the agent's (one of the agent model values), or null for the agent's own. Once a chat reads the procedure, the rest of the conversation runs on this model; a browser or computer task that follows it does too. An eval run that tries the agent on models it picked keeps those. Changing it makes a new revision.
claude-haiku-5-5, claude-sonnet-5-5, claude-opus-5-5, claude-fable-5-1, gpt-6-luna, gpt-6.1-sol, gpt-6-astra, gemini-3.8-flash, gemini-4-argon, null Whether Eager runs this procedure without the agent's model: off (the model follows it), test (only in evals and test chats) or live (every conversation). A chat procedure is compiled into steps in the background when it's turned on or a new revision is saved; a browser procedure is recorded from the next run of it that works (its pages, clicks and typing, the procedure's inputs as blanks) and replayed after that, a small model reading the answer off the last screen. A step that needs judgement, or that can't be done for sure, hands the conversation (or the task) to the model from where it got to. Changing it doesn't make a new revision.
off, test, live The procedure's steps without AI (see plan_mode). The list of procedures gives steps_count; one procedure gives its steps (and a chat procedure's vars). A browser procedure's steps are recorded actions: type (open, click, double_click, type, keypress, scroll, drag, wait), with url, text (the inputs as {name} blanks), keys, page (the host and path it ran on), and target or focus (the control's role and label).
Show child attributes
Show child attributes
The kind of request it's for, from the same set as the test cases' category; null for none. Not versioned.
person, agent For one the agent wrote: the task it learned from.
What a run that used it cost on average in the last 30 days, in cents at list price (to a tenth of a cent): a conversation, or a task on its own, priced by its tasks and chat replies that got it. Finished runs only; null when there are none.
Its evals: the test cases tied to it (procedure_id), and its latest run of them (cold runs left out).
Show child attributes
Show child attributes
Left out of lists.
Show child attributes
Show child attributes
Whether the agent may create, change and delete its own files (write_file, edit_file, delete_file, and with Run code save_sandbox_file, which keeps a file its code made) while a conversation follows this procedure: the one it last read, found or ran on its steps, or a schedule's. read_only (the default) keeps them read-only, as everywhere else. Checked on every change, so turning it off holds at once. A test chat's or an eval's changes go to that conversation's own copy, never the real files. Every change keeps the version it replaced (GET /v1/agents/{agent_id}/file_revisions). Changing it doesn't make a new revision.
read_only, read_write