API Reference

Beta

Agents

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create an agent

Agent beta().agents().create(AgentCreateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())

POST/agents

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

ParametersExpand Collapse

AgentCreateParams params

String model

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

minLength0

maxLength1048576

Optional<String> instructions

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

minLength0

maxLength1048576

Optional<Metadata> metadata

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.

Optional<MultiAgentConfigParam> multiAgent

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

Optional<String> name

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

minLength0

maxLength128

Optional<AgentReasoningParam> reasoning

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

Optional<ServiceTier> serviceTier

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

Optional<AgentTextParam> text

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

Optional<List<PersistedAgentToolParam>> tools

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

ReturnsExpand Collapse

class Agent:

A reusable agent scoped to the caller’s project.

String id

The ID of the reusable agent.

minLength0

long createdAt

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

formatint64

Optional<String> instructions

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

minLength0

Metadata metadata

Custom string key-value pairs attached to the agent.

String model

The requested model name used for inference.

minLength0

MultiAgentConfig multiAgent

The resolved configuration for creating and coordinating subagents.

Optional<String> name

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

minLength0

JsonValue; object_ "agent"constant"agent"constant

The object type. Always agent.

AgentReasoning reasoning

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

ServiceTier serviceTier

The resolved service-tier policy used for model requests.

AgentText text

The resolved configuration for text generated by the agent.

List<PersistedAgentTool> tools

Tools available to the agent.

long updatedAt

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

formatint64

Create an agent

Java

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.Agent;
import com.openai.models.beta.agents.AgentCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        OpenAIClient client = OpenAIOkHttpClient.fromEnv();

        AgentCreateParams params = AgentCreateParams.builder()
            .model("model")
            .build();
        Agent agent = client.beta().agents().create(params);
    }
}

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
}