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