SpyBara
Go Premium

resources/beta/subresources/agents/methods/update/index.md 2026-09-10 18:01 UTC to 2026-09-11 20:00 UTC

This page contains 745 additions and 0 deletions.

2026
Fri 11 20:00 Fri 18 22:59

Update an agent

post /agents/{agent_id}

Updates a reusable agent. See agent configuration.

Path Parameters

  • agent_id: string

Body Parameters

  • instructions: optional string or null

    Additional instructions appended to the agent's default base instructions. Omit to leave unchanged.

  • metadata: optional map[string] or null

    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.

  • model: optional string

    The model to use for the agent. The requested model name is preserved.

  • multi_agent: optional MultiAgentConfigParam or null

    Explicit configuration for creating and coordinating subagents.

    • enabled: boolean

      Whether subagent tools are enabled.

    • max_concurrent_subagents: optional number

      Maximum number of subagents that may run concurrently. Defaults to 6.

  • name: optional string or null

    A replacement name. Omit to leave unchanged, or pass null to clear it.

  • reasoning: optional AgentReasoningParam or null

    Reasoning configuration for the agent.

    • effort: optional "none" or "minimal" or "low" or 4 more or null

      The amount of reasoning effort the model should use.

      • "none"

      • "minimal"

      • "low"

      • "medium"

      • "high"

      • "xhigh"

      • "max"

    • summary: optional "concise" or "detailed" or "auto" or null

      The reasoning summary format requested from the model.

      • "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: optional "auto" or "default" or "flex" or 2 more or null

    The service tier used for model requests.

    • "auto"

      Selects the service tier automatically.

    • "default"

      Uses the default service tier.

    • "flex"

      Uses the flex service tier.

    • "priority"

      Uses the priority service tier.

    • "fast"

      Uses the fast service tier.

  • text: optional AgentTextParam or null

    Configuration for text generated by the agent.

    • format: optional TextFormatParam or null

      The output format for generated text.

      • Text object { type }

        Generates ordinary text without a structured-output constraint.

        • type: "text"

          The type of the object. Always text.

          • "text"

      • JSONSchema object { schema, type }

        Constrains generated text to a JSON Schema.

        • schema: map[unknown]

          The JSON Schema that generated text must match.

        • type: "json_schema"

          The type of the object. Always json_schema.

          • "json_schema"

    • verbosity: optional "low" or "medium" or "high" or null

      The amount of text the model should produce.

      • "low"

        Produces less text.

      • "medium"

        Uses the default amount of text.

      • "high"

        Produces more text.

  • tools: optional array of PersistedAgentToolParam or null

    Tools available to the agent.

    • Function object { description, name, parameters, 2 more }

      A function defined by the application.

      • description: string

        A description of what the function does.

      • name: string

        The name of the function.

      • parameters: map[unknown]

        A JSON Schema object describing the function's arguments.

      • type: "function"

        The type of the object. Always function.

        • "function"

      • defer_loading: optional boolean

        Whether this function is deferred and discovered through tool search. Defaults to false.

    • ToolSearch object { type }

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

      • type: "tool_search"

        The type of the object. Always tool_search.

        • "tool_search"

    • ProgrammaticToolCalling object { type, enabled }

      Enables calling tools from model-generated code.

      • type: "programmatic_tool_calling"

        The type of the object. Always programmatic_tool_calling.

        • "programmatic_tool_calling"

      • enabled: optional boolean

        Whether tools can be called from model-generated code. Defaults to true.

    • Mcp object { server_label, transport, type, 5 more }

      Tools provided by a remote MCP server without stored credentials.

      • server_label: string

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

      • transport: PersistedMcpTransportParam

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

        • HTTP object { server_url, type, headers }

          Connects to an MCP server over HTTP.

          • server_url: string

            The URL of the MCP server.

          • type: "http"

            The type of the object. Always http.

            • "http"

          • headers: optional map[string] or null

            Non-secret HTTP headers sent to the MCP server.

        • Stdio object { command, cwd, type, 2 more }

          Starts an MCP server as a local process.

          • command: string

            The command used to start the MCP server.

          • cwd: string

            The working directory used to start the MCP server.

          • type: "stdio"

            The type of the object. Always stdio.

            • "stdio"

          • args: optional array of string or null

            Arguments passed to the MCP server command.

          • env_vars: optional array of string or null

            Environment variable names to inherit from the selected execution environment.

      • type: "mcp"

        The type of the object. Always mcp.

        • "mcp"

      • allowed_tools: optional array of string or null

        The MCP tools the agent may call. All server tools are allowed when omitted.

      • connection_origin: optional "service" or "environment" or null

        Where outbound MCP HTTP connections originate.

        • "service"

          Uses the Managed Agents service network.

        • "environment"

          Uses the session's execution environment.

      • credential_id: optional string or null

        The vault credential selected for this MCP server. Optional when exactly one attached credential matches the server URL.

      • request_metadata: optional map[unknown] or null

        Metadata included with requests to this MCP server.

      • required: optional boolean

        Whether this MCP server must initialize before the first turn. Defaults to false.

    • WebSearch object { type, allowed_domains, context_size, 2 more }

      Web search.

      • type: "web_search"

        The type of the object. Always web_search.

        • "web_search"

      • allowed_domains: optional array of string or null

        Domains the search may include.

      • context_size: optional "low" or "medium" or "high" or null

        The amount of web search context made available to the model.

        • "low"

        • "medium"

        • "high"

      • location: optional object { city, country, region, timezone } or null

        Approximate user location used to localize web search results.

        • city: optional string or null

          The city name.

        • country: optional string or null

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

        • region: optional string or null

          The region or state name.

        • timezone: optional string or null

          The IANA timezone, such as America/Los_Angeles.

      • mode: optional "disabled" or "cached" or "live" or null

        The source used for web search results.

        • "disabled"

          Disables web search.

        • "cached"

          Uses cached search results.

        • "live"

          Searches the live web.

Returns

  • Agent object { id, created_at, instructions, 10 more }

    A reusable agent scoped to the caller's project.

    • id: string

      The ID of the reusable agent.

    • created_at: number

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

    • instructions: string or null

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

    • metadata: map[string]

      Custom string key-value pairs attached to the agent.

    • model: string

      The requested model name used for inference.

    • multi_agent: MultiAgentConfig

      The resolved configuration for creating and coordinating subagents.

      • enabled: boolean

        Whether subagent tools are enabled. Defaults to false.

      • max_concurrent_subagents: number or null

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

    • name: string or null

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

    • object: "agent"

      The object type. Always agent.

      • "agent"

    • reasoning: AgentReasoning

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

      • effort: "none" or "minimal" or "low" or 4 more or null

        The amount of reasoning effort used by an agent.

        • "none"

        • "minimal"

        • "low"

        • "medium"

        • "high"

        • "xhigh"

        • "max"

      • summary: "concise" or "detailed" or "auto" or null

        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: "auto" or "default" or "flex" or 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.

        • Text object { type }

          Generates ordinary text without a structured-output constraint.

          • type: "text"

            The type of the object. Always text.

            • "text"

        • JSONSchema object { schema, type }

          Constrains generated text to a JSON Schema.

          • schema: map[unknown]

            The JSON Schema that generated text must match.

          • type: "json_schema"

            The type of the object. Always json_schema.

            • "json_schema"

      • verbosity: "low" or "medium" or "high"

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

        • "low"

        • "medium"

        • "high"

    • tools: array of PersistedAgentTool

      Tools available to the agent.

      • Function object { defer_loading, description, name, 2 more }

        A function defined by the application.

        • defer_loading: boolean

          Whether the function is deferred and discovered through tool search.

        • description: string

          A description of what the function does.

        • name: string

          The name of the function.

        • parameters: map[unknown]

          A JSON Schema object describing the function's arguments.

        • type: "function"

          The type of the object. Always function.

          • "function"

      • ToolSearch object { type }

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

        • type: "tool_search"

          The type of the object. Always tool_search.

          • "tool_search"

      • ProgrammaticToolCalling object { enabled, type }

        Enables calling tools from model-generated code.

        • enabled: boolean

          Whether tools can be called from model-generated code.

        • type: "programmatic_tool_calling"

          The type of the object. Always programmatic_tool_calling.

          • "programmatic_tool_calling"

      • Mcp object { allowed_tools, connection_origin, credential_id, 5 more }

        Tools provided by a remote MCP server without stored credentials.

        • allowed_tools: array of string or null

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

        • connection_origin: "service" or "environment"

          Where outbound MCP HTTP connections originate.

          • "service"

          • "environment"

        • credential_id: string or null

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

        • request_metadata: map[unknown]

          Metadata included with requests to this MCP server.

        • required: boolean

          Whether this MCP server must initialize before the first turn.

        • server_label: string

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

        • transport: PersistedMcpTransport

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

          • HTTP object { headers, server_url, type }

            Connects to an MCP server over HTTP.

            • headers: map[string]

              Non-secret HTTP headers sent to the MCP server.

            • server_url: string

              The URL of the MCP server.

            • type: "http"

              The type of the object. Always http.

              • "http"

          • Stdio object { args, command, cwd, 2 more }

            Starts an MCP server as a local process.

            • args: array of string

              Arguments passed to the MCP server command.

            • command: string

              The command used to start the MCP server.

            • cwd: string

              The working directory used to start the MCP server.

            • env_vars: array of string

              Environment variable names inherited from the execution environment.

            • type: "stdio"

              The type of the object. Always stdio.

              • "stdio"

        • type: "mcp"

          The type of the object. Always mcp.

          • "mcp"

      • WebSearch object { allowed_domains, context_size, location, 2 more }

        Web search.

        • allowed_domains: array of string or null

          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.

          • "low"

          • "medium"

          • "high"

        • location: object { city, country, region, timezone } or null

          Approximate user location used to localize web search results.

          • city: string or null

            The city name.

          • country: string or null

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

          • region: string or null

            The region or state name.

          • timezone: string or null

            The IANA timezone, such as America/Los_Angeles.

        • mode: "disabled" or "cached" or "live"

          The source used for web search results.

          • "disabled"

          • "cached"

          • "live"

        • type: "web_search"

          The type of the object. Always web_search.

          • "web_search"

    • updated_at: number

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

Example

curl https://api.openai.com/v1/agents/$AGENT_ID \
    -X POST \
    -H 'OpenAI-Beta: agents=v1' \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

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