AI Agents

Makes Drupal taskable by AI agents, enabling automated site configuration and content management through AI-driven workflows.

ai_agents
5,523 sites
40
drupal.org
api gui integration
ai automation agents Configuration content-management taxonomy fields llm function-calling chatbot
Drupal 10 Drupal 11

インストール

Drupal 11, 10 v1.2.1
composer require 'drupal/ai_agents:^1.2'

概要

AI Agentsモジュールは、Drupalサイト内でAI駆動の自動化を作成・管理するための包括的なフレームワークを提供します。AIエージェントがコンテンツタイプの作成、フィールド管理、タクソノミー処理、その他のサイト設定操作を自然言語でのやり取りを通じて実行できるようにします。

このモジュールはプラグインベースのアーキテクチャを採用しており、各AIエージェントが特定のドメインタスクに特化しています。エージェントはツールコールをループ処理し、アクションを検証し、構造化された出力でユーザーのクエリに応答できます。複雑なマルチステップタスクのために複数の専門エージェントを調整するオーケストレーションエージェントもサポートしています。

主な機能には、AIエージェント用のコンフィグエンティティ管理、サイト操作用のファンクションコーリングツール、エージェント実行監視用のイベントシステム、エラー回復用のロールバックサポート、CKEditorおよびAI Assistantモジュールとの統合が含まれます。

Features

  • 設定可能な動作、ツール、プロンプトを備えたプラグインベースのAIエージェントアーキテクチャ
  • ツール割り当てを含むAIエージェント設定を定義・保存するためのコンフィグエンティティシステム
  • コンテンツタイプ管理用の組み込みエージェント（ノードタイプの作成、編集、クエリ）
  • エンティティフィールド、フィールドストレージ、表示設定の作成・変更用フィールドエージェント
  • 階層構造を含むボキャブラリとタームの管理用タクソノミーエージェント
  • エンティティ操作、スキーマアクセス、サイト設定用のファンクションコーリングツール（30以上）
  • 無限ループを防ぐための設定可能な最大ループ数によるループエージェント実行
  • エージェント機能の詳細な制御のためのツール使用制限とプロパティ制限
  • カスタマイズ可能なスキーマによる構造化JSON出力サポート
  • エージェント実行、ツールコール、レスポンスを監視するイベントシステム
  • エラー時に設定変更を元に戻すロールバック機能
  • カスタムai_agentトークンタイプによるトークン置換システム
  • 大きなツールレスポンスを管理するためのアーティファクトストレージシステム
  • 特定のパーミッションでエージェントを操作するためのロールベースのマスカレード
  • AI支援コンテンツ編集のためのCKEditor統合
  • 会話型インターフェースを通じてエージェントをトリガーするAI Assistant API統合
  • エージェント初期化時に実行される設定可能なデフォルト情報ツール
  • エージェントタスクでのファイルと画像入力のサポート

Use Cases

Automated Content Type Creation

Site builders can describe content type requirements in natural language (e.g., 'Create an Event content type with title, date, location, and description fields'). The Content Type Agent creates the node type with appropriate settings, then the Field Agent can add the required fields with proper configurations.

Field Management via Natural Language

Developers can request field modifications such as 'Add a media reference field for images to the Article content type and place it after the body field in the form display'. The Field Agent handles field storage creation, field config, and display configuration automatically.

Taxonomy Structure Generation

Content managers can populate taxonomies by saying 'Create a vocabulary called Product Categories and add 20 common e-commerce categories with appropriate hierarchy'. The Taxonomy Agent creates the vocabulary and generates relevant terms with parent-child relationships.

AI-Assisted Content Editing

Content editors using CKEditor can invoke configured AI agents to generate or transform content directly in the editor. For example, summarizing selected text, generating content based on prompts, or reformatting existing content.

Chatbot-Driven Site Configuration

Through AI Assistant API integration, administrators can configure their Drupal site via conversational interface. The chatbot routes requests to appropriate agents, enabling non-technical users to make configuration changes safely.

Custom Agent Development

Developers can create custom AI agents by implementing the AiAgentInterface or extending AiAgentBase. Custom agents can handle domain-specific tasks like workflow management, content migration planning, or integration with external services.

Orchestrated Multi-Step Tasks

Complex site setup tasks can be handled by orchestration agents that coordinate multiple specialized agents. For example, setting up an e-commerce site by sequentially invoking content type, field, taxonomy, and view agents.

Tips

  • Use the AI Agents Explorer module during development to debug agent behavior and view execution details step-by-step.
  • Configure the chat_with_complex_json default provider in AI settings, as agents require this for proper function calling support.
  • Set appropriate max_loops values to prevent runaway agent execution while allowing enough iterations for complex tasks.
  • Use tool_usage_limits to constrain agent behavior by forcing values or restricting property options for security and consistency.
  • Enable structured_output when you need programmatic access to agent results with guaranteed schema compliance.
  • Use the default_information_tools configuration to pre-load context that agents commonly need, reducing unnecessary tool calls.
  • Leverage the event system to monitor agent execution, log activities, or implement custom validation.
  • For production deployments, carefully review agent permissions and consider role-based access restrictions through agent_settings.
  • Custom prompts in the prompts/ directory can be overridden through configuration without modifying code.
  • The rollback() method provides automatic recovery when agent actions fail, reverting configuration changes.

Technical Details

Admin Pages 3
AI Agents /admin/config/ai/agents

Lists all available AI agents with their descriptions. Provides links to edit individual agent configurations. Shows both code-defined plugins and config entity agents.

Add AI Agent /admin/config/ai/agents/add

Form for creating new AI agent configuration entities with full customization of prompts, tools, and behavior settings.

AI Agent Explorer /admin/config/ai/agents/explore

Development/debugging interface for running agents directly and viewing execution progress. Requires AI Agents Explorer submodule.

権限 1
Administer AI Agent

Allows users to create, edit, and delete AI Agent configurations.

Hooks 2
hook_ai_function_call_info_alter

Alters the function call plugin definitions. Used by AI Agents to register agent wrapper functions that expose agents as callable tools.

hook_ai_agents_info_alter

Alters AI agent plugin definitions discovered by the plugin manager.

Troubleshooting 6
Agent returns 'ERROR: Sorry, the Agents will not work unless you set up a default Chat with Complex JSON model'

Navigate to /admin/config/ai/settings and configure a default provider for the 'chat_with_complex_json' operation type.

Agent loops indefinitely or times out

Check the max_loops setting for the agent. Reduce the value or review the agent's system prompt to ensure it can reach completion within the loop limit.

Tool execution fails with permission errors

Verify the current user has the required Drupal permissions for the operation (e.g., 'administer content types', 'administer taxonomy'). Consider using masquerade_roles if agents need elevated permissions.

Agent doesn't use expected tools

Review the agent's tools configuration to ensure required tools are enabled. Check tool_usage_limits for any restrictions that might prevent tool usage.

Structured output validation fails

Ensure the structured_output_schema is valid JSON Schema format. Verify the schema matches what the AI is capable of producing based on the system prompt.

Configuration changes not rolling back on error

Rollback only works for configuration entities tracked during the agent run. Custom operations in custom agents need to implement their own rollback logic.

Security Notes 8
  • AI Agents can make significant configuration changes to your Drupal site. Only grant 'administer ai_agent' permission to trusted administrators.
  • Use tool_usage_limits to restrict what values agents can use for sensitive operations.
  • The masquerade_roles feature allows agents to bypass normal user permission checks - use with caution and audit regularly.
  • Agent prompts are visible to AI providers - avoid including sensitive information like API keys in system prompts.
  • Enable the hide_property option in tool_usage_limits for properties containing sensitive values like API keys.
  • Review and test agent behavior in development environments before deploying to production.
  • The secured_system_prompt field (visible only when show_secured_ai_agent_system_prompt is set in settings.php) can contain instructions hidden from UI editors.
  • AI Agents Explorer should not be enabled on production sites as it exposes detailed execution information.