AI Agents

AI Agents add conversational and AI-powered behavior to an ioLoop Project. An Agent combines an AI provider Connection with Project-defined instructions, Knowledge Sources, functions, and other settings that determine what the Agent knows and what it can do.

An Agent can be presented to users through an AI Agent Widget, or invoked from Cloud Flow when AI processing is part of a Web Hook, Background Task, or another Agent workflow.

AI-generated output can be incomplete or incorrect. Design important workflows so that permissions, validation, and consequential operations remain under application control.

How an AI Agent Is Organized

An ioLoop AI Agent has three related parts:

Part	Purpose
Agent configuration	Selects the AI provider Connection and defines model settings, instructions, prompt reinforcement, Knowledge Sources, and Prompt Library entries.
AI Agent Cloud Flow	Implements Function Knowledge Sources and supported customization hooks. It can also use common backend routines exposed through Flow Share.
Invocation surface	Makes the Agent available through an AI Agent Widget or invokes it headlessly from Cloud Flow.

These parts work together, but changing one does not automatically replace the others. For example, changing a Widget title does not change the Agent's instructions, and adding a Function Knowledge Source does not implement that function's server-side behavior by itself.

AI Provider Connections

Every Agent requires an AI provider Connection. The Connection stores the provider profile and authentication configuration used by the Agent.

OpenAI is currently the supported AI provider. The Agent model is designed to support additional providers in the future, so the guides use the general term AI provider Connection except where the current OpenAI-specific setup matters.

Create and test the required Connection in Integrations before configuring the Agent. Keep provider credentials in the Connection profile rather than placing them in instructions or Cloud Flow code.

For Connection concepts and profile lifecycle, see Integrations and Connections.

What Agents Can Use

Knowledge Sources make selected information and operations available to an Agent.

Knowledge Source	Typical Use
File	Let the Agent refer to supported Project files or file URLs.
Database Table	Let the Agent read a Project Database table and, when explicitly enabled, create, update, or delete records.
Custom Function	Define a function tool whose implementation runs in the Agent's Cloud Flow.
Web Search	Allow the Agent to use supported web search behavior.
MCP Server	Expose selected tools from an MCP or MCP-compatible Connection.
Connection	Let the Agent use the AI functions exposed by a supported Connection service.

Choose Knowledge Sources deliberately. More sources do not necessarily produce better results. Give each source a clear description so the Agent can decide when it is relevant, and expose only the operations required by the intended workflow.

See Knowledge Sources, Table Knowledge Sources, and Function Knowledge Sources.

How Users and Workflows Invoke an Agent

An Agent can participate in both interactive and backend workflows.

Interactive Conversations

Add an AI Agent Widget to a Page when Project visitors or authenticated users should chat with the Agent. The Widget provides the conversation interface, while the selected Agent supplies its instructions, knowledge, and functions.

Widget conversations can retain chat history for the applicable user and Agent. See AI Agent Widget.

Headless Cloud Flow Runs

Cloud Flow can invoke an Agent without displaying a chat interface. Common patterns include:

• A Web Hook sends a request to an Agent and returns a controlled result.
• A Background Task asks an Agent to classify, summarize, or plan work.
• A timer-driven Background Task uses Agent output as one step in a bounded agentic loop.
• A Function Knowledge Source delegates a specialized task to another Agent.
• A Cloud Flow module requests structured output for subsequent server-side processing.

The full Agent invocation uses the target Agent's instructions, Knowledge Sources, and functions. A separate simple-prompt API uses only the AI model associated with the target Agent and does not use its full configuration or conversation threads.

See Invoking AI Agents.

The AI Agent Cloud Flow

Each Agent has its own Cloud Flow module. Select Edit Flow from the Agent's actions to open it.

The Agent's Cloud Flow is primarily an extension module. Use it to:

• Implement Custom Function Knowledge Sources.
• Inspect the authenticated Agent user where required.
• Register supported callbacks for table operations using custom server-side code.
• Retrieve shared backend functions or values through Flow Share.
• Call Connections, Project services, another Agent, or a simple model prompt as part of a Function implementation.

It is not necessary to reconstruct the ordinary conversation loop in this flow. The Agent runtime manages the conversation using the configuration and Knowledge Sources you provide.

ioLoop loads Cloud Flow module types in this order:

1. Background Tasks
2. Web Hooks
3. AI Agent modules

This allows a Background Task to publish common routines through Flow Share before an AI Agent module retrieves them. Load order establishes initialization order; it does not wait for asynchronous initialization to finish.

See AI Agent Cloud Flow and Flow Share.

Creating an AI Agent

Before creating an Agent, configure an AI provider Connection under Integrations.

To create an Agent:

1. Open AI Agents in the Project Editor.
2. Select New AI Agent.
3. Enter a meaningful name.
4. Save the Agent.
5. Open the Agent's actions and select Settings.
6. Under AI Provider Connection, select the configured provider Connection and choose Connect.
7. Configure the Agent's instructions and other model settings.
8. Add only the Knowledge Sources needed for the Agent's purpose.
9. Add Prompt Library entries when the user experience benefits from reusable prompts.
10. If the Agent has Custom Function Knowledge Sources, select Edit Flow and implement each function.
11. Configure Access (Security) for users who may access the Agent from the client through an AI Agent Widget.
12. Test representative conversations and actions before publishing.

For the settings in this workflow, see Creating and Configuring AI Agents.

Security Model

Client access, server-side invocation, Knowledge Source availability, and authorization inside an operation are separate layers.

• Agent Access (Security) controls which Project user groups may access the Agent from the client, principally through an AI Agent Widget.
• A Cloud Flow module runs in the trusted server environment and can invoke an Agent regardless of the Agent's Access (Security) settings.
• A Web Hook's own Access (Security) settings control who may invoke that endpoint. After the Web Hook admits the caller, its Cloud Flow can invoke the Agent regardless of the Agent's client access settings.
• A Background Task or another AI Agent module can invoke the Agent as an internal server-side operation.
• Built-in Table Knowledge Source operations enforce the selected table's applicable access rules. Database operations performed directly by a Function do not automatically receive those Table Knowledge Source checks.
• Function implementations receive authentication information and must authorize protected Database, Connection, and other server-side operations before performing them.
• A Connection Knowledge Source uses its Connection's stored profile. Access enforcement depends on the function exposed by that Connection service, so do not assume that selecting a Connection or limiting its external-service permissions authorizes each Agent user.
• MCP servers and Connection tools can reach external systems; expose only the tools and operations the Agent requires.
• Caller-supplied request context is application data, not proof of identity or permission.

Public Agent access is available for client use, but the Project Editor warns against allowing Public users to access an Agent through the Widget. A public Agent can expose any Function or Connection tool that does not independently reject public use, including operations performed with trusted server access or a Connection's stored profile. This setting does not affect trusted Cloud Flow invocation. Treat any prompt, function parameter, file content, web result, MCP output, or caller-supplied context as untrusted input regardless of the invocation surface.

For the group identities and role levels used by Agent Access (Security), see User Groups. To create Project Users and assign their group membership, see Users.

Development and Publishing

AI Agents participate in the same development, testing, and publishing lifecycle as the rest of the Project.

Test the Agent through every intended invocation surface. A Widget conversation, a Web Hook invocation, and a Background Task run have different surrounding context and failure behavior. Changes that work in development are not available in the published Project until the relevant Project changes are published.

External provider activity can have real usage, cost, data-handling, and side-effect implications during testing. Confirm which provider account and external systems a Connection uses before running tests.

Where to Go Next

Topic	What You Will Learn
Creating and Configuring AI Agents	Create an Agent and configure its provider, instructions, model behavior, and prompt reinforcement.
Knowledge Sources	Choose and configure the information and tools available to an Agent.
Table Knowledge Sources	Provide controlled access to Project Database tables.
Function Knowledge Sources	Define and implement server-side Agent functions.
Prompt Library	Provide categorized reusable prompts to Agent users.
AI Agent Cloud Flow	Implement functions, supported hooks, security checks, and shared backend logic.
Invoking AI Agents	Use Widgets, Web Hooks, Background Tasks, and Agent-to-Agent delegation.
Managing and Testing AI Agents	Manage access, usage, logs, history, files, cloning, deletion, and publishing.

For exact Cloud Flow block behavior and Server API signatures, use the AI Agents Cloud Flow reference and the Server $io.system API.