TypeScript Types¶

This page provides the complete TypeScript type definitions exported by @modernpath/agent-ui-react. Types are organized by category: Chat, Grounding, Traces, and Conversations.

Import¶

All types are exported from the package root:

import type {
  ChatRole,
  AgentBackend,
  AgentExecuteRequest,
  AgentExecuteResponse,
  GroundingContext,
  TraceUI,
  SpanUI,
  ConversationBackend,
  // ...
} from "@modernpath/agent-ui-react";

Chat Types¶

ChatRole¶

type ChatRole = "user" | "assistant";

ChatHistoryMessage¶

A message in the chat history sent to the backend as context.

interface ChatHistoryMessage {
  /** Message role */
  role: ChatRole;

  /** Message text content */
  content: string;
}

AgentExecuteRequest¶

Request payload sent to the agent backend.

interface AgentExecuteRequest {
  /** Agent type identifier */
  agentType: string;

  /** User prompt text */
  prompt: string;

  /** Previous messages for context */
  history?: ChatHistoryMessage[];

  /** Additional parameters passed to the agent */
  parameters?: Record<string, unknown>;
}

AgentExecuteResponse\<T>¶

Response payload returned by the agent backend.

interface AgentExecuteResponse<T = any> {
  /** Agent's text response */
  answer: string;

  /** Structured response data (agent-specific) */
  data?: T;

  /** Agent execution plan */
  plan?: {
    steps: Array<{
      title: string;
      description?: string;
    }>;
  };

  /** Execution step results */
  executionDetails?: {
    steps: Array<{
      title: string;
      status: "pending" | "running" | "completed" | "failed" | "skipped";
      durationMs?: number;
      result?: unknown;
      error?: string;
    }>;
  };

  /** Grounding context with RAG chunks, documents, and policy */
  groundingContext?: GroundingContext;

  /** Execution statistics */
  statistics?: {
    totalTokens?: number;
    inputTokens?: number;
    outputTokens?: number;
    durationMs?: number;
    estimatedCost?: number;
  };

  /** Trace ID for this execution */
  traceId?: string;

  /** Research details (web research agents) */
  researchDetails?: {
    references?: Array<{
      title: string;
      url: string;
      snippet?: string;
      score?: number;
    }>;
    metadata?: {
      queriesCount?: number;
      pagesFetched?: number;
      durationMs?: number;
      queries?: string[];
    };
  };
}

AgentStreamEvent¶

Events received during SSE streaming.

type AgentStreamEvent =
  | {
      /** Incremental text content */
      type: "delta";
      content: string;
    }
  | {
      /** Complete response (end of stream) */
      type: "final";
      data: AgentExecuteResponse<any>;
    }
  | {
      /** Stream error */
      type: "error";
      error: string;
      code?: string;
    };

AgentBackend¶

Backend interface for agent communication.

interface AgentBackend {
  /**
   * Execute an agent request and return the complete response.
   */
  execute: (
    request: AgentExecuteRequest,
    signal?: AbortSignal
  ) => Promise<AgentExecuteResponse<any>>;

  /**
   * Execute an agent request with SSE streaming.
   * Optional -- only provided by SSE backends.
   */
  executeStream?: (
    request: AgentExecuteRequest,
    onEvent: (event: AgentStreamEvent) => void,
    signal?: AbortSignal
  ) => Promise<void>;
}

AgentChatMessage¶

A message in the chat UI.

interface AgentChatMessage {
  /** Message role */
  role: ChatRole;

  /** Display text content */
  content: string;

  /** Message timestamp (epoch milliseconds) */
  timestamp: number;

  /** Full backend response data (assistant messages only) */
  data?: AgentExecuteResponse<any>;
}

Grounding Types¶

GroundingContext¶

Top-level grounding context object.

interface GroundingContext {
  /** RAG retrieval chunks */
  ragChunks?: GroundingContextRagChunks;

  /** Canonical documents */
  canonicalDocuments?: GroundingContextCanonicalDocuments;

  /** Document composition details */
  composition?: GroundingContextComposition;

  /** Grounding decision (policy and mode) */
  decision?: GroundingContextDecision;
}

GroundingContextRagChunks¶

interface GroundingContextRagChunks {
  /** Retrieved chunks */
  chunks: Array<{
    /** Chunk text content */
    text: string;

    /** Relevance score (0.0 to 1.0) */
    score: number;

    /** Source document metadata */
    source: GroundingContextRagChunkSource;
  }>;

  /** Total chunks retrieved before filtering */
  totalRetrieved?: number;
}

GroundingContextRagChunkSource¶

interface GroundingContextRagChunkSource {
  /** Source document title */
  title: string;

  /** Source document URI */
  uri?: string;
}

GroundingContextCanonicalDocuments¶

interface GroundingContextCanonicalDocuments {
  /** Array of canonical documents */
  documents: Array<GroundingContextCanonicalDocument>;
}

GroundingContextCanonicalDocument¶

interface GroundingContextCanonicalDocument {
  /** Document display name */
  name: string;

  /** MIME type */
  mimeType: string;

  /** File size in bytes */
  sizeBytes?: number;

  /** Source identifier */
  source: string;

  /** Source type for badge display */
  sourceType?: "knowledge-base" | "sharepoint" | "upload" | "url";

  /** Document URI or download link */
  uri?: string;
}

GroundingContextComposition¶

interface GroundingContextComposition {
  /** Composition bundles */
  bundles: Array<GroundingContextCompositionBundle>;
}

GroundingContextCompositionBundle¶

interface GroundingContextCompositionBundle {
  /** Bundle name */
  name: string;

  /** Documents included in the prompt */
  includes: Array<GroundingContextCompositionInclude>;

  /** Documents excluded from the prompt */
  skipped: Array<GroundingContextCompositionSkipped>;
}

GroundingContextCompositionInclude¶

interface GroundingContextCompositionInclude {
  /** Document name */
  documentName: string;

  /** Character count of the included content */
  charCount: number;
}

GroundingContextCompositionSkipped¶

interface GroundingContextCompositionSkipped {
  /** Document name */
  documentName: string;

  /** Reason for skipping */
  reason: string;
}

GroundingContextDecision¶

interface GroundingContextDecision {
  /** Active grounding mode */
  mode: "rag_and_attachments" | "attachments_only" | "rag_only" | "none";

  /** Human-readable reasoning for the mode selection */
  reasoning?: string;

  /** Whether RAG chunks were included in the LLM prompt */
  ragIncluded: boolean;

  /** Whether canonical documents were included */
  attachmentsIncluded: boolean;
}

Trace Types¶

TraceStatus¶

type TraceStatus = "ok" | "error" | "timeout";

SpanKind¶

type SpanKind = "llm" | "tool" | "retrieval" | "agent" | "internal";

SpanStatus¶

type SpanStatus = "ok" | "error" | "unset";

TraceUI¶

interface TraceUI {
  /** Unique trace identifier */
  traceId: string;

  /** Agent name */
  agent: string;

  /** Trace status */
  status: TraceStatus;

  /** Trace start time (ISO 8601) */
  startTime: string;

  /** Trace end time (ISO 8601) */
  endTime?: string;

  /** Total duration in milliseconds */
  durationMs: number;

  /** Total token count (input + output) */
  totalTokens?: number;

  /** Input token count */
  inputTokens?: number;

  /** Output token count */
  outputTokens?: number;

  /** Estimated cost in USD */
  estimatedCost?: number;

  /** User prompt (may be truncated) */
  prompt?: string;

  /** Trace tags */
  tags?: string[];

  /** Additional metadata */
  metadata?: Record<string, unknown>;
}

SpanUI¶

interface SpanUI {
  /** Unique span identifier */
  spanId: string;

  /** Parent span ID (undefined for root spans) */
  parentSpanId?: string;

  /** Operation name */
  name: string;

  /** Span kind */
  kind: SpanKind;

  /** Span status */
  status: SpanStatus;

  /** Span start time (ISO 8601) */
  startTime: string;

  /** Span end time (ISO 8601) */
  endTime?: string;

  /** Duration in milliseconds */
  durationMs: number;

  /** Input data (JSON-serializable) */
  input?: unknown;

  /** Output data (JSON-serializable) */
  output?: unknown;

  /** Span attributes */
  attributes?: Record<string, unknown>;

  /** Span events */
  events?: Array<{
    /** Event name */
    name: string;
    /** Event timestamp (ISO 8601) */
    timestamp: string;
    /** Event attributes */
    attributes?: Record<string, unknown>;
  }>;
}

SessionUI¶

interface SessionUI {
  /** Session identifier */
  sessionId: string;

  /** User identifier */
  userId?: string;

  /** Session start time */
  startTime: string;

  /** Traces in this session */
  traceIds: string[];

  /** Session metadata */
  metadata?: Record<string, unknown>;
}

ConfigSnapshotUI¶

interface ConfigSnapshotUI {
  /** Agent configuration snapshot */
  agent?: {
    /** Agent name */
    name: string;
    /** Agent version */
    version: string;
    /** Model used */
    model?: string;
    /** Temperature setting */
    temperature?: number;
  };

  /** Tool configurations */
  tools?: Array<{
    /** Tool name */
    name: string;
    /** Tool source (local, mcp, dynamic) */
    source: string;
  }>;

  /** Prompt templates */
  prompts?: Record<string, string>;

  /** Sanitized environment variables */
  environment?: Record<string, string>;
}

TraceBackend¶

interface TraceBackend {
  /** List traces with pagination and filtering */
  listTraces: (params: {
    page: number;
    pageSize: number;
    filter?: TraceListFilter;
  }) => Promise<{ traces: TraceUI[]; total: number }>;

  /** Get a single trace with spans and config snapshot */
  getTrace: (traceId: string) => Promise<{
    trace: TraceUI;
    spans: SpanUI[];
    configSnapshot?: ConfigSnapshotUI;
  }>;
}

TraceListFilter¶

interface TraceListFilter {
  /** Filter by agent name */
  agent?: string;

  /** Filter by trace status */
  status?: TraceStatus;

  /** Filter traces after this date */
  startDate?: Date;

  /** Filter traces before this date */
  endDate?: Date;

  /** Filter by tag */
  tag?: string;

  /** Free-text search across prompt content */
  search?: string;
}

Conversation Types¶

ConversationRole¶

type ConversationRole = "user" | "assistant" | "system";

ConversationUI¶

interface ConversationUI {
  /** Unique conversation identifier */
  id: string;

  /** Conversation title */
  title: string;

  /** Agent name associated with this conversation */
  agentName?: string;

  /** Creation timestamp (ISO 8601) */
  createdAt: string;

  /** Last update timestamp (ISO 8601) */
  updatedAt: string;
}

ConversationMessageUI¶

interface ConversationMessageUI {
  /** Message role */
  role: ConversationRole;

  /** Message text content */
  content: string;

  /** Message timestamp (ISO 8601) */
  timestamp: string;

  /** Trace ID for the assistant response */
  traceId?: string;

  /** Additional metadata */
  metadata?: Record<string, unknown>;
}

ConversationBackend¶

interface ConversationBackend {
  /** List all conversations */
  listConversations: () => Promise<ConversationUI[]>;

  /** Create a new conversation */
  createConversation: (params: {
    agentName?: string;
    parameters?: Record<string, unknown>;
  }) => Promise<ConversationUI>;

  /** Get messages for a conversation */
  getMessages: (conversationId: string) => Promise<ConversationMessageUI[]>;

  /** Send a message and receive the assistant response */
  sendMessage: (
    conversationId: string,
    message: {
      content: string;
      agentName?: string;
      parameters?: Record<string, unknown>;
    }
  ) => Promise<ConversationMessageUI>;

  /** Delete a conversation */
  deleteConversation: (conversationId: string) => Promise<void>;
}

Chat Components -- components using Chat types
Grounding Components -- components using Grounding types
Trace Components -- components using Trace types
Hooks -- hooks returning these types
Backend Factories -- factories creating backend instances