Skip to main content

Agents

For usage examples, see Usage - Agents.

AgentsClient​

Client for running agents via the Mentiora API.

Note: Unlike tracing methods (which return SendTraceResult and never throw), agent methods throw exceptions on errors (ValidationError, NetworkError).

Methods​

run(params: AgentRunParams): Promise<AgentRunResult>​

Run an agent and return the complete result.

Parameters:

  • params: AgentRunParams - Agent run parameters

Returns: Promise<AgentRunResult>

Throws: ValidationError, NetworkError

Example:

const result = await client.agents.run({
  tag: 'production',
  message: 'What is the weather today?',
});
console.log(result.output);

stream(params: AgentRunParams): AsyncGenerator<AgentStreamEvent>​

Run an agent with streaming. Returns an async iterable of events.

Parameters:

  • params: AgentRunParams - Agent run parameters

Yields: AgentStreamEvent objects

Throws: ValidationError, NetworkError

Example:

for await (const event of client.agents.stream({
  tag: 'production',
  message: 'Write a poem about TypeScript.',
})) {
  if (event.type === 'output_text_delta') {
    process.stdout.write(event.delta);
  } else if (event.type === 'error') {
    console.error(`Error: ${event.message}`);
  }
}

Types​

AgentRunParams​

interface AgentRunParams {
  tag?: string; // Tag name to resolve agent (e.g. 'production')
  agentId?: string; // Explicit agent ID (alternative to tag)
  revision?: number; // Explicit revision number (used with agentId)
  message: string; // User message to send (required)
  threadId?: string; // Thread ID for multi-turn conversations
  modelId?: string; // Override the agent's default model
  modelParams?: {
    // Override model parameters
    temperature?: number;
    maxTokens?: number;
    seed?: number;
  };
  endUserId?: string; // End-user identifier for tracking
  metadata?: Record<string, unknown>; // Arbitrary metadata
}

Validation rules:

  • message is required and cannot be empty
  • Either tag or agentId/agent_id must be provided, but not both
  • tag must match ^[a-z0-9][a-z0-9\-_]*$ (lowercase alphanumeric, hyphens, underscores; must start with a letter or digit)

ModelParams​

interface ModelParams {
  temperature?: number; // 0–2 (inclusive)
  maxTokens?: number; // Must be > 0
  seed?: number;
}

Validation rules:

  • temperature must be between 0 and 2 (inclusive)
  • maxTokens/max_tokens must be a positive integer

AgentRunResult​

interface AgentRunResult {
  threadId: string; // Thread ID for the conversation
  traceId?: string; // Trace ID for observability
  agentId: string; // Resolved agent ID
  agentRevision: number; // Resolved agent revision
  agentTag?: string; // Resolved agent tag (if applicable)
  output: string; // Agent output text
  toolCalls: AgentToolCall[]; // Tool calls made during execution
  status: 'completed' | 'failed'; // Execution status
  usage?: {
    // Token usage stats
    promptTokens?: number;
    completionTokens?: number;
  };
}

AgentToolCall​

interface AgentToolCall {
  toolCallId: string;
  name: string;
  arguments: unknown;
  result?: unknown;
}

AgentStreamEvent​

Union type of all possible streaming events:

type AgentStreamEvent =
  | AgentResolvedEvent
  | OutputTextDeltaEvent
  | ToolCallDeltaEvent
  | ToolCallResultEvent
  | SuggestionsEvent
  | ChatCompletedEvent
  | AgentErrorEvent
  | CustomEvent;

AgentResolvedEvent​

Emitted once at stream start with resolved agent metadata.

interface AgentResolvedEvent {
  type: 'agent_resolved';
  agentId: string;
  agentRevision: number;
  agentTag?: string;
  threadId: string;
}

OutputTextDeltaEvent​

Streaming text chunk from the agent.

interface OutputTextDeltaEvent {
  type: 'output_text_delta';
  delta: string;
}

ToolCallDeltaEvent​

Streaming tool call argument chunk.

interface ToolCallDeltaEvent {
  type: 'tool_call_delta';
  toolCallId: string;
  name: string;
  argumentsDelta: string;
}

ToolCallResultEvent​

Completed tool call with result.

interface ToolCallResultEvent {
  type: 'tool_call_result';
  toolCallId: string;
  name: string;
  arguments: unknown;
  result: unknown;
}

SuggestionsEvent​

Emitted when the agent provides follow-up suggestion prompts. Typically sent after the agent's response is complete. The SDK validates suggestions (max 6 items, label ≤ 40 chars) and silently drops invalid entries.

interface SuggestionsEvent {
  type: 'suggestions';
  suggestions: Array<{
    label: string;  // Display text (max 40 chars)
    message: string; // Message to send when clicked
  }>;
}

ChatCompletedEvent​

Emitted when agent execution completes.

interface ChatCompletedEvent {
  type: 'chat_completed';
  threadId: string;
  status: 'completed' | 'failed';
  output: string;
}

AgentErrorEvent​

Error event from the agent backend. Streaming stops after this event.

interface AgentErrorEvent {
  type: 'error';
  code: string;
  message: string;
}

CustomEvent​

Pass-through event for unknown SSE event names. Use this for domain-specific events that are not yet promoted to first-class SDK event types.

interface CustomEvent {
  type: 'custom';
  event: string;
  data: Record<string, unknown>;
}

See also: Client | Streaming Helpers | Errors