resources/beta/subresources/agents/methods/retrieve/index.md +0 −400 deleted
File Deleted View Diff
1## Retrieve an agent
2
3**get** `/agents/{agent_id}`
4
5Retrieves a reusable agent by ID. See [agent configuration](/api/docs/guides/agents-api/configuration).
6
7### Path Parameters
8
9- `agent_id: string`
10
11### Returns
12
13- `Agent object { id, created_at, instructions, 10 more }`
14
15 A reusable agent scoped to the caller's project.
16
17 - `id: string`
18
19 The ID of the reusable agent.
20
21 - `created_at: number`
22
23 The Unix timestamp, in seconds, when the agent was created.
24
25 - `instructions: string or null`
26
27 Custom instructions appended to the agent's default base instructions.
28
29 - `metadata: map[string]`
30
31 Custom string key-value pairs attached to the agent.
32
33 - `model: string`
34
35 The requested model name used for inference.
36
37 - `multi_agent: MultiAgentConfig`
38
39 The resolved configuration for creating and coordinating subagents.
40
41 - `enabled: boolean`
42
43 Whether subagent tools are enabled. Defaults to false.
44
45 - `max_concurrent_subagents: number or null`
46
47 Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.
48
49 - `name: string or null`
50
51 A human-readable name for the agent, or null if it is unnamed.
52
53 - `object: "agent"`
54
55 The object type. Always `agent`.
56
57 - `"agent"`
58
59 - `reasoning: AgentReasoning`
60
61 The resolved reasoning configuration, including the model default for an omitted effort.
62
63 - `effort: "none" or "minimal" or "low" or 4 more or null`
64
65 The amount of reasoning effort used by an agent.
66
67 - `"none"`
68
69 - `"minimal"`
70
71 - `"low"`
72
73 - `"medium"`
74
75 - `"high"`
76
77 - `"xhigh"`
78
79 - `"max"`
80
81 - `summary: "concise" or "detailed" or "auto" or null`
82
83 The reasoning summary format requested from an agent.
84
85 - `"concise"`
86
87 Returns a concise reasoning summary when supported.
88
89 - `"detailed"`
90
91 Returns a detailed reasoning summary when supported.
92
93 - `"auto"`
94
95 Automatically selects the most detailed summary supported by the model.
96
97 - `service_tier: "auto" or "default" or "flex" or 2 more`
98
99 The resolved service-tier policy used for model requests.
100
101 - `"auto"`
102
103 - `"default"`
104
105 - `"flex"`
106
107 - `"priority"`
108
109 - `"fast"`
110
111 - `text: AgentText`
112
113 The resolved configuration for text generated by the agent.
114
115 - `format: TextFormat`
116
117 The effective output format. Defaults to ordinary text.
118
119 - `Text object { type }`
120
121 Generates ordinary text without a structured-output constraint.
122
123 - `type: "text"`
124
125 The type of the object. Always `text`.
126
127 - `"text"`
128
129 - `JSONSchema object { schema, type }`
130
131 Constrains generated text to a JSON Schema.
132
133 - `schema: map[unknown]`
134
135 The JSON Schema that generated text must match.
136
137 - `type: "json_schema"`
138
139 The type of the object. Always `json_schema`.
140
141 - `"json_schema"`
142
143 - `verbosity: "low" or "medium" or "high"`
144
145 The amount of text produced by the agent. Defaults to `medium`.
146
147 - `"low"`
148
149 - `"medium"`
150
151 - `"high"`
152
153 - `tools: array of PersistedAgentTool`
154
155 Tools available to the agent.
156
157 - `Function object { defer_loading, description, name, 2 more }`
158
159 A function defined by the application.
160
161 - `defer_loading: boolean`
162
163 Whether the function is deferred and discovered through tool search.
164
165 - `description: string`
166
167 A description of what the function does.
168
169 - `name: string`
170
171 The name of the function.
172
173 - `parameters: map[unknown]`
174
175 A JSON Schema object describing the function's arguments.
176
177 - `type: "function"`
178
179 The type of the object. Always `function`.
180
181 - `"function"`
182
183 - `ToolSearch object { type }`
184
185 Discovers deferred function tools and loads them into the model context.
186
187 - `type: "tool_search"`
188
189 The type of the object. Always `tool_search`.
190
191 - `"tool_search"`
192
193 - `ProgrammaticToolCalling object { enabled, type }`
194
195 Enables calling tools from model-generated code.
196
197 - `enabled: boolean`
198
199 Whether tools can be called from model-generated code.
200
201 - `type: "programmatic_tool_calling"`
202
203 The type of the object. Always `programmatic_tool_calling`.
204
205 - `"programmatic_tool_calling"`
206
207 - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }`
208
209 Tools provided by a remote MCP server without stored credentials.
210
211 - `allowed_tools: array of string or null`
212
213 The MCP tools the agent may call, or null when all server tools are allowed.
214
215 - `connection_origin: "service" or "environment"`
216
217 Where outbound MCP HTTP connections originate.
218
219 - `"service"`
220
221 - `"environment"`
222
223 - `credential_id: string or null`
224
225 The vault credential selected for this MCP server, if any.
226
227 - `request_metadata: map[unknown]`
228
229 Metadata included with requests to this MCP server.
230
231 - `required: boolean`
232
233 Whether this MCP server must initialize before the first turn.
234
235 - `server_label: string`
236
237 A label used to identify the MCP server in tool calls.
238
239 - `transport: PersistedMcpTransport`
240
241 The credential-free transport used to connect to the MCP server.
242
243 - `HTTP object { headers, server_url, type }`
244
245 Connects to an MCP server over HTTP.
246
247 - `headers: map[string]`
248
249 Non-secret HTTP headers sent to the MCP server.
250
251 - `server_url: string`
252
253 The URL of the MCP server.
254
255 - `type: "http"`
256
257 The type of the object. Always `http`.
258
259 - `"http"`
260
261 - `Stdio object { args, command, cwd, 2 more }`
262
263 Starts an MCP server as a local process.
264
265 - `args: array of string`
266
267 Arguments passed to the MCP server command.
268
269 - `command: string`
270
271 The command used to start the MCP server.
272
273 - `cwd: string`
274
275 The working directory used to start the MCP server.
276
277 - `env_vars: array of string`
278
279 Environment variable names inherited from the execution environment.
280
281 - `type: "stdio"`
282
283 The type of the object. Always `stdio`.
284
285 - `"stdio"`
286
287 - `type: "mcp"`
288
289 The type of the object. Always `mcp`.
290
291 - `"mcp"`
292
293 - `WebSearch object { allowed_domains, context_size, location, 2 more }`
294
295 Web search.
296
297 - `allowed_domains: array of string or null`
298
299 Allowed search domains, or `null` when the search is unrestricted.
300
301 - `context_size: "low" or "medium" or "high"`
302
303 The amount of search context made available to the model. Defaults to `medium`.
304
305 - `"low"`
306
307 - `"medium"`
308
309 - `"high"`
310
311 - `location: object { city, country, region, timezone } or null`
312
313 Approximate user location used to localize web search results.
314
315 - `city: string or null`
316
317 The city name.
318
319 - `country: string or null`
320
321 The two-letter ISO country code, such as `US`.
322
323 - `region: string or null`
324
325 The region or state name.
326
327 - `timezone: string or null`
328
329 The IANA timezone, such as `America/Los_Angeles`.
330
331 - `mode: "disabled" or "cached" or "live"`
332
333 The source used for web search results.
334
335 - `"disabled"`
336
337 - `"cached"`
338
339 - `"live"`
340
341 - `type: "web_search"`
342
343 The type of the object. Always `web_search`.
344
345 - `"web_search"`
346
347 - `updated_at: number`
348
349 The Unix timestamp, in seconds, when the agent was last updated.
350
351### Example
352
353```http
354curl https://api.openai.com/v1/agents/$AGENT_ID \
355 -H 'OpenAI-Beta: agents=v1' \
356 -H "Authorization: Bearer $OPENAI_API_KEY"
357```
358
359#### Response
360
361```json
362{
363 "id": "id",
364 "created_at": 0,
365 "instructions": "instructions",
366 "metadata": {
367 "foo": "string"
368 },
369 "model": "model",
370 "multi_agent": {
371 "enabled": true,
372 "max_concurrent_subagents": 1
373 },
374 "name": "name",
375 "object": "agent",
376 "reasoning": {
377 "effort": "none",
378 "summary": "concise"
379 },
380 "service_tier": "auto",
381 "text": {
382 "format": {
383 "type": "text"
384 },
385 "verbosity": "low"
386 },
387 "tools": [
388 {
389 "defer_loading": true,
390 "description": "description",
391 "name": "name",
392 "parameters": {
393 "foo": "bar"
394 },
395 "type": "function"
396 }
397 ],
398 "updated_at": 0
399}
400```