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.
What a site call is
Section titled “What a site call is”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:
| Kind | What it does | Asks first? |
|---|---|---|
| Read | Fetches 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 list | No — reads run at once |
| Change | Changes data: closes a ticket, updates a record. A POST, PUT or PATCH request | Yes — on an approval card, every time unless you approve all |
How site calls are made
Section titled “How site calls are made”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.
How the agent finds a request
Section titled “How the agent finds a request”- It does the step once in the browser, the ordinary way — or watches you do it.
- 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.
- 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.
- 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.
How a call is checked
Section titled “How a call is checked”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
POSTthe 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 ascmd) names a read — get, list, search and the like. - When the check is not sure, it asks you. If such a
POSTmight 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.
An example
Section titled “An example”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"] }}Every field
Section titled “Every field”| Field | What it says |
|---|---|
name | The 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 |
description | What the call does, in one line of up to 300 characters. The agent reads it to choose the call |
method | GET, HEAD, POST, PUT or PATCH. DELETE cannot be saved — see Limits |
url | The 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 |
inputSchema | What 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 |
body | For 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 |
page | Only 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.borrow | The 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 |
returns | json (the default), text, or file — a file lands in the task’s files |
readOnly | Only 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 |
target | Required 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) |
forbiddenFields | Fields 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 |
verify | For 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.
Addresses and settings
Section titled “Addresses and settings”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://orhttps://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.
Sites whose data lives on another address
Section titled “Sites whose data lives on another address”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:
- 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. - The agent sends the call from that page’s tab, to
{api_url}. TheAuthorizationandx-tenant-idvalues 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. - 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.
One site, several data addresses
Section titled “One site, several data addresses”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.comforapp.example.com,orders.example.comandbilling.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.
Several records in one call
Section titled “Several records in one call”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.
Long answers
Section titled “Long answers”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).
What keeps them safe
Section titled “What keeps them safe”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)
Skill tests
Section titled “Skill tests”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.
When a call does not go through
Section titled “When a call does not go through”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 says | What it means | What helps |
|---|---|---|
| the page has not called that host from this tab | The call goes to a data address the page in that tab has not used yet in this session | Use 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 yet | A sign-in header the call borrows has not been seen on the page’s requests to that address | Use 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 hide | The site’s own sign-in value is too short to keep out of the answer safely, so nothing was sent | The step is done on the page; nothing to fix |
| signed out / redirected after it was sent | The site answered as if nobody were signed in | The agent signs in again, or asks you to, and tries once more |
| wrong page open | No 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 account | Keep one tab on the site |
| the site does not let its page call that host this way | The browser refused the request under the site’s own CORS rules | The step is done on the page; the call cannot work as written |
| the answer is too large | The 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 site | The site refused the call (403) or answered with a challenge page | No more calls go to that site in this task. Check that the account may do this on the page |
| the site said no | The site answered with another error, often because it did not accept a value; the agent reads the site’s reason | The agent corrects the value, or does the step on the page |
| the site said it failed | The site answered, but its answer says the change did not work | The agent reads why, and does the step on the page if it cannot fix it |
| site error | The 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 else | Try again later |
| the call may be out of date | The site answered as if the call no longer existed | Record the call again |
| a value given looks like an action, so nothing was sent | A read was given a value that looks like an action word | Nothing was sent; the agent asks again with a proper value or uses the page |
| the file could not be saved | A file answer, or a long answer, could not be kept in the task’s files | The data did not reach the agent; it says so |
Limits
Section titled “Limits”- No deletes yet. A
DELETEcall 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. APUTorPATCHis 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.
Who can do what
Section titled “Who can do what”| Action | Who |
|---|---|
| Make calls in training or with the agent builder | Anyone who may edit the agent |
| Make calls with Generate with agent | Whoever may change the browser workflow |
| Write or change a call by hand | Anyone 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 calls | Any task that loads the skill |
| Approve a change | Whoever 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 |