Function Knowledge Sources

A Custom Function Knowledge Source gives an AI Agent a Project-defined tool. The Knowledge Source describes the function to the AI model; the Agent's Cloud Flow supplies the trusted server-side implementation.

Use a Function when the Agent needs to do more than retrieve general knowledge. A Function can validate or transform information, read permitted Project data, call a Connection, coordinate application logic, invoke another Agent, or return a result assembled from several backend operations.

Definition and Implementation Are Separate

Every Function Knowledge Source has two parts:

Part	Where It Is Configured	Purpose
Function definition	Agent Settings → Knowledge Sources	Defines the function name, description, and parameter schema shown to the AI model.
Function implementation	Agent Edit Flow	Registers the server-side logic that runs when the model calls the function.

Adding only the definition does not create working behavior. If the model selects a Function whose implementation has not been registered, the run fails when that function is called.

The Function name connects the definition to the implementation. It must match exactly.

When to Use a Function

Function Knowledge Sources are suitable for behavior such as:

• Retrieving a record through application-specific authorization rules.
• Calculating a quote, score, availability result, or recommendation.
• Creating an order or support request after validating the inputs.
• Calling an external service through a configured Connection.
• Combining results from Database and integration operations.
• Using a shared backend helper exposed through Flow Share.
• Delegating a specialized task to another configured AI Agent.
• Requesting a simple model response without using another Agent's knowledge or threads.

Do not use a Function merely to include static reference material. A File Knowledge Source is usually more appropriate for documents, while a Table Knowledge Source is appropriate for controlled access to a Project Database table.

Add the Function Definition

To define a Function:

1. Open AI Agents in the Project Editor.
2. Open the Agent's actions and select Settings.
3. Expand Knowledge Sources (Files, Databases, Functions, etc).
4. Select Add → Custom Function.
5. Enter the Function Name.
6. Write a detailed Description.
7. Add each required parameter.
8. Select Continue.
9. Open Edit Flow for the Agent and implement the matching function.

Function and parameter names cannot contain spaces or special characters and must start with a letter. Use stable names such as lookupOrder, calculateDeliveryDate, or createSupportCase.

After a Function has been created, its name cannot be edited. If the identity must change, create a replacement definition and update its implementation.

Write a Useful Description

The model uses the Function description to decide whether and how to call it. Describe:

• What the Function does.
• When it should be used.
• What information it requires.
• What it returns.
• Important limits or preconditions.
• Whether the operation changes Project or external data.
• Whether user confirmation is required before a consequential action.

For example, a description for lookupOrder should explain which order identifier it accepts, whether it returns only the current user's order, and the shape of the returned status information. A description such as gets an order is not enough to distinguish safe and correct use.

Descriptions guide the model; they do not enforce security. The implementation must validate the actual parameters and authenticated user.

Define Parameters

Each parameter has:

Setting	Purpose
Parameter Name	The property name provided to the implementation.
Parameter Description	Explains the value, format, and intended use.
Parameter Type	Defines the expected JSON-compatible type.
Allowed Values	Optionally restricts string, integer, or number inputs to a comma-separated set.

Supported parameter types are:

• string
• integer
• number
• boolean
• object
• array

For an object, describe its expected properties. For an array, describe the type and meaning of each item. Keep schemas focused; a smaller, explicit schema is easier for the model to populate and for the implementation to validate.

Allowed Values are supported only for string, integer, and number parameters. The editor converts numeric values to the selected numeric type.

Implement the Function in Cloud Flow

Open the Agent's actions and select Edit Flow. Add the AI Agent Function Implementation block and set Function Name to the exact name used in the Knowledge Source.

Inside the implementation, use:

• AI Agent Function Params Object to access the model-supplied parameter object.
• AI Agent Auth Info to access the authentication information supplied for this Agent run.
• Current User with the AI Agent Auth Info to retrieve the authenticated username.
• Current User is in group and role with the AI Agent Auth Info to check group membership and minimum role level.
• Standard Cloud Flow blocks, Connection blocks, Flow Share, or Custom Code for the operation itself.

The implementation must return an ioLoop Result Object. A successful result has status: true, the response value in data, and err: null. A failed result has status: false, data: null, and a useful error in err.

Conceptually:

AI Agent Function Implementation: lookupOrder
  Read orderId from AI Agent Function Params Object
  Read user from AI Agent Auth Info
  Validate orderId
  Verify that the user may access the order
  Retrieve the permitted record

  If successful:
    Return Result Object(status: true, data: permitted order summary, err: null)

  Otherwise:
    Return Result Object(status: false, data: null, err: safe error message)

If the implementation reaches its end without returning a result, the function call fails.

For exact block behavior, see the AI Agents Cloud Flow reference.

Function Inputs and Trust Boundaries

A registered implementation can receive three forms of input:

Input	Meaning	Trust Guidance
Function parameters	Values selected or constructed by the AI model according to the Function schema.	Validate type, range, identity, and business rules.
Authentication information	Runtime-provided information about the user invoking the Agent, including public/admin state and user identity.	Use supported Agent-user helpers for authorization decisions.
Request context	Application-defined context supplied by the Agent client or by runAgentPrompt.	Treat as caller-supplied data, not authentication.

When the Agent calls a Function, the runtime supplies the Agent user's authentication information separately from reqContext. The implementation can use Current User and Current User is in group and role, or the corresponding Server APIs, to decide whether the user may perform the operation and whether the result should be limited or modified.

The implementation does not need the model or caller to place the username or permissions in the Function parameters or request context. In Custom Code, $io.system.registerAgentFunction supplies the parameters, authentication information, and request context as separate arguments to the registered function. The visual Function blocks expose the parameter and authentication objects used by the common implementation workflow.

Never trust a customer identifier, role, ownership claim, or permission flag merely because it appears in a Function parameter or request context. Derive authorization from the authenticated user and trusted Project data.

Direct Database Access

The automatic access checks described for a Table Knowledge Source apply when the Agent uses that built-in table tool. They are not automatically added around arbitrary Database operations performed by a Custom Function.

A Function runs as trusted server-side Cloud Flow. If it reads or modifies a protected table directly, its implementation must use AI Agent Auth Info and trusted Project data to enforce the required group, role, ownership, record-level, and operation-specific rules before accessing the table. This remains necessary even when the same table is also configured as a Table Knowledge Source.

If a public Agent exposes a Function without these checks, any data or operation reachable through the Function can become available to unauthenticated users. Return only the fields the caller is authorized to receive, and apply the same care to create, update, and delete operations as to reads.

Calling Connections

A Function can call configured Connections using supported Cloud Flow blocks or service-specific Server APIs.

Use a Function when application logic must decide how a Connection is called, validate inputs, combine several calls, or return a controlled subset of the provider response. Keep credentials in the Connection profile.

The Connection profile authorizes access to the external service; it does not authorize the Agent user. Before calling a protected Connection operation, use the Function's AI Agent Auth Info to decide whether the current user may cause that operation. This is particularly important when the Agent is public or when the Connection can return private information or change external state.

Handle provider timeouts, rejected requests, rate limits, and partial completion. If an external action may be retried, use an appropriate idempotency or duplicate-prevention strategy.

See Using Connections and Connection Services.

Calling Other AI Agents

A Function implementation can delegate work to another Agent with $io.system.runAgentPrompt, or use $io.system.runAgentSimplePrompt when it needs only a model response.

Method	Behavior
runAgentPrompt	Runs the target Agent with its instructions, Knowledge Sources, Function tools, and other Agent configuration.
runAgentSimplePrompt	Uses the target Agent's underlying provider/model without its Agent configuration or conversation threads.

This makes it possible to create specialized Agents. For example, a customer-facing Agent can call a separate classification Agent through a Function, then use the structured classification result in its response.

A nested full Agent run is a separate service-style run. It does not append messages to the user's Widget conversation for the target Agent.

Prevent Recursive Agent Calls

Agent delegation can create cycles:

Agent A Function → Agent B
Agent B Function → Agent A

An Agent can also call itself. Do not allow unbounded recursion.

When composing Agents:

• Assign each Agent a narrow responsibility.
• Pass a depth or workflow marker in request context when appropriate.
• Reject calls beyond a defined depth.
• Set explicit termination conditions.
• Prefer structured output between Agents.
• Handle timeout and failure without repeatedly calling the same Agent.
• Account for provider usage and latency at every nested level.

See Invoking AI Agents.

Using Request Context

runAgentPrompt can pass application-defined reqContext to Function implementations and Agent database callbacks.

Request context can carry values such as:

• A workflow or correlation identifier.
• A source-module label.
• A bounded delegation depth.
• Application data already validated by the calling workflow.
• Information needed to correlate logs or results.

When one Function invokes another Agent, construct and forward only the context the target workflow needs. Request context is not automatically a security credential and must not replace the authentication information supplied by the runtime.

Reusing Shared Backend Logic

If several Web Hooks, Background Tasks, or Agent functions require the same helper, define it in a Background Task and expose it through Flow Share.

Background Tasks load before AI Agent modules, so the Agent's flow can retrieve a helper during initialization. Load order does not wait for asynchronous setup; shared helpers that depend on delayed initialization need explicit readiness handling.

The helper should receive the current inputs and security context explicitly. Do not store per-user authentication or request-specific mutable state in a common Flow Share value.

See Flow Share.

Security and Side Effects

Before performing a protected or consequential operation, the Function should:

1. Validate every model-supplied parameter.
2. Determine the authenticated Agent user from the separately supplied authentication information.
3. Check group membership or trusted record ownership where required.
4. Apply current business rules using trusted data.
5. Confirm that the requested record or external resource is in scope.
6. Avoid returning sensitive fields that the caller does not need.
7. Record a safe diagnostic result without logging secrets.

The model's decision to call a Function is not authorization. A detailed Function description is not authorization. A value in reqContext is not authorization.

For operations with external or irreversible effects, consider explicit user confirmation, duplicate prevention, and an audit record appropriate to the application.

Testing Function Knowledge Sources

Test the definition and implementation together.

Test	What to Verify
Expected prompt	The model selects the Function and supplies suitable parameters.
Unrelated prompt	The Function is not called unnecessarily.
Missing parameter	The implementation rejects or safely handles incomplete input.
Wrong type or range	Runtime validation prevents an invalid operation.
Public user	Unauthenticated access follows the intended policy.
Authenticated user	Ownership and group rules are applied to actual identity.
Admin user	Administrative behavior is intentional rather than assumed.
Direct Database access	The Function applies table, group, ownership, record-level, and operation-specific authorization before reading or changing data.
Connection failure	The Function returns a controlled failure.
Duplicate request	Repetition does not create unintended duplicate effects.
Nested Agent failure	Delegation terminates and returns a useful error.
Recursive path	Depth and termination guards prevent a cycle.

Review the Agent's Run Logs to see Function entry, return, error, and exception events. Avoid logging full authentication objects, credentials, private provider responses, or sensitive records.

Troubleshooting

Issue	What to Check
Function is never called	Function description, Agent instructions, parameter descriptions, and whether the Function source is active.
Implementation not found	Exact Function name in the Knowledge Source and AI Agent Function Implementation block.
Function reports no return value	Ensure every successful and failed path returns an ioLoop Result Object.
Parameters are incorrect	Parameter types, descriptions, allowed values, and validation in the implementation.
User check fails	AI Agent Auth Info input, Agent context, group identifier, and role level.
Connection call fails	Connection configuration, provider response, input format, and runtime logs.
Nested Agent loops or times out	Delegation graph, depth marker, termination condition, and repeated retry logic.
Old behavior persists	Saved flow, test runtime restart where needed, existing chat history, and publishing state.

Good Practices

• Give the Function one clear responsibility.
• Use precise names and detailed descriptions.
• Keep parameter schemas small and explicit.
• Validate every model-generated argument.
• Return minimal, structured data that the Agent can interpret safely.
• Keep authentication and request context conceptually separate.
• Use Flow Share for common helpers, not per-user state.
• Bound Agent-to-Agent delegation and background loops.
• Handle retries and external side effects deliberately.
• Test both authorized and unauthorized calls.

For the broader module context, see AI Agent Cloud Flow. For exact API contracts, see the Server $io.system API.