Formio 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.

• 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 section. For a working example of this flow, please try out the Agentic Workflow Example.

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.

There is also a 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.

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: