Developer docs · Agentic Coding Plugin · Quickstart · All documentation
The Universal Agent Gateway (UAG) is a server that lets AI agents work with your Form.io forms. It does for an agent what the JavaScript renderer does for a person: it turns Form JSON into something the agent can understand. Then it validates what the agent sends back with the form's own rules, and saves it with the user's own permissions.
The form is the contract. Add a field and agents ask for it; rewrite a task's instructions and the next submission is handled differently. Nothing is redeployed, no prompt changes, no model is retrained.
Build it with your coding agent. The Form.io Agentic Coding Plugin gives Claude Code, Cursor, Codex and other coding agents a formio-uag skill that tags your forms, designs their tasks, deploys the UAG and wires your application to it. Install it in your application's folder with npx skills add formio/ai.
- It sits in front of one Form.io project. At startup the UAG reads the project's
/exportand registers every form taggeduag. It re-reads it everyPROJECT_TTLseconds (default 900). A form without the tag is invisible to agents. - It has three entry points.
/mcpserves MCP tools to agents that bring their own model.{form}/agent/*, the Agent API, runs a form's tasks inside the UAG with the model engines you enable, and saves nothing. The project's own API is served too, so an application can use the UAG's URL as its project URL. - It forwards every submission to Form.io. Form.io saves it and runs the form's own actions (Save Submission, Webhook, Email, Login, Role, Group). The UAG runs only its own actions, such as Agent: Run task, so nothing runs twice.
- Every call has a Form.io identity. A Form.io user token (
x-jwt-token) is verified with Form.io and forwarded unchanged. MCP clients sign in through OAuth 2.0 with PKCE (MCP_OAUTH), and their roles and permissions decide what the agent may read and write for them. Servers usingclient_credentialsor an API key act as the project administrator. - Every write goes through the form. An MCP client's model writes only through tools such as
submit_completed_form. Engines only answer, and are never given a write tool. The UAG validates every value with the form before it forwards the write.
The UAG is built on Form.io's core logic. Every value an agent sends runs through the @formio/core processors, the same validation, conditional and calculation rules Form.io itself applies, so the data it saves is valid and deterministic. More detail: How the UAG works.
A person talks to Claude, ChatGPT or your own chat app, and the agent fills in a form for them. Build it with the MCP tools or Connect Claude, or embed a form as a chat in your own page with the chat widget: Formio.createChat(element, formUrl) from @formio/uag-js, with the UAG as the only backend. source · prompt for your coding agent.
An application saves a submission through the UAG; an Agent: Run task action runs the form's task after the save and saves the result, which can start the next task. source · build it with Workflows · prompt for your coding agent.
A person describes what happened, and the form fills itself in: decisions choose the wizard's pages, extraction prefills the rest. source · build it with the Agent API and @formio/uag-js · prompt for your coding agent.
A person uploads a file to a form, and the form reads it. An AI Document component sends the uploaded files (PDF, Word, Excel, text, or a scan or photo) to the UAG, where an agent engine produces what the form designer's instructions ask for: an exact extraction, a summary, an assessment or a translation. The person reviews the result before they submit, and edits it where the process allows, or in the form field it writes to. What it does is a document plugin installed on the UAG (extract, analyze, translate, or one of your own) that the designer picks in the form builder; extract checks its copy word for word against the file's text and flags a copy it cannot match. It is a module from @formio/uag-extras, added to the formio/uag image by the formio/uag-documents add-on. source · build it with AI Document and Plugins.
One deployment can serve all four. Conversation forms run on Form.io Open Source with no license; the others need a license or a hosted project (see License). The whole demo site, static pages that call the UAG straight from the browser, with a flow log of every call they make, is in demo/; these recordings are made from it by demo/recordings.
Form.io Open Source and the UAG in one Compose stack. Replace every CHANGEME; ADMIN_KEY must match on both services.
services:
mongo:
image: mongo:7
volumes: [mongo-data:/data/db]
formio: # Form.io Open Source, listening on 3001
image: formio/formio
depends_on: [mongo]
ports: ["3000:3001"]
environment:
NODE_CONFIG: '{"mongo": "mongodb://mongo:27017/formio-oss", "jwt": {"secret": "CHANGEME"}, "mongoSecret": "CHANGEME"}'
ROOT_EMAIL: admin@example.com
ROOT_PASSWORD: CHANGEME
ADMIN_KEY: CHANGEME
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://localhost:3001/').then(r => process.exit(r.ok ? 0 : 1)).catch(() => process.exit(1))"]
interval: 5s
retries: 40
formio-uag:
image: formio/uag
depends_on:
formio: { condition: service_healthy }
ports: ["3200:3200"]
environment:
PROJECT: http://formio:3001 # how the UAG reaches Form.io
ADMIN_KEY: CHANGEME
JWT_SECRET: CHANGEME
LOGIN_FORM: http://localhost:3000/user/login
PROJECT_TTL: 10 # re-read the project every 10 s while you experiment
volumes:
mongo-data:docker compose up -d
# Get a token, then list the MCP tools.
TOKEN=$(curl -s -X POST http://localhost:3200/auth/token -H 'Content-Type: application/json' \
-d '{"grant_type":"client_credentials","client_id":"formio-oss-x-admin-key","client_secret":"CHANGEME"}' \
| node -pe 'JSON.parse(require("fs").readFileSync(0)).access_token')
curl -s -X POST http://localhost:3200/mcp -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Then tag a form uag (in the portal, Form Settings → Tags) and connect an agent. The Quickstart covers a hosted Form.io project, a first tool call and the Agent API, and Connect Claude connects Claude Desktop or claude.ai. Or have your coding agent do all of it with the Agentic Coding Plugin.
With Docker, a Form.io Enterprise license and a license that includes the UAG, one command runs the demo site with all four examples, Form.io Enterprise and its portal, and the UAG built from this checkout:
yarn install
npx playwright install chromium # once: connecting the portal stage drives the portal in a browser
yarn demo:start 3430 # the site on :3430, Form.io and its portal on :3431, the UAG on :3432It creates the demo project and its forms itself, and prints where everything is and how to sign in to the portal. It reads LICENSE_KEY and your model keys from the root .env; the portal password and the other secrets come from there too when you set them, and are random otherwise. See the demo's README.
A task teaches an agent to fill part of a form, with instructions written in the form itself. It is defined entirely by custom properties on components (API → Custom Properties in the form builder), and a form can have several.
| Property | On | Meaning |
|---|---|---|
uag: <task> |
Any field, or a panel, container or fieldset | The field belongs to the task. On a container, every field inside it does too, except fields in data grids and edit grids. |
uagField: criteria |
A content component with uag: <task> |
The task's instructions. Write them like a brief for a new employee, including the role the agent acts in, exact option values and formats. |
uagField: input |
A field with uag: <task> |
The text the task reads. Without one, the task reads the submission, except its own fields; {form}/agent/extract then needs text. |
uagContext, uagTools |
The criteria component | Extra data paths sent to the engines; read-only MCP tools the agent may research with. |
uagEngine |
A task field, or the criteria component | Which engine answers that field, or the whole task. |
uagThreshold, uagAuthoritative, … |
A task field | How confident a decision must be; whether the server owns the value, so no client can set it. |
Every property, with its default: Form properties. How tasks, decision fields and value fields work: Concepts.
No form, no error. A form missing the
uagtag simply is not there for agents, and a new tag or criteria edit reaches them after the nextPROJECT_TTLrefresh. Restart the UAG to pick changes up at once.
A workflow is a task that the Agent: Run task action runs on a submission the UAG receives. The demo's college application runs two tasks, and the second is started by the first one's save:
To set one up on Form.io Enterprise:
- Connect a portal stage to the UAG. Set
PORTAL_SECRETon the UAG, then in the portal connect a stage to it as an on-premise environment. In that stage the portal lists the UAG's own actions next to Form.io's. See Deployment → Connecting the Enterprise portal. - Add "Agent: Run task" to the form. Choose the Task, what to Answer (the whole task, or its decision fields only) and When (after the save, in the background, or before it, while the submitter waits), with Form.io's usual methods and conditions. Mark the fields the agent owns
uagAuthoritative, so no client can set them. - Point the application at the UAG. Use the UAG's URL as the project URL in the renderer or your API calls. Login and registration are forwarded to Form.io, and its tokens work unchanged.
On Form.io Open Source, which has no portal stages, add the same action with Form.io's action API (POST /form/{formId}/action) or in a module's project template, and point the application at the UAG. Run task is Agentic Formflow, so it needs a license that includes the UAG, or a project on Form.io's hosted service.
The demo's second action, from demo/module/project.json:
{
"title": "Agent: Run task (finance)", "name": "agentRunTask",
"handler": ["before", "after"], "method": ["update"],
"condition": {
"conjunction": "all",
"conditions": [
{ "component": "status", "operator": "isEqual", "value": "scholarshipEvaluation" },
{ "component": "awardLevel", "operator": "isEmpty" }
]
},
"settings": { "task": "finance", "answer": "task", "when": "after" }
}What one run after the save does:
- Tasks run only for submissions sent to the UAG. A submission sent straight to Form.io runs no task.
- After the save, the submitter does not wait. The task's results are saved as an update through the UAG, so the form's update actions, including other Run task actions, run on it. A run that changes nothing saves nothing.
- Guard update actions with a condition on a field the task sets, as above. Check operator names: Form.io treats a clause with an unknown operator as always true.
- Who the agent acts as. With no Agent role, the task saves with the credential the submission was sent with. With one, and the same
JWT_SECRETas Form.io Enterprise, the UAG acts for the user with that role, so Form.io's permissions keep users off the agent's fields. See Project setup for agents.
Full guide: Workflows.
The Agent API runs a form's tasks inside the UAG and returns validated values. It reads no stored submission and saves nothing; saving is the job of submissions sent to the UAG. Applications call the same endpoints whichever models are behind them.
A form's operations are under the form's URL on the UAG, {form}: the form's path, or form/{formId}, under the project's URL on the UAG (the UAG's root on Form.io Open Source; /{projectName} or /project/{projectId} on Enterprise and the hosted service).
| Endpoint | Does | Saves |
|---|---|---|
POST {form}/agent/extract |
Fills a task's fields from free text (text, or the task's input field in data). Streams results with Accept: text/event-stream, each engine group as it finishes, so fast decisions usually come first. |
No |
POST {form}/agent/decide |
Answers a task's closed-set fields from data, with a calibrated confidence when a decision engine answers. |
No |
POST {form}/agent/generate |
Writes a task's open values (dates, amounts, text) from data. |
No |
POST {form}/agent/chat |
One turn of a conversation that fills the form in: the next message, and the values taken from the person's words, checked against the form. What the chat widget calls. Conversation forms: no Agentic Formflow license. | No |
GET /agent/capabilities (at the UAG's root) |
Lists the enabled engines, the operations they serve, the edition, the license state, and whether durable runs (durableRuns) and remote MCP sign-in (mcpOAuth) are available. |
No |
curl -s -X POST https://uag.example.com/claim/agent/extract \
-H "x-jwt-token: $FORMIO_TOKEN" -H 'Content-Type: application/json' \
-d '{"task": "triage", "text": "I rear-ended a car at the light on Main St yesterday around 5pm."}'Each field comes back with its value, a status (confident, uncertain, suggested or missing), the engine and model that answered, and a confidence where the engine gives one. Values are only answered for empty fields unless overwrite is true.
The operations take the same credentials as the form's submissions: the signed-in user's Form.io token (x-jwt-token), or a portal team member's remote token (x-remote-token), and Form.io permissions apply. A UAG bearer token (Authorization: Bearer) works too. Servers may send x-token: <PROJECT_KEY> or x-admin-key: <ADMIN_KEY> instead; the UAG refuses those on any request with an Origin or Sec-Fetch-Site header, so they never work from a browser. Visitors with no credential are answered only by a form that sets uagAnonymous: "true" and lets Anonymous create submissions, within per-address and total rate limits. To decide on the server whatever a browser sent, add Agent: Run task to the form with its decision fields only, before the save.
Every field, status code and setting: Agent API. Measure decision accuracy on your own forms before going live: Evaluation.
An engine connects the UAG to a model provider. Each engine type is its own npm package, and the formio/uag image includes all of the official ones. None runs until you name it in UAG_ENGINES.
| Kind | Answers | Engines |
|---|---|---|
| Decision | Closed-set fields (radio, select, checkbox, select boxes, survey, single resource selects) within the engine's option limit, with a calibrated confidence | jev, openai with kind: decision |
| Agent | Everything else, marked suggested; may first research with read-only tools the task allows |
claude, openai, grok, gemini |
UAG_ENGINES=jev,fast:claude,deep:claude # instances; <name>:<type> runs one type twice
UAG_ENGINE_FAST_MODEL=claude-haiku-5-5 # UAG_ENGINE_<NAME>_<SETTING> configures one instance
TYPESAFE_API_KEY=... # then each engine's own variables
CLAUDE_API_KEY=...Decision fields go to a decision engine, and fall back to an agent engine (reported calibrated: false) when it fails, times out, is over its rate limit, or none is enabled. A radio, single select or survey with more options than the decision engine accepts (255 for Jev) goes to an agent engine. Override the choice per field, or per task on its criteria, with uagEngine.
Engines run inside the UAG, or on an engine server (formio/uag-engines) so model keys and model traffic stay out of the UAG: name the instance with the remote type. To write your own, see the Engine SDK. Full guide: Engines.
| You run | You need |
|---|---|
MCP and conversation forms (including a form's chat, {form}/agent/chat), on Form.io Open Source or a hosted project |
Nothing |
| MCP and conversation forms, on a self-hosted Form.io Enterprise project | A Form.io license that includes the UAG, in LICENSE_KEY, whose endpoint allowlist includes PROJECT's host. Otherwise the project does not load, and the UAG says why. |
Agentic workflows, Agentic Formflow and AI Documents (the Agent API's extract, decide and generate, the Agent: Run task action, an AI Document's {form}/document/process, the agent_decide and agent_provide tools, uag-eval) on a self-hosted project, Open Source or Enterprise |
A Form.io license that includes the UAG, in LICENSE_KEY |
The same on a project on Form.io's hosted service (https://*.form.io) |
Nothing, as the project runs under Form.io's license; except uag-eval, which runs offline and needs LICENSE_KEY. Leave LICENSE_KEY unset there unless the UAG has its own database. |
The UAG's own database (MONGO), and with it remote MCP sign-in (MCP_OAUTH), on any project |
A Form.io license that includes the UAG. Without one, the UAG starts with its database features off and says why. |
The Agent API, Run task and uag-eval with only the stub engines (UAG_ENGINES=stub-decision,stub-agent), to try them out |
Nothing. The agent_decide and agent_provide tools still need a license or a hosted project. |
A license that includes the UAG is an online license whose key has the uagServer scope (each project endpoint a UAG serves counts as one UAG server, replicas once), or an offline license with the uag option, issued for its project; set LICENSE_REMOTE=true for an offline license. Unlicensed requests get 403 with code: "license_required", and GET /agent/capabilities always reports the edition and formflow.reason. UAG_LICENSE is deprecated in favour of LICENSE_KEY, and still read until UAG 3.0. Contact support@form.io for a trial license. Details: Deployment → Licensing.
- Modules add MCP tools, override the built-in tools and their response templates, add form actions (the UAG runs a module's own actions; Form.io runs its own), and ship a project template of forms and resources that the UAG installs. A module can also add routes on every form, formio.js components (served in the UAG's
/uag-js/uag.use.js), plugins, and settings of its own. Mount one over/app/modulein the container, or name it inUAG_MODULEfor theuagcommand. See Modules,module/Readme.mdand the Claude Desktop example. - Plugins add capabilities of a known type, such as converters that read more file types and the document processes an AI Document runs. List them in a module, or in a plugins file: the one
UAG_PLUGINSnames, or in the image, one per folder under/app/plugins, where add-ons such asformio/uag-documentsput theirs. Plugins and modules are trusted code: they run in the UAG process. See Plugins and AI Document. - Node.js. Embed the UAG in an Express application, or install it (
npm install @formio/uag) and run it withnpx uag:
import Express from 'express';
import { UAGServer } from '@formio/uag';
const server = new UAGServer(); // configured by the environment variables below
// server.use(MyModule); // optional modules
const app = Express();
app.use(await server.router());
app.listen(process.env.PORT || 3200);Run Node 22 or newer with --no-node-snapshot (isolated-vm, which runs form logic, needs it; npx uag adds it itself), and install the engines you use next to the UAG (npm install @formio/uag-claude). See Node.js API.
@formio/uag-jsconnects a formio.js application to the UAG. Register it once withFormio.use(UAG('https://uag.example.com')): submissions of forms taggeduagare then saved through the UAG, and Agent Input fills those forms from what the user wrote, through{form}/agent/extract, when they leave the input, pause, move to the next page, or press a button.Formio.createChat(element, formUrl)renders any of them as a chat instead, templated, translated and themed like a formio.js form. See JavaScript (formio.js) and Chat widget.
| The MCP client is | Example | The UAG must be |
|---|---|---|
| Local: your own process connects out to the UAG | Your backend, an engine server, a script | Reachable from that process only. localhost or a private network address is fine. |
| Remote: a hosted agent connects in | claude.ai and Claude Desktop connectors, other remote MCP hosts | Public over HTTPS, with MCP_OAUTH=true and its database (MONGO, licensed), for the /.well-known OAuth endpoints. |
A local client has no browser, so it exchanges a key for a token at the UAG's /auth/token with the client_credentials grant, as in the Quickstart; this needs no BASE_URL, MONGO or MCP_OAUTH. The client_id is formio-oss-x-admin-key with ADMIN_KEY on Open Source, and <project name>-x-token with PROJECT_KEY on Enterprise or a hosted project, where the name is the project's name setting. A wrong client_id or secret answers 400. Tokens last JWT_EXPIRE_TIME minutes; cache and refresh them.
| Variable | Meaning |
|---|---|
PROJECT |
Required. How the UAG reaches Form.io: the Open Source server's URL, or an Enterprise or hosted project's endpoint. A container-to-container address is fine. |
ADMIN_KEY or PROJECT_KEY |
Required. ADMIN_KEY for Open Source; a project API key (Project Settings → API Keys) for Enterprise or hosted. Setting PROJECT_KEY is what makes the UAG treat PROJECT as an Enterprise project. |
JWT_SECRET |
Required. Signs the tokens the UAG issues. The same as the Form.io Enterprise server's lets an agent act on users' behalf (see Project setup for agents). |
MONGO, UAG_DATABASE |
Optional. The UAG's own database (default name uag; it can share Form.io's MongoDB), for run records in Action Logs, runs that survive a restart, and remote MCP sign-in. It holds only uag-* collections, never submissions. Needs a license. |
MCP_OAUTH |
true turns on OAuth sign-in for remote MCP clients. Needs MONGO. |
TRUST_PROXY |
Optional. Set behind a reverse proxy, so the UAG reads its public URL from the forwarded headers. BASE_URL, also optional, overrides that URL. |
PORTAL_SECRET |
Enterprise. Lets a portal stage connect to the UAG, so you can add Run task actions there. |
LOGIN_FORM |
The project's login form JSON URL, for the browser sign-in at /auth/authorize. Defaults to {PROJECT}/user/login, which a browser often cannot reach, so set it to a public URL. |
LICENSE_KEY |
A Form.io license that includes the UAG. See License. |
UAG_ENGINES |
Engine instances to enable. See Engines and routing. |
PROJECT_TTL |
Seconds between project refreshes. Default 900; 0 disables them. |
UAG_MODULE |
Path to a module, for the uag command (npx uag). The Docker image loads /app/module instead. |
Every variable, Docker and Kubernetes examples, Enterprise and hosted setups, a smaller image with fewer engines, and the production checklist: Deployment. Before exposing the UAG: Security.
| Symptom | Likely cause |
|---|---|
| An agent says a form does not exist | The form is not tagged uag, or the project has not refreshed yet (PROJECT_TTL). |
Every /mcp call is 401 |
The client sends no token: exchange a key at /auth/token first. |
| A remote agent cannot sign in | MCP_OAUTH is off, the UAG has no usable database (MONGO with a license; its startup log says why), or the discovery documents name an address the agent cannot reach (set TRUST_PROXY, or BASE_URL). |
| Every tool fails; the UAG cannot reach Form.io | PROJECT is not reachable from inside the UAG container, or its certificate is not trusted. |
| A task fills some fields but not others | Their uag value does not exactly match the task's name, or they already had a value (see excluded in the response). |
| A Run task action never runs | The submission went to Form.io's URL instead of the UAG's, the action's method or conditions do not match, or the UAG has no license (see its log). |
| A task runs again on every update | The update Run task action has no condition on a field the task sets. |
The full table, with the Agent API's errors: Troubleshooting.
| Package | Version | Works with UAG | What it is |
|---|---|---|---|
@formio/uag, image formio/uag |
2.x | — | The UAG. The image includes every official engine. |
@formio/uag-jev, -claude, -openai, -grok, -gemini |
2.x | ≥ 2.0.0 | The engines, released with the UAG at the same version. |
@formio/uag-sdk |
2.x | ≥ 2.0.0 | Engine contract version 1, remote engine protocol version 1. |
@formio/uag-engines, image formio/uag-engines |
2.x | ≥ 2.0.0 | The engine server. |
@formio/uag-js |
2.x | ≥ 2.0.0 | The formio.js module: saves uag forms through the UAG, adds Agent Input, and renders forms as a chat. Runs in the browser; the UAG also serves it at /uag-js/. |
@formio/uag-extras, image formio/uag-documents |
2.x | ≥ 2.0.0 | The AI Document module, document plugins and converters (npm install @formio/uag-extras@^2); needs Node.js 24 or newer. Its major version is the UAG's; its minor and patch versions are its own. The image is an add-on that runs beside formio/uag and fills its plugins folder (formio/uag-documents:2): see AI Document, and the deployment kit for a Compose file and .env template that run both (curl -fsSLO https://cdn.jsdelivr.net/npm/@formio/uag-extras@2/deploy/docker-compose.yml). |
@formio/uag-claude |
1.3.x | 1.12.0 – 1.13.x | The retired Claude integration (against 2.0, only its direct commands). Security fixes only; see MIGRATING-2.0.md. |
@formio/uag-claude 2.x is the Claude engine, not the 1.x integration; pin @formio/uag-claude@^1 if you still install the integration. Upgrading from 1.x: MIGRATING-2.0.md.
The developer documentation is the Markdown in demo/content/developers. Start with How the UAG works.
| Developer guides | Package and sample READMEs | |
|---|---|---|
| Start here | How the UAG works · Agentic Coding Plugin · Quickstart | Demo site |
| Concepts | Concepts · Form properties | |
| Build | MCP tools · Agent API · Workflows · JavaScript (formio.js) · Chat widget · AI Document · Connect Claude | @formio/uag-js · Claude Desktop module |
| Extend | Node.js API · Modules · Plugins · Engines · Engine SDK · Engine server | Modules · Response templates · Engines · Engine SDK · Engine server · Engine setups |
| Operate | Security · Deployment · Evaluation · Troubleshooting | Docker Hub · Migrating to 2.0 · Security policy · End-to-end tests |