langwatch 1.10.0 → 1.11.0

package/dist/agent/index.d.mts

@@ -0,0 +1,301 @@
+interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+
+/**
+ * The frames the SDK and the platform exchange over the agent socket.
+ *
+ * Every frame is one JSON text message with a `type` and the protocol
+ * version. The shapes here match the contract table in ADR-128 and the
+ * platform's own frame module; the validators are small and hand-written
+ * because this file is part of the public `langwatch/agent` surface, where no
+ * schema library may cross as a value.
+ *
+ * @see dev/docs/adr/128-connected-agents.md
+ */
+declare const PROTOCOL_VERSION = 1;
+/** One conversation message, OpenAI style. Extra keys are carried as is. */
+interface AgentMessage {
+    role: string;
+    content?: unknown;
+    [key: string]: unknown;
+}
+/** The value of one run parameter as the platform sends it. */
+type AgentParameterValue = string | number | boolean;
+/** A JSON Schema object as the SDK sends it in `register`. */
+type JsonSchemaObject = Record<string, unknown>;
+
+/**
+ * The connection the client speaks over, behind one small interface so the
+ * client never depends on how the frames travel.
+ *
+ * Two transports carry the same frames. The WebSocket is the default and it
+ * needs the `ws` package: the platform authenticates from the request
+ * headers of the upgrade, and no global `WebSocket` constructor can send
+ * them. HTTP long polling is for a network that blocks WebSockets: one POST
+ * registers, a GET waits for the next frames, a POST carries the answers. It
+ * speaks through the global `fetch` (Node 20+).
+ */
+declare const AGENT_TRANSPORTS: readonly ["websocket", "http"];
+type AgentTransport = (typeof AGENT_TRANSPORTS)[number];
+/**
+ * The transport to start with: the explicit option, then
+ * `LANGWATCH_AGENT_TRANSPORT`, else the WebSocket. Anything that is not
+ * `http` is the WebSocket, which falls back to HTTP on its own when the
+ * upgrade is refused.
+ */
+declare function resolveTransport({ explicit, env, }: {
+    explicit?: string;
+    env?: NodeJS.ProcessEnv;
+}): AgentTransport;
+
+/**
+ * The run parameters an agent declares, and the values a call supplies.
+ *
+ * Three forms are accepted: a definition map, any Standard JSON Schema object
+ * (read through `"~standard".jsonSchema`, so zod 4, valibot and arktype work
+ * without this package importing them), or a plain JSON Schema. A schema
+ * library instance that offers no JSON Schema converter is refused with the
+ * three forms named, because the SDK never takes a zod instance as a value.
+ */
+
+/** The scalar types a run parameter may hold. */
+type ParameterType = "string" | "number" | "boolean";
+/** One entry of the definition map. */
+interface ParameterDefinition {
+    /** The value type. Read from `options`, then `default`, else string. */
+    type?: ParameterType;
+    /** A closed list of accepted values. */
+    options?: readonly string[];
+    /** The value a run takes when it does not supply one. Without it the parameter is required. */
+    default?: AgentParameterValue;
+    description?: string;
+}
+/** Parameters declared by name. */
+type ParameterDefinitions = Record<string, ParameterDefinition>;
+/**
+ * The Standard JSON Schema converter an object exposes under `"~standard"`.
+ * Method syntax on purpose: a library narrows `target` to its own union, and
+ * a method parameter is checked bivariantly, so zod 4, valibot and arktype
+ * all fit without the SDK naming any of them.
+ */
+interface StandardJsonSchemaConverter {
+    input?(options: {
+        readonly target: string;
+    }): Record<string, unknown>;
+    output?(options: {
+        readonly target: string;
+    }): Record<string, unknown>;
+}
+/** One problem a Standard Schema `validate` reports. */
+interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+type StandardSchemaResult<O> = {
+    readonly value: O;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+};
+/**
+ * Any object that implements the Standard JSON Schema interface. When it also
+ * implements Standard Schema (`validate`), the values of every call go
+ * through it before the handler runs, so a zod 4 schema validates, fills its
+ * defaults and types `params` in one place.
+ */
+interface StandardJsonSchema<O = unknown> {
+    readonly "~standard": {
+        readonly jsonSchema: StandardJsonSchemaConverter;
+        validate?(value: unknown): StandardSchemaResult<O> | Promise<StandardSchemaResult<O>>;
+        /** Type-only, from Standard Schema: the parsed output type. */
+        readonly types?: {
+            readonly input: unknown;
+            readonly output: O;
+        } | undefined;
+    };
+}
+/** The `params` type a Standard Schema object gives the handler: its parsed output. */
+type InferStandardOutput<S> = S extends {
+    readonly "~standard": {
+        readonly types?: infer T;
+    };
+} ? [NonNullable<T>] extends [never] ? Record<string, AgentParameterValue> : NonNullable<T> extends {
+    readonly output: infer O;
+} ? O extends Record<string, unknown> ? O : Record<string, AgentParameterValue> : Record<string, AgentParameterValue> : Record<string, AgentParameterValue>;
+/** Every form `parameters` accepts. */
+type ParameterInput = ParameterDefinitions | StandardJsonSchema | JsonSchemaObject;
+/** One parameter as the platform lists it, derived from the schema. */
+interface ParameterSpec {
+    name: string;
+    type: ParameterType;
+    options?: string[];
+    default?: AgentParameterValue;
+    description?: string;
+    required?: boolean;
+}
+/** The refusal of a parameter definition or of a value a call supplied. */
+declare class AgentParameterError extends Error {
+    readonly code = "agent_parameter_invalid";
+    constructor(message: string);
+}
+/**
+ * The parameter schema the `register` frame carries, from any accepted form.
+ * No parameters is an object schema with no properties.
+ */
+declare function toParameterSchema(input: ParameterInput | undefined): JsonSchemaObject;
+/**
+ * The parameters a schema declares, one spec per property, the way the
+ * platform lists them. Unsupported property types read as text.
+ */
+declare function parameterSpecsFromSchema(schema: JsonSchemaObject): ParameterSpec[];
+
+/**
+ * `connectAgent`: the function that runs an agent becomes a simulation target.
+ *
+ * The wrapper resolves the environment and the parameter schema at definition,
+ * registers the agent with the process-wide client, and returns a function
+ * that is directly callable (for unit tests and local runs) and exposes
+ * `disconnect()`.
+ *
+ * @see specs/typescript-sdk/agent-wrapper.feature
+ */
+
+/** The default call timeout, and the cap the platform enforces. */
+declare const DEFAULT_TIMEOUT_MS = 120000;
+declare const MAX_TIMEOUT_MS = 300000;
+/** What a handler may return: a string, one message, a list of messages, or an output with a session. */
+type AgentOutput = string | AgentMessage | AgentMessage[];
+/** The output of one turn plus the session the agent keeps for the next turn of the same thread. */
+interface AgentResult {
+    output: AgentOutput;
+    session?: unknown;
+}
+type AgentReply = AgentOutput | AgentResult;
+/** The one object a handler receives on every turn. */
+interface AgentCall<P = Record<string, AgentParameterValue>> {
+    /** The full conversation, OpenAI style. */
+    messages: AgentMessage[];
+    /** The messages added since the last turn of this thread. */
+    newMessages: AgentMessage[];
+    /** The platform's conversation id. */
+    threadId: string;
+    /** The value the handler returned as `session` on the previous turn of this thread, null on the first. */
+    session: unknown;
+    /** The run parameters, validated and with defaults filled. */
+    params: P;
+    /** The trace id of the turn, so the agent's own spans join it. Empty when the call carries none. */
+    traceId: string;
+}
+type AgentHandler<P> = (call: AgentCall<P>) => AgentReply | Promise<AgentReply>;
+/** What a direct call of the wrapped function takes: messages, and anything else is optional. */
+interface DirectAgentCall<P> {
+    messages: AgentMessage[];
+    newMessages?: AgentMessage[];
+    threadId?: string;
+    session?: unknown;
+    params?: Partial<P>;
+    traceId?: string;
+}
+interface ConnectAgentOptions<P extends ParameterInput = ParameterDefinitions> {
+    /** The agent name. One row per name and environment on the platform. */
+    name: string;
+    /** Resolved from LANGWATCH_AGENT_ENVIRONMENT, APP_ENV, ENVIRONMENT, NODE_ENV, else development. */
+    environment?: string;
+    /** A definition map, a Standard JSON Schema object, or a JSON Schema object. */
+    parameters?: P;
+    /** Default true, except when CI is truthy. LANGWATCH_AGENT_CONNECT=0 always disables. */
+    enabled?: boolean;
+    /** Names this instance in the platform. Also LANGWATCH_AGENT_INSTANCE_LABEL. */
+    instanceLabel?: string;
+    /** Per call, default 120000, at most 300000. */
+    timeoutMs?: number;
+    /** Calls in flight per instance, default 1 in development and 4 elsewhere. */
+    concurrency?: number;
+    /** Keep every turn of a thread on the instance that answered the first one. */
+    sticky?: boolean;
+    apiKey?: string;
+    endpoint?: string;
+    projectId?: string;
+    /** `websocket` (default, falls back to HTTP when the upgrade is refused) or `http`. Also LANGWATCH_AGENT_TRANSPORT. */
+    transport?: AgentTransport;
+    logger?: Logger;
+}
+/** The wrapped function: callable, and connected until `disconnect()`. */
+interface ConnectedAgent<P> {
+    (call: DirectAgentCall<P>): Promise<AgentResult>;
+    readonly name: string;
+    readonly environment: string;
+    /** The parameter schema as registered. */
+    readonly parameters: JsonSchemaObject;
+    /** Send deregister and close the socket when this was the last agent of the process. */
+    disconnect: () => Promise<void>;
+}
+type Widen<V> = V extends string ? string : V extends number ? number : V extends boolean ? boolean : V;
+type ParameterValueOf<D extends ParameterDefinition> = D extends {
+    options: readonly (infer O extends string)[];
+} ? O : D extends {
+    type: "number";
+} ? number : D extends {
+    type: "boolean";
+} ? boolean : D extends {
+    type: "string";
+} ? string : D extends {
+    default: infer V;
+} ? Widen<V> : string;
+/** The `params` type a definition map gives the handler. */
+type InferParameters<P extends ParameterDefinitions> = {
+    [K in keyof P]: ParameterValueOf<P[K]>;
+};
+/** One of the four reply shapes as the `{ output, session }` the result frame carries. */
+declare function normalizeReply(reply: unknown): AgentResult;
+/**
+ * A schema library object (zod 4, valibot, arktype: anything with Standard
+ * Schema and Standard JSON Schema) types `params` as its parsed output and
+ * validates every call's values before the handler runs.
+ */
+declare function connectAgent<const S extends StandardJsonSchema>(options: ConnectAgentOptions<S> & {
+    parameters: S;
+}, handler: AgentHandler<InferStandardOutput<S>>): ConnectedAgent<InferStandardOutput<S>>;
+declare function connectAgent<const P extends ParameterDefinitions = Record<string, never>>(options: ConnectAgentOptions<P>, handler: AgentHandler<InferParameters<P>>): ConnectedAgent<InferParameters<P>>;
+declare function connectAgent(options: ConnectAgentOptions<JsonSchemaObject>, handler: AgentHandler<Record<string, AgentParameterValue>>): ConnectedAgent<Record<string, AgentParameterValue>>;
+
+/**
+ * Who and where a connected agent is: its environment, its instance identity
+ * and the endpoint it connects to. Every read of the machine is defensive, so
+ * a locked-down sandbox with no hostname or no passwd entry still connects.
+ */
+
+/**
+ * An environment name as the platform stores it: lowercase, `[a-z0-9_-]`
+ * only, at most 32 characters. Anything else collapses to a dash, and an
+ * empty result is the default environment.
+ */
+declare function sanitizeEnvironment(name: string): string;
+/**
+ * The environment an agent registers under: the explicit option, then
+ * `LANGWATCH_AGENT_ENVIRONMENT`, `APP_ENV`, `ENVIRONMENT`, `NODE_ENV`, else
+ * `development`.
+ */
+declare function resolveEnvironment({ explicit, env, }: {
+    explicit?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/**
+ * The socket URL for an endpoint: `https://app.langwatch.ai` becomes
+ * `wss://app.langwatch.ai/api/v1/agents/connect`, `http://localhost:5560`
+ * becomes `ws://localhost:5560/api/v1/agents/connect`.
+ */
+declare function resolveConnectUrl(endpoint?: string | null): string;
+/**
+ * The base of the HTTP long-poll routes for an endpoint:
+ * `https://app.langwatch.ai` becomes `https://app.langwatch.ai/api/v1/agents/connect`.
+ */
+declare function resolveHttpConnectUrl(endpoint?: string | null): string;
+
+export { AGENT_TRANSPORTS, type AgentCall, type AgentHandler, type AgentMessage, type AgentOutput, AgentParameterError, type AgentParameterValue, type AgentReply, type AgentResult, type AgentTransport, type ConnectAgentOptions, type ConnectedAgent, DEFAULT_TIMEOUT_MS, type DirectAgentCall, type InferParameters, type JsonSchemaObject, MAX_TIMEOUT_MS, PROTOCOL_VERSION, type ParameterDefinition, type ParameterDefinitions, type ParameterInput, type ParameterSpec, type ParameterType, type StandardJsonSchema, connectAgent, normalizeReply, parameterSpecsFromSchema, resolveConnectUrl, resolveEnvironment, resolveHttpConnectUrl, resolveTransport, sanitizeEnvironment, toParameterSchema };

package/dist/agent/index.d.ts

@@ -0,0 +1,301 @@
+interface Logger {
+    debug: (message: string, ...args: unknown[]) => void;
+    info: (message: string, ...args: unknown[]) => void;
+    warn: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+
+/**
+ * The frames the SDK and the platform exchange over the agent socket.
+ *
+ * Every frame is one JSON text message with a `type` and the protocol
+ * version. The shapes here match the contract table in ADR-128 and the
+ * platform's own frame module; the validators are small and hand-written
+ * because this file is part of the public `langwatch/agent` surface, where no
+ * schema library may cross as a value.
+ *
+ * @see dev/docs/adr/128-connected-agents.md
+ */
+declare const PROTOCOL_VERSION = 1;
+/** One conversation message, OpenAI style. Extra keys are carried as is. */
+interface AgentMessage {
+    role: string;
+    content?: unknown;
+    [key: string]: unknown;
+}
+/** The value of one run parameter as the platform sends it. */
+type AgentParameterValue = string | number | boolean;
+/** A JSON Schema object as the SDK sends it in `register`. */
+type JsonSchemaObject = Record<string, unknown>;
+
+/**
+ * The connection the client speaks over, behind one small interface so the
+ * client never depends on how the frames travel.
+ *
+ * Two transports carry the same frames. The WebSocket is the default and it
+ * needs the `ws` package: the platform authenticates from the request
+ * headers of the upgrade, and no global `WebSocket` constructor can send
+ * them. HTTP long polling is for a network that blocks WebSockets: one POST
+ * registers, a GET waits for the next frames, a POST carries the answers. It
+ * speaks through the global `fetch` (Node 20+).
+ */
+declare const AGENT_TRANSPORTS: readonly ["websocket", "http"];
+type AgentTransport = (typeof AGENT_TRANSPORTS)[number];
+/**
+ * The transport to start with: the explicit option, then
+ * `LANGWATCH_AGENT_TRANSPORT`, else the WebSocket. Anything that is not
+ * `http` is the WebSocket, which falls back to HTTP on its own when the
+ * upgrade is refused.
+ */
+declare function resolveTransport({ explicit, env, }: {
+    explicit?: string;
+    env?: NodeJS.ProcessEnv;
+}): AgentTransport;
+
+/**
+ * The run parameters an agent declares, and the values a call supplies.
+ *
+ * Three forms are accepted: a definition map, any Standard JSON Schema object
+ * (read through `"~standard".jsonSchema`, so zod 4, valibot and arktype work
+ * without this package importing them), or a plain JSON Schema. A schema
+ * library instance that offers no JSON Schema converter is refused with the
+ * three forms named, because the SDK never takes a zod instance as a value.
+ */
+
+/** The scalar types a run parameter may hold. */
+type ParameterType = "string" | "number" | "boolean";
+/** One entry of the definition map. */
+interface ParameterDefinition {
+    /** The value type. Read from `options`, then `default`, else string. */
+    type?: ParameterType;
+    /** A closed list of accepted values. */
+    options?: readonly string[];
+    /** The value a run takes when it does not supply one. Without it the parameter is required. */
+    default?: AgentParameterValue;
+    description?: string;
+}
+/** Parameters declared by name. */
+type ParameterDefinitions = Record<string, ParameterDefinition>;
+/**
+ * The Standard JSON Schema converter an object exposes under `"~standard"`.
+ * Method syntax on purpose: a library narrows `target` to its own union, and
+ * a method parameter is checked bivariantly, so zod 4, valibot and arktype
+ * all fit without the SDK naming any of them.
+ */
+interface StandardJsonSchemaConverter {
+    input?(options: {
+        readonly target: string;
+    }): Record<string, unknown>;
+    output?(options: {
+        readonly target: string;
+    }): Record<string, unknown>;
+}
+/** One problem a Standard Schema `validate` reports. */
+interface StandardSchemaIssue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+}
+type StandardSchemaResult<O> = {
+    readonly value: O;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+};
+/**
+ * Any object that implements the Standard JSON Schema interface. When it also
+ * implements Standard Schema (`validate`), the values of every call go
+ * through it before the handler runs, so a zod 4 schema validates, fills its
+ * defaults and types `params` in one place.
+ */
+interface StandardJsonSchema<O = unknown> {
+    readonly "~standard": {
+        readonly jsonSchema: StandardJsonSchemaConverter;
+        validate?(value: unknown): StandardSchemaResult<O> | Promise<StandardSchemaResult<O>>;
+        /** Type-only, from Standard Schema: the parsed output type. */
+        readonly types?: {
+            readonly input: unknown;
+            readonly output: O;
+        } | undefined;
+    };
+}
+/** The `params` type a Standard Schema object gives the handler: its parsed output. */
+type InferStandardOutput<S> = S extends {
+    readonly "~standard": {
+        readonly types?: infer T;
+    };
+} ? [NonNullable<T>] extends [never] ? Record<string, AgentParameterValue> : NonNullable<T> extends {
+    readonly output: infer O;
+} ? O extends Record<string, unknown> ? O : Record<string, AgentParameterValue> : Record<string, AgentParameterValue> : Record<string, AgentParameterValue>;
+/** Every form `parameters` accepts. */
+type ParameterInput = ParameterDefinitions | StandardJsonSchema | JsonSchemaObject;
+/** One parameter as the platform lists it, derived from the schema. */
+interface ParameterSpec {
+    name: string;
+    type: ParameterType;
+    options?: string[];
+    default?: AgentParameterValue;
+    description?: string;
+    required?: boolean;
+}
+/** The refusal of a parameter definition or of a value a call supplied. */
+declare class AgentParameterError extends Error {
+    readonly code = "agent_parameter_invalid";
+    constructor(message: string);
+}
+/**
+ * The parameter schema the `register` frame carries, from any accepted form.
+ * No parameters is an object schema with no properties.
+ */
+declare function toParameterSchema(input: ParameterInput | undefined): JsonSchemaObject;
+/**
+ * The parameters a schema declares, one spec per property, the way the
+ * platform lists them. Unsupported property types read as text.
+ */
+declare function parameterSpecsFromSchema(schema: JsonSchemaObject): ParameterSpec[];
+
+/**
+ * `connectAgent`: the function that runs an agent becomes a simulation target.
+ *
+ * The wrapper resolves the environment and the parameter schema at definition,
+ * registers the agent with the process-wide client, and returns a function
+ * that is directly callable (for unit tests and local runs) and exposes
+ * `disconnect()`.
+ *
+ * @see specs/typescript-sdk/agent-wrapper.feature
+ */
+
+/** The default call timeout, and the cap the platform enforces. */
+declare const DEFAULT_TIMEOUT_MS = 120000;
+declare const MAX_TIMEOUT_MS = 300000;
+/** What a handler may return: a string, one message, a list of messages, or an output with a session. */
+type AgentOutput = string | AgentMessage | AgentMessage[];
+/** The output of one turn plus the session the agent keeps for the next turn of the same thread. */
+interface AgentResult {
+    output: AgentOutput;
+    session?: unknown;
+}
+type AgentReply = AgentOutput | AgentResult;
+/** The one object a handler receives on every turn. */
+interface AgentCall<P = Record<string, AgentParameterValue>> {
+    /** The full conversation, OpenAI style. */
+    messages: AgentMessage[];
+    /** The messages added since the last turn of this thread. */
+    newMessages: AgentMessage[];
+    /** The platform's conversation id. */
+    threadId: string;
+    /** The value the handler returned as `session` on the previous turn of this thread, null on the first. */
+    session: unknown;
+    /** The run parameters, validated and with defaults filled. */
+    params: P;
+    /** The trace id of the turn, so the agent's own spans join it. Empty when the call carries none. */
+    traceId: string;
+}
+type AgentHandler<P> = (call: AgentCall<P>) => AgentReply | Promise<AgentReply>;
+/** What a direct call of the wrapped function takes: messages, and anything else is optional. */
+interface DirectAgentCall<P> {
+    messages: AgentMessage[];
+    newMessages?: AgentMessage[];
+    threadId?: string;
+    session?: unknown;
+    params?: Partial<P>;
+    traceId?: string;
+}
+interface ConnectAgentOptions<P extends ParameterInput = ParameterDefinitions> {
+    /** The agent name. One row per name and environment on the platform. */
+    name: string;
+    /** Resolved from LANGWATCH_AGENT_ENVIRONMENT, APP_ENV, ENVIRONMENT, NODE_ENV, else development. */
+    environment?: string;
+    /** A definition map, a Standard JSON Schema object, or a JSON Schema object. */
+    parameters?: P;
+    /** Default true, except when CI is truthy. LANGWATCH_AGENT_CONNECT=0 always disables. */
+    enabled?: boolean;
+    /** Names this instance in the platform. Also LANGWATCH_AGENT_INSTANCE_LABEL. */
+    instanceLabel?: string;
+    /** Per call, default 120000, at most 300000. */
+    timeoutMs?: number;
+    /** Calls in flight per instance, default 1 in development and 4 elsewhere. */
+    concurrency?: number;
+    /** Keep every turn of a thread on the instance that answered the first one. */
+    sticky?: boolean;
+    apiKey?: string;
+    endpoint?: string;
+    projectId?: string;
+    /** `websocket` (default, falls back to HTTP when the upgrade is refused) or `http`. Also LANGWATCH_AGENT_TRANSPORT. */
+    transport?: AgentTransport;
+    logger?: Logger;
+}
+/** The wrapped function: callable, and connected until `disconnect()`. */
+interface ConnectedAgent<P> {
+    (call: DirectAgentCall<P>): Promise<AgentResult>;
+    readonly name: string;
+    readonly environment: string;
+    /** The parameter schema as registered. */
+    readonly parameters: JsonSchemaObject;
+    /** Send deregister and close the socket when this was the last agent of the process. */
+    disconnect: () => Promise<void>;
+}
+type Widen<V> = V extends string ? string : V extends number ? number : V extends boolean ? boolean : V;
+type ParameterValueOf<D extends ParameterDefinition> = D extends {
+    options: readonly (infer O extends string)[];
+} ? O : D extends {
+    type: "number";
+} ? number : D extends {
+    type: "boolean";
+} ? boolean : D extends {
+    type: "string";
+} ? string : D extends {
+    default: infer V;
+} ? Widen<V> : string;
+/** The `params` type a definition map gives the handler. */
+type InferParameters<P extends ParameterDefinitions> = {
+    [K in keyof P]: ParameterValueOf<P[K]>;
+};
+/** One of the four reply shapes as the `{ output, session }` the result frame carries. */
+declare function normalizeReply(reply: unknown): AgentResult;
+/**
+ * A schema library object (zod 4, valibot, arktype: anything with Standard
+ * Schema and Standard JSON Schema) types `params` as its parsed output and
+ * validates every call's values before the handler runs.
+ */
+declare function connectAgent<const S extends StandardJsonSchema>(options: ConnectAgentOptions<S> & {
+    parameters: S;
+}, handler: AgentHandler<InferStandardOutput<S>>): ConnectedAgent<InferStandardOutput<S>>;
+declare function connectAgent<const P extends ParameterDefinitions = Record<string, never>>(options: ConnectAgentOptions<P>, handler: AgentHandler<InferParameters<P>>): ConnectedAgent<InferParameters<P>>;
+declare function connectAgent(options: ConnectAgentOptions<JsonSchemaObject>, handler: AgentHandler<Record<string, AgentParameterValue>>): ConnectedAgent<Record<string, AgentParameterValue>>;
+
+/**
+ * Who and where a connected agent is: its environment, its instance identity
+ * and the endpoint it connects to. Every read of the machine is defensive, so
+ * a locked-down sandbox with no hostname or no passwd entry still connects.
+ */
+
+/**
+ * An environment name as the platform stores it: lowercase, `[a-z0-9_-]`
+ * only, at most 32 characters. Anything else collapses to a dash, and an
+ * empty result is the default environment.
+ */
+declare function sanitizeEnvironment(name: string): string;
+/**
+ * The environment an agent registers under: the explicit option, then
+ * `LANGWATCH_AGENT_ENVIRONMENT`, `APP_ENV`, `ENVIRONMENT`, `NODE_ENV`, else
+ * `development`.
+ */
+declare function resolveEnvironment({ explicit, env, }: {
+    explicit?: string;
+    env?: NodeJS.ProcessEnv;
+}): string;
+/**
+ * The socket URL for an endpoint: `https://app.langwatch.ai` becomes
+ * `wss://app.langwatch.ai/api/v1/agents/connect`, `http://localhost:5560`
+ * becomes `ws://localhost:5560/api/v1/agents/connect`.
+ */
+declare function resolveConnectUrl(endpoint?: string | null): string;
+/**
+ * The base of the HTTP long-poll routes for an endpoint:
+ * `https://app.langwatch.ai` becomes `https://app.langwatch.ai/api/v1/agents/connect`.
+ */
+declare function resolveHttpConnectUrl(endpoint?: string | null): string;
+
+export { AGENT_TRANSPORTS, type AgentCall, type AgentHandler, type AgentMessage, type AgentOutput, AgentParameterError, type AgentParameterValue, type AgentReply, type AgentResult, type AgentTransport, type ConnectAgentOptions, type ConnectedAgent, DEFAULT_TIMEOUT_MS, type DirectAgentCall, type InferParameters, type JsonSchemaObject, MAX_TIMEOUT_MS, PROTOCOL_VERSION, type ParameterDefinition, type ParameterDefinitions, type ParameterInput, type ParameterSpec, type ParameterType, type StandardJsonSchema, connectAgent, normalizeReply, parameterSpecsFromSchema, resolveConnectUrl, resolveEnvironment, resolveHttpConnectUrl, resolveTransport, sanitizeEnvironment, toParameterSchema };