API Reference

Beta

Agents

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Retrieve an agent

client.Beta.Agents.Get(ctx, agentID) (*Agent, error)

GET/agents/{agent_id}

Retrieves a reusable agent by ID. See agent configuration.

ParametersExpand Collapse

agentID string

minLength0

maxLength1048576

ReturnsExpand Collapse

type Agent struct{…}

A reusable agent scoped to the caller’s project.

ID string

The ID of the reusable agent.

minLength0

CreatedAt int64

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 map[string, string]

Custom string key-value pairs attached to the agent.

Model string

The requested model name used for inference.

minLength0

MultiAgent MultiAgentConfig

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

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

ServiceTier AgentServiceTier

The resolved service-tier policy used for model requests.

Text AgentText

The resolved configuration for text generated by the agent.

Tools []PersistedAgentToolUnion

Tools available to the agent.

UpdatedAt int64

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

formatint64

Retrieve an agent

Go

HTTP

Python

TypeScript

Go

Ruby

Java

CLI Tool

package main

import (
  "context"
  "fmt"

  "github.com/openai/openai-go"
  "github.com/openai/openai-go/option"
)

func main() {
  client := openai.NewClient(
    option.WithAPIKey("My API Key"),
  )
  agent, err := client.Beta.Agents.Get(context.TODO(), "agent_id")
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", agent.ID)
}

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
}