@reminix/sdk 0.10.0 → 0.12.0

package/src/resources/agents.ts

@@ -3,48 +3,61 @@
 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.
-   *
-   * **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
+   * 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.
    *
-   * **Use cases:**
+   * @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.
    *
-   * - Customer support chatbots
-   * - AI assistants with memory
-   * - Multi-step question answering
-   * - Conversational agents that need context
+   * **Supported Agents:** Managed agents only. Custom agents should use the /execute
+   * endpoint.
    *
-   * **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,8 +89,12 @@ 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.
+   * Invoke a custom agent with the provided input.
+   *
+   * **Supported Agents:** Custom agents only. Managed agents should use the /chat
+   * endpoint.
+   *
+   * **Input:** Pass structured input data matching the agent's parameter schema.
    *
    * **Timeout:** Agent invocations have a 60-second timeout. If the agent takes
    * longer to respond, you will receive a 504 Gateway Timeout error. For
@@ -88,30 +105,18 @@ 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 responses.
    *
    * @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.invoke('name');
    * ```
    */
   invoke(
     name: string,
-    body: AgentInvokeParamsNonStreaming,
+    body?: AgentInvokeParamsNonStreaming,
     options?: RequestOptions,
   ): APIPromise<AgentInvokeResponse>;
   invoke(
@@ -121,27 +126,182 @@ export class Agents extends APIResource {
   ): APIPromise<Stream<StreamChunk>>;
   invoke(
     name: string,
-    body: AgentInvokeParamsBase,
+    body?: AgentInvokeParamsBase | undefined,
     options?: RequestOptions,
   ): APIPromise<Stream<StreamChunk> | AgentInvokeResponse>;
   invoke(
     name: string,
-    body: AgentInvokeParams,
+    body: AgentInvokeParams | undefined = {},
     options?: RequestOptions,
   ): APIPromise<AgentInvokeResponse> | APIPromise<Stream<StreamChunk>> {
     return this._client.post(path`/agents/${name}/invoke`, {
       body,
       ...options,
-      stream: body.stream ?? false,
+      stream: body?.stream ?? false,
     }) as APIPromise<AgentInvokeResponse> | 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 +314,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 +338,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,61 +361,91 @@ 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 AgentInvokeResponse = { [key: string]: unknown };
+
+export interface AgentListParams extends CursorParams {
+  /**
+   * Filter by agent status
+   */
+  status?: 'active' | 'inactive';
+
   /**
-   * Output from the agent. Structure depends on agent implementation.
+   * Filter by agent type (managed, python, typescript, python-langchain, etc.)
    */
-  output?: unknown;
+  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;
 
   /**
-   * Whether to stream the response as SSE.
+   * Conversation ID to continue an existing conversation
+   */
+  conversation_id?: string;
+
+  /**
+   * 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;
 }
@@ -263,47 +454,63 @@ export type AgentInvokeParams = AgentInvokeParamsNonStreaming | AgentInvokeParam
 
 export interface AgentInvokeParamsBase {
   /**
-   * Input data for the agent. Structure depends on agent implementation.
-   */
-  input: { [key: string]: unknown };
-
-  /**
-   * Optional request context passed to the agent handler.
+   * Optional context for the agent execution
    */
-  context?: Context;
+  context?: AgentInvokeParams.Context;
 
   /**
-   * Whether to stream the response as SSE.
+   * Enable streaming response (SSE)
    */
   stream?: boolean;
+
+  [k: string]: unknown;
 }
 
 export namespace AgentInvokeParams {
+  /**
+   * 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 AgentInvokeParamsNonStreaming = AgentsAPI.AgentInvokeParamsNonStreaming;
   export type AgentInvokeParamsStreaming = AgentsAPI.AgentInvokeParamsStreaming;
 }
 
 export interface AgentInvokeParamsNonStreaming extends AgentInvokeParamsBase {
   /**
-   * Whether to stream the response as SSE.
+   * Enable streaming response (SSE)
    */
   stream?: false;
+
+  [k: string]: unknown;
 }
 
 export interface AgentInvokeParamsStreaming extends AgentInvokeParamsBase {
   /**
-   * 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 AgentsCursor as AgentsCursor,
+    type AgentListParams as AgentListParams,
     type AgentChatParams as AgentChatParams,
     type AgentChatParamsNonStreaming as AgentChatParamsNonStreaming,
     type AgentChatParamsStreaming as AgentChatParamsStreaming,

package/src/resources/conversations.ts

@@ -0,0 +1,146 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../core/resource';
+import { APIPromise } from '../core/api-promise';
+import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
+import { buildHeaders } from '../internal/headers';
+import { RequestOptions } from '../internal/request-options';
+import { path } from '../internal/utils/path';
+
+export class Conversations extends APIResource {
+  /**
+   * Get details of a specific conversation including all messages.
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<ConversationRetrieveResponse> {
+    return this._client.get(path`/conversations/${id}`, options);
+  }
+
+  /**
+   * List conversations for the project with optional filtering.
+   *
+   * Conversations store chat history between users and agents. Use filters to narrow
+   * down results by agent name or identity fields.
+   *
+   * **Filters:**
+   *
+   * - `agent_name`: Filter by agent name
+   * - `identity.*`: Filter by identity fields (e.g., identity.user_id=user_123)
+   */
+  list(
+    query: ConversationListParams | null | undefined = {},
+    options?: RequestOptions,
+  ): PagePromise<ConversationsCursor, Conversation> {
+    return this._client.getAPIList('/conversations', Cursor<Conversation>, { query, ...options });
+  }
+
+  /**
+   * Delete a conversation and all its messages. This action cannot be undone.
+   */
+  delete(id: string, options?: RequestOptions): APIPromise<void> {
+    return this._client.delete(path`/conversations/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export type ConversationsCursor = Cursor<Conversation>;
+
+export interface Conversation {
+  /**
+   * Unique conversation ID
+   */
+  id: string;
+
+  /**
+   * Agent name
+   */
+  agentName: string;
+
+  /**
+   * When the conversation was created
+   */
+  createdAt: string;
+
+  /**
+   * Identity fields for conversation scoping
+   */
+  identity: { [key: string]: unknown };
+
+  /**
+   * Project ID
+   */
+  projectId: string;
+
+  /**
+   * When the conversation was last updated
+   */
+  updatedAt: string;
+}
+
+export interface ConversationRetrieveResponse extends Conversation {
+  /**
+   * Conversation messages
+   */
+  messages: Array<ConversationRetrieveResponse.Message>;
+}
+
+export namespace ConversationRetrieveResponse {
+  export interface Message {
+    /**
+     * Unique message ID
+     */
+    id: string;
+
+    /**
+     * Message content
+     */
+    content: string | null;
+
+    /**
+     * Conversation ID
+     */
+    conversationId: string;
+
+    /**
+     * When the message was created
+     */
+    createdAt: string;
+
+    /**
+     * Tool name (for tool messages)
+     */
+    name: string | null;
+
+    /**
+     * Message role
+     */
+    role: 'system' | 'user' | 'assistant' | 'tool';
+
+    /**
+     * Tool call ID (for tool messages)
+     */
+    toolCallId: string | null;
+
+    /**
+     * Tool calls (for assistant messages)
+     */
+    toolCalls?: unknown;
+  }
+}
+
+export interface ConversationListParams extends CursorParams {
+  /**
+   * Filter by agent name
+   */
+  agent_name?: string;
+}
+
+export declare namespace Conversations {
+  export {
+    type Conversation as Conversation,
+    type ConversationRetrieveResponse as ConversationRetrieveResponse,
+    type ConversationsCursor as ConversationsCursor,
+    type ConversationListParams as ConversationListParams,
+  };
+}