resources/beta/subresources/agents/methods/update/index.md +0 −745 deleted
File Deleted View Diff
1## Update an agent
2
3**post** `/agents/{agent_id}`
4
5Updates a reusable agent. See [agent configuration](/api/docs/guides/agents-api/configuration).
6
7### Path Parameters
8
9- `agent_id: string`
10
11### Body Parameters
12
13- `instructions: optional string or null`
14
15 Additional instructions appended to the agent's default base instructions. Omit to leave unchanged.
16
17- `metadata: optional map[string] or null`
18
19 Replaces all metadata. Omit to leave unchanged, or pass null or {} to clear it. Up to 16 string key-value pairs, with keys up to 64 and values up to 512 characters.
20
21- `model: optional string`
22
23 The model to use for the agent. The requested model name is preserved.
24
25- `multi_agent: optional MultiAgentConfigParam or null`
26
27 Explicit configuration for creating and coordinating subagents.
28
29 - `enabled: boolean`
30
31 Whether subagent tools are enabled.
32
33 - `max_concurrent_subagents: optional number`
34
35 Maximum number of subagents that may run concurrently. Defaults to 6.
36
37- `name: optional string or null`
38
39 A replacement name. Omit to leave unchanged, or pass null to clear it.
40
41- `reasoning: optional AgentReasoningParam or null`
42
43 Reasoning configuration for the agent.
44
45 - `effort: optional "none" or "minimal" or "low" or 4 more or null`
46
47 The amount of reasoning effort the model should use.
48
49 - `"none"`
50
51 - `"minimal"`
52
53 - `"low"`
54
55 - `"medium"`
56
57 - `"high"`
58
59 - `"xhigh"`
60
61 - `"max"`
62
63 - `summary: optional "concise" or "detailed" or "auto" or null`
64
65 The reasoning summary format requested from the model.
66
67 - `"concise"`
68
69 Returns a concise reasoning summary when supported.
70
71 - `"detailed"`
72
73 Returns a detailed reasoning summary when supported.
74
75 - `"auto"`
76
77 Automatically selects the most detailed summary supported by the model.
78
79- `service_tier: optional "auto" or "default" or "flex" or 2 more or null`
80
81 The service tier used for model requests.
82
83 - `"auto"`
84
85 Selects the service tier automatically.
86
87 - `"default"`
88
89 Uses the default service tier.
90
91 - `"flex"`
92
93 Uses the flex service tier.
94
95 - `"priority"`
96
97 Uses the priority service tier.
98
99 - `"fast"`
100
101 Uses the fast service tier.
102
103- `text: optional AgentTextParam or null`
104
105 Configuration for text generated by the agent.
106
107 - `format: optional TextFormatParam or null`
108
109 The output format for generated text.
110
111 - `Text object { type }`
112
113 Generates ordinary text without a structured-output constraint.
114
115 - `type: "text"`
116
117 The type of the object. Always `text`.
118
119 - `"text"`
120
121 - `JSONSchema object { schema, type }`
122
123 Constrains generated text to a JSON Schema.
124
125 - `schema: map[unknown]`
126
127 The JSON Schema that generated text must match.
128
129 - `type: "json_schema"`
130
131 The type of the object. Always `json_schema`.
132
133 - `"json_schema"`
134
135 - `verbosity: optional "low" or "medium" or "high" or null`
136
137 The amount of text the model should produce.
138
139 - `"low"`
140
141 Produces less text.
142
143 - `"medium"`
144
145 Uses the default amount of text.
146
147 - `"high"`
148
149 Produces more text.
150
151- `tools: optional array of PersistedAgentToolParam or null`
152
153 Tools available to the agent.
154
155 - `Function object { description, name, parameters, 2 more }`
156
157 A function defined by the application.
158
159 - `description: string`
160
161 A description of what the function does.
162
163 - `name: string`
164
165 The name of the function.
166
167 - `parameters: map[unknown]`
168
169 A JSON Schema object describing the function's arguments.
170
171 - `type: "function"`
172
173 The type of the object. Always `function`.
174
175 - `"function"`
176
177 - `defer_loading: optional boolean`
178
179 Whether this function is deferred and discovered through tool search. Defaults to `false`.
180
181 - `ToolSearch object { type }`
182
183 Discovers deferred function tools and loads them into the model context.
184
185 - `type: "tool_search"`
186
187 The type of the object. Always `tool_search`.
188
189 - `"tool_search"`
190
191 - `ProgrammaticToolCalling object { type, enabled }`
192
193 Enables calling tools from model-generated code.
194
195 - `type: "programmatic_tool_calling"`
196
197 The type of the object. Always `programmatic_tool_calling`.
198
199 - `"programmatic_tool_calling"`
200
201 - `enabled: optional boolean`
202
203 Whether tools can be called from model-generated code. Defaults to `true`.
204
205 - `Mcp object { server_label, transport, type, 5 more }`
206
207 Tools provided by a remote MCP server without stored credentials.
208
209 - `server_label: string`
210
211 A label used to identify the MCP server in tool calls.
212
213 - `transport: PersistedMcpTransportParam`
214
215 The credential-free transport used to connect to the MCP server.
216
217 - `HTTP object { server_url, type, headers }`
218
219 Connects to an MCP server over HTTP.
220
221 - `server_url: string`
222
223 The URL of the MCP server.
224
225 - `type: "http"`
226
227 The type of the object. Always `http`.
228
229 - `"http"`
230
231 - `headers: optional map[string] or null`
232
233 Non-secret HTTP headers sent to the MCP server.
234
235 - `Stdio object { command, cwd, type, 2 more }`
236
237 Starts an MCP server as a local process.
238
239 - `command: string`
240
241 The command used to start the MCP server.
242
243 - `cwd: string`
244
245 The working directory used to start the MCP server.
246
247 - `type: "stdio"`
248
249 The type of the object. Always `stdio`.
250
251 - `"stdio"`
252
253 - `args: optional array of string or null`
254
255 Arguments passed to the MCP server command.
256
257 - `env_vars: optional array of string or null`
258
259 Environment variable names to inherit from the selected execution environment.
260
261 - `type: "mcp"`
262
263 The type of the object. Always `mcp`.
264
265 - `"mcp"`
266
267 - `allowed_tools: optional array of string or null`
268
269 The MCP tools the agent may call. All server tools are allowed when omitted.
270
271 - `connection_origin: optional "service" or "environment" or null`
272
273 Where outbound MCP HTTP connections originate.
274
275 - `"service"`
276
277 Uses the Managed Agents service network.
278
279 - `"environment"`
280
281 Uses the session's execution environment.
282
283 - `credential_id: optional string or null`
284
285 The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL.
286
287 - `request_metadata: optional map[unknown] or null`
288
289 Metadata included with requests to this MCP server.
290
291 - `required: optional boolean`
292
293 Whether this MCP server must initialize before the first turn. Defaults to `false`.
294
295 - `WebSearch object { type, allowed_domains, context_size, 2 more }`
296
297 Web search.
298
299 - `type: "web_search"`
300
301 The type of the object. Always `web_search`.
302
303 - `"web_search"`
304
305 - `allowed_domains: optional array of string or null`
306
307 Domains the search may include.
308
309 - `context_size: optional "low" or "medium" or "high" or null`
310
311 The amount of web search context made available to the model.
312
313 - `"low"`
314
315 - `"medium"`
316
317 - `"high"`
318
319 - `location: optional object { city, country, region, timezone } or null`
320
321 Approximate user location used to localize web search results.
322
323 - `city: optional string or null`
324
325 The city name.
326
327 - `country: optional string or null`
328
329 The two-letter ISO country code, such as `US`.
330
331 - `region: optional string or null`
332
333 The region or state name.
334
335 - `timezone: optional string or null`
336
337 The IANA timezone, such as `America/Los_Angeles`.
338
339 - `mode: optional "disabled" or "cached" or "live" or null`
340
341 The source used for web search results.
342
343 - `"disabled"`
344
345 Disables web search.
346
347 - `"cached"`
348
349 Uses cached search results.
350
351 - `"live"`
352
353 Searches the live web.
354
355### Returns
356
357- `Agent object { id, created_at, instructions, 10 more }`
358
359 A reusable agent scoped to the caller's project.
360
361 - `id: string`
362
363 The ID of the reusable agent.
364
365 - `created_at: number`
366
367 The Unix timestamp, in seconds, when the agent was created.
368
369 - `instructions: string or null`
370
371 Custom instructions appended to the agent's default base instructions.
372
373 - `metadata: map[string]`
374
375 Custom string key-value pairs attached to the agent.
376
377 - `model: string`
378
379 The requested model name used for inference.
380
381 - `multi_agent: MultiAgentConfig`
382
383 The resolved configuration for creating and coordinating subagents.
384
385 - `enabled: boolean`
386
387 Whether subagent tools are enabled. Defaults to false.
388
389 - `max_concurrent_subagents: number or null`
390
391 Maximum number of subagents that may run concurrently, or null when disabled. Defaults to 6 when enabled.
392
393 - `name: string or null`
394
395 A human-readable name for the agent, or null if it is unnamed.
396
397 - `object: "agent"`
398
399 The object type. Always `agent`.
400
401 - `"agent"`
402
403 - `reasoning: AgentReasoning`
404
405 The resolved reasoning configuration, including the model default for an omitted effort.
406
407 - `effort: "none" or "minimal" or "low" or 4 more or null`
408
409 The amount of reasoning effort used by an agent.
410
411 - `"none"`
412
413 - `"minimal"`
414
415 - `"low"`
416
417 - `"medium"`
418
419 - `"high"`
420
421 - `"xhigh"`
422
423 - `"max"`
424
425 - `summary: "concise" or "detailed" or "auto" or null`
426
427 The reasoning summary format requested from an agent.
428
429 - `"concise"`
430
431 Returns a concise reasoning summary when supported.
432
433 - `"detailed"`
434
435 Returns a detailed reasoning summary when supported.
436
437 - `"auto"`
438
439 Automatically selects the most detailed summary supported by the model.
440
441 - `service_tier: "auto" or "default" or "flex" or 2 more`
442
443 The resolved service-tier policy used for model requests.
444
445 - `"auto"`
446
447 - `"default"`
448
449 - `"flex"`
450
451 - `"priority"`
452
453 - `"fast"`
454
455 - `text: AgentText`
456
457 The resolved configuration for text generated by the agent.
458
459 - `format: TextFormat`
460
461 The effective output format. Defaults to ordinary text.
462
463 - `Text object { type }`
464
465 Generates ordinary text without a structured-output constraint.
466
467 - `type: "text"`
468
469 The type of the object. Always `text`.
470
471 - `"text"`
472
473 - `JSONSchema object { schema, type }`
474
475 Constrains generated text to a JSON Schema.
476
477 - `schema: map[unknown]`
478
479 The JSON Schema that generated text must match.
480
481 - `type: "json_schema"`
482
483 The type of the object. Always `json_schema`.
484
485 - `"json_schema"`
486
487 - `verbosity: "low" or "medium" or "high"`
488
489 The amount of text produced by the agent. Defaults to `medium`.
490
491 - `"low"`
492
493 - `"medium"`
494
495 - `"high"`
496
497 - `tools: array of PersistedAgentTool`
498
499 Tools available to the agent.
500
501 - `Function object { defer_loading, description, name, 2 more }`
502
503 A function defined by the application.
504
505 - `defer_loading: boolean`
506
507 Whether the function is deferred and discovered through tool search.
508
509 - `description: string`
510
511 A description of what the function does.
512
513 - `name: string`
514
515 The name of the function.
516
517 - `parameters: map[unknown]`
518
519 A JSON Schema object describing the function's arguments.
520
521 - `type: "function"`
522
523 The type of the object. Always `function`.
524
525 - `"function"`
526
527 - `ToolSearch object { type }`
528
529 Discovers deferred function tools and loads them into the model context.
530
531 - `type: "tool_search"`
532
533 The type of the object. Always `tool_search`.
534
535 - `"tool_search"`
536
537 - `ProgrammaticToolCalling object { enabled, type }`
538
539 Enables calling tools from model-generated code.
540
541 - `enabled: boolean`
542
543 Whether tools can be called from model-generated code.
544
545 - `type: "programmatic_tool_calling"`
546
547 The type of the object. Always `programmatic_tool_calling`.
548
549 - `"programmatic_tool_calling"`
550
551 - `Mcp object { allowed_tools, connection_origin, credential_id, 5 more }`
552
553 Tools provided by a remote MCP server without stored credentials.
554
555 - `allowed_tools: array of string or null`
556
557 The MCP tools the agent may call, or null when all server tools are allowed.
558
559 - `connection_origin: "service" or "environment"`
560
561 Where outbound MCP HTTP connections originate.
562
563 - `"service"`
564
565 - `"environment"`
566
567 - `credential_id: string or null`
568
569 The vault credential selected for this MCP server, if any.
570
571 - `request_metadata: map[unknown]`
572
573 Metadata included with requests to this MCP server.
574
575 - `required: boolean`
576
577 Whether this MCP server must initialize before the first turn.
578
579 - `server_label: string`
580
581 A label used to identify the MCP server in tool calls.
582
583 - `transport: PersistedMcpTransport`
584
585 The credential-free transport used to connect to the MCP server.
586
587 - `HTTP object { headers, server_url, type }`
588
589 Connects to an MCP server over HTTP.
590
591 - `headers: map[string]`
592
593 Non-secret HTTP headers sent to the MCP server.
594
595 - `server_url: string`
596
597 The URL of the MCP server.
598
599 - `type: "http"`
600
601 The type of the object. Always `http`.
602
603 - `"http"`
604
605 - `Stdio object { args, command, cwd, 2 more }`
606
607 Starts an MCP server as a local process.
608
609 - `args: array of string`
610
611 Arguments passed to the MCP server command.
612
613 - `command: string`
614
615 The command used to start the MCP server.
616
617 - `cwd: string`
618
619 The working directory used to start the MCP server.
620
621 - `env_vars: array of string`
622
623 Environment variable names inherited from the execution environment.
624
625 - `type: "stdio"`
626
627 The type of the object. Always `stdio`.
628
629 - `"stdio"`
630
631 - `type: "mcp"`
632
633 The type of the object. Always `mcp`.
634
635 - `"mcp"`
636
637 - `WebSearch object { allowed_domains, context_size, location, 2 more }`
638
639 Web search.
640
641 - `allowed_domains: array of string or null`
642
643 Allowed search domains, or `null` when the search is unrestricted.
644
645 - `context_size: "low" or "medium" or "high"`
646
647 The amount of search context made available to the model. Defaults to `medium`.
648
649 - `"low"`
650
651 - `"medium"`
652
653 - `"high"`
654
655 - `location: object { city, country, region, timezone } or null`
656
657 Approximate user location used to localize web search results.
658
659 - `city: string or null`
660
661 The city name.
662
663 - `country: string or null`
664
665 The two-letter ISO country code, such as `US`.
666
667 - `region: string or null`
668
669 The region or state name.
670
671 - `timezone: string or null`
672
673 The IANA timezone, such as `America/Los_Angeles`.
674
675 - `mode: "disabled" or "cached" or "live"`
676
677 The source used for web search results.
678
679 - `"disabled"`
680
681 - `"cached"`
682
683 - `"live"`
684
685 - `type: "web_search"`
686
687 The type of the object. Always `web_search`.
688
689 - `"web_search"`
690
691 - `updated_at: number`
692
693 The Unix timestamp, in seconds, when the agent was last updated.
694
695### Example
696
697```http
698curl https://api.openai.com/v1/agents/$AGENT_ID \
699 -X POST \
700 -H 'OpenAI-Beta: agents=v1' \
701 -H "Authorization: Bearer $OPENAI_API_KEY"
702```
703
704#### Response
705
706```json
707{
708 "id": "id",
709 "created_at": 0,
710 "instructions": "instructions",
711 "metadata": {
712 "foo": "string"
713 },
714 "model": "model",
715 "multi_agent": {
716 "enabled": true,
717 "max_concurrent_subagents": 1
718 },
719 "name": "name",
720 "object": "agent",
721 "reasoning": {
722 "effort": "none",
723 "summary": "concise"
724 },
725 "service_tier": "auto",
726 "text": {
727 "format": {
728 "type": "text"
729 },
730 "verbosity": "low"
731 },
732 "tools": [
733 {
734 "defer_loading": true,
735 "description": "description",
736 "name": "name",
737 "parameters": {
738 "foo": "bar"
739 },
740 "type": "function"
741 }
742 ],
743 "updated_at": 0
744}
745```