How Agents Are Defined for OpenAI Plugins: YAML Configuration Guide

Agents in OpenAI plugins are defined using YAML configuration files stored in the hidden .agents/skills/<skill-name>/agents/ directory, where each openai.yaml file declares the agent's metadata, JSON Schema inputs/outputs, system prompts, and few-shot examples.

The OpenAI plugins repository employs a declarative, file-based architecture for defining AI agents. Instead of embedding agent logic directly in application code, developers create structured YAML files that the Agents SDK consumes at runtime. This configuration-driven approach enables version-controlled, reusable agent definitions that multiple plugins can reference simultaneously.

Agent Definition Structure and File Locations

Agents reside in a specific hidden directory hierarchy within the repository:

/.agents/
├─ skills/
│  └─ <skill-name>/
│     └─ agents/
│        └─ openai.yaml          ← Primary agent definition
├─ plugins/
│  ├─ marketplace.json         ← Marketplace catalog
│  └─ api_marketplace.json     ← API discovery metadata
└─ ...

Each skill (a reusable capability unit) contains an agents subfolder housing one or more YAML definition files. While openai.yaml serves as the conventional filename, you can define multiple agent variants within a single skill directory to support different runtime configurations.

Supporting infrastructure files include:

• .agents/plugins/marketplace.json: The marketplace catalog consumed by the Codex UI for agent discovery
• plugins/*/.codex-plugin/plugin.json: Plugin manifests that bind specific YAML files to plugin endpoints

Anatomy of the Agent YAML Configuration

The openai.yaml file follows a strict schema that dictates how the Agents SDK initializes, validates, and executes the agent.

Required Metadata Fields

Every agent definition must specify identification and runtime fields:

• name: Human-readable identifier (e.g., build-zoom-virtual-agent)
• description: UI-facing explanation displayed in the Codex interface
• type: Runtime specification, typically set to openai for LLM-driven agents

Input and Output Schemas

The inputs and outputs fields use JSON Schema to enforce type safety at the API boundary:

inputs:
  type: object
  properties:
    query:
      type: string
      description: The question to answer.
outputs:
  type: object
  properties:
    answer:
      type: string
      description: The model's generated response.

These schemas validate request data before LLM invocation and structure the model's return values for downstream consumers.

Prompt Engineering and Few-Shot Examples

The prompt field contains the system instruction that guides LLM behavior. Optional samples provide few-shot context:

prompt: |
  You are a helpful assistant. Answer the user's query concisely.
samples:
  - input: { "query": "What is the capital of France?" }
    output: { "answer": "Paris." }

The complete YAML for a minimal agent definition in .agents/skills/example-skill/agents/openai.yaml looks like this:

name: Example Agent
description: Demonstrates a minimal agent definition.
type: openai
inputs:
  type: object
  properties:
    query:
      type: string
      description: The question to answer.
outputs:
  type: object
  properties:
    answer:
      type: string
      description: The model's answer.
prompt: |
  You are a helpful assistant. Answer the user's query concisely.
samples:
  - input: { "query": "What is the capital of France?" }
    output: { "answer": "Paris." }

Registering Agents in Plugin Manifests

For a plugin to expose an agent, it must declare the relationship in its plugin.json file located at plugins/<plugin-name>/.codex-plugin/plugin.json:

{
  "name": "example-plugin",
  "description": "Plugin exposing the Example Agent",
  "agents": [
    {
      "id": "example-agent",
      "yamlPath": ".agents/skills/example-skill/agents/openai.yaml"
    }
  ]
}

The yamlPath key points to the relative repository location of the agent definition. This indirection allows multiple plugins to reference the same underlying agent configuration without duplication, creating a shared library of capabilities.

Runtime Execution via the Agents SDK

At runtime, the Agents SDK loads the YAML configuration from the specified path, constructs the final prompt using the prompt field and any provided samples, and invokes the OpenAI model (e.g., gpt-4-turbo). The SDK validates the model's response against the outputs JSON Schema before returning data to the caller.

Example invocation using the JavaScript SDK:

import { Agents } from '@openai/agents-sdk';

async function run() {
  const agent = await Agents.load('example-agent');
  const result = await agent.run({ query: 'Explain quantum entanglement.' });
  console.log(result.answer);
}
run();

The SDK handles schema validation, prompt templating, and response parsing automatically based on the YAML definition.

Summary

• Agents are defined declaratively in YAML files located at .agents/skills/<skill-name>/agents/openai.yaml
• Configuration includes metadata (name, description, type), JSON Schema validation (inputs/outputs), and prompt engineering (prompt, samples)
• Plugins reference these YAML files via the yamlPath property in their plugin.json manifests
• The Agents SDK reads these definitions at runtime to initialize LLM-driven workflows with built-in schema validation
• Marketplace metadata in .agents/plugins/marketplace.json enables discovery across the plugin ecosystem

Frequently Asked Questions

What file format is used to define agents in OpenAI plugins?

Agents are defined using YAML configuration files. Each agent requires a separate .yaml file (conventionally named openai.yaml) stored within the .agents/skills/<skill-name>/agents/ directory structure. These files declare the agent's schema, prompts, and runtime behavior.

How do I reference an existing agent in my plugin?

Reference the agent's YAML file path in your plugin's plugin.json manifest using the yamlPath property. The path should be relative to the repository root, such as .agents/skills/example-skill/agents/openai.yaml. This allows the Codex runtime to locate and load the agent definition.

Can I define multiple agents within a single skill?

Yes. A skill directory can contain multiple agent YAML files within its agents subfolder. Each file represents a distinct agent configuration with unique prompts, inputs, and outputs. This enables variations of a skill tailored to different use cases while sharing underlying infrastructure.

What is the purpose of the inputs and outputs schemas in the YAML definition?

The inputs and outputs fields use JSON Schema to enforce type safety and validation. The schema validates incoming data before sending it to the LLM and ensures the model's response conforms to expected structures. This contract-based approach prevents runtime errors and standardizes agent interfaces across the plugin ecosystem.

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