Create an agent
Creates a reusable agent without storing credentials. See agent configuration.
Body ParametersJSON
The model to use for the agent. The requested model name is preserved.
compaction: optional object { async } or nullContext compaction settings. Omission or null enables background compaction.
Context compaction settings. Omission or null enables background compaction.
experimental: optional object { time_awareness } (default: {"time_awareness":false})Experimental agent settings. All experimental features default to disabled.
Experimental agent settings. All experimental features default to disabled.
Additional instructions appended to the agent’s default base instructions. Omit or set to null to add no custom instructions.
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.
A human-readable name for the agent. Omission or null leaves the agent unnamed.
Configuration for model reasoning. Omission uses the model’s default effort.
Configuration for model reasoning. Omission uses the model’s default effort.
service_tier: optional "auto" or "default" or "flex" or 3 more or nullThe service tier used for model requests. Defaults to auto.
The service tier used for model requests. Defaults to auto.
Configuration for generated text. Defaults to the text format and medium verbosity.
Configuration for generated text. Defaults to the text format and medium verbosity.
Tools available to the agent. Defaults to an empty list. The tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
minItems0maxItems2000
Tools available to the agent. Defaults to an empty list. The tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
Function object { description, name, parameters, 3 more } A function defined by the application.
A function defined by the application.
Mcp object { server_label, transport, type, 5 more } Tools provided by a remote MCP server without stored credentials.
Tools provided by a remote MCP server without stored credentials.
A label used to identify the MCP server in tool calls.
The credential-free transport used to connect to the MCP server.
The credential-free transport used to connect to the MCP server.
The MCP tools the agent may call. All server tools are allowed when omitted.
connection_origin: optional "service" or "environment" or nullSelects where outbound MCP HTTP connections originate.
Selects where outbound MCP HTTP connections originate.
WebSearch object { type, allowed_domains, context_size, 2 more } Web search.
Web search.
Domains the search may include.
context_size: optional "low" or "medium" or "high" or nullThe amount of search context made available to the model. Defaults to medium.
The amount of search context made available to the model. Defaults to medium.
Returns
Agent object { id, created_at, instructions, 12 more } A reusable agent scoped to the caller’s project.
A reusable agent scoped to the caller’s project.
Custom instructions appended to the agent’s default base instructions.
The resolved reasoning configuration, including the model default for an omitted effort.
The resolved reasoning configuration, including the model default for an omitted effort.
service_tier: "auto" or "default" or "flex" or 3 moreThe resolved service-tier policy used for model requests.
The resolved service-tier policy used for model requests.
The resolved configuration for text generated by the agent.
The resolved configuration for text generated by the agent.
Mcp object { allowed_tools, connection_origin, credential_id, 5 more } Tools provided by a remote MCP server without stored credentials.
Tools provided by a remote MCP server without stored credentials.
The MCP tools the agent may call, or null when all server tools are allowed.
The credential-free transport used to connect to the MCP server.
The credential-free transport used to connect to the MCP server.
WebSearch object { allowed_domains, context_size, location, 2 more } Web search.
Web search.
Allowed search domains, or null when the search is unrestricted.
context_size: "low" or "medium" or "high"The amount of search context made available to the model. Defaults to medium.
The amount of search context made available to the model. Defaults to medium.
location: object { city, country, region, timezone } or nullApproximate location used to localize search results, if provided.
Approximate location used to localize search results, if provided.
Create an agent
curl https://api.openai.com/v1/agents \
-H 'Content-Type: application/json' \
-H 'OpenAI-Beta: agents=v1' \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-d '{
"model": "model"
}'{
"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",
"async": true
}
],
"updated_at": 0,
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
}Returns Examples
{
"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",
"async": true
}
],
"updated_at": 0,
"compaction": {
"async": true
},
"experimental": {
"time_awareness": true
}
}