@reminix/sdk 0.10.0 → 0.11.0

package/src/resources/agents.ts

@@ -3,48 +3,64 @@
 import { APIResource } from '../core/resource';
 import * as AgentsAPI from './agents';
 import { APIPromise } from '../core/api-promise';
+import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
 import { Stream } from '../core/streaming';
 import { RequestOptions } from '../internal/request-options';
 import { path } from '../internal/utils/path';
 
 export class Agents extends APIResource {
   /**
-   * Have a conversational interaction with an agent. This endpoint maintains
-   * conversation context through the messages array, allowing for multi-turn
-   * conversations.
+   * Get details of a specific agent by name.
    *
-   * **Timeout:** Chat requests have a 60-second timeout. If the agent takes longer
-   * to respond, you will receive a 504 Gateway Timeout error. For long-running
-   * conversations, consider using streaming mode which does not have the same
-   * timeout constraints.
+   * @example
+   * ```ts
+   * const agent = await client.agents.retrieve('x');
+   * ```
+   */
+  retrieve(name: string, options?: RequestOptions): APIPromise<Agent> {
+    return this._client.get(path`/agents/${name}`, options);
+  }
+
+  /**
+   * List all agents in the project with optional filtering by type and status.
    *
-   * **Idempotency:** For non-streaming requests, send an `Idempotency-Key` header
-   * with a unique value (e.g., UUID) to ensure duplicate requests return the same
-   * response. Keys are valid for 24 hours. Streaming responses are not cached.
+   * @example
+   * ```ts
+   * // Automatically fetches more pages as needed.
+   * for await (const agent of client.agents.list()) {
+   *   // ...
+   * }
+   * ```
+   */
+  list(
+    query: AgentListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<AgentsCursor, Agent> {
+    return this._client.getAPIList('/agents', Cursor<Agent>, { query, ...options });
+  }
+
+  /**
+   * Send a chat message to an agent and receive a response.
    *
-   * **Use cases:**
+   * **Supported Agents:**
    *
-   * - Customer support chatbots
-   * - AI assistants with memory
-   * - Multi-step question answering
-   * - Conversational agents that need context
+   * - Managed agents: Always supported
+   * - Custom agents: Only supported if agent has `messages` in both requestKeys and
+   *   responseKeys
    *
-   * **Message format:** Follows OpenAI-compliant message structure with support for:
+   * **Tool Calls:** Messages support the OpenAI tool calling format:
    *
-   * - `system`, `user`, `assistant`, and `tool` roles
-   * - Multimodal content (text + images)
-   * - Tool/function calling
+   * - Assistant messages can include `tool_calls` array with function calls
+   * - Tool result messages use `role: "tool"` with `tool_call_id` and `name`
+   * - Content can be `null` when `tool_calls` is present
    *
-   * **Streaming:** Set `stream: true` in the request body to receive Server-Sent
-   * Events (SSE) stream with incremental chunks. Perfect for ChatGPT-like real-time
-   * chat interfaces.
+   * **Streaming:** Set `stream: true` to receive Server-Sent Events (SSE) for
+   * real-time responses.
    *
    * @example
    * ```ts
    * const response = await client.agents.chat('name', {
-   *   messages: [
-   *     { role: 'user', content: 'What is the weather today?' },
-   *   ],
+   *   messages: [{ content: 'string', role: 'system' }],
    * });
    * ```
    */
@@ -76,10 +92,14 @@ export class Agents extends APIResource {
   }
 
   /**
-   * Execute a one-shot task with an agent. This endpoint is designed for
-   * task-oriented operations where you provide input and receive a complete output.
+   * Execute an agent with the provided input.
    *
-   * **Timeout:** Agent invocations have a 60-second timeout. If the agent takes
+   * **Agent Types:**
+   *
+   * - Task-oriented agents: Pass structured input data
+   * - Chat agents: Pass `{ messages: [...] }` in the input
+   *
+   * **Timeout:** Agent executions have a 60-second timeout. If the agent takes
    * longer to respond, you will receive a 504 Gateway Timeout error. For
    * long-running tasks, consider using streaming mode which does not have the same
    * timeout constraints.
@@ -88,60 +108,203 @@ export class Agents extends APIResource {
    * with a unique value (e.g., UUID) to ensure duplicate requests return the same
    * response. Keys are valid for 24 hours. Streaming responses are not cached.
    *
-   * **Use cases:**
-   *
-   * - Data analysis and processing
-   * - Content generation (with streaming for long outputs)
-   * - One-time operations that don't require conversation history
-   * - API-like operations
-   *
    * **Streaming:** Set `stream: true` in the request body to receive Server-Sent
    * Events (SSE) stream with incremental chunks. Useful for long-running tasks or
-   * real-time progress updates.
+   * real-time chat interfaces.
    *
    * @example
    * ```ts
-   * const response = await client.agents.invoke('name', {
-   *   input: {
-   *     task: 'analyze this data',
-   *     data: { value: 123, items: ['a', 'b', 'c'] },
-   *   },
-   * });
+   * const response = await client.agents.execute('name');
    * ```
    */
-  invoke(
+  execute(
     name: string,
-    body: AgentInvokeParamsNonStreaming,
+    body?: AgentExecuteParamsNonStreaming,
     options?: RequestOptions,
-  ): APIPromise<AgentInvokeResponse>;
-  invoke(
+  ): APIPromise<AgentExecuteResponse>;
+  execute(
     name: string,
-    body: AgentInvokeParamsStreaming,
+    body: AgentExecuteParamsStreaming,
     options?: RequestOptions,
   ): APIPromise<Stream<StreamChunk>>;
-  invoke(
+  execute(
     name: string,
-    body: AgentInvokeParamsBase,
+    body?: AgentExecuteParamsBase | undefined,
     options?: RequestOptions,
-  ): APIPromise<Stream<StreamChunk> | AgentInvokeResponse>;
-  invoke(
+  ): APIPromise<Stream<StreamChunk> | AgentExecuteResponse>;
+  execute(
     name: string,
-    body: AgentInvokeParams,
+    body: AgentExecuteParams | undefined = {},
     options?: RequestOptions,
-  ): APIPromise<AgentInvokeResponse> | APIPromise<Stream<StreamChunk>> {
-    return this._client.post(path`/agents/${name}/invoke`, {
+  ): APIPromise<AgentExecuteResponse> | APIPromise<Stream<StreamChunk>> {
+    return this._client.post(path`/agents/${name}/execute`, {
       body,
       ...options,
-      stream: body.stream ?? false,
-    }) as APIPromise<AgentInvokeResponse> | APIPromise<Stream<StreamChunk>>;
+      stream: body?.stream ?? false,
+    }) as APIPromise<AgentExecuteResponse> | APIPromise<Stream<StreamChunk>>;
   }
 }
 
+export type AgentsCursor = Cursor<Agent>;
+
+export interface Agent {
+  /**
+   * Unique agent ID
+   */
+  id: string;
+
+  /**
+   * Whether agent supports chat interface
+   */
+  canChat: boolean | null;
+
+  /**
+   * Whether agent supports streaming
+   */
+  canStream: boolean | null;
+
+  /**
+   * Agent configuration (for managed agents)
+   */
+  config: AgentConfig | null;
+
+  /**
+   * Creation timestamp
+   */
+  createdAt: string;
+
+  /**
+   * User who created the agent
+   */
+  createdBy: string | null;
+
+  /**
+   * Agent description
+   */
+  description: string | null;
+
+  /**
+   * When the agent was discovered (for custom agents)
+   */
+  discoveredAt: string | null;
+
+  /**
+   * Agent name
+   */
+  name: string;
+
+  /**
+   * JSON Schema for agent input parameters
+   */
+  output: Agent.Output | null;
+
+  /**
+   * JSON Schema for agent input parameters
+   */
+  parameters: Agent.Parameters | null;
+
+  /**
+   * Project ID
+   */
+  projectId: string;
+
+  /**
+   * Top-level keys expected in request body
+   */
+  requestKeys: Array<string> | null;
+
+  /**
+   * Top-level keys returned in response body
+   */
+  responseKeys: Array<string> | null;
+
+  /**
+   * Agent status
+   */
+  status: 'active' | 'inactive';
+
+  /**
+   * Agent type: "managed" for UI-created, "{language}" for custom agents (e.g.,
+   * "python"), or "{language}-{adapter}" for adapter-based (e.g.,
+   * "python-langchain")
+   */
+  type: string;
+
+  /**
+   * Last update timestamp
+   */
+  updatedAt: string;
+}
+
+export namespace Agent {
+  /**
+   * JSON Schema for agent input parameters
+   */
+  export interface Output {
+    type: string;
+
+    properties?: { [key: string]: unknown };
+
+    required?: Array<string>;
+
+    [k: string]: unknown;
+  }
+
+  /**
+   * JSON Schema for agent input parameters
+   */
+  export interface Parameters {
+    type: string;
+
+    properties?: { [key: string]: unknown };
+
+    required?: Array<string>;
+
+    [k: string]: unknown;
+  }
+}
+
+/**
+ * Agent configuration (for managed agents)
+ */
+export interface AgentConfig {
+  /**
+   * Model identifier (e.g., "gpt-4o", "claude-sonnet-4-20250514")
+   */
+  model: string;
+
+  /**
+   * LLM provider
+   */
+  provider: 'openai' | 'anthropic';
+
+  /**
+   * System prompt for the agent
+   */
+  systemPrompt: string;
+
+  /**
+   * List of tools available to the agent
+   */
+  tools: Array<string>;
+
+  /**
+   * Maximum tool call iterations
+   */
+  maxIterations?: number;
+
+  /**
+   * Whether to require approval for tool calls
+   */
+  requireApproval?: boolean;
+}
+
 export interface ChatMessage {
   /**
-   * Message content. Can be string, array (multimodal), or object (tool).
+   * Message content. Can be string, array (multimodal), object (tool), or null (when
+   * tool_calls present).
    */
-  content: string | Array<ChatMessage.MultimodalContent> | { [key: string]: unknown };
+  content: string | Array<ChatMessage.MultimodalContent> | { [key: string]: unknown } | null;
 
   /**
    * Message role
@@ -154,9 +317,14 @@ export interface ChatMessage {
   name?: string;
 
   /**
-   * Tool call ID (for tool role)
+   * Tool call ID (for tool role messages)
    */
   tool_call_id?: string;
+
+  /**
+   * Tool calls requested by assistant (for assistant role messages)
+   */
+  tool_calls?: Array<ChatMessage.ToolCall>;
 }
 
 export namespace ChatMessage {
@@ -173,26 +341,22 @@ export namespace ChatMessage {
       url: string;
     }
   }
-}
 
-/**
- * Optional request context passed to the agent handler.
- */
-export interface Context {
-  /**
-   * ID to track multi-turn conversations
-   */
-  conversation_id?: string;
+  export interface ToolCall {
+    id: string;
 
-  /**
-   * Additional custom context fields
-   */
-  custom?: { [key: string]: unknown };
+    function: ToolCall.Function;
 
-  /**
-   * ID of the user making the request
-   */
-  user_id?: string;
+    type: 'function';
+  }
+
+  export namespace ToolCall {
+    export interface Function {
+      arguments: string;
+
+      name: string;
+    }
+  }
 }
 
 export interface StreamChunk {
@@ -200,115 +364,161 @@ export interface StreamChunk {
    * Text chunk from the stream
    */
   chunk: string;
+
+  [k: string]: unknown;
 }
 
 export interface AgentChatResponse {
   /**
-   * Full conversation history including the assistant response
+   * Array of assistant response messages
    */
   messages: Array<ChatMessage>;
 
   /**
-   * Final assistant response text
+   * Conversation ID (present when conversation persistence is enabled)
    */
-  output: string;
+  conversation_id?: string;
 }
 
-export interface AgentInvokeResponse {
+/**
+ * Response with dynamic keys based on agent configuration. Regular agents return {
+ * output: ... }, chat agents return { messages: [...] }.
+ */
+export type AgentExecuteResponse = { [key: string]: unknown };
+
+export interface AgentListParams extends CursorParams {
   /**
-   * Output from the agent. Structure depends on agent implementation.
+   * Filter by agent status
    */
-  output?: unknown;
+  status?: 'active' | 'inactive';
+
+  /**
+   * Filter by agent type (managed, python, typescript, python-langchain, etc.)
+   */
+  type?: string;
 }
 
 export type AgentChatParams = AgentChatParamsNonStreaming | AgentChatParamsStreaming;
 
 export interface AgentChatParamsBase {
   /**
-   * Conversation history. Must include at least one message.
+   * Array of chat messages
    */
   messages: Array<ChatMessage>;
 
   /**
-   * Optional request context passed to the agent handler.
+   * Optional context for the agent execution
    */
-  context?: Context;
+  context?: AgentChatParams.Context;
+
+  /**
+   * Conversation ID to continue an existing conversation
+   */
+  conversation_id?: string;
 
   /**
-   * Whether to stream the response as SSE.
+   * Enable streaming response
    */
   stream?: boolean;
 }
 
 export namespace AgentChatParams {
+  /**
+   * Optional context for the agent execution
+   */
+  export interface Context {
+    /**
+     * Identity fields for conversation scoping (e.g., user_id, tenant_id)
+     */
+    identity?: { [key: string]: unknown };
+
+    [k: string]: unknown;
+  }
+
   export type AgentChatParamsNonStreaming = AgentsAPI.AgentChatParamsNonStreaming;
   export type AgentChatParamsStreaming = AgentsAPI.AgentChatParamsStreaming;
 }
 
 export interface AgentChatParamsNonStreaming extends AgentChatParamsBase {
   /**
-   * Whether to stream the response as SSE.
+   * Enable streaming response
    */
   stream?: false;
 }
 
 export interface AgentChatParamsStreaming extends AgentChatParamsBase {
   /**
-   * Whether to stream the response as SSE.
+   * Enable streaming response
    */
   stream: true;
 }
 
-export type AgentInvokeParams = AgentInvokeParamsNonStreaming | AgentInvokeParamsStreaming;
+export type AgentExecuteParams = AgentExecuteParamsNonStreaming | AgentExecuteParamsStreaming;
 
-export interface AgentInvokeParamsBase {
+export interface AgentExecuteParamsBase {
   /**
-   * Input data for the agent. Structure depends on agent implementation.
+   * Optional context for the agent execution
    */
-  input: { [key: string]: unknown };
+  context?: AgentExecuteParams.Context;
 
   /**
-   * Optional request context passed to the agent handler.
+   * Enable streaming response (SSE)
    */
-  context?: Context;
+  stream?: boolean;
+
+  [k: string]: unknown;
+}
 
+export namespace AgentExecuteParams {
   /**
-   * Whether to stream the response as SSE.
+   * Optional context for the agent execution
    */
-  stream?: boolean;
-}
+  export interface Context {
+    /**
+     * Identity fields for conversation scoping (e.g., user_id, tenant_id)
+     */
+    identity?: { [key: string]: unknown };
 
-export namespace AgentInvokeParams {
-  export type AgentInvokeParamsNonStreaming = AgentsAPI.AgentInvokeParamsNonStreaming;
-  export type AgentInvokeParamsStreaming = AgentsAPI.AgentInvokeParamsStreaming;
+    [k: string]: unknown;
+  }
+
+  export type AgentExecuteParamsNonStreaming = AgentsAPI.AgentExecuteParamsNonStreaming;
+  export type AgentExecuteParamsStreaming = AgentsAPI.AgentExecuteParamsStreaming;
 }
 
-export interface AgentInvokeParamsNonStreaming extends AgentInvokeParamsBase {
+export interface AgentExecuteParamsNonStreaming extends AgentExecuteParamsBase {
   /**
-   * Whether to stream the response as SSE.
+   * Enable streaming response (SSE)
    */
   stream?: false;
+
+  [k: string]: unknown;
 }
 
-export interface AgentInvokeParamsStreaming extends AgentInvokeParamsBase {
+export interface AgentExecuteParamsStreaming extends AgentExecuteParamsBase {
   /**
-   * Whether to stream the response as SSE.
+   * Enable streaming response (SSE)
    */
   stream: true;
+
+  [k: string]: unknown;
 }
 
 export declare namespace Agents {
   export {
+    type Agent as Agent,
+    type AgentConfig as AgentConfig,
     type ChatMessage as ChatMessage,
-    type Context as Context,
     type StreamChunk as StreamChunk,
     type AgentChatResponse as AgentChatResponse,
-    type AgentInvokeResponse as AgentInvokeResponse,
+    type AgentExecuteResponse as AgentExecuteResponse,
+    type AgentsCursor as AgentsCursor,
+    type AgentListParams as AgentListParams,
     type AgentChatParams as AgentChatParams,
     type AgentChatParamsNonStreaming as AgentChatParamsNonStreaming,
     type AgentChatParamsStreaming as AgentChatParamsStreaming,
-    type AgentInvokeParams as AgentInvokeParams,
-    type AgentInvokeParamsNonStreaming as AgentInvokeParamsNonStreaming,
-    type AgentInvokeParamsStreaming as AgentInvokeParamsStreaming,
+    type AgentExecuteParams as AgentExecuteParams,
+    type AgentExecuteParamsNonStreaming as AgentExecuteParamsNonStreaming,
+    type AgentExecuteParamsStreaming as AgentExecuteParamsStreaming,
   };
 }