// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../core/resource';
import * as Shared from './shared';
import { APIPromise } from '../core/api-promise';
import { Cursor, type CursorParams, PagePromise } from '../core/pagination';
import { RequestOptions } from '../internal/request-options';
import { path } from '../internal/utils/path';

export class Agents extends APIResource {
  /**
   * Get details of a specific agent by name.
   *
   * @example
   * ```ts
   * const agent = await client.agents.retrieve('name');
   * ```
   */
  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 stack and status.
   *
   * @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.
   *
   * **Tool Calls:** Messages support the OpenAI tool calling format:
   *
   * - 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` to receive Server-Sent Events (SSE) for
   * real-time responses.
   *
   * @example
   * ```ts
   * const response = await client.agents.chat('name', {
   *   messages: [{ content: 'string', role: 'developer' }],
   * });
   * ```
   */
  chat(name: string, body: AgentChatParams, options?: RequestOptions): APIPromise<AgentChatResponse> {
    return this._client.post(path`/agents/${name}/chat`, { body, ...options });
  }

  /**
   * Invoke an agent with the provided input.
   *
   * **Input:** Pass structured input data matching the agent's input 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
   * long-running tasks, 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.
   *
   * **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 responses.
   *
   * @example
   * ```ts
   * const response = await client.agents.invoke('name', {
   *   input: {
   *     prompt: 'Summarize the key points of machine learning',
   *   },
   * });
   * ```
   */
  invoke(
    name: string,
    body: AgentInvokeParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<AgentInvokeResponse> {
    return this._client.post(path`/agents/${name}/invoke`, { body, ...options });
  }

  /**
   * Start a new workflow run for a workflow agent.
   *
   * **Input:** Pass structured input matching the agent's workflow input schema. The
   * agent will execute and return the run status, state, and any pending actions.
   *
   * **Lifecycle:** The run is created with status `running`, then transitions to
   * `completed`, `paused`, or `failed` based on agent output. When `paused`, use the
   * resume endpoint to continue.
   *
   * @example
   * ```ts
   * const response = await client.agents.startWorkflow('name');
   * ```
   */
  startWorkflow(
    name: string,
    body: AgentStartWorkflowParams | null | undefined = {},
    options?: RequestOptions,
  ): APIPromise<AgentStartWorkflowResponse> {
    return this._client.post(path`/agents/${name}/workflow`, { body, ...options });
  }
}

export type AgentsCursor = Cursor<Agent>;

export interface Agent {
  /**
   * Unique agent ID
   */
  id: string;

  /**
   * Agent capabilities (e.g. streaming)
   */
  capabilities: Agent.Capabilities | null;

  /**
   * Creation timestamp
   */
  createdAt: string;

  /**
   * Agent description
   */
  description: string | null;

  /**
   * When the agent was last discovered from a deployment
   */
  discoveredAt: string | null;

  /**
   * Example input for code snippets
   */
  exampleInput: { [key: string]: unknown } | null;

  /**
   * JSON Schema for agent input
   */
  inputSchema: Shared.JsonSchema | null;

  /**
   * Extra metadata from runtime
   */
  metadata: { [key: string]: unknown } | null;

  /**
   * Agent name
   */
  name: string;

  /**
   * JSON Schema for agent input
   */
  outputSchema: Shared.JsonSchema | null;

  /**
   * Project ID
   */
  projectId: string;

  /**
   * Agent stack (e.g., "python", "typescript", "python-langchain")
   */
  stack: string;

  /**
   * Agent status
   */
  status: 'active' | 'inactive';

  /**
   * Tags for categorization
   */
  tags: Array<string> | null;

  /**
   * Agent type (e.g., prompt, chat, task, rag, thread, workflow); null if not set
   */
  type: 'prompt' | 'chat' | 'task' | 'rag' | 'thread' | 'workflow' | null;

  /**
   * Last update timestamp
   */
  updatedAt: string;
}

export namespace Agent {
  /**
   * Agent capabilities (e.g. streaming)
   */
  export interface Capabilities {
    /**
     * Whether agent supports streaming
     */
    streaming?: boolean;

    [k: string]: unknown;
  }
}

export interface ChatMessage {
  /**
   * Message content. String, array of content parts (multimodal), or null when
   * tool_calls present.
   */
  content:
    | string
    | Array<
        | ChatMessage.ContentPartText
        | ChatMessage.ContentPartImageURL
        | ChatMessage.ContentPartInputAudio
        | ChatMessage.ContentPartFile
        | ChatMessage.ContentPartRefusal
      >
    | null;

  /**
   * Message role
   */
  role: 'developer' | 'system' | 'user' | 'assistant' | 'tool';

  /**
   * Optional participant name
   */
  name?: string;

  /**
   * Tool call ID (required when role is "tool")
   */
  tool_call_id?: string;

  /**
   * Tool calls (assistant role only)
   */
  tool_calls?: Array<ChatMessage.ToolCall>;
}

export namespace ChatMessage {
  export interface ContentPartText {
    text: string;

    type: 'text';
  }

  export interface ContentPartImageURL {
    image_url: ContentPartImageURL.ImageURL;

    type: 'image_url';
  }

  export namespace ContentPartImageURL {
    export interface ImageURL {
      /**
       * URL or base64 image data
       */
      url: string;

      detail?: 'auto' | 'low' | 'high';
    }
  }

  export interface ContentPartInputAudio {
    input_audio: ContentPartInputAudio.InputAudio;

    type: 'input_audio';
  }

  export namespace ContentPartInputAudio {
    export interface InputAudio {
      /**
       * Base64 encoded audio data
       */
      data: string;

      format: 'wav' | 'mp3';
    }
  }

  export interface ContentPartFile {
    file: ContentPartFile.File;

    type: 'file';
  }

  export namespace ContentPartFile {
    export interface File {
      /**
       * Base64 encoded file data
       */
      file_data?: string;

      file_id?: string;

      filename?: string;
    }
  }

  export interface ContentPartRefusal {
    refusal: string;

    type: 'refusal';
  }

  export interface ToolCall {
    id: string;

    function: ToolCall.Function;

    type: 'function';
  }

  export namespace ToolCall {
    export interface Function {
      arguments: string;

      name: string;
    }
  }
}

/**
 * Execution reference for tracking
 */
export interface ExecutionRef {
  /**
   * Execution log ID
   */
  id: string;

  /**
   * Type of execution
   */
  type: 'agent_invoke' | 'tool_call';

  /**
   * URL to fetch the execution log
   */
  url: string;

  /**
   * Duration in milliseconds
   */
  duration_ms?: number;

  /**
   * Execution result status
   */
  status?: 'success' | 'error' | 'timeout';
}

export interface AgentChatResponse {
  /**
   * Array of assistant response messages
   */
  messages: Array<ChatMessage>;

  /**
   * Conversation ID (present when conversation persistence is enabled)
   */
  conversation_id?: string;
}

/**
 * Response with output from the agent and optional execution reference.
 */
export interface AgentInvokeResponse {
  /**
   * Execution reference for tracking
   */
  execution?: ExecutionRef;

  /**
   * Output from the agent
   */
  output?: unknown;
}

export interface AgentStartWorkflowResponse {
  /**
   * Workflow run ID
   */
  run_id: string;

  /**
   * Full workflow state (steps, result, etc.)
   */
  state: { [key: string]: unknown };

  /**
   * Workflow run status
   */
  status: string;

  /**
   * Execution reference for tracking
   */
  execution?: ExecutionRef;

  /**
   * Pending action details when paused
   */
  pendingAction?: { [key: string]: unknown } | null;
}

export interface AgentListParams extends CursorParams {
  /**
   * Filter by agent stack (e.g., python, typescript, python-langchain)
   */
  stack?: string;

  /**
   * Filter by agent status
   */
  status?: 'active' | 'inactive';
}

export interface AgentChatParams {
  /**
   * Array of chat messages
   */
  messages: Array<ChatMessage>;

  /**
   * Optional context: identity (conversation scoping), attributes (injected into
   * system prompt), and pass-through for tools
   */
  context?: Shared.Context;

  /**
   * Conversation ID to continue an existing conversation
   */
  conversation_id?: string;

  /**
   * Enable streaming response
   */
  stream?: boolean;
}

export interface AgentInvokeParams {
  /**
   * Optional context: identity (conversation scoping), attributes (injected into
   * system prompt), and pass-through for tools
   */
  context?: Shared.Context;

  /**
   * Input data for the agent
   */
  input?: { [key: string]: unknown };

  /**
   * Enable streaming response (SSE)
   */
  stream?: boolean;
}

export interface AgentStartWorkflowParams {
  /**
   * Optional context: identity (conversation scoping), attributes (injected into
   * system prompt), and pass-through for tools
   */
  context?: Shared.Context;

  /**
   * Input data for the workflow agent
   */
  input?: { [key: string]: unknown };

  /**
   * Enable streaming response (SSE)
   */
  stream?: boolean;
}

export declare namespace Agents {
  export {
    type Agent as Agent,
    type ChatMessage as ChatMessage,
    type ExecutionRef as ExecutionRef,
    type AgentChatResponse as AgentChatResponse,
    type AgentInvokeResponse as AgentInvokeResponse,
    type AgentStartWorkflowResponse as AgentStartWorkflowResponse,
    type AgentsCursor as AgentsCursor,
    type AgentListParams as AgentListParams,
    type AgentChatParams as AgentChatParams,
    type AgentInvokeParams as AgentInvokeParams,
    type AgentStartWorkflowParams as AgentStartWorkflowParams,
  };
}