Documentation / Developer Guidelines

Developer Guidelines

Updated May 5, 2026

Agentic Plugin Developer Guidelines

Welcome to the Agentic Plugin developer community! Before submitting your agent, please review these guidelines to ensure a smooth review process. Agents that meet these standards are approved faster and are more likely to be featured in the marketplace.

1. Code Quality Standards

  • Your agent must extend the AgenticAgent_Base class
  • Follow WordPress coding standards (WPCS) — use the official PHPCS ruleset
  • No obfuscated or minified PHP code
  • No external phone-home functionality without clear disclosure in the README
  • Include proper documentation and inline comments for all public methods
  • Use meaningful variable and function names — avoid single-letter variables outside of loop counters
  • Avoid global variables; use class properties or dependency injection instead

2. Security Requirements

  • Sanitize all inputs using sanitize_text_field(), absint(), or the appropriate WP function
  • Escape all outputs using esc_html(), esc_attr(), wp_kses(), or equivalent
  • Use WordPress nonces (wp_nonce_field() / wp_verify_nonce()) for all form submissions and AJAX requests
  • Implement proper capability checks (current_user_can()) before any privileged action
  • No hardcoded API keys, passwords, or credentials — use WordPress options or environment variables
  • Validate and sanitize any data written to the database; use $wpdb->prepare() for all custom queries
  • Tools that modify posts, files, or settings must verify the user has appropriate permissions before executing

3. Licensing

  • Agents must be licensed under GPL v2 or later, or a compatible open-source license
  • Include license information in the agent.php file header
  • Respect third-party licenses for any included libraries — bundled libraries must be GPL-compatible
  • Premium agents can charge for support, services, or additional features but the core PHP code must remain GPL

4. Naming Conventions

  • Do not use trademarks you do not own in your agent name (WordPress, OpenAI, Claude, Google, etc.)
  • Agent slugs cannot be changed after approval — choose carefully
  • Choose a unique, descriptive name that clearly reflects your agent’s purpose
  • Avoid names that could be confused with official Agent Builder built-in agents
  • Prefix your PHP classes and functions with a unique namespace to prevent conflicts with other plugins

5. Required Files

  • agent.php — Main agent file in the root of your ZIP archive
  • README.md — Documentation including: description, installation steps, usage instructions, configuration options, and a changelog
  • Proper file headers in agent.php with: Agent Name, Version, Description, Author, Author URI, License
  • A screenshots/ directory with at least one screenshot of the agent in action (PNG, max 1MB each)

6. Tool Registration

Each tool your agent registers must include a clear description field — this is what the LLM reads to decide when to use the tool. Vague descriptions like “does stuff” will cause the LLM to misuse or ignore the tool. Write descriptions as a single sentence explaining exactly what the tool does and what it returns.

  • Tool names must be lowercase, underscore-separated, and unique within your agent namespace
  • Tool parameters must include type hints and descriptions
  • Destructive tools (those that delete, overwrite, or send messages) must implement a confirmation step or require explicit user intent in the parameters

7. Testing Requirements

Before submitting, verify your agent against the following checklist:

  • Tested on WordPress 6.4+ with Agent Builder installed and active
  • No PHP warnings or errors in debug mode (WP_DEBUG = true)
  • All tools return the correct data types documented in their schema
  • Tools fail gracefully — errors return a structured error message, not a PHP exception or empty response
  • Tested with at least two different AI providers (e.g., OpenAI GPT-4o and Anthropic Claude)
  • Agent uninstalls cleanly — all custom database tables and options are removed on deletion

8. Review Process

After submission, your agent enters our review queue. We typically review submissions within 14 business days. During review we check: code quality, security, licensing compliance, README completeness, and that tools behave as documented. You will receive an email with the outcome. If your agent is rejected, the email will include specific feedback on what needs to change before resubmitting.

Common Rejection Reasons

  • Missing nonces on AJAX requests or form submissions
  • Unsanitized user input being stored in the database
  • Misleading tool descriptions that don’t match actual tool behaviour
  • Phone-home functionality (e.g., licence checks to remote servers) not disclosed in the README
  • Agent slug or name that infringes on a trademark
  • README missing installation or usage instructions

Ready to Submit?

Submit Your Agent

Frequently Asked Questions

Can I submit a paid/premium agent?

Yes. Premium agents are welcome on the marketplace. You can charge for the agent itself, or use a freemium model where the core agent is free and premium features require a licence key. All PHP code must remain GPL-licensed regardless of your pricing model. You may use a remote licence validation service, but this must be disclosed in your README.

Can I update my agent after it has been approved?

Yes. Submit an updated ZIP through the developer portal with an incremented version number and an updated changelog in your README. Minor updates (bug fixes, small improvements) are reviewed within 5 business days. Major version bumps that add new tools or change core behaviour go through a full 14-day review.

What happens if my agent is rejected?

You will receive an email with a list of specific issues to address. Fix each item, increment the version number, and resubmit. There is no limit on resubmissions. If you disagree with a rejection reason, reply to the review email and our team will take a second look.

Can my agent connect to external APIs or services?

Yes, but all external connections must be disclosed in the README under a “Third-Party Services” section. This includes any API calls to services other than the user’s configured AI provider. Users must be able to opt out of non-essential external connections. Connections that transmit user data must be covered by a privacy policy linked in your README.

Do I need to handle my own tool errors, or does Agent Builder do that?

You handle your own tool errors. Agent Builder does not catch exceptions thrown inside tool callbacks — an unhandled exception will surface as a generic error to the user and may break the conversation flow. Your tools should return a structured error array (e.g., ['error' => 'Description of what went wrong']) rather than throwing exceptions, so the LLM can relay the issue to the user gracefully.

Is there a limit to how many tools an agent can register?

There is no hard limit in the platform, but practical LLM context limits apply. Most LLMs handle up to 64 tools reliably. Beyond that, tool selection accuracy drops. If your agent has many tools, group them logically and consider whether some should be split into separate agents rather than combined into one.

Related Articles

Browse all documentation →