Skip to content

Site calls

When you click Close on a ticket in most web applications, the page sends a request to the site behind it, and the site closes the ticket. A site call is one of those requests, saved in a skill so the agent can send it itself. Instead of opening each ticket, finding the button, choosing a reason and waiting for the page, the agent closes three tickets with one call — from its own browser, where it is already signed in to the site.

A skill that carries site calls still has its ordinary steps. Whenever a call cannot be used — the site refuses it, the site has changed, the workspace does not allow calls — the agent does that step on the page instead, the way it always has.

Site calls are most often part of a browser workflow: a connector for one website whose tools each carry the calls for one area of work. How to lay one out is in Organizing a browser workflow.

A site call is a file in a skill’s Scripts, under calls/ — calls/close_ticket.json, for example. It says which request to send, what the agent must fill in, and what the call may and may not change. A skill holds up to 20 calls.

When a task uses one, the request goes out from the agent’s browser tab on that site, as whoever is signed in there — the same request the site’s page would have sent. The site has to be open in that tab. A call goes only to the site itself or to the data addresses its own page uses; a call to any other site is not sent.

Calls come in two kinds:

KindWhat it doesAsks first?
ReadFetches data: a list of open tickets, one ticket’s details, a report. A GET or HEAD request, or a POST the site uses only to search or listNo — reads run at once
ChangeChanges data: closes a ticket, updates a record. A POST, PUT or PATCH requestYes — on an approval card, every time unless you approve all

There are three ways, and each one ends with a person’s approval or a person’s own edit.

1. Train the agent. In a training session you do the job on the agent’s computer — yourself, or by letting the agent do it while you watch. While the site is used, the agent can see the requests the site’s page sends — their addresses, the names of their fields and headers and the shape of each answer, not the values in them; the values are in a recording of the step. It writes a call for each step worth turning into one, checks every call against what the site was seen sending, and keeps the skill under Learned so far. When you press Save · N, the card lists each call in plain words:

  • “get_ticket” reads: Read one ticket: its status, assignee and notes. (GET /api/tickets/{id}) from desk.example.com
  • “close_ticket” changes data: PUT /api/tickets/{id}/status on desk.example.com — never changes assignee, priority — read back with “get_ticket” afterwards — always sends status = closed

Each value a call always sends, whatever the agent fills in, is listed as an always sends line, so you see the fixed values before you approve (a long list is shortened to a few lines and how many more). A credential, or a value under a field named like a password, token or key, is named but never shown: always sends token (a credential, hidden).

Approve saves the skill with its calls. A call the agent wrote can be saved only if it passed its check with exactly the content being saved, so a call you change on the card has to be checked by the agent again before it can be saved.

Generate with agent on a browser workflow works the same way for a workflow’s tools: you use the site together on the session’s computer, the agent finds and checks the requests, and its proposal card saves the tools with their calls.

2. Ask the agent builder. In Create or Refine, with the computer in Try it open and in view, use the site on that computer — or let the builder use it — and ask the builder to turn a step into a site call. It checks each call the same way and adds the skill to your draft, where the Skills section lists its calls. Saving the agent is the approval: the skill is saved as one of the agent’s own skills. The builder never sends a change call, not even to test one.

3. Write one by hand. Anyone who can edit a skill can add a call themselves: on the skill’s page, in its panel in the agent builder, or in a browser workflow tool’s Editor, choose Add script and give it a path such as calls/close_ticket.json. A hand-written call is checked for mistakes when you save, but not against the site, and the skill says so: Written by hand, not checked against the site.

  1. It does the step once in the browser, the ordinary way — or watches you do it.
  2. It reads the list of requests the page sent in that tab: each one’s method, address, the names of its query and body fields, the names of the headers it carried, and the shape of its answer — not the values. When a call needs a value the page never shows, such as a hidden field’s, it reads what the page sent from a recording of the step, with credentials hidden, or asks you to record the step once.
  3. It takes only a request the site’s own page made. It never guesses an address, and never turns a sign-in, security, token or analytics request into a call.
  4. For a change, it reads the rules of the site’s own form — required fields, lengths, patterns, the options a list offers — without submitting it, and writes them into the call’s inputs. A rule it cannot see, it asks you about.

Before a call the agent wrote can be saved, the agent checks it against the site, in the same session:

  • The site’s page must have made this request in that session: the same method, address, query fields, body fields and borrowed headers. A call that leaves out a sign-in header the page sent fails its check, because the site would refuse it.
  • A read runs once for real, and its answer is shown to the agent. A POST the site uses only to search or list runs for real in a check only when the page itself sent exactly that request to the same address, the site answered it with success, and its address (or a field such as cmd) names a read — get, list, search and the like.
  • When the check is not sure, it asks you. If such a POST might change something — its address is not exactly the page’s, its fields differ, it does not name a read, or a word in it may name an action — a card asks Send this once for real?, showing exactly the request and why the check is not sure. Approve sends exactly that request once; Decline sends nothing. Approve all, an approval level, even Never ask, and an automation never answer it for you, and a skill test never sends it.
  • A change is built and shown, but not sent. If you name a record that is safe to change, the agent can also make that one change for real while it checks — on an approval card, and only after you approve it. It never changes a record you did not name.
  • The check covers the exact content. Change anything afterwards — an input’s rule, the description, even a space — and the call has to be checked again before it can be saved.
  • No credential in a call. A call with a password, token, key or connection string written into it fails its check and is refused when it is saved, whether the agent wrote it or you edited it. A call borrows its sign-in from the page; it never carries one.

Exporting what was checked. Ask the agent to export its checked calls: it writes each one, exactly as checked and with any credential hidden, as a file on the agent’s computer, in out/site-calls/ — useful when a call was checked early in a long session. To download one, ask the agent to add it to the task’s files.

On a workspace that holds regulated data, calls are not run against the site: only the file and its match with the page’s requests are checked.

A service desk at desk.example.com shows each ticket on its own page, and the page reads it with one request and closes it with another. A skill for closing resolved tickets could carry these two calls.

calls/get_ticket.json — a read:

{
"name": "get_ticket",
"description": "Read one ticket: its status, assignee and notes.",
"method": "GET",
"url": "https://desk.example.com/api/tickets/{id}",
"inputSchema": {
"type": "object",
"properties": {
"id": { "type": "string", "pattern": "^[0-9]+$" }
},
"required": ["id"]
},
"returns": "json"
}

calls/close_ticket.json — a change:

{
"name": "close_ticket",
"description": "Close one ticket with a reason and an optional note.",
"method": "PUT",
"url": "https://desk.example.com/api/tickets/{id}/status",
"inputSchema": {
"type": "object",
"properties": {
"id": { "type": "string", "pattern": "^[0-9]+$" },
"reason": { "type": "string", "enum": ["Resolved", "Duplicate"] },
"note": { "type": "string", "maxLength": 200 }
},
"required": ["id", "reason"]
},
"body": {
"kind": "json",
"template": { "status": "closed", "reason": "{reason}", "note": "{note}" }
},
"auth": { "borrow": ["x-csrf-token"] },
"target": { "param": "id", "label": "Ticket" },
"forbiddenFields": ["assignee", "priority"],
"verify": {
"call": "get_ticket",
"params": { "id": "{id}" },
"ignore": ["status", "closedAt", "updatedAt"]
}
}
FieldWhat it says
nameThe call’s name: lower-case letters, digits and _, starting with a letter, up to 40 characters. It must be the file’s name too — close_ticket lives in calls/close_ticket.json
descriptionWhat the call does, in one line of up to 300 characters. The agent reads it to choose the call
methodGET, HEAD, POST, PUT or PATCH. DELETE cannot be saved — see Limits
urlThe address, up to 2,000 characters. It starts with a fixed site address (https://desk.example.com/…, or http:// for a site served that way) or with one of the skill’s variables followed by a path ({site_url}/api/…; see Addresses and settings). {id}-style blanks in the path and query are filled from the inputs. The site address itself can never come from an input, a query field’s name can never be a blank, and there is no #fragment
inputSchemaWhat the agent must supply: an object whose properties (up to 50) are each a string, integer, number or boolean, with required listing the ones that must be given. A property can carry description, enum (a list of allowed values), pattern (up to 200 characters), minLength and maxLength, minimum and maximum, or format (date or date-time). allOf with if / then pairs can make an input required only when another has a given value. A value that breaks a rule is not sent
bodyFor a change, the fields sent, as json or as a form, written as a template with blanks. It sends the fields the page sent — every one it always sent, none it never sent. An optional value the agent leaves out is left out of the request too
pageOnly for a site whose data lives on another address: the address of the page the call runs from, such as {site_url}. See Sites whose data lives on another address
auth.borrowThe names of the sign-in headers the site’s own page sends with this request, such as x-csrf-token, x-xsrf-token, authorization or any x-…-token. Their values are borrowed from the page at the moment of the call — never written in the file. cookie, host and headers the browser sets itself cannot be listed
returnsjson (the default), text, or file — a file lands in the task’s files
readOnlyOnly on a POST the site uses to search or list: true makes it a read. Its address and body may not name an action, and an input in its path must have an enum or a pattern. Every place that shows the call says This POST is treated as a read, so it runs without a card
targetRequired on a change: which input names the record (it must be a required input), and what to call it on the approval card (Ticket 4812)
forbiddenFieldsFields this call must never send, and the site must never change along the way (assignee, approvedBy). A call whose body names one cannot be saved. A field the change is meant to alter belongs in verify.ignore instead
verifyFor a change: a read call in the same skill (never the call itself), with the inputs to give it, run before and after each change to check what actually changed. ignore lists the fields the change is meant to alter, or that the site updates on its own

A call the agent wrote also carries a record of the request it was matched with (observed); you never write that part yourself.

A call in a browser workflow works for every company that uses the workflow, because its address starts with one of the workflow’s variables rather than with one company’s site:

"url": "{site_url}/api/tickets/{id}"

Each company fills in its own value for site_url when it creates its connector, and the call is built from that value when the task runs. Three rules hold:

  • A variable at the start of an address is the site’s address only — https://desk.example.com, with or without a final /. A value with a path, a query or a user name in it (https://desk.example.com/app) is refused when the call is built: The variable “site_url” must be the site’s address only (like https://host), with no path, query or sign-in. When the site lives under a path, put the path in the call: {site_url}/app/api/tickets/{id}.
  • It must be followed by a path, and it must be one of the workflow’s own variables. Give such a variable the kind Web address, so the connector’s settings refuse anything that is not an http:// or https:// address.
  • Other variables can appear inside the address or the body, such as a tenant or region of kind Text ({site_url}/api/{tenant}/orders). Only Web address variables count as the workflow’s addresses when sign-in headers are shared between them; a Text variable that happens to hold an address never does.

Many web applications sign you in at one address and fetch their data from another: the page you use is app.example.com, while its lists and records come from api.example.com. The page signs in once, keeps a sign-in token, and sends it with every request to the data address — usually as an Authorization: Bearer … header, often with a company or language header beside it.

A call for such a site names the page it runs from with page:

{
"name": "list_open_orders",
"description": "Every open order, newest first.",
"method": "GET",
"url": "{api_url}/orders?status=open",
"page": "{site_url}",
"auth": { "borrow": ["authorization", "x-tenant-id"] },
"returns": "json"
}

What happens when the agent uses it:

  1. The page at {site_url} is signed in, in the agent’s browser — by the agent with a stored sign-in, or by you in the live view. The page then calls its data address the way it always does.
  2. The agent sends the call from that page’s tab, to {api_url}. The Authorization and x-tenant-id values are borrowed from the page’s own most recent request to that address — the token is never stored, never written into the skill, and never shown to the agent.
  3. The site’s own rules for which pages may call it (its CORS settings) apply as for the page itself. If the site does not let its page make the call, the agent is told so and does the step on the page.

The rules that keep this safe:

  • Only addresses the page itself uses. A call goes to another address only if the page in that tab has already called it during the computer’s session — or has called another of the same workflow’s data addresses, under the rule below. The agent cannot point a signed-in page at an address of its own choosing. Until then, the transcript says the page has not called that host from this tab.
  • A header must have been seen. A borrowed header comes from what the page sent from that tab. If the page has not sent it yet, nothing is sent: The page has not sent authorization to api.example.com from this tab yet. Use the site’s page once (or reload it), then check again.
  • Everything else is unchanged. Reads run at once, changes ask on a card, the record must have been seen in the task, and every answer is cleaned of sign-in values before the agent reads it.

In a browser workflow, declare each address as a variable of kind Web address — site_url for the page and api_url for the data address — and the calls use them as {site_url} and {api_url}. Short headers that are not secrets, such as a tenant or language id, are sent as they are; a short sign-in token is refused, because it could not be kept out of the answer.

Some sites spread their data over several addresses, and the page sends its sign-in token to only some of them: it sends Authorization to orders.example.com, say, while the call you need goes to billing.example.com, which the page reaches another way. A call may then use the sign-in headers the page sent to another of the same browser workflow’s data addresses — only when all three of these hold:

  • Both addresses are settings of that workflow. The call’s own address and the one it borrows from are both values of the workflow’s Web address variables ({orders_url}, {billing_url}). An address that is not one of them never lends, and never borrows.
  • Both are on the same site as the page — the same registrable domain, such as example.com for app.example.com, orders.example.com and billing.example.com.
  • The page itself called the address that lends, from the same tab.

The page’s own address ({site_url}) never lends: only data addresses do. A header the page sent to the call’s own address always wins over a borrowed one, and a borrowed value is cleaned from the answer like any other.

Never shared: intranet names (tms or tms.corp), IP addresses, and shared hosting domains where every customer’s app is a site of its own — an address ending in azurewebsites.net, herokuapp.com, github.io or cloudfront.net, for example. There each address needs the headers the page sent to it. A computer that does not yet have the latest update shares nothing either.

The agent can give one call several sets of inputs at once — its items:

  • A read takes up to 10 items — ten tickets read in one call.
  • A change takes up to 25 items, and one approval card covers them, listing every record and the values it will set. More records take another call, and another card.

A skill’s steps should say so: Call “close_ticket” once, with every ticket to close (up to 25 per call). If it is refused or fails, do the step on the page. They should not ask for your approval in the conversation as well — the card is the approval, and asking twice only slows you down.

A read can bring back far more than the agent should carry through the conversation — a month of invoices, thousands of rows. An answer of more than about 20 KB is kept as a file in the task’s files, the same way a connector’s large result is:

  • The agent gets the file’s path and a short preview, and reads the file with a script on its computer. Counts, totals and filters are worked out over every row of the file — never from the preview, and never retyped. A list of ten or more rows is also kept as a data file for that purpose.
  • You can open and download it. The file is listed on the Documents tab of the task’s side panel, under Agent’s artifacts, and opens in the file viewer; a long one-line JSON answer is laid out for reading there, while the download is the answer exactly as the site sent it.
  • It follows the connector rule. It is removed from the agent’s computer a few minutes after it arrives, and put back when one of the agent’s scripts needs it. It can be opened and downloaded for an hour after it was fetched, because a site’s data goes out of date; after that the agent calls the site again. A record the agent read from the file counts as seen in the task while the file is kept.
  • Up to 8 MB. A longer answer is not read: the agent is told to ask for less — a filter, a smaller page, a shorter date range.
  • Never cut in the middle. If part of an answer did not reach the agent, it is told so and stopped from sending anything built on it, as with a connector; see When a connector’s data comes back incomplete.

A read of several items keeps every answer. When the agent reads more than one item in one call, each item’s answer is kept as a file too, however short, so a script can work over all of them. This needs an agent that can run scripts on its computer; otherwise the answers come back in the conversation.

A skill whose reads can be long should say so in its steps: A long answer comes back as a file: count, total or filter it with a script that reads that file. The transcript line still counts every item: Read 1,901 items from desk.example.com (GET, 200).

Reads run without asking; changes always ask. Each change call waits on one approval card for up to 25 records — The agent wants to run “close_ticket” from “‹skill›” on desk.example.com for 3 records. Allow it? — listing every record and the values it will set. Approve makes those changes once, Approve all also covers the task’s later site-call changes, and Decline sends nothing. In a task started by an automation that runs on its own, the changes are made without a card, and the transcript says each one was done without asking — as for the agent’s other actions.

The record must have been seen in the task. A change is sent only for a record whose id came from an earlier answer in the same task — a site call’s or a connector’s, a kept long answer included — or from your own message. An id the agent made up, or copied wrong, is not sent.

Read before and after. A change call with verify reads the record before and after each change. If anything changed beyond what the call is meant to change, the transcript says changed more than expected and the rest of the batch stops. Fields every change touches on its own — updatedAt, version, etag and the like — are not counted.

Protected fields. The fields in forbiddenFields are never sent, and the read-back reports a change to one.

Paced. Changes go one at a time, at least a second apart, and a task changes at most 500 records this way; past that, a new task continues the work.

A site that refuses stops. If the site refuses a call, or answers with a challenge page, the agent sends no more calls to that site in the task and does the step on the page. If the agent has been signed out, it signs in again in the browser, or asks you to in the live view, and tries again.

A changed site falls back to the page. When a site answers that the call no longer exists, nothing more is sent, the agent does the step on the page, and the transcript notes ‹call›: The call needs re-recording. Record it again with training, the builder or Generate with agent.

A change is never sent twice on its own. If the site fails while a change is being made, the agent is told it may or may not have been applied, and reads the record before trying again. The transcript says May have changed Ticket 4812 on desk.example.com.

Tokens and cookies stay in the browser. The sign-in values a call needs are borrowed from the page at the moment it is sent — headers of up to 32 KB each, so the long sign-in tokens some sites use work too. They are never stored, never written into a skill, and never shown to the agent or in the transcript; anything the site sends back is cleaned of them before the agent reads it. An answer that still carries the page’s token, even encoded, is not passed on. The agent’s own scripts on the computer cannot reach the signed-in browser.

Credentials with a recognisable shape are hidden. Whatever its field is called, a value is shown as [hidden:secret] when it has the shape of a credential: a connection string with a password, a sign-in token, a private key, a web address with a password in it, or an API key in a well-known format. It is hidden in a recording, in a call’s answer and on the cards. A password or token that looks like ordinary text may not be recognised, and is then not hidden. A file a call saves keeps the site’s original values on the agent’s computer; what the agent reads from it is hidden. A saved file with too many credentials to hide one by one is withheld from the agent whole, and the agent is told so.

What runs is what was saved. A task runs the calls as they were saved when it loaded the skill. A save made while the task runs applies from the next task, and nothing on the computer can change what a call does.

Every call leaves one line in the transcript:

  • Read 42 items from desk.example.com (POST, 200)
  • Changed Ticket 4812 on desk.example.com (PUT, 200)
  • Did not change Ticket 4812 on desk.example.com: refused by the site (403)

When a skill with calls is tested — a skill test in a training session, or a skill trial in a task — its read calls run for real and its change calls are never sent. A change in a test is answered as a trial, with nothing sent to the site.

A call that cannot be sent, or whose answer cannot be used, ends in a line such as Could not read from api.example.com: the page has not called that host from this tab. The agent then does the step on the page, or tries again once the cause is gone. What each reason means:

The line saysWhat it meansWhat helps
the page has not called that host from this tabThe call goes to a data address the page in that tab has not used yet in this sessionUse the site’s page once so it loads its data, then the agent calls again. For a site with several data addresses, see One site, several data addresses
the page has not sent ‹header› from this tab yetA sign-in header the call borrows has not been seen on the page’s requests to that addressUse the page once, or reload it, after signing in. If the page never sends that header to that address, the call’s auth.borrow or its address is wrong
the ‹header› header is too short to hideThe site’s own sign-in value is too short to keep out of the answer safely, so nothing was sentThe step is done on the page; nothing to fix
signed out / redirected after it was sentThe site answered as if nobody were signed inThe agent signs in again, or asks you to, and tries once more
wrong page openNo tab is on the call’s site, or more than one tab is — the agent is asked to close the others and keep the one signed in to the right accountKeep one tab on the site
the site does not let its page call that host this wayThe browser refused the request under the site’s own CORS rulesThe step is done on the page; the call cannot work as written
the answer is too largeThe answer is over 8 MB (256 KB for a change, or on a computer without the latest update)Ask for less: a filter, a smaller page, a shorter date range
refused by the siteThe site refused the call (403) or answered with a challenge pageNo more calls go to that site in this task. Check that the account may do this on the page
the site said noThe site answered with another error, often because it did not accept a value; the agent reads the site’s reasonThe agent corrects the value, or does the step on the page
the site said it failedThe site answered, but its answer says the change did not workThe agent reads why, and does the step on the page if it cannot fix it
site errorThe site had an error of its own. A read is tried twice; a change may or may not have been applied, and is read back before anything elseTry again later
the call may be out of dateThe site answered as if the call no longer existedRecord the call again
a value given looks like an action, so nothing was sentA read was given a value that looks like an action wordNothing was sent; the agent asks again with a proper value or uses the page
the file could not be savedA file answer, or a long answer, could not be kept in the task’s filesThe data did not reach the agent; it says so
  • No deletes yet. A DELETE call cannot be saved. The agent deletes on the page, asking first as it always does.
  • A read that looks like an action is refused when saved. A read whose address contains an action word — close, update, save, delete, create, send and the like — cannot be saved, even when it is harmless (/post/{id}). The agent then does that step on the page. A PUT or PATCH is never a read.
  • Off on regulated workspaces. On a workspace that holds regulated data, no task uses site calls, and they cannot be checked against the site there.
  • An updated computer is needed. Until a task’s computer has the update, the agent uses the page.
  • Signing in stays on the page. Signing in, security checks and anything to do with passwords are never site calls; the agent signs in on the page, with a stored sign-in or with your help.
  • Fixed limits. Up to 20 calls per skill, 10 items per read, 25 records per approval card and 500 changed records per task, paced one change per second. These cannot be changed per site yet.
  • Answers have a size limit. A read’s answer can be up to 8 MB, and one over about 20 KB is kept as a file. A change’s answer is read up to 256 KB, and so is every answer on a computer that does not yet have the latest update. A call that returns a file can bring one of up to 25 MB into the task’s files.
ActionWho
Make calls in training or with the agent builderAnyone who may edit the agent
Make calls with Generate with agentWhoever may change the browser workflow
Write or change a call by handAnyone who may edit the skill — for an agent’s own skill, anyone who may edit the agent; for a browser workflow’s tool, whoever may change the workflow
Use a skill’s callsAny task that loads the skill
Approve a changeWhoever answers the task’s approval card, as for any other approval
Answer Send this once for real?Whoever answers the task’s cards; Approve all never covers it