feat: add filters to count_agents endpoint [LET-5380] [LET-5497]

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 116
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/letta-ai%2Fletta-sdk-5db911b088119948c6ff8eb328caa30a5085ce2e217bf139aa654d5fa602f642.yml
-openapi_spec_hash: 6de73deeb221b0e3fd8b60d73b2d2e12
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/letta-ai%2Fletta-sdk-779ee7a7a34dc46d2e6b71e0c87eb3b31520e439b27542a8b40963480ad63f74.yml
+openapi_spec_hash: d03e9b957df56ce2ea87653feb9bdb6a
 config_hash: 436e42e127dea74b3004397fffda6f99

api.md

@@ -120,7 +120,7 @@ Methods:
 - <code title="get /v1/agents/{agent_id}">client.agents.<a href="./src/resources/agents/agents.ts">retrieve</a>(agentID, { ...params }) -> AgentState</code>
 - <code title="get /v1/agents/">client.agents.<a href="./src/resources/agents/agents.ts">list</a>({ ...params }) -> AgentStatesArrayPage</code>
 - <code title="delete /v1/agents/{agent_id}">client.agents.<a href="./src/resources/agents/agents.ts">delete</a>(agentID) -> unknown</code>
-- <code title="get /v1/agents/count">client.agents.<a href="./src/resources/agents/agents.ts">count</a>() -> AgentCountResponse</code>
+- <code title="get /v1/agents/count">client.agents.<a href="./src/resources/agents/agents.ts">count</a>({ ...params }) -> AgentCountResponse</code>
 - <code title="get /v1/agents/{agent_id}/export">client.agents.<a href="./src/resources/agents/agents.ts">exportFile</a>(agentID, { ...params }) -> string</code>
 - <code title="post /v1/agents/import">client.agents.<a href="./src/resources/agents/agents.ts">importFile</a>({ ...params }) -> AgentImportFileResponse</code>
 - <code title="patch /v1/agents/{agent_id}">client.agents.<a href="./src/resources/agents/agents.ts">modify</a>(agentID, { ...params }) -> AgentState</code>

src/client.ts

@@ -58,6 +58,7 @@ import {
   ToolsArrayPage,
 } from './resources/tools';
 import {
+  AgentCountParams,
   AgentCountResponse,
   AgentCreateParams,
   AgentDeleteResponse,
@@ -1046,6 +1047,7 @@ export declare namespace Letta {
     type AgentCreateParams as AgentCreateParams,
     type AgentRetrieveParams as AgentRetrieveParams,
     type AgentListParams as AgentListParams,
+    type AgentCountParams as AgentCountParams,
     type AgentExportFileParams as AgentExportFileParams,
     type AgentImportFileParams as AgentImportFileParams,
     type AgentModifyParams as AgentModifyParams,

src/resources/agents/agents.ts

@@ -149,10 +149,14 @@ export class Agents extends APIResource {
   }
 
   /**
-   * Get the total number of agents.
+   * Get the total number of agents with optional filtering. Supports the same
+   * filters as list_agents for consistent querying.
    */
-  count(options?: RequestOptions): APIPromise<AgentCountResponse> {
-    return this._client.get('/v1/agents/count', options);
+  count(
+    query: AgentCountParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<AgentCountResponse> {
+    return this._client.get('/v1/agents/count', { query, ...options });
   }
 
   /**
@@ -1491,6 +1495,59 @@ export interface AgentListParams extends ArrayPageParams {
   template_id?: string | null;
 }
 
+export interface AgentCountParams {
+  /**
+   * Search agents by base template ID
+   */
+  base_template_id?: string | null;
+
+  /**
+   * Search agents by identifier keys
+   */
+  identifier_keys?: Array<string> | null;
+
+  /**
+   * Search agents by identity ID
+   */
+  identity_id?: string | null;
+
+  /**
+   * Filter agents by their last stop reason.
+   */
+  last_stop_reason?: RunsAPI.StopReasonType | null;
+
+  /**
+   * If True, only counts agents that match ALL given tags. Otherwise, counts agents
+   * that have ANY of the passed-in tags.
+   */
+  match_all_tags?: boolean;
+
+  /**
+   * Name of the agent
+   */
+  name?: string | null;
+
+  /**
+   * Search agents by project ID - this will default to your default project on cloud
+   */
+  project_id?: string | null;
+
+  /**
+   * Search agents by name
+   */
+  query_text?: string | null;
+
+  /**
+   * List of tags to filter agents by
+   */
+  tags?: Array<string> | null;
+
+  /**
+   * Search agents by template ID
+   */
+  template_id?: string | null;
+}
+
 export interface AgentExportFileParams {
   /**
    * @deprecated
@@ -1811,6 +1868,7 @@ export declare namespace Agents {
     type AgentCreateParams as AgentCreateParams,
     type AgentRetrieveParams as AgentRetrieveParams,
     type AgentListParams as AgentListParams,
+    type AgentCountParams as AgentCountParams,
     type AgentExportFileParams as AgentExportFileParams,
     type AgentImportFileParams as AgentImportFileParams,
     type AgentModifyParams as AgentModifyParams,

src/resources/agents/index.ts

@@ -26,6 +26,7 @@ export {
   type AgentCreateParams,
   type AgentRetrieveParams,
   type AgentListParams,
+  type AgentCountParams,
   type AgentExportFileParams,
   type AgentImportFileParams,
   type AgentModifyParams,

src/resources/index.ts

@@ -26,6 +26,7 @@ export {
   type AgentCreateParams,
   type AgentRetrieveParams,
   type AgentListParams,
+  type AgentCountParams,
   type AgentExportFileParams,
   type AgentImportFileParams,
   type AgentModifyParams,

tests/api-resources/agents/agents.test.ts

@@ -111,6 +111,28 @@ describe('resource agents', () => {
     expect(dataAndResponse.response).toBe(rawResponse);
   });
 
+  // Prism tests are disabled
+  test.skip('count: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.agents.count(
+        {
+          base_template_id: 'base_template_id',
+          identifier_keys: ['string'],
+          identity_id: 'identity_id',
+          last_stop_reason: 'end_turn',
+          match_all_tags: true,
+          name: 'name',
+          project_id: 'project_id',
+          query_text: 'query_text',
+          tags: ['string'],
+          template_id: 'template_id',
+        },
+        { path: '/_stainless_unknown_path' },
+      ),
+    ).rejects.toThrow(Letta.NotFoundError);
+  });
+
   // Prism tests are disabled
   test.skip('exportFile', async () => {
     const responsePromise = client.agents.exportFile('agent_id');