# How to Create Agents Within a Plugin Using `agents/openai.yaml`

> Learn to create agents in your OpenAI plugin by adding an openai.yaml file to the agents directory. Define interfaces and policies for seamless marketplace integration.

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

---

**You create agents within a plugin by placing an [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file in the skill's `agents/` directory, defining the `interface` metadata and optional `policy` controls that the OpenAI platform automatically discovers and surfaces in the marketplace.**

The OpenAI plugins repository enables developers to extend AI capabilities through modular skills that expose specialized agents. Each agent acts as a skill entry-point that the platform invokes, configured through a single YAML file that supplies both UI metadata for the marketplace and fine-grained invocation policies for the runtime.

## Understanding the [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) Structure

The configuration file divides into two primary sections: the required `interface` block that drives the marketplace UI, and the optional `policy` block that governs runtime constraints.

### The Interface Section

This section supplies human-readable metadata that appears in the OpenAI Plugin Store and ChatGPT UI. According to the canonical Zotero implementation at [`plugins/zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml), valid fields include:

- **`display_name`**: The agent's title in the marketplace
- **`short_description`**: A brief tagline explaining functionality
- **`icon_small`** and **`icon_large`**: Relative paths to PNG or SVG asset files
- **`default_prompt`**: The system prompt context provided when the agent initializes

### The Policy Section (Optional)

When you need fine-grained control over how the model invokes your agent, the `policy` section specifies runtime constraints. This controls whether the agent can be selected automatically or requires explicit tool calls, among other behaviors.

## Step-by-Step Guide to Creating an Agent

Follow these steps to add an agent to your plugin using the [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) configuration method:

1. **Create the directory structure.** Inside your skill folder, create an `agents/` subdirectory:
   ```text
   plugins/<your-plugin>/skills/<skill-name>/agents/
   ```

2. **Add the configuration file.** Create [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) in that directory with the required interface fields:
   ```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. ..."
   ```

3. **Provide visual assets.** Place the icon files referenced by `icon_small` and `icon_large` in the specified relative paths (typically an `assets/` subfolder).

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 your plugin's *Agents* tab in the OpenAI Plugin Store.

## Controlling Agent Invocation with Policy Fields

The optional `policy` section in [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) lets you enforce specific runtime behaviors. These fields control costs, concurrency, and invocation methods:

- **`allow_implicit_invocation`**: Set to `false` to require explicit tool calls rather than automatic model selection
- **`explicit_only_invoke_cost_tokens`**: Integer cap on token costs for explicit-only invocations (e.g., `1000` or `2000`)
- **`estimated_static_policy_aware`**: When `true`, treats the agent as static for budgeting purposes, preventing inflation of the implicit-invocation score
- **`max_concurrency`**: (Advanced) Limits the number of parallel executions of this agent

## Complete Configuration Examples

### Minimal Configuration (Zotero Style)

Based on the reference implementation at [`plugins/zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/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."

```

### Advanced Configuration with Policy Controls

For agents requiring strict invocation controls, such as expensive SQL generation tools:

```yaml
interface:
  display_name: "SQL Generator"
  short_description: "Generate parameterised SQL queries"
  icon_small: "./assets/sql-sm.png"
  icon_large: "./assets/sql.png"
  default_prompt: "You are a SQL generator. ..."

policy:
  allow_implicit_invocation: false
  explicit_only_invoke_cost_tokens: 2000
  estimated_static_policy_aware: true

```

### Directory Structure

The complete layout for a skill with an agent configuration:

```text
plugins/
└─ my-plugin/
   ├─ skills/
   │  └─ sql-gen/
   │     ├─ agents/
   │     │  └─ openai.yaml
   │     ├─ references/
   │     └─ SKILL.md
   └─ .codex-plugin/
      └─ plugin.json

```

## How the Platform Discovers Your Agents

The OpenAI plugin infrastructure implements automatic discovery—no manual registration required. When you place [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) in the `agents/` folder, the platform scans this directory during the build process. The plugin manifest at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) automatically picks up the agent definition, as demonstrated in the GitHub plugin example at [`plugins/github/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/plugins/github/.codex-plugin/plugin.json) within the OpenAI plugins repository.

This discovery mechanism means you can add multiple agents to a single plugin by creating separate [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) files in different skill directories, each with independent metadata and policy configurations.

## Summary

- **Create an `agents/` folder** inside your skill directory to house the configuration file
- **Define the `interface` section** in [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) to control marketplace display names, descriptions, icons, and default prompts
- **Add the optional `policy` section** to restrict implicit invocation, set token cost caps, or configure concurrency limits
- **Rely on automatic discovery**—the platform detects [`agents/openai.yaml`](https://github.com/openai/plugins/blob/main/agents/openai.yaml) files without manual manifest updates at [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json)
- **Validate through CI**—the repository automatically checks YAML syntax when you commit changes

## Frequently Asked Questions

### What is the exact file path for the openai.yaml configuration?

The file must reside at `plugins/<your-plugin>/skills/<skill-name>/agents/openai.yaml` within the repository. For example, the Zotero plugin uses [`plugins/zotero/skills/zotero/agents/openai.yaml`](https://github.com/openai/plugins/blob/main/plugins/zotero/skills/zotero/agents/openai.yaml) to define its agent interface.

### Do I need to manually register the agent in the plugin manifest?

No. The platform automatically discovers agents by scanning the `agents/` directory for [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) files. The [`.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) manifest updates automatically to include these definitions, eliminating manual registration steps.

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

The `icon_small` and `icon_large` fields accept relative paths to standard web image formats, typically PNG or SVG files. Place these assets in the same directory or a subdirectory (such as `assets/`) relative to the [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml) file.

### How do I restrict an agent to explicit invocation only?

Set `allow_implicit_invocation: false` in the `policy` section of your [`openai.yaml`](https://github.com/openai/plugins/blob/main/openai.yaml). This configuration forces the model to invoke the agent through explicit tool calls rather than automatic selection based on user intent matching.