Agents and skills

Agents on the bus

You want the person using your application to have an agent that knows how to work it — alongside everything else on the bus. Here is what an agent is in XataWorks, and how to make one.

What an agent is

The bus carries traffic; an agent decides what traffic to send. In XataWorks an agent is a short definition:

Instructions — the procedure, in prose: which applications to use for what, in what order, and when to stop and ask.
A model — which provider and model answer for it.
Tool access — all tools, none, or a chosen set.
An approval policy — how its own tool calls are approved.
Web permissions — sites it may use without the person being asked first.

A chat runs with one agent. Everything on the bus that its tools reach — every open tab’s WebMCP tools — is available to it, subject to the person’s permissions.

Creating one

From the Agents menu, choose New Agent…. The form has tabs — General, Advanced, Tools, Approval, Skills, Browser, Web permissions, Variables and Chat setup. A name and instructions on General are enough to start; OK saves it, and it appears in the Agents menu.

Agents › New Agent…; a name, Order desk, and instructions that send it to the Orders page and then the Shipping page; the Tools and Web permissions tabs; the Declared site dialog opened and closed; OK; the new agent in the Agents menu. No sound.

Instructions that orchestrate

The agent in the recording was given this:

Answer questions about orders. Look the order up on the
Orders page, then track it on the Shipping page. Never
change an order unless asked to.

That is orchestration in three sentences: which application holds which fact, the order to consult them in, and a limit. Good instructions name the applications and the tools by what they are for, and say plainly which steps need the person’s say-so — the permission questions will ask anyway, but an agent that expects them explains itself better.

Declaring web permissions

An agent built for a known set of applications can declare those sites in advance, so the person is not asked the site-permission question in every chat. The Web permissions tab lists them:

The agent form on its Web permissions tab. Help text explains that these sites are allowed for every chat opened with this agent without being asked. A table with the columns Site, Read this page, Use this site's page tools, Page tools reach and Named tools, empty, and buttons Add…, Edit… and Remove. — An agent’s declared sites: allowed for every chat that runs with this agent.

Add… opens the declaration:

The Declared site dialog over the agent form. A Site field with the placeholder jira.example.com and help text saying a site is matched exactly and that a tenant can be covered by writing its path, as in jira.example.com/tenant-a. Checkboxes Read this page and Use this site's page tools. Page tools reach: Only tools that read, with the note that anything else is confirmed first. Named tools: a Tools… button. OK and Cancel. — A site, what the agent may do there, and how far its page tools reach.

Site is a host, or a host and path for one tenant — it is matched exactly.
Use this site’s page tools is the WebMCP permission; Read this page lets the agent read the page’s text.
Page tools reach is the same ladder the site question offers: Only tools that read, Tools that change things too, The consequential ones too.
Named tools picks individual tools that may run without asking, whatever their class.

A declaration never overrides the person. Their explicit answers are read first — a chat that refused the site stays refused — and a program connected to XataWorks from outside can never use an agent’s declarations.

Skills

Instructions say what this agent does. A skill says how to use one application, and can come from the application itself — see publishing a skill.