@nimble-way/nimble-js 0.20.0 → 1.1.0

package/src/resources/{task-agent/task-agent.ts → agents/agents.ts}

@@ -3,12 +3,14 @@
 import { APIResource } from '../../core/resource';
 import * as RunsAPI from './runs';
 import {
+  RunCreateParams,
+  RunCreateResponse,
   RunGetParams,
   RunGetResponse,
-  RunGetResultParams,
-  RunGetResultResponse,
   RunListParams,
   RunListResponse,
+  RunResultParams,
+  RunResultResponse,
   RunStreamEventsParams,
   Runs,
 } from './runs';
@@ -19,82 +21,76 @@ import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
-export class TaskAgent extends APIResource {
+export class Agents extends APIResource {
   templates: TemplatesAPI.Templates = new TemplatesAPI.Templates(this._client);
   runs: RunsAPI.Runs = new RunsAPI.Runs(this._client);
 
   /**
-   * Create a Web Search Agent instance.
-   *
-   * `account_id` is JWT-derived and never read from the request body.
-   *
-   * @deprecated
+   * Create a Web Search Agent. Either pass `template` to materialize a pre-built
+   * template (its fields, goals, sources, and suggested questions are copied), or
+   * define the agent from scratch with `display_name`, `goals`, `sources`, and an
+   * optional `output_schema` for structured results.
    */
-  create(body: TaskAgentCreateParams, options?: RequestOptions): APIPromise<TaskAgentCreateResponse> {
-    return this._client.post('/v1/task-agents', { body, ...options });
+  create(body: AgentCreateParams, options?: RequestOptions): APIPromise<AgentCreateResponse> {
+    return this._client.post('/v2/agents', { body, ...options });
   }
 
   /**
-   * Update Agent
-   *
-   * @deprecated
+   * Update an agent with a
+   * [JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) document — an array
+   * of `{op, path, value}` operations applied to the agent, e.g.
+   * `[{"op": "replace", "path": "/display_name", "value": "My agent"}]`. Returns the
+   * updated agent.
    */
   update(
     agentID: string,
-    params: TaskAgentUpdateParams,
+    params: AgentUpdateParams,
     options?: RequestOptions,
-  ): APIPromise<TaskAgentUpdateResponse> {
+  ): APIPromise<AgentUpdateResponse> {
     const { body } = params;
-    return this._client.patch(path`/v1/task-agents/${agentID}`, { body: body, ...options });
+    return this._client.patch(path`/v2/agents/${agentID}`, { body: body, ...options });
   }
 
   /**
-   * List Web Search Agent instances.
-   *
-   * Callers are strictly scoped to their (account, workspace). If `workspace_id` is
-   * omitted, the user's default workspace is used.
-   *
-   * @deprecated
+   * List the active Web Search Agents in your account. Results are scoped to the
+   * workspace resolved from your token (or the optional `workspace_id` query
+   * parameter) and paginated with `offset`/`limit`.
    */
   list(
-    query: TaskAgentListParams | null | undefined = {},
+    query: AgentListParams | null | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<TaskAgentListResponse> {
-    return this._client.get('/v1/task-agents', { query, ...options });
+  ): APIPromise<AgentListResponse> {
+    return this._client.get('/v2/agents', { query, ...options });
   }
 
   /**
-   * Deactivate Agent
-   *
-   * @deprecated
+   * Deactivate an agent. This is a soft delete: the agent can no longer start new
+   * runs, but its existing runs and their results remain retrievable.
    */
-  deactivate(agentID: string, options?: RequestOptions): APIPromise<void> {
-    return this._client.delete(path`/v1/task-agents/${agentID}`, {
+  delete(agentID: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/v2/agents/${agentID}`, {
       ...options,
       headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
     });
   }
 
   /**
-   * Get Agent
-   *
-   * @deprecated
+   * Retrieve a single Web Search Agent by ID.
    */
-  get(agentID: string, options?: RequestOptions): APIPromise<TaskAgentGetResponse> {
-    return this._client.get(path`/v1/task-agents/${agentID}`, options);
+  get(agentID: string, options?: RequestOptions): APIPromise<AgentGetResponse> {
+    return this._client.get(path`/v2/agents/${agentID}`, options);
   }
 
   /**
-   * Create a research run for a Web Search Agent instance.
-   *
-   * @deprecated
+   * Creates a minimal persistent Web Search Agent and starts a run for it. The
+   * response includes `web_search_agent_id` for later agent and run queries.
    */
-  run(agentID: string, body: TaskAgentRunParams, options?: RequestOptions): APIPromise<TaskAgentRunResponse> {
-    return this._client.post(path`/v1/task-agents/${agentID}/runs`, { body, ...options });
+  run(body: AgentRunParams, options?: RequestOptions): APIPromise<AgentRunResponse> {
+    return this._client.post('/v2/agents/runs', { body, ...options });
   }
 }
 
-export interface TaskAgentCreateResponse {
+export interface AgentCreateResponse {
   /**
    * Unique web search agent identifier (wsa\_<uuid>).
    */
@@ -115,11 +111,6 @@ export interface TaskAgentCreateResponse {
    */
   display_name: string;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise: string;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -128,7 +119,7 @@ export interface TaskAgentCreateResponse {
   /**
    * Ordered goals for the agent to follow.
    */
-  goals: Array<TaskAgentCreateResponse.Goal>;
+  goals: Array<AgentCreateResponse.Goal>;
 
   /**
    * Icon identifier used when presenting the agent.
@@ -145,15 +136,20 @@ export interface TaskAgentCreateResponse {
    */
   output_schema: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill: string;
+
   /**
    * Source guidance for the agent.
    */
-  sources: TaskAgentCreateResponse.Sources;
+  sources: AgentCreateResponse.Sources;
 
   /**
    * Suggested prompts users can run with this agent.
    */
-  suggested_questions: Array<TaskAgentCreateResponse.SuggestedQuestion>;
+  suggested_questions: Array<AgentCreateResponse.SuggestedQuestion>;
 
   /**
    * When the agent was last updated.
@@ -171,7 +167,7 @@ export interface TaskAgentCreateResponse {
   agent_name?: string | null;
 }
 
-export namespace TaskAgentCreateResponse {
+export namespace AgentCreateResponse {
   export interface Goal {
     /**
      * Unique goal identifier (wsag\_<uuid>).
@@ -278,7 +274,7 @@ export namespace TaskAgentCreateResponse {
   }
 }
 
-export interface TaskAgentUpdateResponse {
+export interface AgentUpdateResponse {
   /**
    * Unique web search agent identifier (wsa\_<uuid>).
    */
@@ -299,11 +295,6 @@ export interface TaskAgentUpdateResponse {
    */
   display_name: string;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise: string;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -312,7 +303,7 @@ export interface TaskAgentUpdateResponse {
   /**
    * Ordered goals for the agent to follow.
    */
-  goals: Array<TaskAgentUpdateResponse.Goal>;
+  goals: Array<AgentUpdateResponse.Goal>;
 
   /**
    * Icon identifier used when presenting the agent.
@@ -329,15 +320,20 @@ export interface TaskAgentUpdateResponse {
    */
   output_schema: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill: string;
+
   /**
    * Source guidance for the agent.
    */
-  sources: TaskAgentUpdateResponse.Sources;
+  sources: AgentUpdateResponse.Sources;
 
   /**
    * Suggested prompts users can run with this agent.
    */
-  suggested_questions: Array<TaskAgentUpdateResponse.SuggestedQuestion>;
+  suggested_questions: Array<AgentUpdateResponse.SuggestedQuestion>;
 
   /**
    * When the agent was last updated.
@@ -355,7 +351,7 @@ export interface TaskAgentUpdateResponse {
   agent_name?: string | null;
 }
 
-export namespace TaskAgentUpdateResponse {
+export namespace AgentUpdateResponse {
   export interface Goal {
     /**
      * Unique goal identifier (wsag\_<uuid>).
@@ -462,11 +458,11 @@ export namespace TaskAgentUpdateResponse {
   }
 }
 
-export interface TaskAgentListResponse {
+export interface AgentListResponse {
   /**
    * Items returned in this page.
    */
-  items: Array<TaskAgentListResponse.Item>;
+  items: Array<AgentListResponse.Item>;
 
   /**
    * Maximum number of items returned.
@@ -484,7 +480,7 @@ export interface TaskAgentListResponse {
   total: number;
 }
 
-export namespace TaskAgentListResponse {
+export namespace AgentListResponse {
   export interface Item {
     /**
      * Unique web search agent identifier (wsa\_<uuid>).
@@ -506,11 +502,6 @@ export namespace TaskAgentListResponse {
      */
     display_name: string;
 
-    /**
-     * Domain expertise or operating context for the agent.
-     */
-    domain_expertise: string;
-
     /**
      * Default effort level for this agent's runs.
      */
@@ -536,6 +527,11 @@ export namespace TaskAgentListResponse {
      */
     output_schema: { [key: string]: unknown } | null;
 
+    /**
+     * Skill or operating context for the agent.
+     */
+    skill: string;
+
     /**
      * Source guidance for the agent.
      */
@@ -670,7 +666,7 @@ export namespace TaskAgentListResponse {
   }
 }
 
-export interface TaskAgentGetResponse {
+export interface AgentGetResponse {
   /**
    * Unique web search agent identifier (wsa\_<uuid>).
    */
@@ -691,11 +687,6 @@ export interface TaskAgentGetResponse {
    */
   display_name: string;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise: string;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -704,7 +695,7 @@ export interface TaskAgentGetResponse {
   /**
    * Ordered goals for the agent to follow.
    */
-  goals: Array<TaskAgentGetResponse.Goal>;
+  goals: Array<AgentGetResponse.Goal>;
 
   /**
    * Icon identifier used when presenting the agent.
@@ -721,15 +712,20 @@ export interface TaskAgentGetResponse {
    */
   output_schema: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill: string;
+
   /**
    * Source guidance for the agent.
    */
-  sources: TaskAgentGetResponse.Sources;
+  sources: AgentGetResponse.Sources;
 
   /**
    * Suggested prompts users can run with this agent.
    */
-  suggested_questions: Array<TaskAgentGetResponse.SuggestedQuestion>;
+  suggested_questions: Array<AgentGetResponse.SuggestedQuestion>;
 
   /**
    * When the agent was last updated.
@@ -747,7 +743,7 @@ export interface TaskAgentGetResponse {
   agent_name?: string | null;
 }
 
-export namespace TaskAgentGetResponse {
+export namespace AgentGetResponse {
   export interface Goal {
     /**
      * Unique goal identifier (wsag\_<uuid>).
@@ -854,7 +850,7 @@ export namespace TaskAgentGetResponse {
   }
 }
 
-export interface TaskAgentRunResponse {
+export interface AgentRunResponse {
   /**
    * Run identifier, format "task*run*{uuid}".
    */
@@ -898,7 +894,7 @@ export interface TaskAgentRunResponse {
   /**
    * Error details when the run failed.
    */
-  error?: TaskAgentRunResponse.Error | null;
+  error?: AgentRunResponse.Error | null;
 
   /**
    * Prompt submitted for the run.
@@ -911,7 +907,7 @@ export interface TaskAgentRunResponse {
   started_at?: string | null;
 }
 
-export namespace TaskAgentRunResponse {
+export namespace AgentRunResponse {
   /**
    * Error details when the run failed.
    */
@@ -928,7 +924,7 @@ export namespace TaskAgentRunResponse {
   }
 }
 
-export interface TaskAgentCreateParams {
+export interface AgentCreateParams {
   /**
    * Stable agent name.
    */
@@ -944,11 +940,6 @@ export interface TaskAgentCreateParams {
    */
   display_name?: string | null;
 
-  /**
-   * Domain expertise or operating context for the agent.
-   */
-  domain_expertise?: string | null;
-
   /**
    * Default effort level for this agent's runs.
    */
@@ -974,10 +965,15 @@ export interface TaskAgentCreateParams {
    */
   output_schema?: { [key: string]: unknown } | null;
 
+  /**
+   * Skill or operating context for the agent.
+   */
+  skill?: string | null;
+
   /**
    * Source guidance for the agent.
    */
-  sources?: TaskAgentCreateParams.Sources;
+  sources?: AgentCreateParams.Sources;
 
   /**
    * Suggested prompts users can run with this agent.
@@ -996,7 +992,7 @@ export interface TaskAgentCreateParams {
   use_case?: 'research' | 'enrichment' | 'dataset_building' | null;
 }
 
-export namespace TaskAgentCreateParams {
+export namespace AgentCreateParams {
   /**
    * Source guidance for the agent.
    */
@@ -1059,14 +1055,14 @@ export namespace TaskAgentCreateParams {
   }
 }
 
-export interface TaskAgentUpdateParams {
+export interface AgentUpdateParams {
   /**
    * A JSON Patch document per RFC 6902 — a JSON array of patch operations.
    */
-  body: Array<TaskAgentUpdateParams.Body>;
+  body: Array<AgentUpdateParams.Body>;
 }
 
-export namespace TaskAgentUpdateParams {
+export namespace AgentUpdateParams {
   /**
    * A single JSON Patch operation per RFC 6902.
    */
@@ -1081,7 +1077,7 @@ export namespace TaskAgentUpdateParams {
   }
 }
 
-export interface TaskAgentListParams {
+export interface AgentListParams {
   limit?: number;
 
   offset?: number;
@@ -1089,7 +1085,7 @@ export interface TaskAgentListParams {
   workspace_id?: string | null;
 }
 
-export interface TaskAgentRunParams {
+export interface AgentRunParams {
   /**
    * User prompt or task instructions for the run.
    */
@@ -1124,10 +1120,10 @@ export interface TaskAgentRunParams {
   /**
    * Source guidance overriding the agent default.
    */
-  sources?: TaskAgentRunParams.Sources | null;
+  sources?: AgentRunParams.Sources | null;
 }
 
-export namespace TaskAgentRunParams {
+export namespace AgentRunParams {
   /**
    * Source guidance overriding the agent default.
    */
@@ -1190,20 +1186,20 @@ export namespace TaskAgentRunParams {
   }
 }
 
-TaskAgent.Templates = Templates;
-TaskAgent.Runs = Runs;
+Agents.Templates = Templates;
+Agents.Runs = Runs;
 
-export declare namespace TaskAgent {
+export declare namespace Agents {
   export {
-    type TaskAgentCreateResponse as TaskAgentCreateResponse,
-    type TaskAgentUpdateResponse as TaskAgentUpdateResponse,
-    type TaskAgentListResponse as TaskAgentListResponse,
-    type TaskAgentGetResponse as TaskAgentGetResponse,
-    type TaskAgentRunResponse as TaskAgentRunResponse,
-    type TaskAgentCreateParams as TaskAgentCreateParams,
-    type TaskAgentUpdateParams as TaskAgentUpdateParams,
-    type TaskAgentListParams as TaskAgentListParams,
-    type TaskAgentRunParams as TaskAgentRunParams,
+    type AgentCreateResponse as AgentCreateResponse,
+    type AgentUpdateResponse as AgentUpdateResponse,
+    type AgentListResponse as AgentListResponse,
+    type AgentGetResponse as AgentGetResponse,
+    type AgentRunResponse as AgentRunResponse,
+    type AgentCreateParams as AgentCreateParams,
+    type AgentUpdateParams as AgentUpdateParams,
+    type AgentListParams as AgentListParams,
+    type AgentRunParams as AgentRunParams,
   };
 
   export {
@@ -1215,12 +1211,14 @@ export declare namespace TaskAgent {
 
   export {
     Runs as Runs,
+    type RunCreateResponse as RunCreateResponse,
     type RunListResponse as RunListResponse,
     type RunGetResponse as RunGetResponse,
-    type RunGetResultResponse as RunGetResultResponse,
+    type RunResultResponse as RunResultResponse,
+    type RunCreateParams as RunCreateParams,
     type RunListParams as RunListParams,
     type RunGetParams as RunGetParams,
-    type RunGetResultParams as RunGetResultParams,
+    type RunResultParams as RunResultParams,
     type RunStreamEventsParams as RunStreamEventsParams,
   };
 }

package/src/resources/{task-agent → agents}/index.ts

@@ -1,27 +1,29 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
+export {
+  Agents,
+  type AgentCreateResponse,
+  type AgentUpdateResponse,
+  type AgentListResponse,
+  type AgentGetResponse,
+  type AgentRunResponse,
+  type AgentCreateParams,
+  type AgentUpdateParams,
+  type AgentListParams,
+  type AgentRunParams,
+} from './agents';
 export {
   Runs,
+  type RunCreateResponse,
   type RunListResponse,
   type RunGetResponse,
-  type RunGetResultResponse,
+  type RunResultResponse,
+  type RunCreateParams,
   type RunListParams,
   type RunGetParams,
-  type RunGetResultParams,
+  type RunResultParams,
   type RunStreamEventsParams,
 } from './runs';
-export {
-  TaskAgent,
-  type TaskAgentCreateResponse,
-  type TaskAgentUpdateResponse,
-  type TaskAgentListResponse,
-  type TaskAgentGetResponse,
-  type TaskAgentRunResponse,
-  type TaskAgentCreateParams,
-  type TaskAgentUpdateParams,
-  type TaskAgentListParams,
-  type TaskAgentRunParams,
-} from './task-agent';
 export {
   Templates,
   type TemplateListResponse,