Building a Custom Agent

This guide covers the full structure of an Agent Builder agent — from file layout to packaging. If you want to build agents without code, see the Assistant Trainer instead.

File Structure

An agent is a folder (named with its slug) containing at minimum two files. When you distribute an agent, you ZIP this folder.

my-agent/
├── agent.php              # Required — main agent class
├── README.md              # Required — description and documentation
├── abilities.json         # Recommended — tool risk levels and knowledge files
├── knowledge/             # Optional — reference data files
├── abilities-signature    # Auto-generated — integrity hash
└── templates/
    └── system-prompt.txt  # Recommended — the agent system prompt

agent.php — The Main File

Every agent must have an agent.php file in the root of its folder. This file contains a file header and a class that extends AgenticAgent_Base.

File Header

The header follows the same convention as WordPress plugin headers:

<?php
/**
 * Agent Name: My Custom Agent
 * Version: 1.0.0
 * Description: A short description of what this agent does.
 * Author: Your Name
 * Author URI: https://yoursite.com
 * Category: content
 * Tags: writing, automation, posts
 * Capabilities: edit_posts
 * Icon: 🤖
 * Requires PHP: 8.1
 * Requires at least: 6.4
 * License: GPL v2
 */

Key fields:

• Agent Name — displayed in the admin UI and marketplace
• Category — groups your agent in the marketplace (content, security, seo, maintenance, utility)
• Capabilities — WordPress capabilities required to use this agent (e.g. edit_posts, manage_options)
• Icon — an emoji displayed next to the agent name
• Tags — comma-separated keywords for marketplace search

The Agent Class

Your class must extend AgenticAgent_Base and implement the required methods:

class My_Custom_Agent extends AgenticAgent_Base {

    public function get_id(): string {
        return 'my-custom-agent';  // Must match the folder name
    }

    public function get_name(): string {
        return 'My Custom Agent';
    }

    public function get_description(): string {
        return 'A short description of what this agent does.';
    }

    public function get_system_prompt(): string {
        // Load from a template file (recommended)
        $file = __DIR__ . '/templates/system-prompt.txt';
        return file_exists( $file ) ? file_get_contents( $file ) : '';
    }

    public function get_icon(): string {
        return '🤖';
    }

    public function get_category(): string {
        return 'utility';
    }

    public function get_required_capabilities(): array {
        return [ 'edit_posts' ];
    }

    public function get_welcome_message(): string {
        return "👋 Hi! I'm your custom agent. How can I help?";
    }

    public function get_suggested_prompts(): array {
        return [
            'Do something useful',
            'Help me with a task',
        ];
    }

    public function get_tool_names(): array {
        return [
            'list_posts',
            'get_post_content',
            'create_post_content',
        ];
    }
}

Registering the Agent

At the bottom of agent.php, register your agent with the plugin:

add_action( 'agentic_register_agents', function ( $registry ) {
    $registry->register( new My_Custom_Agent() );
} );

System Prompt

The system prompt defines your agent’s personality, expertise, and behaviour rules. Store it in templates/system-prompt.txt and load it from get_system_prompt().

A good system prompt includes:

• Role definition — who the agent is and what it specialises in
• Behaviour rules — how it should respond, what tone to use
• Tool usage instructions — when to use which tools
• Safety boundaries — what the agent should never do

abilities.json — Tool Risk Levels

The abilities.json file declares which tools your agent uses and their risk level. Agent Builder uses this for the 5-tier safety system.

{
  "$schema": "https://agentic-plugin.com/schemas/abilities/v1.json",
  "version": "1.0",
  "agent": "my-custom-agent",
  "description": "Tools for my custom agent",
  "abilities": {
    "list_posts":          { "risk": "none" },
    "get_post_content":    { "risk": "none" },
    "create_post_content": { "risk": "medium", "reason": "Creates new posts" },
    "update_post_content": { "risk": "medium", "reason": "Modifies existing content" },
    "delete_post":         { "risk": "high",   "reason": "Permanently removes content" }
  }
}

Risk levels control approval behaviour:

• none — runs automatically, no approval needed
• low — runs automatically but logged
• medium — pauses for approval in Supervised mode
• high — always pauses for approval
• extreme — disabled by default, must be manually enabled

Knowledge Files

Agents can declare knowledge_files in their abilities.json to receive reference data in their system prompt. This is ideal for giving agents access to structured information like product catalogs, FAQs, company policies, or platform documentation.

{
  "tools": { ... },
  "knowledge_files": [
    "library/knowledge/platform-knowledge.txt",
    "library/knowledge/my-agent-knowledge.txt"
  ]
}

Paths are relative to the plugin directory. At runtime, the agent controller reads each file and appends its content to the system prompt. The bundled Assistant Trainer, WordPress Assistant, and Plugin Assistant all ship with platform reference data via this system.

You can also set knowledge per-agent from the admin UI via Settings → Personas → Knowledge. Content entered there is saved as a knowledge file and automatically linked in the agent’s abilities.json.

• Keep files under 50KB for optimal prompt performance
• Use plain text with clear section headers for best LLM comprehension
• Multiple agents can share the same knowledge file
• Changes take effect immediately — no restart needed
• Knowledge files are covered by integrity verification (abilities-signature)

README.md

Every agent must include a README.md. This is displayed on the agent’s detail page in the marketplace and in the admin UI. Include:

• What the agent does
• Example prompts users can try
• List of tools and what each one does
• Any requirements or limitations

Available Tools

Agent Builder ships with dozens of built-in tools your agent can use. List the ones your agent needs in get_tool_names(). See Agent Tools for the full reference of available tools.

You can also define custom tools by implementing them in your agent class. Each tool is a PHP method that receives parameters from the LLM and returns a result.

Integrity Verification

The abilities-signature file contains a SHA-256 hash of your abilities.json. Agent Builder verifies this at runtime — if the signature does not match, the agent is blocked from running. This prevents tampering with tool permissions after distribution.

The signature is generated automatically when you submit your agent to the marketplace.

Packaging and Distribution

1. Make sure your folder name matches the slug returned by get_id()
2. ZIP the folder: zip -r my-custom-agent.zip my-custom-agent/
3. Test by uploading via Agent Builder → Installed Agents → Upload Assistant
4. When ready, submit to the marketplace

Quick Reference

Method	Required	Purpose
get_id()	Yes	Unique slug, must match folder name
get_name()	Yes	Display name in UI
get_description()	Yes	Short description
get_system_prompt()	Yes	Instructions for the LLM
get_icon()	Yes	Emoji icon
get_category()	Yes	Marketplace category
get_required_capabilities()	Yes	WordPress caps needed to use agent
get_tool_names()	Yes	List of tools the agent can call
get_welcome_message()	No	Opening message in chat
get_suggested_prompts()	No	Quick-action buttons in chat

Next Steps

• Agent Tools Reference — all available built-in tools
• Permissions and Safety — the 5-tier risk system
• Developer Guidelines — submission requirements
• Selling on the Marketplace — publish and monetise your agent