feat(api): document agent tool limits

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: fd87a332-8b41-4969-82ea-bee78e04c9b0
-openapi_spec_hash: f0ac7c2da11e51bf51fe8f65e5b313b9
-openapi_transformed_spec_hash: 90042e27fae59af49799aee80b3882b0
+generation_id: a26155e9-8b52-4849-ad00-8229a36843b8
+openapi_spec_hash: e698495055a5af617444922b7655d899
+openapi_transformed_spec_hash: 542f8888ff1a5b6c76197a094418a526
 config_hash: 3336a08a5a6cf26a723db96a2602e503
-codegen_sha: c76b241333d2b0ecd43eb9f8a4bc308fea1defa1
-codegen_hash: 12b19e5d66cb42739f0d86618cd872d65c9067cfcf395cef3c9fbf2bfd359de1
-public_codegen_sha: 4dd493cf89ad33dd52f93d8e2485f8ed7a4fdede
+codegen_sha: 4e1673e54c04f8751e523405946bdd6f0f48b8d5
+codegen_hash: af555eb5d89d61ff400385029285dd9585c6ef548f5570b604b0c7441d076bfa
+public_codegen_sha: 797c53a12d2a80d852def547b56956473e8c9f41

api_reference/openapi.transformed.yml

@@ -80923,6 +80923,11 @@ components:
           format: int64
           minimum: -2147483648
           maximum: 2147483647
+        compute_units:
+          type:
+          - integer
+          - 'null'
+          format: int64
       required:
       - input_tokens
       - input_tokens_details
@@ -84263,7 +84268,7 @@ components:
             $ref: '#/components/schemas/PersistedAgentToolConfigParam'
           minItems: 0
           maxItems: 2000
-          description: Tools available to the agent. Defaults to an empty list.
+          description: 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.
         multi_agent:
           anyOf:
           - $ref: '#/components/schemas/MultiAgentConfigCurrentParam'
@@ -84338,7 +84343,7 @@ components:
             $ref: '#/components/schemas/PersistedAgentToolConfigParam'
           minItems: 0
           maxItems: 2000
-          description: Tools available to the agent.
+          description: Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
       additionalProperties: false
       description: Fields to replace on an existing reusable agent.
     DeletedAgentResource:
@@ -86303,7 +86308,7 @@ components:
             $ref: '#/components/schemas/AgentToolConfigParam'
           minItems: 0
           maxItems: 16384
-          description: Tools available to the agent. Omit to inherit, or pass null to clear them.
+          description: Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
       additionalProperties: false
       description: Agent configuration for a session. Omitted fields inherit from `agent_id` when supplied. Supplied objects and arrays replace the whole field; null resets nullable fields.
     EnvironmentParamNone:

openai-java-core/src/main/kotlin/com/openai/models/beta/agents/AgentCreateParams.kt

@@ -102,7 +102,8 @@ private constructor(
     fun text(): Optional<AgentTextParam> = body.text()
 
     /**
-     * Tools available to the agent. Defaults to an empty list.
+     * 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.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -356,7 +357,10 @@ private constructor(
          */
         fun text(text: JsonField<AgentTextParam>) = apply { body.text(text) }
 
-        /** Tools available to the agent. Defaults to an empty list. */
+        /**
+         * 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.
+         */
         fun tools(tools: List<PersistedAgentToolParam>?) = apply { body.tools(tools) }
 
         /** Alias for calling [Builder.tools] with `tools.orElse(null)`. */
@@ -673,7 +677,8 @@ private constructor(
         fun text(): Optional<AgentTextParam> = text.getOptional("text")
 
         /**
-         * Tools available to the agent. Defaults to an empty list.
+         * 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.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -951,7 +956,10 @@ private constructor(
              */
             fun text(text: JsonField<AgentTextParam>) = apply { this.text = text }
 
-            /** Tools available to the agent. Defaults to an empty list. */
+            /**
+             * 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.
+             */
             fun tools(tools: List<PersistedAgentToolParam>?) = tools(JsonField.ofNullable(tools))
 
             /** Alias for calling [Builder.tools] with `tools.orElse(null)`. */

openai-java-core/src/main/kotlin/com/openai/models/beta/agents/AgentUpdateParams.kt

@@ -104,7 +104,8 @@ private constructor(
     fun text(): Optional<AgentTextParam> = body.text()
 
     /**
-     * Tools available to the agent.
+     * Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The replacement
+     * must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -360,7 +361,10 @@ private constructor(
          */
         fun text(text: JsonField<AgentTextParam>) = apply { body.text(text) }
 
-        /** Tools available to the agent. */
+        /**
+         * Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The
+         * replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
+         */
         fun tools(tools: List<PersistedAgentToolParam>?) = apply { body.tools(tools) }
 
         /** Alias for calling [Builder.tools] with `tools.orElse(null)`. */
@@ -677,7 +681,8 @@ private constructor(
         fun text(): Optional<AgentTextParam> = text.getOptional("text")
 
         /**
-         * Tools available to the agent.
+         * Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The
+         * replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -946,7 +951,10 @@ private constructor(
              */
             fun text(text: JsonField<AgentTextParam>) = apply { this.text = text }
 
-            /** Tools available to the agent. */
+            /**
+             * Replaces the tool list. Omit to leave it unchanged, or pass null to clear it. The
+             * replacement must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
+             */
             fun tools(tools: List<PersistedAgentToolParam>?) = tools(JsonField.ofNullable(tools))
 
             /** Alias for calling [Builder.tools] with `tools.orElse(null)`. */

openai-java-core/src/main/kotlin/com/openai/models/beta/agents/sessions/SessionCreateParams.kt

@@ -1023,7 +1023,8 @@ private constructor(
         fun text(): Optional<AgentTextParam> = text.getOptional("text")
 
         /**
-         * Tools available to the agent. Omit to inherit, or pass null to clear them.
+         * Tools available to the agent. Omit to inherit, or pass null to clear them. The resolved
+         * tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -1239,7 +1240,10 @@ private constructor(
              */
             fun text(text: JsonField<AgentTextParam>) = apply { this.text = text }
 
-            /** Tools available to the agent. Omit to inherit, or pass null to clear them. */
+            /**
+             * Tools available to the agent. Omit to inherit, or pass null to clear them. The
+             * resolved tool list must fit within 3 MiB (3,145,728 bytes) of compact UTF-8 JSON.
+             */
             fun tools(tools: List<AgentToolParam>?) = tools(JsonField.ofNullable(tools))
 
             /** Alias for calling [Builder.tools] with `tools.orElse(null)`. */

openai-java-core/src/main/kotlin/com/openai/models/decisions/Decision.kt

@@ -2214,6 +2214,7 @@ private constructor(
         private val outputTokens: JsonField<Long>,
         private val outputTokensDetails: JsonField<OutputTokensDetails>,
         private val totalTokens: JsonField<Long>,
+        private val computeUnits: JsonField<Long>,
         private val additionalProperties: MutableMap<String, JsonValue>,
     ) {
 
@@ -2234,12 +2235,16 @@ private constructor(
             @JsonProperty("total_tokens")
             @ExcludeMissing
             totalTokens: JsonField<Long> = JsonMissing.of(),
+            @JsonProperty("compute_units")
+            @ExcludeMissing
+            computeUnits: JsonField<Long> = JsonMissing.of(),
         ) : this(
             inputTokens,
             inputTokensDetails,
             outputTokens,
             outputTokensDetails,
             totalTokens,
+            computeUnits,
             mutableMapOf(),
         )
 
@@ -2275,6 +2280,12 @@ private constructor(
          */
         fun totalTokens(): Long = totalTokens.getRequired("total_tokens")
 
+        /**
+         * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
+         *   server responded with an unexpected value).
+         */
+        fun computeUnits(): Optional<Long> = computeUnits.getOptional("compute_units")
+
         /**
          * Returns the raw JSON value of [inputTokens].
          *
@@ -2323,6 +2334,16 @@ private constructor(
         @ExcludeMissing
         fun _totalTokens(): JsonField<Long> = totalTokens
 
+        /**
+         * Returns the raw JSON value of [computeUnits].
+         *
+         * Unlike [computeUnits], this method doesn't throw if the JSON field has an unexpected
+         * type.
+         */
+        @JsonProperty("compute_units")
+        @ExcludeMissing
+        fun _computeUnits(): JsonField<Long> = computeUnits
+
         @JsonAnySetter
         private fun putAdditionalProperty(key: String, value: JsonValue) {
             additionalProperties.put(key, value)
@@ -2360,6 +2381,7 @@ private constructor(
             private var outputTokens: JsonField<Long>? = null
             private var outputTokensDetails: JsonField<OutputTokensDetails>? = null
             private var totalTokens: JsonField<Long>? = null
+            private var computeUnits: JsonField<Long> = JsonMissing.of()
             private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
             @JvmSynthetic
@@ -2369,6 +2391,7 @@ private constructor(
                 outputTokens = usage.outputTokens
                 outputTokensDetails = usage.outputTokensDetails
                 totalTokens = usage.totalTokens
+                computeUnits = usage.computeUnits
                 additionalProperties = usage.additionalProperties.toMutableMap()
             }
 
@@ -2435,6 +2458,29 @@ private constructor(
              */
             fun totalTokens(totalTokens: JsonField<Long>) = apply { this.totalTokens = totalTokens }
 
+            fun computeUnits(computeUnits: Long?) = computeUnits(JsonField.ofNullable(computeUnits))
+
+            /**
+             * Alias for [Builder.computeUnits].
+             *
+             * This unboxed primitive overload exists for backwards compatibility.
+             */
+            fun computeUnits(computeUnits: Long) = computeUnits(computeUnits as Long?)
+
+            /** Alias for calling [Builder.computeUnits] with `computeUnits.orElse(null)`. */
+            fun computeUnits(computeUnits: Optional<Long>) = computeUnits(computeUnits.getOrNull())
+
+            /**
+             * Sets [Builder.computeUnits] to an arbitrary JSON value.
+             *
+             * You should usually call [Builder.computeUnits] with a well-typed [Long] value
+             * instead. This method is primarily for setting the field to an undocumented or not yet
+             * supported value.
+             */
+            fun computeUnits(computeUnits: JsonField<Long>) = apply {
+                this.computeUnits = computeUnits
+            }
+
             fun additionalProperties(additionalProperties: Map<String, JsonValue>) = apply {
                 this.additionalProperties.clear()
                 putAllAdditionalProperties(additionalProperties)
@@ -2477,6 +2523,7 @@ private constructor(
                     checkRequired("outputTokens", outputTokens),
                     checkRequired("outputTokensDetails", outputTokensDetails),
                     checkRequired("totalTokens", totalTokens),
+                    computeUnits,
                     additionalProperties.toMutableMap(),
                 )
         }
@@ -2502,6 +2549,7 @@ private constructor(
             outputTokens()
             outputTokensDetails().validate()
             totalTokens()
+            computeUnits()
             validated = true
         }
 
@@ -2525,7 +2573,8 @@ private constructor(
                 (inputTokensDetails.asKnown().getOrNull()?.validity() ?: 0) +
                 (if (outputTokens.asKnown().isPresent) 1 else 0) +
                 (outputTokensDetails.asKnown().getOrNull()?.validity() ?: 0) +
-                (if (totalTokens.asKnown().isPresent) 1 else 0)
+                (if (totalTokens.asKnown().isPresent) 1 else 0) +
+                (if (computeUnits.asKnown().isPresent) 1 else 0)
 
         class InputTokensDetails
         @JsonCreator(mode = JsonCreator.Mode.DISABLED)
@@ -2943,6 +2992,7 @@ private constructor(
                 outputTokens == other.outputTokens &&
                 outputTokensDetails == other.outputTokensDetails &&
                 totalTokens == other.totalTokens &&
+                computeUnits == other.computeUnits &&
                 additionalProperties == other.additionalProperties
         }
 
@@ -2953,14 +3003,15 @@ private constructor(
                 outputTokens,
                 outputTokensDetails,
                 totalTokens,
+                computeUnits,
                 additionalProperties,
             )
         }
 
         override fun hashCode(): Int = hashCode
 
         override fun toString() =
-            "Usage{inputTokens=$inputTokens, inputTokensDetails=$inputTokensDetails, outputTokens=$outputTokens, outputTokensDetails=$outputTokensDetails, totalTokens=$totalTokens, additionalProperties=$additionalProperties}"
+            "Usage{inputTokens=$inputTokens, inputTokensDetails=$inputTokensDetails, outputTokens=$outputTokens, outputTokensDetails=$outputTokensDetails, totalTokens=$totalTokens, computeUnits=$computeUnits, additionalProperties=$additionalProperties}"
     }
 
     override fun equals(other: Any?): Boolean {

openai-java-core/src/test/kotlin/com/openai/models/decisions/DecisionTest.kt

@@ -33,6 +33,7 @@ internal class DecisionTest {
                                 .build()
                         )
                         .totalTokens(-2147483648L)
+                        .computeUnits(0L)
                         .build()
                 )
                 .build()
@@ -61,6 +62,7 @@ internal class DecisionTest {
                             .build()
                     )
                     .totalTokens(-2147483648L)
+                    .computeUnits(0L)
                     .build()
             )
     }
@@ -90,6 +92,7 @@ internal class DecisionTest {
                                 .build()
                         )
                         .totalTokens(-2147483648L)
+                        .computeUnits(0L)
                         .build()
                 )
                 .build()