feat(api): filter agent sessions by metadata (#4200)

## Summary

Adds optional metadata filters when listing agent sessions.

## Changes

- Filter sessions by exact metadata key-value matches.
- Combine metadata filters with existing pagination and agent filters.

Author: jbeckwith-oai

.castiron.stats.yml

@@ -1,7 +1,7 @@
 schema_version: 1
-generation_id: e164ac83-c112-4711-be50-ebb428fe3158
-openapi_spec_hash: 0fa065837f86231ded0decb63dbdf0b7
-openapi_transformed_spec_hash: 89a4e53d02ad69dde25fe7b073c64609
+generation_id: 45c2be6c-9b78-4bff-b88b-f437435ae397
+openapi_spec_hash: 7b8e0964b34b0cf993d2e2946e8eac7a
+openapi_transformed_spec_hash: 096782182a5f2b2d0d09fb4822e35e10
 config_hash: 0e042fd083471fc089bcbfe7011a7d01
-codegen_sha: 3f4c502584c527f11658bdeb8c487e8cee0ed4da
-codegen_hash: a13510d3bcce387fb660ffbe32d7a3155e53c9b19fe9339d4ff1dd4e4211335c
+codegen_sha: 2d3d72e9eb4ebaca41912b7d0ce1bc8733a90569
+codegen_hash: fec5e33e84cf8605506e7b95a1dd30735e4cffe16ec560150a65b669d4975ebd

api_reference/openapi.transformed.yml

@@ -33173,6 +33173,24 @@ paths:
           minLength: 0
           maxLength: 1048576
         description: Only return sessions whose root agent has this ID. Omit to return sessions for all agents.
+      - name: metadata
+        in: query
+        required: false
+        schema:
+          type: object
+          additionalProperties:
+            type: string
+            minLength: 0
+            maxLength: 512
+          propertyNames:
+            type: string
+            minLength: 1
+            maxLength: 64
+          minProperties: 0
+          maxProperties: 16
+        description: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512 characters. New sessions and metadata updates may take time to appear in filtered results.
+        style: deepObject
+        explode: true
       responses:
         '200':
           description: A page of sessions.

scripts/castiron/generated-files.json

@@ -283,7 +283,7 @@
     },
     "src/openai/resources/beta/agents/sessions/sessions.py": {
       "mode": "100644",
-      "sha256": "65699418bb2e7b847de57b9c2d9c82acf0f94dfb99b46391ab61331580e7032c"
+      "sha256": "d1719b767d0b16e9eba1c405a66e9c11874da30a6ba2fa873603d1e6a9f6f7e2"
     },
     "src/openai/resources/beta/agents/sessions/subagents/__init__.py": {
       "mode": "100644",
@@ -2003,7 +2003,7 @@
     },
     "src/openai/types/beta/agents/session_list_params.py": {
       "mode": "100644",
-      "sha256": "4f0902a10fe694a0efa2f7073cca64a2aea6e4c346f71176e49aef4621ed049d"
+      "sha256": "2de32d51ce2cfdbcf2224acfa8b04a28234717d6c373a3d68ee66bac90f75d2d"
     },
     "src/openai/types/beta/agents/session_update_params.py": {
       "mode": "100644",
@@ -7691,7 +7691,7 @@
     },
     "tests/api_resources/beta/agents/test_sessions.py": {
       "mode": "100644",
-      "sha256": "6b8c1e42b3465b95d3c6ab5449ea8cb95c8b93427ccd59c0b96694e5e1a972bb"
+      "sha256": "10a9f8cbd1fda1b32b4bf7a0ac422073e82463b9dd1f9151d159951ea47005d8"
     },
     "tests/api_resources/beta/agents/test_vaults.py": {
       "mode": "100644",

src/openai/resources/beta/agents/sessions/sessions.py

@@ -379,6 +379,7 @@ def list(
         after: str | Omit = omit,
         agent_id: str | Omit = omit,
         limit: int | Omit = omit,
+        metadata: Dict[str, str] | Omit = omit,
         order: Literal["asc", "desc"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -400,6 +401,11 @@ def list(
 
           limit: The maximum number of resources to return, between 1 and 100. Defaults to 20.
 
+          metadata: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must
+              match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512
+              characters. New sessions and metadata updates may take time to appear in
+              filtered results.
+
           order: The order in which resources are returned. Defaults to `desc`.
 
               - `asc` - Returns resources in ascending order.
@@ -427,6 +433,7 @@ def list(
                         "after": after,
                         "agent_id": agent_id,
                         "limit": limit,
+                        "metadata": metadata,
                         "order": order,
                     },
                     session_list_params.SessionListParams,
@@ -781,6 +788,7 @@ def list(
         after: str | Omit = omit,
         agent_id: str | Omit = omit,
         limit: int | Omit = omit,
+        metadata: Dict[str, str] | Omit = omit,
         order: Literal["asc", "desc"] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -802,6 +810,11 @@ def list(
 
           limit: The maximum number of resources to return, between 1 and 100. Defaults to 20.
 
+          metadata: Exact string matches supplied as `metadata[key]=value`. All supplied pairs must
+              match. Up to 16 pairs, with keys from 1 to 64 characters and values up to 512
+              characters. New sessions and metadata updates may take time to appear in
+              filtered results.
+
           order: The order in which resources are returned. Defaults to `desc`.
 
               - `asc` - Returns resources in ascending order.
@@ -829,6 +842,7 @@ def list(
                         "after": after,
                         "agent_id": agent_id,
                         "limit": limit,
+                        "metadata": metadata,
                         "order": order,
                     },
                     session_list_params.SessionListParams,

src/openai/types/beta/agents/session_list_params.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from typing import Dict
 from typing_extensions import Literal, TypedDict
 
 __all__ = ["SessionListParams"]
@@ -20,6 +21,14 @@ class SessionListParams(TypedDict, total=False):
     limit: int
     """The maximum number of resources to return, between 1 and 100. Defaults to 20."""
 
+    metadata: Dict[str, str]
+    """Exact string matches supplied as `metadata[key]=value`.
+
+    All supplied pairs must match. Up to 16 pairs, with keys from 1 to 64 characters
+    and values up to 512 characters. New sessions and metadata updates may take time
+    to appear in filtered results.
+    """
+
     order: Literal["asc", "desc"]
     """The order in which resources are returned. Defaults to `desc`.
 

tests/api_resources/beta/agents/test_sessions.py

@@ -261,6 +261,7 @@ def test_method_list_with_all_params(self, client: OpenAI) -> None:
             after="after",
             agent_id="agent_id",
             limit=1,
+            metadata={"foo": "string"},
             order="asc",
         )
         assert_matches_type(SyncCursorPage[AgentSession], session, path=["response"])
@@ -572,6 +573,7 @@ async def test_method_list_with_all_params(self, async_client: AsyncOpenAI) -> N
             after="after",
             agent_id="agent_id",
             limit=1,
+            metadata={"foo": "string"},
             order="asc",
         )
         assert_matches_type(AsyncCursorPage[AgentSession], session, path=["response"])