Skip to content
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to the page URL.
Primary navigation

Suggested
Overview Models Agents Tools Audio & voice Production API reference

Create an agent

client.beta.agents.create(AgentCreateParams { model, instructions, metadata, 6 more } body, RequestOptionsoptions?): Agent { id, created_at, instructions, 10 more }
POST/agents

Creates a reusable agent without storing credentials. See agent configuration.

ParametersExpand Collapse
body: AgentCreateParams { model, instructions, metadata, 6 more }
model: string

The model to use for the agent. The requested model name is preserved.

minLength0
maxLength1048576
instructions?: string | null

Additional instructions appended to the agent’s default base instructions. Omit or set to null to add no custom instructions.

minLength0
maxLength1048576
metadata?: Record<string, string> | null

Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters. Omission or null defaults to an empty map.

multi_agent?: MultiAgentConfigParam { enabled, max_concurrent_subagents } | null

Configuration for creating and coordinating subagents. Subagent tools are disabled by default.

name?: string | null

A human-readable name for the agent. Omission or null leaves the agent unnamed.

minLength0
maxLength128
reasoning?: AgentReasoningParam { effort, summary } | null

Configuration for model reasoning. Omission uses the model’s default effort.

service_tier?: "auto" | "default" | "flex" | 2 more | null

The service tier used for model requests. Defaults to auto.

text?: AgentTextParam { format, verbosity } | null

Configuration for generated text. Defaults to the text format and medium verbosity.

tools?: Array<PersistedAgentToolParam> | null

Tools available to the agent. Defaults to an empty list. The tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.

ReturnsExpand Collapse
Agent { id, created_at, instructions, 10 more }

A reusable agent scoped to the caller’s project.

id: string

The ID of the reusable agent.

minLength0
created_at: number

The Unix timestamp, in seconds, when the agent was created.

formatint64
instructions: string | null

Custom instructions appended to the agent’s default base instructions.

minLength0
metadata: Record<string, string>

Custom string key-value pairs attached to the agent.

model: string

The requested model name used for inference.

minLength0
multi_agent: MultiAgentConfig { enabled, max_concurrent_subagents }

The resolved configuration for creating and coordinating subagents.

name: string | null

A human-readable name for the agent, or null if it is unnamed.

minLength0
object: "agent"

The object type. Always agent.

reasoning: AgentReasoning { effort, summary }

The resolved reasoning configuration, including the model default for an omitted effort.

service_tier: "auto" | "default" | "flex" | 3 more

The resolved service-tier policy used for model requests.

text: AgentText { format, verbosity }

The resolved configuration for text generated by the agent.

tools: Array<PersistedAgentTool>

Tools available to the agent.

updated_at: number

The Unix timestamp, in seconds, when the agent was last updated.

formatint64

Create an agent

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env['OPENAI_API_KEY'], // This is the default and can be omitted
});

const agent = await client.beta.agents.create({ model: 'model' });

console.log(agent.id);
{
  "id": "id",
  "created_at": 0,
  "instructions": "instructions",
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 1
  },
  "name": "name",
  "object": "agent",
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "service_tier": "auto",
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "tools": [
    {
      "defer_loading": true,
      "description": "description",
      "name": "name",
      "parameters": {
        "foo": "bar"
      },
      "type": "function"
    }
  ],
  "updated_at": 0
}
Returns Examples
{
  "id": "id",
  "created_at": 0,
  "instructions": "instructions",
  "metadata": {
    "foo": "string"
  },
  "model": "model",
  "multi_agent": {
    "enabled": true,
    "max_concurrent_subagents": 1
  },
  "name": "name",
  "object": "agent",
  "reasoning": {
    "effort": "none",
    "summary": "concise"
  },
  "service_tier": "auto",
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "low"
  },
  "tools": [
    {
      "defer_loading": true,
      "description": "description",
      "name": "name",
      "parameters": {
        "foo": "bar"
      },
      "type": "function"
    }
  ],
  "updated_at": 0
}