# What Are Agent Descriptors? Structure and Location in OpenAI Plugins

> Discover agent descriptors in OpenAI plugins. Learn their structure and common locations within metadata files to define autonomous agent capabilities and requirements.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: deep-dive
- Published: 2026-09-13

---

**Agent descriptors are JSON or YAML metadata files that define autonomous agents within OpenAI plugins, specifying capabilities, tool schemas, and runtime requirements to enable dynamic instantiation and validation by the OpenAI platform.**

Agent descriptors serve as the declarative backbone for autonomous agents in the OpenAI plugins ecosystem. These structured configuration files allow the OpenAI runtime to discover, validate, and invoke agent capabilities without hardcoded logic. In the `openai/plugins` repository, each agent is accompanied by a descriptor that formalizes its interface and operational constraints.

## Understanding Agent Descriptors

An **agent descriptor** is a machine-readable manifest that encapsulates an agent's identity, functionality, and environmental requirements. According to the source code in the openai/plugins repository, these files enable the platform to expose agents in the ChatGPT interface while ensuring type-safe interactions through JSON Schema validation.

The descriptor declares:

- **Identity metadata**: Human-readable `name` and `description` fields that identify the agent's purpose
- **Tool specifications**: Available operations and HTTP endpoints the agent can invoke
- **Input/output schemas**: JSON-Schema definitions that validate arguments and return values
- **Environment configuration**: Required variables and runtime hints for proper execution

## Where Agent Descriptors Are Located

In the openai/plugins codebase, agent descriptors follow a consistent organizational pattern. They reside in plugin-specific directories under the `agents/` folder, typically as JSON files.

Common file paths include:

- [`plugins/figma/agents/figma-implementation-agent.json`](https://github.com/openai/plugins/blob/main/plugins/figma/agents/figma-implementation-agent.json)
- [`plugins/figma/agents/design-system-rules-agent.json`](https://github.com/openai/plugins/blob/main/plugins/figma/agents/design-system-rules-agent.json)
- [`plugins/zoom/agents/virtual-agent.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/agents/virtual-agent.json)
- [`plugins/vercel/agents/type-safe-agent.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/agents/type-safe-agent.json)
- [`plugins/temporal/agents/openai-agents-sdk.json`](https://github.com/openai/plugins/blob/main/plugins/temporal/agents/openai-agents-sdk.json)

Each plugin maintains its agents in isolated subdirectories, allowing the OpenAI platform to load descriptors dynamically based on the requested service integration.

## Anatomy of an Agent Descriptor File

A complete agent descriptor contains several mandatory and optional fields that define the agent's contract with the runtime.

### Core Identification Fields

- **name**: Unique identifier for the agent (e.g., "figma-implementation-agent")
- **description**: Concise summary of the agent's purpose and capabilities

### Tool and Schema Definitions

- **tools**: Array of available tools with HTTP endpoints and operation types
- **inputSchema**: JSON-Schema defining required parameters and their types
- **outputSchema**: JSON-Schema describing the structure of return values

### Runtime Configuration

- **environment**: Map of required environment variables (e.g., `Figma-Access-Token`)
- **metadata**: Version information, author attribution, and licensing details

## Practical Implementation Example

The following JSON structure illustrates a complete agent descriptor for the Figma implementation agent:

```json
{
  "name": "figma-implementation-agent",
  "description": "Generates Figma component implementations from design specs.",
  "tools": [
    {
      "type": "http",
      "name": "createComponent",
      "endpoint": "POST https://api.figma.com/v1/components",
      "inputSchema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "frameId": { "type": "string" }
        },
        "required": ["name", "frameId"]
      },
      "outputSchema": {
        "type": "object",
        "properties": {
          "componentId": { "type": "string" }
        }
      }
    }
  ],
  "environment": {
    "Figma-Access-Token": "required"
  },
  "metadata": {
    "version": "1.2.0",
    "author": "OpenAI"
  }
}

```

## Loading Agent Descriptors Programmatically

When building tooling around the openai/plugins repository, you can load agent descriptors using standard file system operations. The following Node.js example demonstrates dynamic descriptor loading:

```javascript
import fs from 'fs';
import path from 'path';

function loadAgentDescriptor(plugin, agent) {
  const descriptorPath = path.join(
    __dirname,
    'plugins',
    plugin,
    'agents',
    `${agent}.json`
  );
  const raw = fs.readFileSync(descriptorPath, 'utf-8');
  return JSON.parse(raw);
}

// Load the Figma implementation agent
const figmaAgent = loadAgentDescriptor('figma', 'figma-implementation-agent');
console.log(figmaAgent.name); // → figma-implementation-agent

```

This pattern allows automated validation tools and runtime environments to discover available agents without manual registration.

## Summary

- **Agent descriptors** are JSON or YAML configuration files that define autonomous agent capabilities in OpenAI plugins
- **Location pattern**: Stored in `plugins/<plugin-name>/agents/` directories throughout the repository
- **Key components** include identity fields, tool specifications, JSON Schema definitions for inputs/outputs, and environment requirements
- **Runtime function**: Enable dynamic discovery, argument validation, and type-safe invocation through the OpenAI platform
- **Implementation examples** are found in [`plugins/figma/agents/figma-implementation-agent.json`](https://github.com/openai/plugins/blob/main/plugins/figma/agents/figma-implementation-agent.json) and similar paths for Zoom, Vercel, and Temporal integrations

## Frequently Asked Questions

### What file format do agent descriptors use?

Agent descriptors typically use **JSON** or **YAML** formats to declare agent metadata and capabilities. The openai/plugins repository primarily utilizes JSON files with descriptive naming conventions such as [`figma-implementation-agent.json`](https://github.com/openai/plugins/blob/main/figma-implementation-agent.json).

### How does the OpenAI platform use agent descriptors?

The platform reads these descriptors to **expose agents** in the ChatGPT UI as selectable assistants, **validate arguments** against declared JSON Schemas to prevent malformed calls, and **generate OpenAPI specifications** that downstream models can invoke dynamically.

### Where can I find examples of agent descriptors in the repository?

Production examples are located at specific paths including [`plugins/figma/agents/figma-implementation-agent.json`](https://github.com/openai/plugins/blob/main/plugins/figma/agents/figma-implementation-agent.json), [`plugins/zoom/agents/virtual-agent.json`](https://github.com/openai/plugins/blob/main/plugins/zoom/agents/virtual-agent.json), and [`plugins/vercel/agents/type-safe-agent.json`](https://github.com/openai/plugins/blob/main/plugins/vercel/agents/type-safe-agent.json). Each follows the standardized schema for agent definition.

### What is the difference between an agent and a plugin?

A **plugin** represents the entire integration package for a service (such as Figma or Zoom), while an **agent** is a specific autonomous capability within that plugin defined by its descriptor file. A single plugin may contain multiple agents, each with distinct tools and schemas housed in the `agents/` subdirectory.