AI Agent Cloud Flow

Every AI Agent has its own Cloud Flow module. Use this module to implement the Agent's Custom Function Knowledge Sources and register supported callbacks that customize trusted server-side operations.

The Agent runtime manages normal conversations using the Agent's provider, instructions, Knowledge Sources, and settings. The AI Agent Cloud Flow extends that behavior; it is not a flowchart of every conversation turn.

Open the Agent's Flow

To edit the module:

1. Open AI Agents in the Project Editor.
2. Open the Agent's actions.
3. Select Edit Flow.
4. Add the required visual blocks or supported Custom Code.
5. Save the flow.
6. Start the Cloud Flow test runtime and invoke the Agent through its intended surface.

Use Settings to change the provider, instructions, Knowledge Sources, and Prompt Library. Use Edit Flow to implement server-side behavior.

What Belongs in the Agent Module

Typical responsibilities include:

• Registering Custom Function implementations.
• Validating Function arguments and enforcing business rules.
• Checking the current Agent user's identity and group membership.
• Registering callbacks for Agent-initiated table operations.
• Calling configured Connections.
• Retrieving common backend helpers from Flow Share.
• Invoking another Agent or a simple model prompt from a Function implementation.

General recurring orchestration usually belongs in a Background Task, while request/response endpoints belong in Web Hooks.

Implement Function Knowledge Sources

Use the AI Agent Function Implementation block for a Function defined in the Agent's Knowledge Sources.

The Function Name must match the Knowledge Source exactly. Inside the block, use:

• AI Agent Function Params Object for model-supplied arguments.
• AI Agent Auth Info for the current run's authentication information.
• Current User for the authenticated username.
• Current User is in group and role for an Agent-specific group check.
• A Result Object returned from every completion path.

A Function can use any supported backend capability appropriate to its work, including Database operations, files, Connections, Flow Share helpers, and Agent invocation.

See Function Knowledge Sources.

Agent User and Authorization

Web Hook user blocks and AI Agent user blocks are not interchangeable.

Context	Supported User Helpers
Web Hook	Current Web Hook user and Web Hook group-membership operations.
AI Agent Function	Current User and Current User is in group and role, using AI Agent Auth Info.

Whenever the Agent calls a Function, the runtime supplies authentication information for the user invoking the Agent. This information is separate from the Function parameters and reqContext. It includes information about whether the caller is public or an administrator and the user's identity.

The Function implementation can use Current User and Current User is in group and role to decide whether to allow the operation, reject it, or limit the returned data. Use these supported helpers rather than interpreting caller-supplied values as identity.

Authorization belongs in the operation that protects the resource. Agent Execute access controls client access through an AI Agent Widget; it does not restrict invocation from trusted Cloud Flow. A Function may still require a group, ownership check, or business rule regardless of how the Agent was invoked.

Register Table Operation Callbacks

Custom Code in the Agent module can register callbacks for Agent-initiated Database operations:

• $io.system.registerAgentDbCreateCallback
• $io.system.registerAgentDbReadCallback
• $io.system.registerAgentDbQueryCallback
• $io.system.registerAgentDbUpdateCallback
• $io.system.registerAgentDbDeleteCallback

Use these callbacks to reject an operation or replace supported operation data before it reaches the Database. Common uses include adding an ownership condition, preventing an overly broad batch change, applying trusted defaults, or blocking a prohibited transition.

Callbacks receive the authentication information for the user invoking the Agent, operation-specific data, and request context as separate arguments. A callback can use the runtime-provided user information to allow or reject the operation and, where supported, narrow or modify the proposed database operation. It must not treat identity or permission claims in reqContext as authoritative.

Callbacks return an ioLoop Result Object. Follow the exact contract in the Server $io.system API.

Do not rely on undocumented callbacks merely because a registration method exists internally. The task-oriented guides cover the hooks with current, usable runtime behavior.

For table configuration and callback scenarios, see Table Knowledge Sources.

Use Flow Share Helpers

A Background Task can define common server-side routines and publish them through Flow Share. The AI Agent module can retrieve and use those routines rather than duplicating them.

ioLoop loads module types in this order:

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

For example:

Background Task: SharedCustomerRules
  Define customer-access helper
  Store helper through Flow Share

AI Agent module: SupportAssistant
  Retrieve customer-access helper
  Register lookupCustomer Function
  When called, pass current auth information and parameters to helper

Load order makes synchronous registration available in sequence. It does not wait for a provider module's asynchronous work to complete. If a shared helper depends on delayed initialization, expose readiness explicitly and handle the unavailable state.

Flow Share is runtime state. It is recreated when the Cloud Flow runtime starts and is not a persistent store for Agent conversations, user identity, or business records.

See Flow Share.

Invoke Other Agents from a Function

An Agent Function implementation can call:

• $io.system.runAgentPrompt for a full run of another configured Agent.
• $io.system.runAgentSimplePrompt for a model-only prompt using the target Agent's provider/model.
• The AI Prompt Output block for the supported visual full-Agent invocation workflow.

This supports specialized composition. One Agent can expose a user-facing workflow while delegating classification, extraction, or another bounded task to a second Agent.

The called Agent may itself have Functions that invoke other Agents. Design the dependency graph deliberately. Prevent self-invocation and A-to-B-to-A cycles unless a strict depth and termination strategy makes the recursion safe.

See Invoking AI Agents.

Request Context

A caller using runAgentPrompt can provide options.reqContext. The runtime passes that application-defined context to Function implementations and Agent Database callbacks used during the run.

Request context is useful for values such as:

• Workflow and correlation identifiers.
• A source module or operation label.
• A bounded Agent-delegation depth.
• Application context already validated by trusted caller logic.

Request context is caller-supplied data. It is not authentication information and must not be used by itself to establish identity, group membership, record ownership, or permission. Function implementations and Agent database-operation callbacks receive the Agent user's authentication information separately and should use that runtime-provided information for user-aware decisions.

When a Function delegates to another Agent, forward only the values the target Agent needs. Avoid passing entire request bodies or sensitive objects as general context.

Connections and Credentials

The Agent module can call configured Connections through supported Cloud Flow blocks and Server APIs.

Use Connections for provider profiles and credentials. Do not embed API keys, access tokens, or secrets in blocks, Function parameters, prompt text, request context, Flow Share, or logs.

If several functions use the same Connection wrapper, a shared Background Task helper may reduce duplication. The helper must still receive and validate current inputs and authorization context.

See Using Connections.

Module Initialization

Function and callback registration occurs when the AI Agent module loads. Keep initialization predictable:

• Register required functions every time the runtime starts.
• Do not depend on state left from an earlier runtime process.
• Keep Function names synchronized with Knowledge Source definitions.
• Check that Flow Share dependencies exist before using them.
• Handle missing Connections or unavailable external services.
• Avoid performing consequential user-specific work merely because the module loaded.

The module's enabled state matters. If it is disabled, its registered Function implementations and callbacks should not be assumed to be available.

Testing the Agent Module

Test through the operation that causes the code to run. Merely saving the flow does not execute a Function implementation.

1. Save the Agent Cloud Flow.
2. Start the Cloud Flow test runtime.
3. Begin a new Agent conversation when prior history could influence the result.
4. Send a prompt likely to select the Function or table operation.
5. Review the Agent response and Run Logs.
6. Inspect resulting Database or external-service state.
7. Test unauthorized, invalid, empty, and repeated requests.

Test	What to Verify
Module load	Functions and callbacks are registered without initialization errors.
Function success	The correct Result Object data reaches the Agent.
Function failure	Errors are safe, useful, and do not claim success.
Authorization	Public and unauthorized users cannot perform protected work.
Shared helper missing	The Function fails safely instead of calling an undefined value.
External failure	Timeouts and provider errors are handled.
Nested Agent call	Structured output, failure, depth, and termination behavior are correct.
Runtime restart	Registrations and shared dependencies are recreated.
Published runtime	The published Agent uses the intended published flow and dependencies.

Troubleshooting

Issue	What to Check
Function is not implemented	Function name, module enabled state, saved flow, and test runtime.
Agent user is empty	Whether the code runs in an AI Agent Function context and receives AI Agent Auth Info.
Group check always fails	Group identifier, minimum role, authentication object, and Agent context.
Table callback does not run	Callback registration, module initialization, operation type, and table capability.
Flow Share helper is missing	Provider module enabled state, shared name, load order, and asynchronous readiness.
Nested Agent cannot run	Target Agent identifier, target initialization, access context, and recursive dependency.
Works in test but not published	Publishing state, published Connections, enabled modules, and production logs.

Good Practices

• Treat the Agent module as a server-side extension point.
• Register each Function once with an exact, stable name.
• Validate model-supplied arguments before using them.
• Derive authorization from runtime authentication and trusted data.
• Keep request context separate from authentication.
• Put common helpers in an earlier Background Task and expose them through Flow Share.
• Make initialization repeatable after runtime restarts.
• Bound nested Agent calls and report failures explicitly.
• Keep secrets and sensitive data out of logs.

For editor fundamentals and custom code, see Cloud Flow Editor and Node.js Runtime and SDK Libraries.