How to Create Plugin-Level Agents in the OpenAI Plugins Repository

Plugin-level agents are autonomous YAML-defined brains that live inside a Codex plugin, orchestrating skills and maintaining private state through the agents/ directory and manifest registration.

The openai/plugins repository enables developers to extend Codex capabilities through modular plugins. When you create plugin-level agents, you embed autonomous decision-making logic directly within your plugin structure, allowing the system to handle complex workflows, call external APIs, and persist conversation state without external orchestration.

Understanding Plugin Agent Architecture

Every plugin-level agent resides within a specific plugin directory under plugins/<plugin-name>/. The Codex runtime discovers agents by scanning the plugin manifest at plugins/<plugin-name>/.codex-plugin/plugin.json. If this JSON file contains an agents array or the plugin contains an agents/ folder, Codex loads the YAML definitions found there and registers them under the plugin's namespace.

Directory Structure and Manifest Discovery

The system expects a standardized layout for agent discovery:

plugins/
└─ my-plugin/
   ├─ .codex-plugin/
   │   └─ plugin.json          # declares agents array

   ├─ agents/
   │   └─ openai.yaml          # agent definition file

   ├─ skills/                 # callable skill bundles

   └─ assets/                 # static resources

When Codex scans the repository, it parses every plugins/*/.codex-plugin/plugin.json to identify available agents. The manifest may contain an agents field that points to relative paths (e.g., "agents": ["agents/openai.yaml"]). Once discovered, the runtime registers the agent at the endpoint /.agents/<plugin-name>/<agent-name>.

The Agent YAML Schema

Agent definitions follow the OpenAI agent schema implemented in the repository. A valid configuration requires name, description, model, and instructions fields. You can optionally define memory for state persistence and tools for skill integration.

The runtime wires these components together by:

1. Validating the YAML against the agent schema
2. Loading the specified model (e.g., gpt-4o, gpt-4o-mini)
3. Initializing memory stores with the configured TTL
4. Binding tools to the skill endpoints declared in the tools section

Creating Your First Plugin-Level Agent

Step 1: Define the Plugin Manifest

First, ensure your plugin manifest includes the agents array. In plugins/my-plugin/.codex-plugin/plugin.json, add the agents field pointing to your YAML files:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "agents": [
    "agents/openai.yaml"
  ]
}

This declaration tells Codex to look for agent definitions in the agents/ subdirectory relative to the plugin root.

Step 2: Create the Agent YAML Definition

Create the file plugins/my-plugin/agents/openai.yaml with the following minimal structure:

name: my-plugin-openai
description: |
  A tiny agent that echoes back whatever the user says.
model: gpt-4o-mini
instructions: |
  You are a friendly echo bot. Return the user's last message verbatim.
memory:
  type: simple
  ttl: 86400
tools: []

This registers the agent under the namespace my-plugin/openai. When a user invokes the agent via the Codex UI or API, the runtime passes the latest user message to the specified model and returns the generated response.

Step 3: Integrate Skills via Tools

To enable your agent to perform actions beyond simple text generation, reference skill endpoints in the tools section. Here is a production example from the Zoom plugin at plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml:

name: zoom-sdk-agent
description: Interacts with the Zoom Apps SDK to list meetings.
model: gpt-4o
instructions: |
  Use the provided Zoom SDK skill to retrieve the list of upcoming meetings and format them as a markdown table.
tools:
  - name: list_meetings
    description: Returns a list of meetings from the Zoom SDK.
    type: http
    url: /skills/zoom-apps-sdk/list_meetings
    method: GET
memory:
  type: simple
  ttl: 3600

The url field references the skill endpoint relative to the plugin's base path. This allows the agent to orchestrate complex workflows by calling GET or POST requests to your plugin's internal skills.

Managing Agent State and Permissions

Memory Configuration

The memory section in the YAML definition controls how agents maintain context between interactions. According to the schema implemented in openai/plugins, you can specify:

• type: Currently supports simple for basic key-value persistence
• ttl: Time-to-live in seconds (e.g., 86400 for 24 hours)

Because agents inherit the same access permissions as their parent plugin defined in plugin.json, you can scope capabilities by restricting the plugin's policy settings. This inheritance model makes it straightforward to limit agents to read-only operations or specific network domains without additional configuration.

Summary

• Plugin-level agents are defined in YAML files within the agents/ directory of a plugin
• The plugins/<plugin-name>/.codex-plugin/plugin.json manifest must declare agents via the agents array
• Agent configurations specify model, instructions, memory TTL, and tool integrations
• Skills are integrated through the tools section by referencing HTTP endpoints under /skills/<skill-name>
• Agents register under the plugin namespace at /.agents/<plugin-name>/<agent-name>
• State persistence uses the memory configuration with configurable TTL

Frequently Asked Questions

What is the difference between a plugin and a plugin-level agent?

A plugin is the container structure defined by the manifest in .codex-plugin/plugin.json, while a plugin-level agent is an autonomous runtime component defined by YAML in the agents/ directory. The plugin provides the security context and skill endpoints, whereas the agent provides the decision-making logic and conversation state management.

How do I reference skills inside an agent definition?

Reference skills in the tools array of your agent YAML by specifying the endpoint path relative to your plugin's base. For example, setting url: /skills/zoom-apps-sdk/list_meetings allows the agent to call that specific skill when the model decides to invoke the list_meetings tool.

Where does the agent store its state?

Agents store state according to the memory configuration in their YAML definition. When you specify type: simple and a ttl value, the runtime maintains a private memory store for that agent instance that persists for the specified duration (in seconds) between conversations.

Can I deploy multiple agents in a single plugin?

Yes. You can define multiple YAML files in the agents/ directory and list each one in the agents array within plugin.json. Each agent operates independently with its own namespace (<plugin-name>/<agent-name>) and can target different models or skill sets.

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