Orchardcore AI Tools

Orchard Core AI Tools - Prompt Templates

Register and Select AI Tools

You are an Orchard Core expert. Generate secure AI tool registration and selection patterns for CrestApps AI Services. A tool is a named AITool registered in the shared Core tool definitions and resolved as a keyed service when an authorized completion needs it.

Guidelines

• Enable CrestApps.OrchardCore.AI for the Orchard Core AI tool selection and permission integration.
• Register a tool through AddCoreAITool<TTool>(name) and give it a unique, stable name.
• AddCoreAITool registers the keyed AITool service and its definition under the same name. Do not register an unrelated duplicate keyed service.
• A new Core tool is hidden by default. Call .Selectable() only when Orchard users should be able to select it.
• Set title, description, and category with the returned builder; these values drive capability pickers.
• GetSelectableTools() excludes tools marked as system tools. System tools are for internal orchestration paths and are not shown in capability pickers.
• LocalToolRegistryProvider returns only names configured on the completion context, skips system tools, and checks AccessAITool authorization.
• The provider resolves a selected tool from DI with GetKeyedService<AITool>(toolName).
• Tool selection is stored as FunctionInvocationMetadata.Names for AI Profiles.
• Profile-source templates store selected names in ProfileTemplateMetadata.ToolNames.
• Chat Interactions store selected names in ChatInteraction.ToolNames.
• Direct-config workflow tasks store selected names in AICompletionWithConfigTask.ToolNames.
• Capability editors group tools by category and filter them by the current editor's permission.
• The AccessAnyAITool permission is security-critical. Dynamic AccessAITool_{toolName} permissions are created for registered definitions.
• Do not make privileged system-management, content-management, or external side-effect tools available by default.
• Tool metadata must accurately describe side effects, required access, and argument expectations so orchestration can select safely.
• Install CrestApps packages in the web/startup project.

Feature Overview

Install and Enable

Install AI Services in the web/startup project:

dotnet add package CrestApps.OrchardCore.AI

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Agent"
      ],
      "disable": []
    }
  ]
}

Enable CrestApps.OrchardCore.AI.Agent only when the site needs its Orchard-management tool catalog. A custom local tool does not require the Agent feature.

Register a Custom Tool

Register a named tool in the web/startup project or custom Orchard module. The shared Core registration API adds its definition and keyed service:

using CrestApps.Core.AI.Tooling;
using Microsoft.Extensions.DependencyInjection;

namespace MyModule;

public sealed class Startup : OrchardCore.Modules.StartupBase
{
    public override void ConfigureServices(IServiceCollection services)
    {
        services.AddCoreAITool<LookupOrderTool>("lookup_order")
            .WithTitle("Order Lookup")
            .WithDescription("Looks up a customer's order status by order identifier.")
            .WithCategory("Commerce")
            .Selectable();
    }
}

Implement the tool using the shared AITool contract and a JSON schema that limits arguments. Give the tool a narrow description and perform authorization before accessing tenant data or making an external call.

Tool Sources and Registry Resolution

The orchestrator can combine registry sources. For local Orchard registrations:

1. AddCoreAITool adds a definition to AIToolDefinitionOptions and a keyed AITool service.
2. A profile, interaction, or workflow task supplies selected tool names in its completion context.
3. LocalToolRegistryProvider finds matching definitions.
4. It excludes entries where IsSystemTool is true.
5. It authorizes the current user against AIPermissions.AccessAITool and the tool name resource.
6. It resolves the keyed AITool instance and returns a local ToolRegistryEntry.

System tools follow a separate Core system-registry path. Orchard's LocalToolRegistryProvider resolves explicitly selected non-system tools in the current tenant and user authorization context. Do not expect system tools in profile, template, interaction, workflow-task, or post-session capability pickers.

Select Tools on an AI Profile

1. Register and authorize the tool.
2. Go to Artificial Intelligence → Profiles.
3. Edit the profile and open Capabilities.
4. Select tools in the grouped tool list.
5. Save the profile.

AIProfileToolsDisplayDriver saves the names in FunctionInvocationMetadata. It also reads the legacy AIProfileFunctionInvocationMetadata property for compatibility, but new integrations must use the current metadata.

Select Tools on a Profile Template

Only templates with Source = Profile show the tools editor:

1. Create or edit a profile-source template.
2. Select tools under Capabilities.
3. Save the template.
4. Create a profile from the template.

AIProfileTemplateToolsDisplayDriver stores ProfileTemplateMetadata.ToolNames, which can seed the generated profile configuration.

Select Tools on a Chat Interaction

Enable the interactions feature first:

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Chat.Interactions"
      ],
      "disable": []
    }
  ]
}

ChatInteractionToolsDisplayDriver filters selectable tools by the editing user's access and persists the selected names on ChatInteraction.ToolNames.

Use Tools in a Workflow Task

The AI Completion using Direct Config task accepts selected local tools. It configures ChatToolMode.Auto, resolves each selected name through IAIToolsService, and uses function invocation middleware with the configured maximum iterations.

{{ Workflow.Output["AI-order-summary"].Content }}

Use a direct-config task only for tightly controlled workflow automation. Prefer a dedicated profile when the completion should inherit a reusable profile policy and capability set.

Tool Permissions

AIToolPermissionProvider registers:

OrchardCoreAIToolAccessEvaluator delegates tool decisions to Orchard Core IAuthorizationService. Grant access per tool rather than granting AccessAnyAITool to ordinary users.

Security Checklist

• Model every tool as an explicit capability, not as an implicit extension of a profile.
• Use strict JSON schemas and validate all input before an external call or data mutation.
• Require the least-privileged AccessAITool_{toolName} permission.
• Keep destructive operations separate from read-only lookup tools.
• Mark internal orchestration-only tools as system tools so administrators cannot select them accidentally.
• Test with both authorized and unauthorized users before exposing a tool on a production profile.