Managing and Testing AI Agents

The AI Agents area provides controls for configuration, Cloud Flow logic, access, enabled state, cloning, deletion, usage, chat history, Run Logs, and generated files.

Manage an Agent as a combination of configuration and executable backend behavior. A change to instructions, a Function schema, Cloud Flow logic, or a dependent Connection can alter the same user workflow.

Agent Actions

Open an Agent's actions from the AI Agents list.

Action	Purpose
Settings	Configure the provider, instructions, model behavior, Knowledge Sources, Prompt Library, and usage.
Edit Flow	Implement Function Knowledge Sources and supported callbacks.
Access (Security)	Select the Project groups that may access the Agent from the client through an AI Agent Widget.
Enable / Disable	Control whether the Agent is enabled.
Clone	Create a separate Agent based on the selected Agent.
Delete	Remove the development Agent after required cleanup and dependency review.

The list can be viewed as tiles or a table. The table view shows the Agent name, enabled status, and Access (Security) groups.

Access and Security

Use Access (Security) to grant Execute access to the Project groups that may access the Agent from the client through an AI Agent Widget.

For the group identities and role levels available here, see User Groups. To create Project User accounts and assign their membership, see Users.

The editor warns when Public access is selected because an unauthenticated visitor could access the Agent through the Widget. Before allowing public client access, review:

• Instructions and possible disclosures.
• Every File and Table Knowledge Source.
• Every Function implementation.
• Connection and MCP tools.
• Generated files and external side effects.
• Rate, usage, and abuse considerations.

Agent Access (Security) is not checked when the Agent is invoked from trusted Cloud Flow. Background Tasks and AI Agent modules can invoke it directly. A Web Hook uses the Web Hook's own Access (Security) settings to admit callers; after that check passes, its flow can invoke the Agent regardless of the Agent's client access settings.

Neither client access nor trusted server invocation authorizes every underlying operation. Built-in Table Knowledge Source operations enforce table permissions, but Database access performed directly by a Function requires authorization in that Function. Connection functions receive the Agent user's access context, but enforcement depends on the function exposed by the service. The external profile authorizes the Connection to use the service; it does not by itself authorize the Agent user.

Test with actual users from the relevant groups. Administrative testing alone can conceal missing restrictions that ordinary users encounter.

Enable and Disable an Agent

Use Enable / Disable to control the Agent's enabled state.

Before disabling an Agent, identify dependencies such as:

• AI Agent Widgets.
• Web Hooks that invoke it.
• Background Tasks and timer-driven loops.
• Other Agent Function tools that delegate to it.
• Operational processes that expect its output.

A disabled dependency can cause a larger workflow to fail. Callers should handle that failure rather than assuming the Agent is always available.

After re-enabling, test initialization, Knowledge Sources, registered functions, and dependent workflows.

Clone an Agent

Use Clone to create a separate Agent based on an existing one. Enter a new name for the clone.

Cloning is useful for creating a specialized variation or testing a new configuration without changing the original. After cloning, review the entire Agent:

Review	Why It Matters
Provider Connection	The clone may need a different profile or environment.
Instructions and model parameters	The original responsibility may not match the clone.
Knowledge Sources	The clone may expose data or tools that are not appropriate.
Prompt Library	Prompts may refer to the original Agent's purpose.
Cloud Flow	Function names, shared dependencies, and nested Agent references may need changes.
Access (Security)	The clone should not automatically be assumed safe for the same Widget audience.
Enabled state and callers	Widgets and Cloud Flow callers are not automatically redirected to the clone.

Avoid leaving two enabled Agents with confusingly similar responsibilities when users or other modules can select the wrong one.

Manage Usage

Open Settings → Manage Usage (Run Logs, Chat History, Files, etc) to review Agent usage and maintenance controls.

Available controls include:

• Clear Chat History
• View Logs
• Clear Logs
• Delete Files
• Copy for loaded Run Log text

These operations affect Agent runtime data rather than its instructions or Cloud Flow definition.

Clear Chat History

Clear Chat History deletes chat history for all users of the Agent. It is not limited to the current Project Creator or one selected conversation.

Clear history when:

• A significant instruction or Knowledge Source change must be tested without earlier conversation context.
• Retained conversations are no longer required under the application's data policy.
• A broad reset is operationally intended and its effect on users is understood.

Do not use it casually as a per-user troubleshooting control. If only one test conversation is affected, start a new chat through the Widget where appropriate.

Changing configuration does not automatically rewrite existing messages. Earlier messages can continue influencing a conversation until a new chat is started or history is cleared.

View and Clear Run Logs

View Logs loads Agent Run Logs into the Settings panel. Logs can include:

• The initiating prompt.
• Run start and completion events.
• Function entry, return, error, and exception events.
• MCP tool activity.
• Cancellation and runtime errors.
• Timing information and the user associated with a run.

Use Copy when the displayed text needs to be reviewed elsewhere. Remove or protect sensitive information before sharing copied logs.

Clear Logs deletes the Agent's Run Logs. Clear them only when the diagnostic and audit value has been considered.

Logs can contain prompts, tool arguments, provider messages, or application information. Do not intentionally write credentials, access tokens, full authentication objects, or unnecessary sensitive records to logs.

Delete Generated Files

When Allow Running Code is enabled, Agent activity can generate charts, images, CSV files, and other artifacts in Project Cloud Storage.

Use Delete Files to remove AI-generated files for the Agent. The editor indicates that files may be restored by revisiting the chats in which they were generated, subject to the continued availability of those chats and provider behavior.

Deleting generated files does not delete chat history or Run Logs. Review links or workflows that rely on a generated file before removing it.

An Agent with generated files cannot be deleted until those files have been removed. Use Delete Files before deleting the Agent.

Test an Agent

Test the Agent through every surface that will invoke it.

Configuration Tests

• Provider Connection initializes successfully.
• System Instructions produce the intended scope and response style.
• Advanced parameters are valid for the selected provider.
• Prompt reinforcement improves behavior without creating conflicts.
• A new chat reflects changed settings.

Knowledge Tests

• File questions retrieve information actually present in the source.
• Web Search is used only when appropriate and external claims are treated cautiously.
• Table reads return only permitted records.
• Table modifications obey single/batch settings and authorization.
• Connection and MCP tools expose only intended capabilities.

Function Tests

• The model calls the correct Function.
• Function names match their implementations.
• Model-supplied inputs are validated.
• Public, ordinary, elevated, and unauthorized users receive the intended result.
• Every path returns an ioLoop Result Object.
• A Function that accesses the Database directly rejects users who would not be permitted to perform the equivalent protected table operation.
• A public Agent cannot use a Function to retrieve protected records or perform protected changes through trusted server access.
• Nested Agent calls terminate and propagate failures safely.

Connection Knowledge Source Tests

• Public and unauthorized Agent users cannot retrieve protected external information.
• Side-effecting tools cannot send messages or create, update, or delete external resources unless the Agent user is permitted to cause the operation.
• The selected Connection profile has only the external-service permissions needed by the Agent.
• Returned provider data is filtered to the fields the Agent user may receive.
• Repeated prompts do not cause unintended duplicate external actions.

Invocation Tests

• Widget conversations, controls, and history behave correctly.
• Web Hooks validate requests and filter Agent output.
• Background Tasks stop, resume, and avoid duplicate work as designed.
• Structured output is parsed and validated before use.
• Request context reaches the intended Function/callback and is not used as authentication.

Failure Tests

• Provider timeout or rejection.
• Connection or MCP service unavailable.
• Invalid or missing Function parameters.
• Missing Flow Share helper.
• Database authorization failure.
• Empty, malformed, or schema-incompatible model output.
• Runtime restart during Background Task processing.
• Disabled or deleted target Agent in a delegation workflow.

Development Test Runtime and Logs

Use the Cloud Flow Start Test, Stop Test, and Logs controls when testing Agent Cloud Flow behavior. Agent Run Logs and general Cloud Flow logs provide different perspectives:

Log	Useful For
Agent Run Logs	Prompt lifecycle, model tool selection, Function calls, MCP activity, and Agent-run failures.
Cloud Flow logs	Module initialization, custom server-side messages, shared-helper problems, and surrounding Web Hook or Background Task behavior.

Correlate both when a headless workflow spans several modules. Add safe correlation identifiers through request context when useful, but do not treat those identifiers as authentication.

For general backend testing guidance, see Testing and Logs.

Publishing

Tested development changes are not available to the published Project until the relevant changes are published.

Before publishing an Agent change:

1. Review the provider and dependent Connections.
2. Test the Agent's enabled state and client Access (Security) through its Widget.
3. Test its Widget and headless callers.
4. Verify Function implementations and shared Background Task helpers.
5. Confirm Database behavior against appropriate data and permissions.
6. Review external side effects, provider usage, and generated files.
7. Publish the Project.
8. Verify the published workflow with an appropriate user.

Development and published runtimes can use different Project data and lifecycle state. Do not assume a successful development test proves that production data, permissions, or external profiles are correct.

Delete an Agent

Delete an Agent only after reviewing every caller and dependency.

Before deleting:

• Remove or reconfigure AI Agent Widgets that select it.
• Update Web Hooks and Background Tasks that invoke it.
• Update Function implementations that delegate to it.
• Review Flow Share helpers created specifically for it.
• Delete AI-generated files through Manage Usage.
• Confirm that its Prompt Library, chat history, logs, and Knowledge Sources are no longer required.
• Consider published behavior that continues until a subsequent publish updates the Project.

Deleting the development Agent removes its associated Agent configuration and runtime data as part of cleanup. It does not reverse Database changes or external actions the Agent previously performed.

If deletion reports that generated files remain, return to Settings → Manage Usage, use Delete Files, and then retry deletion.

Troubleshooting

Issue	What to Check
Agent cannot initialize	Provider Connection, profile credentials, model parameters, and provider availability.
Changed behavior is not visible	Saved settings, new chat, cleared history where appropriate, test runtime, and publishing state.
Function works for admin only	Table permissions, Function group checks, ownership rules, invocation context, and test identity. For Widget calls, also check Agent Access (Security).
Widget cannot start a chat	Selected Agent, enabled state, Access (Security), and provider initialization.
Headless caller fails	Target Agent identifier, hook context, caller error handling, and target dependencies.
Run Logs are empty	Whether the Agent was actually invoked and whether logs were cleared.
Generated files consume storage	Allow Running Code usage and Delete Files under Manage Usage.
Agent cannot be deleted	Generated files and dependent cleanup.
Published behavior differs	Published configuration, production data, Connections, Widget Agent access, Web Hook access where applicable, and runtime logs.

Good Practices

• Give each Agent a defined responsibility and owner.
• Test with representative users, not only administrators.
• Start a new chat after material behavior changes.
• Keep logs useful without recording secrets.
• Review generated files and provider usage regularly.
• Treat cloning as the start of a new review, not proof that the clone is ready.
• Check every caller before disabling or deleting an Agent.
• Publish and verify related configuration and Cloud Flow changes together.
• Revisit permissions whenever a new Knowledge Source or Function is added.

For configuration settings, see Creating and Configuring AI Agents. For execution patterns, see Invoking AI Agents. For application identities and membership, see Users and User Groups.