What Are Agent Descriptors? Structure and Location in OpenAI Plugins

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
• plugins/figma/agents/design-system-rules-agent.json
• plugins/zoom/agents/virtual-agent.json
• plugins/vercel/agents/type-safe-agent.json
• 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:

{
  "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:

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 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.

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, plugins/zoom/agents/virtual-agent.json, and 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.

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