How to Add Agents to an OpenAI Plugin: Implementation Guide

To add agents to an OpenAI plugin, create an agents/ directory inside your plugin folder, write a markdown definition file describing the agent's role and constraints, and optionally provide a YAML policy file to control invocation behavior and token budgets.

The openai/plugins repository enables developers to extend plugins with specialized agents—LLM-driven assistants that perform automated tasks like security audits or policy reviews. Agents reside in a dedicated agents/ directory within each plugin and are automatically discovered by the Codex runtime at initialization.

Understanding Agent Components

Each agent consists of two primary files: a markdown definition that instructs the LLM how to behave, and an optional YAML policy that governs how and when the agent may be invoked.

Agent Definition Files (Markdown)

Every agent requires a markdown file named <agent-name>.md stored in plugins/<plugin-name>/agents/. This file must contain a clear role definition, operational purpose, behavioral rules, and expected output format. For a concrete implementation, see the Zoom plugin's [agents/zoom-oauth-scope-auditor.md](https://github.com/openai/plugins/blob/main/plugins/zoom/agents/zoom-oauth-scope-auditor.md) (lines 1‑17), which demonstrates how to structure an agent that audits OAuth scopes.

Invocation Policy Files (YAML)

While optional, a YAML policy file named <agent-name>.yaml (or a shared agents/openai.yaml for multiple agents) is strongly recommended. According to the Zoom plugin README (lines 12‑16), this file sets policy.allow_implicit_invocation: false to require explicit agent calls, defines a description string, and specifies a token budget under cost.tokens to prevent runaway LLM usage.

Step-by-Step: Adding Agents to Your Plugin

Step 1: Create the Agents Directory

Inside your target plugin folder, create the agents/ subdirectory if it does not exist. The Codex runtime scans this location during startup to register available agents.

mkdir -p plugins/myplugin/agents

Step 2: Write the Markdown Definition

Create a file named <agent-name>.md containing the agent’s instructions. Define the agent’s identity, purpose, strict rules it must follow, and the exact output format you expect.

cat > plugins/myplugin/agents/my-reviewer.md <<'EOF'
You are the MyPlugin Review Agent.
Purpose:
- Review user-submitted content for compliance with MyPlugin policies.
Rules:
- Reject anything that violates the policy.
- Provide a concise feedback summary.
Output format:
1. Findings ordered by severity
2. Suggested remediation
EOF

Step 3: Configure the Invocation Policy (Optional)

Add a YAML file to control runtime behavior. Set allow_implicit_invocation to true only if the agent should run automatically; otherwise, keep it false for explicit invocation only.

cat > plugins/myplugin/agents/my-reviewer.yaml <<'EOF'
policy:
  allow_implicit_invocation: false   # Agent must be called explicitly

  description: "Compliance reviewer for MyPlugin"
  cost:
    tokens: 5000                      # Rough budget for a single call

EOF

Step 4: Verify Agent Discovery

The runtime automatically discovers agents by scanning the agents/ directory. While not mandatory, you can optionally reference agent IDs in your plugin’s .codex-plugin/plugin.json manifest under a custom field (e.g., "agents": ["my-reviewer"]).

Validate your implementation with a quick Python check:

import pathlib

plugin_root = pathlib.Path("plugins/myplugin")
agent_file = plugin_root / "agents" / "my-reviewer.md"
policy_file = plugin_root / "agents" / "my-reviewer.yaml"

print("Agent file exists:", agent_file.is_file())
print("Policy file exists:", policy_file.is_file())

Complete Working Example

The following script combines the setup commands to create a fully functional compliance agent in a single execution:

# Create directory structure

mkdir -p plugins/myplugin/agents

# Write agent definition

cat > plugins/myplugin/agents/my-reviewer.md <<'EOF'
You are the MyPlugin Review Agent.
Purpose:
- Review user-submitted content for compliance with MyPlugin policies.
Rules:
- Reject anything that violates the policy.
- Provide a concise feedback summary.
Output format:
1. Findings ordered by severity
2. Suggested remediation
EOF

# Write invocation policy

cat > plugins/myplugin/agents/my-reviewer.yaml <<'EOF'
policy:
  allow_implicit_invocation: false
  description: "Compliance reviewer for MyPlugin"
  cost:
    tokens: 5000
EOF

# Verify files were created

python3 - <<'PY'
import pathlib
plugin_root = pathlib.Path("plugins/myplugin")
print("Agent ready:", (plugin_root / "agents" / "my-reviewer.md").is_file())
print("Policy ready:", (plugin_root / "agents" / "my-reviewer.yaml").is_file())
PY

Key Files and Their Roles

• .codex-plugin/plugin.json — The central plugin manifest that may optionally list agent IDs under a custom agents array.
• plugins/<plugin-name>/agents/<agent-name>.md — The markdown definition containing the agent's role, rules, and output format (e.g., zoom/agents/zoom-oauth-scope-auditor.md).
• plugins/<plugin-name>/agents/<agent-name>.yaml (or agents/openai.yaml) — The YAML policy controlling implicit invocation permissions, description metadata, and token cost budgets.
• plugins/<plugin-name>/README.md — Documentation file that should reference the agents directory structure, as demonstrated in the Zoom plugin.

Summary

• Create an agents/ directory inside your plugin folder to house agent definitions.
• Define each agent in a <agent-name>.md file with clear role instructions, rules, and output formats.
• Control runtime behavior using an optional <agent-name>.yaml policy file to set allow_implicit_invocation and token budgets.
• Discover agents automatically via the Codex runtime scan, or optionally declare them in .codex-plugin/plugin.json.

Frequently Asked Questions

Where should I place the agents folder?

Create the agents/ directory inside your specific plugin folder (e.g., plugins/zoom/agents/). The Codex runtime recursively scans plugin directories for this folder name during initialization.

Is the YAML policy file mandatory?

No, the YAML policy is optional but recommended. Without it, the runtime uses default settings that may allow implicit invocation. Explicitly setting allow_implicit_invocation: false ensures the agent only runs when directly called, preventing accidental execution.

How does the Codex runtime discover agents?

The runtime automatically discovers agents by scanning for markdown files in any agents/ subdirectory within the plugins/ tree. You do not need to register agents in .codex-plugin/plugin.json, though doing so can improve documentation clarity.

Can I restrict how agents are invoked?

Yes. Set policy.allow_implicit_invocation: false in your agent's YAML policy file to require explicit invocation (e.g., via openai.ChatCompletion.create(..., agent="agent-name")). You can also set cost.tokens to limit the LLM budget per call, protecting against excessive token consumption.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}