# How to Add Custom Agents to a Plugin Using openai.yaml

> Learn to add custom agents to your OpenAI plugin by utilizing the openai.yaml file. Expose UI metadata and invocation policies for seamless integration.

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

---

**You add custom agents to an OpenAI plugin by placing an [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file inside a skill's `agents/` folder, which exposes the agent's UI metadata and optional invocation policies to the OpenAI platform.**

The [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) configuration file serves as the entry point for defining custom agents in the `openai/plugins` repository. Each agent represents a skill entry-point that the OpenAI platform can invoke through the ChatGPT interface or API. By placing this file in the correct directory structure, the plugin automatically registers the agent without requiring manual updates to the manifest.

## Understanding the openai.yaml Structure

The [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file contains two primary sections: `interface` for UI metadata and an optional `policy` block for runtime behavior controls.

### The Interface Section

The `interface` section provides human-readable metadata that appears in the OpenAI Plugin Marketplace and the ChatGPT UI. According to the source code in [`plugins/zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml), this section requires:

- **`display_name`**: The human-readable name shown in the marketplace
- **`short_description`**: A brief tagline explaining the agent's purpose
- **`icon_small`**: Relative path to a small icon (PNG or SVG recommended)
- **`icon_large`**: Relative path to a larger icon for detailed views
- **`default_prompt`**: Instructions that define the agent's behavior and capabilities

### The Policy Section (Optional)

The optional `policy` section controls how the OpenAI runtime invokes the agent. This block is defined in the same [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file and governs cost management and invocation methods.

Key policy fields include:

- **`allow_implicit_invocation`**: When set to `true`, the model can automatically select this agent based on user requests; when `false`, users must explicitly invoke it via tool calls
- **`explicit_only_invoke_cost_tokens`**: Sets an upper bound on token costs for explicit-only invocations
- **`estimated_static_policy_aware`**: When `true`, treats the agent as static for budgeting purposes, preventing inflation of implicit-invocation scores
- **`max_concurrency`**: (Advanced) Limits the number of parallel executions allowed

## Step-by-Step Implementation Guide

Follow these steps to add custom agents to your plugin:

1. **Create the directory structure** inside your skill folder:

   ```text
   plugins/<your-plugin>/skills/<skill-name>/agents/
   ```

2. **Create the [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file** in the `agents/` directory with your metadata:

   ```yaml
   interface:
     display_name: "My Awesome Agent"
     short_description: "Brief tagline for the agent"
     icon_small: "./assets/icon-small.png"
     icon_large: "./assets/icon.png"
     default_prompt: "You are My Awesome Agent. Help users accomplish specific tasks."
   
   policy:
     allow_implicit_invocation: false
     explicit_only_invoke_cost_tokens: 1000
   ```

3. **Provide asset files** referenced by `icon_small` and `icon_large` in the same directory or a subfolder like `./assets/`.

4. **Commit your changes**. The repository's CI pipeline automatically validates the [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) syntax against the OpenAI specification.

5. **Verify in the marketplace**. After deployment, the new agent appears under the plugin's *Agents* tab in the OpenAI Plugin Store.

## Configuring Agent Invocation Policies

Policy configuration allows fine-grained control over when and how your agent executes. In [`plugins/zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml) and similar implementations, these settings prevent unauthorized implicit invocations and manage computational costs.

Use **`allow_implicit_invocation: false`** when your agent performs expensive operations like code generation or database queries. This forces users to explicitly request the agent rather than having the model select it automatically.

Set **`explicit_only_invoke_cost_tokens`** to cap token consumption for safety-critical or resource-intensive agents. For example, a SQL generator agent might limit costs to 2000 tokens:

```yaml
policy:
  allow_implicit_invocation: false
  explicit_only_invoke_cost_tokens: 2000
  estimated_static_policy_aware: true

```

## Complete File Structure Example

Here is the complete directory layout for a plugin with custom agents, based on the repository structure at `openai/plugins`:

```text
plugins/
└─ my-plugin/
   ├─ skills/
   │  └─ sql-gen/
   │     ├─ agents/
   │     │  └─ openai.yaml        ← Metadata & policy configuration
   │     ├─ references/
   │     └─ SKILL.md
   └─ .codex-plugin/
      └─ plugin.json               ← Automatically discovers agents

```

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file (as seen in [`plugins/github/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/github/.codex-plugin/plugin.json)) automatically picks up agents by scanning the `agents/` directory for [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) files. No manual registration entries are required.

## Minimal Configuration Example

For a lightweight implementation similar to the Zotero plugin, use this minimal [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml):

```yaml
interface:
  display_name: "Zotero"
  short_description: "Search Zotero and add citations"
  icon_small: "./assets/icon.png"
  icon_large: "./assets/icon.png"
  default_prompt: "Use $Zotero to search my Zotero library, export BibTeX, and add citations to my draft."

```

## Summary

- **Place [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) in the `agents/` folder** of your skill directory to register custom agents automatically.
- **Define the `interface` section** with `display_name`, `short_description`, icons, and `default_prompt` for marketplace visibility.
- **Add optional `policy` controls** using `allow_implicit_invocation` and `explicit_only_invoke_cost_tokens` to manage invocation behavior and costs.
- **Reference files correctly** via relative paths for assets, and ensure the [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) exists in your plugin root.
- **Commit and push** to trigger automatic validation and marketplace updates.

## Frequently Asked Questions

### Where do I place the openai.yaml file when adding custom agents?

Place the [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file inside the `agents/` subdirectory of your specific skill folder, following the pattern `plugins/<plugin-name>/skills/<skill-name>/agents/openai.yaml`. The OpenAI platform scans this directory automatically to discover available agents.

### Is the policy section required in openai.yaml?

No, the `policy` section is optional. If omitted, the agent uses default invocation settings. However, for agents that perform expensive operations or require explicit user consent, adding `allow_implicit_invocation: false` is strongly recommended to prevent automatic selection by the model.

### How does the plugin manifest discover new agents?

The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) file automatically discovers agents by scanning the `agents/` directory for any [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) files. As implemented in the `openai/plugins` repository, you do not need to manually update the manifest or add registry entries when creating new agent configurations.

### What image formats are supported for agent icons?

The `icon_small` and `icon_large` fields in [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) support standard web image formats including PNG and SVG. Place these assets in the same directory as your [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file or in a subfolder (commonly `./assets/`) and reference them using relative paths.