# How to Add Agents to an OpenAI Plugin: Implementation Guide

> Learn how to add agents to your OpenAI plugin. This guide covers creating agent definitions and policy files for enhanced functionality. Implement agents effectively today!

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**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/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`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) for multiple agents) is strongly recommended. According to the [Zoom plugin README](https://github.com/openai/plugins/blob/main/plugins/zoom/README.md) (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.

```bash
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.

```bash
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.

```bash
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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest under a custom field (e.g., `"agents": ["my-reviewer"]`).

Validate your implementation with a quick Python check:

```python
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:

```bash

# 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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/zoom/agents/zoom-oauth-scope-auditor.md)).
- **`plugins/<plugin-name>/agents/<agent-name>.yaml`** (or [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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.