# How to Create Plugin-Level Agents in the OpenAI Plugins Repository > Learn to create plugin-level agents in the OpenAI plugins repository. Define autonomous agents within your Codex plugin using YAML for orchestration and state management. - Repository: [OpenAI/plugins](https://github.com/openai/plugins) - Tags: how-to-guide - Published: 2026-06-28 --- **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//`. The Codex runtime discovers agents by scanning the plugin manifest at `plugins//.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//`. ### 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`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/.codex-plugin/plugin.json), add the agents field pointing to your YAML files: ```json { "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`](https://github.com/openai/plugins/blob/main/plugins/my-plugin/agents/openai.yaml) with the following minimal structure: ```yaml 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`](https://github.com/openai/plugins/blob/main/plugins/zoom/skills/zoom-apps-sdk/agents/openai.yaml): ```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`](https://github.com/openai/plugins/blob/main/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//.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/` - Agents register under the plugin namespace at `/.agents//` - 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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/plugin.json). Each agent operates independently with its own namespace (`/`) and can target different models or skill sets.