API Reference

Beta

Agents

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create an agent

beta.agents.create(**kwargs) -> Agent { id, created_at, instructions, 10 more }

POST/agents

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

ParametersExpand Collapse

model: String

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

minLength0

maxLength1048576

instructions: String

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

minLength0

maxLength1048576

metadata: Hash[Symbol, String]

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 }

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

name: String

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

minLength0

maxLength128

reasoning: AgentReasoningParam { effort, summary }

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

service_tier: :auto | :default | :flex | 2 more

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

text: AgentTextParam { format_, verbosity }

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

tools: Array[PersistedAgentToolParam]

Tools available to the agent. Defaults to an empty list.

ReturnsExpand Collapse

class 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: Integer

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

formatint64

instructions: String

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

minLength0

metadata: Hash[Symbol, 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

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 | 2 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: Integer

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

formatint64

Create an agent

Ruby

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

require "openai"

openai = OpenAI::Client.new(api_key: "My API Key")

agent = openai.beta.agents.create(model: "model")

puts(agent)

200 example

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

200 example

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