AI Agents
Makes Drupal taskable by AI agents, enabling automated site configuration and content management through AI-driven workflows.
ai_agents
Install
composer require 'drupal/ai_agents:^1.2'
Overview
The AI Agents module provides a comprehensive framework for creating and managing AI-powered automation within Drupal sites. It enables AI agents to perform tasks such as creating content types, managing fields, handling taxonomy, and other site configuration operations through natural language interactions.
The module implements a plugin-based architecture where each AI agent specializes in specific domain tasks. Agents can loop through tool calls, validate their actions, and respond to user queries with structured outputs. The module supports orchestration agents that can coordinate multiple specialized agents for complex multi-step tasks.
Key capabilities include: configuration entity management for AI agents, function calling tools for site manipulation, an event system for monitoring agent execution, rollback support for error recovery, and integration with CKEditor and AI Assistant modules.
Features
- Plugin-based AI Agent architecture with configurable behaviors, tools, and prompts
- Config entity system for defining and storing AI agent configurations with tool assignments
- Built-in agents for Content Type management (create, edit, query node types)
- Field Agent for creating and modifying entity fields, field storage, and display configurations
- Taxonomy Agent for vocabulary and term management including hierarchical structures
- Function calling tools (30+) for entity operations, schema access, and site configuration
- Looping agent execution with configurable max loops to prevent infinite cycles
- Tool usage limits and property restrictions for fine-grained control over agent capabilities
- Structured JSON output support with customizable schemas
- Event system for monitoring agent execution, tool calls, and responses
- Rollback functionality to revert configuration changes on errors
- Token replacement system with custom ai_agent token type
- Artifact storage system for managing large tool responses
- Role-based masquerading for agents to operate with specific permissions
- CKEditor integration for AI-assisted content editing
- AI Assistant API integration for triggering agents through conversational interfaces
- Configurable default information tools that run at agent initialization
- Support for file and image inputs in agent tasks
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
/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.
/admin/config/ai/agents/add
Form for creating new AI agent configuration entities with full customization of prompts, tools, and behavior settings.
/admin/config/ai/agents/explore
Development/debugging interface for running agents directly and viewing execution progress. Requires AI Agents Explorer submodule.
Permissions 1
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
Navigate to /admin/config/ai/settings and configure a default provider for the 'chat_with_complex_json' operation type.
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.
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.
Review the agent's tools configuration to ensure required tools are enabled. Check tool_usage_limits for any restrictions that might prevent tool usage.
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.
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.