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
Theme

Suggested
Overview Models Agents Tools Audio & voice Production API reference

List agents

AgentListPage beta().agents().list(params = AgentListParams.none(), requestOptions = RequestOptions.none())
GET
/agents

Lists reusable agents in the current project. See agent configuration.

Parameters
AgentListParams params
Optional<String> after

Return resources after this resource ID in the selected order.

minLength0
maxLength1048576
Optional<Long> limit

The maximum number of resources to return, between 1 and 100. Defaults to 20.

formatint64
minimum1
maximum100
Optional<Order> order

The order in which resources are returned. Defaults to desc.

Returns
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_
constant
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.

minItems0
maxItems2000
long updatedAt

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

formatint64
Optional<Compaction> compaction

The effective context compaction settings.

Optional<Experimental> experimental

The effective experimental settings for the agent.

List agents

package com.openai.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentListPage;
import com.openai.models.beta.agents.AgentListParams;

public final class Main {
    private Main() {}

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

        AgentListPage page = client.beta().agents().list();
    }
}
200 — Example
{
  "data": [
    {
      "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,
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}
Returns Examples
200 — Example
{
  "data": [
    {
      "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,
      "compaction": {
        "async": true
      },
      "experimental": {
        "time_awareness": true
      }
    }
  ],
  "first_id": "first_id",
  "has_more": true,
  "last_id": "last_id",
  "object": "list"
}