@langwatch/mcp-server 2.0.0 → 2.2.0

package/src/langwatch-api-agents.ts

@@ -1,5 +1,41 @@
-import { makeRequest } from "./langwatch-api.js";
-import { requestPublicJson } from "./public-http-request.js";
+import { z } from "zod";
+
+import { makeRequest } from "./langwatch-api.ts";
+import { requestPublicJson } from "./public-http-request.ts";
+
+/**
+ * The run parameters a call carries: a flat record of scalars. The platform
+ * declares run parameters as `string`, `number` or `boolean`, so a nested
+ * object or an array is outside the contract and is refused here.
+ */
+export const agentCallParamsSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.number(), z.boolean()]),
+);
+
+export type AgentCallParams = z.infer<typeof agentCallParamsSchema>;
+
+/**
+ * One run parameter an agent declares, as the platform lists it. An agent
+ * never declares a secret parameter: a secret belongs to the scenario and is
+ * supplied per run.
+ */
+export interface AgentParameterSpec {
+  name: string;
+  type: "string" | "number" | "boolean";
+  options?: string[];
+  default?: string | number | boolean;
+  description?: string;
+  required?: boolean;
+}
+
+/** One process connected as an instance of a connected agent. */
+export interface AgentInstance {
+  id: string;
+  hostname: string;
+  label?: string | null;
+  connectedAt: string;
+}
 
 export interface AgentSummary {
   id: string;
@@ -8,6 +44,19 @@ export interface AgentSummary {
   config: Record<string, unknown> | null;
   createdAt: string;
   updatedAt: string;
+  /** Connected agents: the environment the SDK registered under. */
+  environment?: string | null;
+  /** Connected agents: online while at least one instance is connected. */
+  status?: "online" | "offline" | null;
+  instances?: AgentInstance[];
+  lastSeenAt?: string | null;
+  owner?: { userId: string; name: string } | null;
+  hostLabel?: string | null;
+  /** Whether this key can run the agent. */
+  selectable?: boolean;
+  /** Why the agent cannot be run with this key; null when it can. */
+  notSelectableReason?: "owned_by_another_person" | null;
+  parameters?: AgentParameterSpec[];
 }
 
 export interface AgentListResponse {
@@ -20,6 +69,31 @@ export interface AgentListResponse {
   };
 }
 
+/** One conversation message as the relay carries it, OpenAI style. */
+export interface AgentCallMessage {
+  role: string;
+  content?: unknown;
+  [key: string]: unknown;
+}
+
+/** The body `POST /api/v1/agents/:id/call` takes. */
+export interface AgentCallBody {
+  messages: AgentCallMessage[];
+  newMessages?: AgentCallMessage[];
+  threadId?: string;
+  params?: AgentCallParams;
+  session?: unknown;
+  traceparent?: string;
+}
+
+/** The reply of the relay: the function's output and the instance that ran it. */
+export interface AgentCallResponse {
+  output: unknown;
+  session?: unknown;
+  instance: { hostname: string; label?: string | null };
+  durationMs: number;
+}
+
 export async function listAgents(params?: {
   page?: number;
   limit?: number;
@@ -28,14 +102,11 @@ export async function listAgents(params?: {
   if (params?.page) query.set("page", String(params.page));
   if (params?.limit) query.set("limit", String(params.limit));
   const qs = query.toString() ? `?${query}` : "";
-  return makeRequest("GET", `/api/agents${qs}`) as Promise<AgentListResponse>;
+  return makeRequest("GET", `/api/v1/agents${qs}`) as Promise<AgentListResponse>;
 }
 
 export async function getAgent(id: string): Promise<AgentSummary> {
-  return makeRequest(
-    "GET",
-    `/api/agents/${encodeURIComponent(id)}`,
-  ) as Promise<AgentSummary>;
+  return makeRequest("GET", `/api/v1/agents/${encodeURIComponent(id)}`) as Promise<AgentSummary>;
 }
 
 export async function createAgent(data: {
@@ -43,7 +114,7 @@ export async function createAgent(data: {
   type: string;
   config: Record<string, unknown>;
 }): Promise<AgentSummary> {
-  return makeRequest("POST", "/api/agents", data) as Promise<AgentSummary>;
+  return makeRequest("POST", "/api/v1/agents", data) as Promise<AgentSummary>;
 }
 
 export async function updateAgent(params: {
@@ -55,22 +126,132 @@ export async function updateAgent(params: {
   const { id, ...data } = params;
   return makeRequest(
     "PATCH",
-    `/api/agents/${encodeURIComponent(id)}`,
+    `/api/v1/agents/${encodeURIComponent(id)}`,
     data,
   ) as Promise<AgentSummary>;
 }
 
 /**
- * Run an agent. For HTTP agents, calls the configured URL directly.
- * For workflow-linked agents, calls the workflow run endpoint.
+ * Runs one turn of a connected agent through the relay: the platform
+ * dispatches it to a live instance and answers with the function's output.
  */
-export async function runAgent(
-  id: string,
-  input?: Record<string, unknown>,
-): Promise<{ agentType: string; result: Record<string, unknown> }> {
+export async function callAgent({
+  id,
+  body,
+}: {
+  id: string;
+  body: AgentCallBody;
+}): Promise<AgentCallResponse> {
+  return makeRequest(
+    "POST",
+    `/api/v1/agents/${encodeURIComponent(id)}/call`,
+    body,
+  ) as Promise<AgentCallResponse>;
+}
+
+/** The ids `POST /api/v1/agents/:id/test` answers with. */
+export interface AgentTestRunResponse {
+  scenarioRunId: string;
+  batchRunId: string;
+  setId: string;
+}
+
+/**
+ * Runs one scripted "ping" scenario against an agent and succeeds when
+ * the answer arrives. Creates no scenario, run plan or test suite; the
+ * response carries the run ids to follow.
+ */
+export async function testAgent(id: string): Promise<AgentTestRunResponse> {
+  return makeRequest(
+    "POST",
+    `/api/v1/agents/${encodeURIComponent(id)}/test`,
+    {},
+  ) as Promise<AgentTestRunResponse>;
+}
+
+const isMessageList = (value: unknown): value is AgentCallMessage[] =>
+  Array.isArray(value) &&
+  value.every(
+    (item) =>
+      typeof item === "object" &&
+      item !== null &&
+      typeof (item as AgentCallMessage).role === "string",
+  );
+
+/**
+ * The relay body for a connected agent: `message` is one user turn,
+ * `input` is the raw body (must carry `messages`), `parameters` are run
+ * parameters, `threadId` continues a conversation. A string is a refusal.
+ */
+export function buildRelayBody({
+  input,
+  message,
+  parameters,
+  threadId,
+}: {
+  input: Record<string, unknown>;
+  message?: string;
+  parameters?: AgentCallParams;
+  threadId?: string;
+}): AgentCallBody | string {
+  let messages: AgentCallMessage[];
+  if (message !== undefined) {
+    messages = [{ role: "user", content: message }];
+  } else if (isMessageList(input.messages)) {
+    messages = input.messages;
+  } else {
+    return "a connected agent takes a conversation: give `message`, or `input` with a `messages` list.";
+  }
+  const body: AgentCallBody = { messages };
+  const thread = threadId ?? (typeof input.threadId === "string" ? input.threadId : undefined);
+  if (thread) body.threadId = thread;
+  if (isMessageList(input.newMessages)) body.newMessages = input.newMessages;
+  if (input.session !== undefined) body.session = input.session;
+  let inputParams: AgentCallParams | undefined;
+  if (input.params !== undefined) {
+    const parsed = agentCallParamsSchema.safeParse(input.params);
+    if (!parsed.success) {
+      return "`params` takes one flat object of string, number or boolean values. Nested objects and arrays are not run parameters.";
+    }
+    inputParams = parsed.data;
+  }
+  if (inputParams || parameters) body.params = { ...inputParams, ...parameters };
+  return body;
+}
+
+/**
+ * Run an agent. A connected agent runs one turn through the relay; an HTTP
+ * agent is called at its URL; a workflow-linked agent runs on the workflow
+ * engine.
+ */
+export async function runAgent({
+  id,
+  input,
+  message,
+  parameters,
+  threadId,
+}: {
+  id: string;
+  input?: Record<string, unknown>;
+  message?: string;
+  parameters?: AgentCallParams;
+  threadId?: string;
+}): Promise<{ agentType: string; result: Record<string, unknown> }> {
   const agent = await getAgent(id);
   const config = agent.config ?? {};
 
+  if (agent.type === "connected") {
+    const body = buildRelayBody({ input: input ?? {}, message, parameters, threadId });
+    if (typeof body === "string") throw new Error(body);
+    if (agent.status === "offline") {
+      throw new Error(
+        `Agent "${agent.name}" is offline. Start the process that calls connectAgent (or connect_agent) and try again.`,
+      );
+    }
+    const result = await callAgent({ id: agent.id, body });
+    return { agentType: "connected", result: result as unknown as Record<string, unknown> };
+  }
+
   if (agent.type === "http") {
     const url = (config as Record<string, unknown>).url as string | undefined;
     if (!url) {
@@ -91,18 +272,18 @@ export async function runAgent(
   if (!workflowId) {
     throw new Error(
       `Agent "${agent.name}" (type: ${agent.type}) cannot be executed directly. ` +
-        `Only HTTP agents and workflow-linked agents can be run.`,
+        `Only connected agents, HTTP agents and workflow-linked agents can be run.`,
     );
   }
 
-  const { runWorkflow } = await import("./langwatch-api-workflows.js");
+  const { runWorkflow } = await import("./langwatch-api-workflows.ts");
   const result = await runWorkflow(workflowId, input);
   return { agentType: agent.type, result };
 }
 
 export async function deleteAgent(id: string): Promise<{ id: string; name: string }> {
-  return makeRequest(
-    "DELETE",
-    `/api/agents/${encodeURIComponent(id)}`,
-  ) as Promise<{ id: string; name: string }>;
+  return makeRequest("DELETE", `/api/v1/agents/${encodeURIComponent(id)}`) as Promise<{
+    id: string;
+    name: string;
+  }>;
 }

package/src/langwatch-api-annotations.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 export interface AnnotationResponse {
   id?: string;
@@ -13,21 +13,20 @@ export interface AnnotationResponse {
 }
 
 export async function listAnnotations(): Promise<AnnotationResponse[]> {
-  return makeRequest("GET", "/api/annotations") as Promise<AnnotationResponse[]>;
+  return makeRequest("GET", "/api/v1/annotations") as Promise<AnnotationResponse[]>;
 }
 
 export async function getAnnotation(id: string): Promise<AnnotationResponse> {
   return makeRequest(
     "GET",
-    `/api/annotations/${encodeURIComponent(id)}`,
+    `/api/v1/annotations/${encodeURIComponent(id)}`,
   ) as Promise<AnnotationResponse>;
 }
 
 export async function getAnnotationsByTrace(traceId: string): Promise<AnnotationResponse[]> {
-  return makeRequest(
-    "GET",
-    `/api/annotations/trace/${encodeURIComponent(traceId)}`,
-  ) as Promise<AnnotationResponse[]>;
+  return makeRequest("GET", `/api/v1/annotations/trace/${encodeURIComponent(traceId)}`) as Promise<
+    AnnotationResponse[]
+  >;
 }
 
 export async function createAnnotation(
@@ -36,14 +35,14 @@ export async function createAnnotation(
 ): Promise<AnnotationResponse> {
   return makeRequest(
     "POST",
-    `/api/annotations/trace/${encodeURIComponent(traceId)}`,
+    `/api/v1/annotations/trace/${encodeURIComponent(traceId)}`,
     data,
   ) as Promise<AnnotationResponse>;
 }
 
 export async function deleteAnnotation(id: string): Promise<{ status?: string; message?: string }> {
-  return makeRequest(
-    "DELETE",
-    `/api/annotations/${encodeURIComponent(id)}`,
-  ) as Promise<{ status?: string; message?: string }>;
+  return makeRequest("DELETE", `/api/v1/annotations/${encodeURIComponent(id)}`) as Promise<{
+    status?: string;
+    message?: string;
+  }>;
 }

package/src/langwatch-api-api-keys.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 export interface RoleBinding {
   id: string;
@@ -28,7 +28,7 @@ export interface ApiKeyCreateResponse {
 }
 
 export async function listApiKeys(): Promise<{ data: ApiKeySummary[] }> {
-  return makeRequest("GET", "/api/api-keys") as Promise<{ data: ApiKeySummary[] }>;
+  return makeRequest("GET", "/api/v1/api-keys") as Promise<{ data: ApiKeySummary[] }>;
 }
 
 export async function createApiKey(data: {
@@ -36,19 +36,18 @@ export async function createApiKey(data: {
   name: string;
   description?: string;
   expiresAt?: string;
-  bindings?: Array<{
+  bindings?: {
     role: "ADMIN" | "MEMBER" | "VIEWER";
     scopeType: "ORGANIZATION" | "TEAM" | "PROJECT";
     scopeId: string;
-  }>;
+  }[];
   projectIds?: string[];
 }): Promise<ApiKeyCreateResponse> {
-  return makeRequest("POST", "/api/api-keys", data) as Promise<ApiKeyCreateResponse>;
+  return makeRequest("POST", "/api/v1/api-keys", data) as Promise<ApiKeyCreateResponse>;
 }
 
 export async function revokeApiKey(id: string): Promise<{ success: boolean }> {
-  return makeRequest(
-    "DELETE",
-    `/api/api-keys/${encodeURIComponent(id)}`,
-  ) as Promise<{ success: boolean }>;
+  return makeRequest("DELETE", `/api/v1/api-keys/${encodeURIComponent(id)}`) as Promise<{
+    success: boolean;
+  }>;
 }

package/src/langwatch-api-boards.ts

@@ -0,0 +1,46 @@
+import { makeRequest } from "./langwatch-api.js";
+
+/**
+ * A board in the Dashboards area, the place a widget is added to
+ * (`modules/dashboard/contract/src/board-rest.schemas.ts`). Analytics Reports boards are
+ * `/api/v1/dashboards`, and hold no widget.
+ */
+export interface Board {
+  id: string;
+  name: string;
+  description: string | null;
+  scope: "PRIVATE" | "PROJECT" | "ORGANIZATION";
+  createdAt: string;
+  updatedAt: string;
+  platformUrl: string;
+}
+
+export interface BoardListItem extends Board {
+  widgetCount: number;
+}
+
+/** The project's Dashboards boards, each with how many widgets it holds. */
+export async function listBoards({
+  projectId,
+}: {
+  projectId: string;
+}): Promise<{ data: BoardListItem[] }> {
+  return makeRequest(
+    "GET",
+    `/api/v1/projects/${encodeURIComponent(projectId)}/analytics/boards`,
+  ) as Promise<{ data: BoardListItem[] }>;
+}
+
+/** Reads one Dashboards board; a board in another project, or only in Reports, answers 404. */
+export async function getBoard({
+  projectId,
+  boardId,
+}: {
+  projectId: string;
+  boardId: string;
+}): Promise<Board> {
+  return makeRequest(
+    "GET",
+    `/api/v1/projects/${encodeURIComponent(projectId)}/analytics/boards/${encodeURIComponent(boardId)}`,
+  ) as Promise<Board>;
+}

package/src/langwatch-api-dashboard-widgets.ts

@@ -0,0 +1,112 @@
+import { makeRequest } from "./langwatch-api.js";
+
+/**
+ * One named LangWatchQL statement a widget may run, as the REST endpoint validates it
+ * (`modules/dashboard/contract/src/dashboard-widget-rest.schemas.ts`).
+ */
+export interface DashboardWidgetQueryInput {
+  name: string;
+  sql: string;
+  parameters?: {
+    name: string;
+    type: "string" | "number" | "boolean";
+    default?: string | number | boolean;
+  }[];
+}
+
+/** Where a widget came from, as the platform records it. */
+export type DashboardWidgetSource =
+  | { kind: "catalogue"; catalogueId: string }
+  | { kind: "langy" }
+  | { kind: "code" }
+  | { kind: "api" };
+
+export interface DashboardWidgetDefinition {
+  version: number;
+  code: string;
+  queries: DashboardWidgetQueryInput[];
+  description?: string;
+  prompt?: string;
+  source?: DashboardWidgetSource;
+}
+
+export interface DashboardWidget {
+  id: string;
+  name: string;
+  definition: DashboardWidgetDefinition;
+  createdAt: string;
+  updatedAt: string;
+  platformUrl: string;
+  dashboardId: string | null;
+  gridColumn: number;
+  gridRow: number;
+  colSpan: number;
+  rowSpan: number;
+}
+
+/** Saves a new widget, unplaced (not yet on any dashboard). */
+export async function createDashboardWidget(params: {
+  projectId: string;
+  name: string;
+  code: string;
+  queries: DashboardWidgetQueryInput[];
+}): Promise<DashboardWidget> {
+  const { projectId, ...data } = params;
+  return makeRequest(
+    "POST",
+    `/api/v1/projects/${encodeURIComponent(projectId)}/analytics/dashboard-widgets`,
+    data,
+  ) as Promise<DashboardWidget>;
+}
+
+/** Reads one widget; a widget in another project answers 404. */
+export async function getDashboardWidget(params: {
+  projectId: string;
+  widgetId: string;
+}): Promise<DashboardWidget> {
+  return makeRequest(
+    "GET",
+    `/api/v1/projects/${encodeURIComponent(params.projectId)}/analytics/dashboard-widgets/${encodeURIComponent(params.widgetId)}`,
+  ) as Promise<DashboardWidget>;
+}
+
+/** Changes the fields given; every field left out keeps its stored value. */
+export async function updateDashboardWidget(params: {
+  projectId: string;
+  widgetId: string;
+  name?: string;
+  code?: string;
+  queries?: DashboardWidgetQueryInput[];
+  description?: string;
+}): Promise<DashboardWidget> {
+  const { projectId, widgetId, ...data } = params;
+  return makeRequest(
+    "PATCH",
+    `/api/v1/projects/${encodeURIComponent(projectId)}/analytics/dashboard-widgets/${encodeURIComponent(widgetId)}`,
+    data,
+  ) as Promise<DashboardWidget>;
+}
+
+/** Places an existing widget on a dashboard, at the next free row. */
+export async function assignDashboardWidgetToDashboard(params: {
+  projectId: string;
+  widgetId: string;
+  dashboardId: string;
+}): Promise<DashboardWidget> {
+  return makeRequest(
+    "POST",
+    `/api/v1/projects/${encodeURIComponent(params.projectId)}/analytics/dashboard-widgets/${encodeURIComponent(params.widgetId)}/dashboard`,
+    { dashboardId: params.dashboardId },
+  ) as Promise<DashboardWidget>;
+}
+
+/** Deletes a widget. Used to undo a create when placing it fails. */
+export async function deleteDashboardWidget(params: {
+  projectId: string;
+  widgetId: string;
+}): Promise<void> {
+  await makeRequest(
+    "DELETE",
+    `/api/v1/projects/${encodeURIComponent(params.projectId)}/analytics/dashboard-widgets/${encodeURIComponent(params.widgetId)}`,
+  );
+}

package/src/langwatch-api-dashboards.ts

@@ -1,4 +1,4 @@
-import { makeRequest } from "./langwatch-api.js";
+import { makeRequest } from "./langwatch-api.ts";
 
 export interface DashboardSummary {
   id: string;
@@ -18,31 +18,34 @@ export interface DashboardListResponse {
 }
 
 export async function listDashboards(): Promise<DashboardListResponse> {
-  return makeRequest("GET", "/api/dashboards") as Promise<DashboardListResponse>;
+  return makeRequest("GET", "/api/v1/dashboards") as Promise<DashboardListResponse>;
 }
 
 export async function getDashboard(id: string): Promise<DashboardDetail> {
   return makeRequest(
     "GET",
-    `/api/dashboards/${encodeURIComponent(id)}`,
+    `/api/v1/dashboards/${encodeURIComponent(id)}`,
   ) as Promise<DashboardDetail>;
 }
 
 export async function createDashboard(data: { name: string }): Promise<DashboardDetail> {
-  return makeRequest("POST", "/api/dashboards", data) as Promise<DashboardDetail>;
+  return makeRequest("POST", "/api/v1/dashboards", data) as Promise<DashboardDetail>;
 }
 
-export async function renameDashboard(id: string, data: { name: string }): Promise<DashboardDetail> {
+export async function renameDashboard(
+  id: string,
+  data: { name: string },
+): Promise<DashboardDetail> {
   return makeRequest(
     "PATCH",
-    `/api/dashboards/${encodeURIComponent(id)}`,
+    `/api/v1/dashboards/${encodeURIComponent(id)}`,
     data,
   ) as Promise<DashboardDetail>;
 }
 
 export async function deleteDashboard(id: string): Promise<{ id: string; name: string }> {
-  return makeRequest(
-    "DELETE",
-    `/api/dashboards/${encodeURIComponent(id)}`,
-  ) as Promise<{ id: string; name: string }>;
+  return makeRequest("DELETE", `/api/v1/dashboards/${encodeURIComponent(id)}`) as Promise<{
+    id: string;
+    name: string;
+  }>;
 }