Knowledge Sources

Knowledge Sources define the information, data, and tools an AI Agent can use while responding to a prompt. They can provide reference material, controlled access to Project data, Project-defined functions, web search, or tools supplied by configured Connections.

Knowledge Sources are configured separately for each Agent. Adding a source makes it available to that Agent; it does not make it available automatically to every Agent in the Project.

Choose Sources by Responsibility

Start with the Agent's intended responsibility, then add only the sources needed to fulfill it.

Requirement	Knowledge Source
Answer questions using a document	File
Read or modify Project records	Database Table
Run Project-specific server logic	Custom Function
Retrieve current information from the web	Web Search
Use tools advertised by an MCP server	MCP Server
Use AI functions exposed by a supported service	Connection

For example, a support Agent might use product-document files and a Function that retrieves an authorized order status. It does not need update access to the entire orders table merely because order information is involved.

Before Adding Knowledge Sources

An Agent must be initialized with an AI provider Connection before its Knowledge Sources can be managed.

Before adding a source:

1. Confirm the Agent's purpose and intended users.
2. Configure and test any required Connection under Integrations.
3. Configure Project Database permissions for any table the Agent will use.
4. Decide whether the Agent needs information only or also needs permission to perform actions.
5. Prepare a clear description that tells the Agent what the source contains and when to use it.

Descriptions are part of the Agent's decision-making context. Avoid vague text such as customer data or use when needed. Describe the relevant data, purpose, important constraints, and expected result.

Adding a Knowledge Source

To add a source:

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.
5. Choose the Knowledge Source type.
6. Complete the settings for that type.
7. Continue to add the source.
8. Review its status in the Knowledge Sources list.
9. Test prompts that should and should not use the source.

Use the refresh control when recently created tables or Connections are not shown.

Changing an Agent's Knowledge Sources can affect existing conversations because earlier messages remain in chat history. The Project Editor may recommend clearing chat history after a configuration change. See Managing and Testing AI Agents.

File Knowledge Sources

A File Knowledge Source provides reference material that the Agent can search and use when producing an answer.

You can specify a supported URL or select a file from the Project's files. The settings include:

Setting	Purpose
File URL / selected file	Identifies the source file.
Display Title	Provides the title associated with the file.
Description	Explains the file's subject and when it is relevant.
AI Model Parameters (Advanced)	Supplies an optional provider-specific JSON object for advanced file behavior.

To add a file:

1. Choose Add → File.
2. Enter the file URL or browse the available Project files.
3. Enter a useful Display Title.
4. Add a description when it helps distinguish the file from other sources.
5. Leave the advanced parameters empty unless the selected provider's documented behavior requires them.
6. Select Continue and wait for processing to finish.

The file must remain available to the Agent. Replacing or removing the underlying Project file can make the Knowledge Source stale or unavailable. After changing source content, test retrieval with questions whose answers are present in the updated file.

Do not place secrets in a file merely because it is attached to an Agent. Configure credentials through Connections and apply the Project's normal data-handling requirements to source documents.

Web Search

Web Search allows the Agent to use supported web search behavior. It has no additional settings and can be added only once to an Agent.

To enable it, choose Add → Web Search. The Knowledge Sources list shows Web Search after it has been added.

Web content is external and untrusted. It can be outdated, inaccurate, malicious, or inconsistent with the Project's requirements. Do not treat a search result as authorization to perform an operation. For important decisions, ask the Agent to identify the basis for its answer and validate the information through an appropriate trusted process.

Provider capabilities can differ. The availability and behavior of web search may change when additional AI providers are supported.

Connection Knowledge Sources

A Connection Knowledge Source gives the Agent access to AI functions exposed by a supported Connection service.

Only Connections whose service supports AI Agent use are offered. For each Connection Knowledge Source, configure:

Setting	Purpose
Connection	Selects the configured Connection instance.
Description	Tells the Agent what the Connection can do and when and how it should use it.

The description should state the intended operations and relevant boundaries. For example, explain whether the Connection should look up information, create an external item, send a notification, or perform another supported action.

An Agent cannot add the same Connection twice. It also cannot add two Connection Knowledge Sources backed by the same Connection service implementation. If several profiles exist for one service, choose the Connection whose profile and environment match the Agent's responsibility.

The Connection's profile contains the service authentication or authorization information. It is not copied into the Agent. Changes to the Connection or profile can therefore affect Agent tools that depend on it.

Connection Access and Agent Users

A Connection Knowledge Source runs its functions with the selected Connection's stored profile. That profile authorizes ioLoop to communicate with the external service; it does not establish that the user invoking the Agent may perform every operation available through the Connection.

The Agent runtime supplies the Agent user's access groups to the Connection function. Whether and how those groups are checked depends on the function exposed by the Connection service. Do not assume that the Agent's Access (Security) settings, the Connection's access settings, or the external profile's scopes provide a complete per-user authorization check for every tool.

This distinction is especially important for a public Agent. If an exposed Connection function does not reject public use, an unauthenticated user may be able to cause the function to read external information, send messages, create or modify external resources, or perform other actions using the Connection profile.

Before adding a Connection Knowledge Source:

1. Review the functions exposed by that Connection service.
2. Add only a Connection whose profile and external permissions are appropriate for the Agent's audience.
3. Restrict the Agent to the intended client groups unless every exposed operation is safe for public use.
4. Test information retrieval and side-effecting operations as public, ordinary, unauthorized, and elevated users.
5. Use a Custom Function instead when the operation requires Project-specific authorization, input validation, ownership checks, result filtering, or confirmation before calling the Connection.

For service identifiers, supported AI Agent behavior, and provider-specific setup, see Connection Services. For the Connection and profile lifecycle, see Connections.

MCP Server Knowledge Sources

An MCP Server Knowledge Source exposes tools provided through an MCP or MCP-compatible Connection.

Configure:

Setting	Purpose
Name/Label	Gives the MCP source a recognizable name.
Description	Tells the Agent what the server provides and when its tools are appropriate.
Connection	Selects the MCP or MCP-compatible Connection.
Validation	Connects to the server and retrieves its advertised information and tools.
Allowed Tools	Optionally limits the Agent to a comma-separated list of tool names.

To add an MCP source:

1. Create and test the MCP Connection under Integrations.
2. In the Agent's Knowledge Sources, choose Add → MCP Server.
3. Enter a Name/Label and a detailed Description.
4. Select the Connection.
5. Use the validation control to verify the Connection and load its tools.
6. If the Agent should use only selected tools, copy their exact names into Allowed Tools.
7. Select Continue.

Validation is required before the source can be saved. If validation fails, review the Connection configuration and the MCP server's availability.

Restricting MCP Tools

Prefer an explicit Allowed Tools list when the server advertises more capabilities than the Agent requires. Tool descriptions and output come from the external server and must be treated as untrusted.

Before allowing a tool that changes external state, consider:

• Which Agent users are permitted to cause the action.
• Whether the tool needs an additional confirmation or business-rule check.
• What happens if the request is repeated.
• What information is sent to the MCP server.
• How failures and partial completion are reported.

Database Table Knowledge Sources

A Database Table source makes a Project Database table available to the Agent. Reading is available as part of the source; record creation, updates, and deletion must be enabled deliberately.

Table sources include a maximum records setting and separate controls for single-record and batch modifications. Built-in Table Knowledge Source operations enforce Project Database access rules, and custom table callbacks can provide additional filtering or authorization. These automatic checks do not wrap Database calls made independently by a Custom Function.

See Table Knowledge Sources.

Custom Function Knowledge Sources

A Custom Function describes an operation the model may request. Its implementation is registered in the Agent's Cloud Flow.

Defining the name, description, and parameters does not implement the function. The Agent's flow must contain a matching AI Agent Function Implementation block or supported custom code registration.

A function can perform Project operations, call Connections, use shared helpers, invoke another Agent, or request a simple model response. It must validate inputs, authorize the operation, and return an ioLoop Result Object. If it accesses a Database table directly, it must enforce the required table, group, role, ownership, and record-level rules itself.

See Function Knowledge Sources.

Editing and Removing Sources

Use the actions beside a Knowledge Source to edit or remove it. Some identity fields, such as a Function name or selected file, cannot be changed after creation; create a replacement when the source identity must change.

Before removing a source:

• Check instructions and Prompt Library entries that refer to it.
• Check Function implementations or shared helpers associated with it.
• Test how the Agent responds without the source.
• Consider existing chat history, which may still contain earlier results.

Removing a source prevents future runs from using it. It does not rewrite earlier messages or reverse external operations already performed through that source.

Testing Knowledge Sources

Use prompts that test both correct use and correct non-use.

Test	What to Verify
Direct question	The Agent uses the intended source and gives a relevant result.
Ambiguous request	The description helps the Agent choose the correct source.
Unavailable information	The Agent does not invent information absent from its sources.
Unauthorized user	Protected data or actions remain unavailable.
Invalid tool input	Functions and external tools reject malformed or unsafe input.
Provider failure	The workflow reports the failure without pretending the action succeeded.
Repeated request	Consequential tools avoid unintended duplicate side effects.
Changed source	Updated content and settings are reflected after any required history reset.

Review Agent Run Logs when a response suggests that the wrong source was selected or a tool failed.

Good Practices

• Keep the source set focused. Add sources that support the Agent's defined responsibility.
• Write operational descriptions. Explain both what a source provides and when it should be used.
• Grant the minimum operations needed. Read access does not imply that create, update, or delete should be enabled.
• Separate knowledge from authorization. A model choosing a tool does not authorize the underlying action.
• Treat external content as untrusted. Validate MCP output, web results, files, and Connection responses.
• Retest after changes. Instructions, descriptions, schemas, provider capabilities, and chat history can all influence source selection.
• Use generated references for exact interfaces. Product guides explain workflows; the Programming Guide defines precise blocks and APIs.

For Agent setup, see Creating and Configuring AI Agents. For testing and usage controls, see Managing and Testing AI Agents.