## Retrieve an agent

`beta.agents.retrieve(stragent_id)  -> Agent`

**get** `/agents/{agent_id}`

Retrieves a reusable agent by ID. See [agent configuration](/api/docs/guides/agents-api/configuration).

### Parameters

- `agent_id: str`

### Returns

- `class Agent: …`

  A reusable agent scoped to the caller's project.

  - `id: str`

    The ID of the reusable agent.

  - `created_at: int`

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

  - `instructions: Optional[str]`

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

  - `metadata: Dict[str, str]`

    Custom string key-value pairs attached to the agent.

  - `model: str`

    The requested model name used for inference.

  - `multi_agent: MultiAgentConfig`

    The resolved configuration for creating and coordinating subagents.

    - `enabled: bool`

      Whether subagent tools are enabled. Defaults to false.

    - `max_concurrent_subagents: Optional[int]`

      Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.

  - `name: Optional[str]`

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

  - `object: Literal["agent"]`

    The object type. Always `agent`.

    - `"agent"`

  - `reasoning: AgentReasoning`

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

    - `effort: Optional[Literal["none", "minimal", "low", 4 more]]`

      The amount of reasoning effort used by an agent.

      - `"none"`

      - `"minimal"`

      - `"low"`

      - `"medium"`

      - `"high"`

      - `"xhigh"`

      - `"max"`

    - `summary: Optional[Literal["concise", "detailed", "auto"]]`

      The reasoning summary format requested from an agent.

      - `"concise"`

        Returns a concise reasoning summary when supported.

      - `"detailed"`

        Returns a detailed reasoning summary when supported.

      - `"auto"`

        Automatically selects the most detailed summary supported by the model.

  - `service_tier: Literal["auto", "default", "flex", 2 more]`

    The resolved service-tier policy used for model requests.

    - `"auto"`

    - `"default"`

    - `"flex"`

    - `"priority"`

    - `"fast"`

  - `text: AgentText`

    The resolved configuration for text generated by the agent.

    - `format: TextFormat`

      The effective output format. Defaults to ordinary text.

      - `class TextFormatResourceText: …`

        Generates ordinary text without a structured-output constraint.

        - `type: Literal["text"]`

          The type of the object. Always `text`.

          - `"text"`

      - `class TextFormatResourceJSONSchema: …`

        Constrains generated text to a JSON Schema.

        - `schema: Dict[str, object]`

          The JSON Schema that generated text must match.

        - `type: Literal["json_schema"]`

          The type of the object. Always `json_schema`.

          - `"json_schema"`

    - `verbosity: Literal["low", "medium", "high"]`

      The amount of text produced by the agent. Defaults to `medium`.

      - `"low"`

      - `"medium"`

      - `"high"`

  - `tools: List[PersistedAgentTool]`

    Tools available to the agent.

    - `class PersistedAgentToolResourceFunction: …`

      A function defined by the application.

      - `defer_loading: bool`

        Whether the function is deferred and discovered through tool search.

      - `description: str`

        A description of what the function does.

      - `name: str`

        The name of the function.

      - `parameters: Dict[str, object]`

        A JSON Schema object describing the function's arguments.

      - `type: Literal["function"]`

        The type of the object. Always `function`.

        - `"function"`

    - `class PersistedAgentToolResourceToolSearch: …`

      Discovers deferred function tools and loads them into the model context.

      - `type: Literal["tool_search"]`

        The type of the object. Always `tool_search`.

        - `"tool_search"`

    - `class PersistedAgentToolResourceProgrammaticToolCalling: …`

      Enables calling tools from model-generated code.

      - `enabled: bool`

        Whether tools can be called from model-generated code.

      - `type: Literal["programmatic_tool_calling"]`

        The type of the object. Always `programmatic_tool_calling`.

        - `"programmatic_tool_calling"`

    - `class PersistedAgentToolResourceMcp: …`

      Tools provided by a remote MCP server without stored credentials.

      - `allowed_tools: Optional[List[str]]`

        The MCP tools the agent may call, or null when all server tools are allowed.

      - `connection_origin: Literal["service", "environment"]`

        Where outbound MCP HTTP connections originate.

        - `"service"`

        - `"environment"`

      - `credential_id: Optional[str]`

        The vault credential selected for this MCP server, if any.

      - `request_metadata: Dict[str, object]`

        Metadata included with requests to this MCP server.

      - `required: bool`

        Whether this MCP server must initialize before the first turn.

      - `server_label: str`

        A label used to identify the MCP server in tool calls.

      - `transport: PersistedMcpTransport`

        The credential-free transport used to connect to the MCP server.

        - `class PersistedMcpTransportResourceHTTP: …`

          Connects to an MCP server over HTTP.

          - `headers: Dict[str, str]`

            Non-secret HTTP headers sent to the MCP server.

          - `server_url: str`

            The URL of the MCP server.

          - `type: Literal["http"]`

            The type of the object. Always `http`.

            - `"http"`

        - `class PersistedMcpTransportResourceStdio: …`

          Starts an MCP server as a local process.

          - `args: List[str]`

            Arguments passed to the MCP server command.

          - `command: str`

            The command used to start the MCP server.

          - `cwd: str`

            The working directory used to start the MCP server.

          - `env_vars: List[str]`

            Environment variable names inherited from the execution environment.

          - `type: Literal["stdio"]`

            The type of the object. Always `stdio`.

            - `"stdio"`

      - `type: Literal["mcp"]`

        The type of the object. Always `mcp`.

        - `"mcp"`

    - `class PersistedAgentToolResourceWebSearch: …`

      Web search.

      - `allowed_domains: Optional[List[str]]`

        Allowed search domains, or `null` when the search is unrestricted.

      - `context_size: Literal["low", "medium", "high"]`

        The amount of search context made available to the model. Defaults to `medium`.

        - `"low"`

        - `"medium"`

        - `"high"`

      - `location: Optional[PersistedAgentToolResourceWebSearchLocation]`

        Approximate user location used to localize web search results.

        - `city: Optional[str]`

          The city name.

        - `country: Optional[str]`

          The two-letter ISO country code, such as `US`.

        - `region: Optional[str]`

          The region or state name.

        - `timezone: Optional[str]`

          The IANA timezone, such as `America/Los_Angeles`.

      - `mode: Literal["disabled", "cached", "live"]`

        The source used for web search results.

        - `"disabled"`

        - `"cached"`

        - `"live"`

      - `type: Literal["web_search"]`

        The type of the object. Always `web_search`.

        - `"web_search"`

  - `updated_at: int`

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

### Example

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),  # This is the default and can be omitted
)
agent = client.beta.agents.retrieve(
    "agent_id",
)
print(agent.id)
```

#### Response

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