Uag

The Universal Agent Gateway (UAG) leverages the Model Context Protocol (MCP) to enable in-process agentic automation using Form.io. It provides to an AI Agent the same thing that our JavaScript Renderer provides to a human; an interpretation of the Form JSON schema into an understandable format. In the case of UAG, it transforms the Form JSON model into an AI readible markdown format so that the Agent can easily understand the purpose and structure of the data that needs to be collected.

-------------------------- There are two primary scenarios that the UAG enables:

• Unstructured 'chat' input to deterministic form submission: This capability uses the JSON schema of a Form.io form to produce a deterministic structured data object provided natural language conversational input.

For a working example of this flow, please try out the [Conversation Form Example](./examples/conversation-form).

• Agentic Form.io Workflows: UAG provides an AI Agent the ability to take existing submission data + "context" criteria in order to prompt an AI Agent to provide its own data and analysis within a workflow scenario. The following example, which shows a college application process using a Form.io application form, shows how this primary scenario works.

For more information on Agentic workflows, checkout the dedicated [Agentic Workflows](#agentic-workflows) section. For a working example of this flow, please try out the [Agentic Workflow Example](./examples/agentic-workflow).

---

One of the many benefits that the UAG has to offer is the ability to inject Dynamic Context into an AI processing cycle. This is achieved from the dynamic nature of the Form JSON schemas that can easily be modified and deployed to any environment without the need to update your application or re-train the agents within the process. Because of this, dynamic context changes can be injected seamlessly into an existing running process which will automatically update the behaviors of the Agents utilizing the UAG.

Try it out!

There are three working examples in this repo, each spinning up a Form.io server alongside the UAG with Docker Compose. Pick the one that matches what you are building.

| Example | Pattern | Licensing | |---------|---------|-----------| | [Custom Module](examples/custom-module) | Conversational, existing client. Connect Claude Desktop to your forms and talk to them: "I would like to add a new customer." Built as a custom module, so roles and permissions decide what the agent may do. | Open Source — free | | [Conversation Form](examples/conversation-form) | Conversational, your own UI. A chat application whose questions come entirely from a form. About 200 lines, no field names in the code — edit the form and the conversation changes. | Open Source — free | | [Agentic Workflow](examples/agentic-workflow) | Autonomous. A submission triggers an agent that scores it against a rubric and writes its decision back, which in turn triggers a second agent. No human, no chat window. | Enterprise |

There is also a [Flow Viewer](examples/flow-viewer) — a small proxy that shows every leg of an agentic run live, which is the fastest way to see what an agent is actually doing.

Documentation in this repository

This file is the main reference: what the UAG is, how to configure a form for it, how to deploy it, and how to troubleshoot it. The rest of the documentation lives next to the code it describes.

| Document | What it covers | |----------|----------------| | README.md (this file) | Concepts, [agentic workflow setup](#agentic-workflows), the [MCP tools](#pre-defined-mcp-tools-providing-dynamic-context), [deployment](#deploying-uag), [environment variables](#environment-variables), and [troubleshooting](#troubleshooting). | | [module/Readme.md](./module/Readme.md) | Building a custom module — adding your own MCP tools, form actions, pre-defined forms and resources, and configuration overrides, then mounting it into the Docker container. | | [integrations/claude/Readme.md](./integrations/claude/Readme.md) | The Claude integration: its API endpoints and commands, how to run it with Node or Docker, its environment variables, and how to trigger it from a Form.io Webhook action. | | [examples/custom-module/Readme.md](./examples/custom-module/Readme.md) | Example — a custom module driven conversationally from Claude Desktop, where roles and permissions govern what the agent may do. | | [examples/conversation-form/Readme.md](./examples/conversation-form/Readme.md) | Example — a chat application of your own whose questions come entirely from a form. | | [examples/agentic-workflow/Readme.md](./examples/agentic-workflow/Readme.md) | Example — an autonomous, webhook-triggered workflow with two chained agent personas. | | [examples/flow-viewer/Readme.md](./examples/flow-viewer/Readme.md) | A small proxy that shows every leg of an agentic run live — the token request, each tool call, and the write-back. The quickest way to see what an agent is doing. | | [examples/custom-module/module/templates/Readme.md](./examples/custom-module/module/templates/Readme.md) | Overriding the response templates the UAG returns to the agent, using Lodash templates. | | [test/e2e/Readme.md](./test/e2e/Readme.md) | The end-to-end test suite — its three layers, what each covers, and how to run it. |

---

Agentic Workflows

One of the more powerful features of the UAG is the agent_provide_data tool. This tool provides the ability to instruct a generically trained agent how to analyze existing submission data, and then produce its own data by following a configurable Criteria. This behavior historically could only be achieved using a specifically trained agent, which does not provide any benefits of dynamic configurability that the Form.io platform offers. This tool is able to achieve this goal by providing a generally trained agent with the necessary "context" it needs to accurately produce its own data as part of an automated workflow. This feature is particularly helpful if you wish to utilize the UAG within an Agentic Workflow, where the AI Agent is capable of understanding structured data, and then contribute its own data by following the configured Criteria "context" provided by the UAG.

For example, let's suppose you wish to automate the backend administration behind a College Application Process. In this example, a potential student submits an application that consists of many different fields of data, such as Academics, Extra curricular activities, Honors, Volunteer work, as well as possibly written Essays. Historically, these applications would be reviewed by an administrator in order to assess the candidates qualifications for acceptance. With the agent_provide_data tool, it is now possible to automate this process as the following diagram illustrates.

To achieve this feat, the agent_provide_data tool utilizes the following information, which is then fed to the Generally trained agent to produce its own submission data.

• Existing Submission Data: In order for the agent to be able to contribute its own data, it must first have an existing submission to be used as the data that it will analyze according to the configured Criteria.
• Criteria: This is a piece of content that provides the agent the Criteria to follow when analyzing the data, but also provides instructions on how the agent should populate the Required Fields.
• Required Fields: These are the form fields which the Agent is required to fill out as part of the agent_provide_data process.

Setup

To configure a form to use the agent_provide_data tool, you must first designate a section of your form that will be read and used by the AI Agent. This is similar to what you would see in a form that says "For Office Use Only", but instead of a Human contributing to the values of this section, it will be an automated AI Agent. There are two types of fields that can be added to a form to configure it for use by the agent_provide_data tool: Criteria and Agent Fields

A complete setup is four steps, and all four are required:

1. Tag the form uag (described below) — without this the UAG will not register the form at all.
2. Add the Criteria content component that teaches the agent what to do.
3. Add the Agent Fields the agent is allowed to fill.
4. Add a Webhook action to trigger the agent on submission — see the [Claude Integration](./integrations/claude/Readme.md#formio-webhook-setup). This step requires the Enterprise Server, because the action has to set a request header and transform its payload; on Community Edition, trigger the integration from your own code after creating the submission.

For a working reference containing all four, see the [Agentic Workflow example](./examples/agentic-workflow).

Tagging the form uag

The UAG only registers forms that carry the uag tag. Any form without it is invisible to every agent and to every tool, including get_forms. In the Form Builder this is set under Form Settings → Tags; in a form's JSON it looks like this:

"tags": ["uag"]

This is worth checking first whenever an agent insists that a form does not exist, because a missing tag produces no error anywhere — the form simply is not there as far as the agent is concerned. Note also that newly tagged forms are picked up on the next project cache expiry, so allow up to PROJECT_TTL seconds (see [Project Cache and TTL](#project-cache-and-ttl)).

Agent "Criteria" component

The first thing that needs to be configured is a special Content Component that instructs the AI Agent how to interpret the data. For example, here is a Criteria content block that was written to instruct an AI Agent on how to assess the submission of a College Application Essay.

The goal of this content is to be written as you would write an instruction manual for a new employee who needs to learn how to analyze and understand the submission data that is provided. It is also used to instruct the AI Agent on how to populate the form values that are configured for that criteria. Once this criteria is written, It will then need to be "flagged" as a UAG field by adding a property called uag and the value of that property is to be thought of as the persona of the Agent. This provides the ability to have more than one agent assume different roles as it analyzes the submission data to provide their own values. In addition, the "criteria" content will also need to be provided a uagField property with the value equal to criteria. Below is what a properly configured uag criteria content component looks like.

Once you have added this Criteria Content Component to your form, the next object is to add the fields you wish for the Agent to populate. These are called the Agent Fields.

Agent Fields

Anywhere in your form, you can drag and drop fields that can be flagged as Agent fields. Using the example above, imagine your form has a "For Office Use Only" section (maybe a Panel). Within this panel, the first thing you see is a Content Component with instructions on how the following fields should be filled out. This is the Criteria we just described. The next thing that follows are the fields that the Agent needs to populate. Any field that with a property of uag set to the same value as the Criteria content component will be used as the Agent fields.

For example, lets suppose that we have created a form for College Application essays. Below the Criteria may be some fields that the Agent needs to "score" the essays according to the provided Criteria. This may look like the following...

In order to "flag" each of these fields as Agent Fields, you simply need to add the uag property with the same persona flag that was giving to the Criteria content.

Nested Components It is also possible to "flag" a collection of fields with the uag property. This can be done by wrapping all of these fields within a Nested Component (such as Panel, Container, Fieldset, etc), and then all the fields within this nested component will be added to the context of that agent with that persona.

Multiple Personas per form

It is also possible to achieve multiple personas per-form. This is very helpful if there are several isolated evaluations that need to occur within a process. For example, if we look at the flow chart diagram shown above, we can see a College Application Form. The first agentic evaluation occurs when the form is submitted by the applicant, where their application is assessed to be accepted or not. From that point, IF the applicant is accepted, a completely different evaluation needs to occur to award Financial Aid or even Scholarships to the applicant. These would require completely different criteria to assess the submission data differently from one another.

To achieve this, you simply need to "flag" the components uag property value differently with the persona that applies for that field. For the example above, you would add a Content component to assess if the applicant should be accepted, and then provide the following uag property to that content. uag="application". Any fields that need to be filled out by the AI Agent for application approval would also be flagged with the property uag="application". Then, in a different section of the form, you would create a separate Content component with the criteria for the financial admin AI Agent. This content would be flagged with the property uag="finance". Any fields that the finance admin AI Agent need to fill out would also be flagged with uag="finance". This provides a truly flexible and dynamic AI engagement where multiple generically trained agents can be "taught" dynamically how to read and interpret data that is only relevant to that part of the agentic process.

Agent fields do not have to sit next to their criteria, either. A status field in one panel can be flagged uag="application" while the field beside it is flagged uag="finance", which is how a single workflow field can be owned by whichever persona is responsible for that stage.

Chaining personas into a workflow

Multiple personas on a form are only useful if something triggers the later ones. Because each persona writes to the submission, the natural trigger for the second persona is the first persona's write.

This is configured with a second Webhook action that fires on update rather than create, narrowed by a condition on a field that the first persona sets:

{
  "name": "webhook", "handler": ["after"], "method": ["update"], "priority": 0,
  "condition": {
    "conjunction": "all",
    "conditions": [
      { "component": "status", "operator": "isEqual", "value": "scholarshipEvaluation" }
    ]
  },
  "settings": {
    "method": "post",
    "url": "http://formio-uag-claude:3300/agent/claude/agent_provide_data",
    "headers": [{ "header": "x-token", "value": "" }],
    "transform": "payload = {formName: 'application', submissionId: payload.submission._id, persona: 'finance'};",
    "block": false
  }
}

In the college application workflow, the admissions persona sets status to scholarshipEvaluation only for applicants on the scholarship track, so only those submissions wake the finance persona. Applicants who were simply accepted or declined never trigger it.

> Avoid loops. The second persona also writes to the submission, which fires the same update webhook again. Make sure each persona's own write cannot re-match the condition that triggered it — in the example above the finance persona sets status to scholarshipGranted, which no longer satisfies the condition, so the workflow termin

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: formio
• Source: formio/uag
• License: MIT

Install and usage instructions live in the source repository linked above.