Run Pipe langbase.pipes.run()

You can use the langbase.pipes.run() function to run a pipe. It can both generate or stream text for a user prompt like "Who is an AI Engineer?" or give it a an entire doc and ask it to summarize it.


Generate a User/Org API key

You will need to generate an API key to authenticate your requests. For more information, visit the User/Org API key documentation.


API reference

langbase.pipes.run(options)

Request LLM by running a pipe with langbase.pipes.run() function.

Function Signature

langbase.pipes.run(options);

// with types.
langbase.pipes.run(options: RunOptions);

options

  • Name
    options
    Type
    RunOptions
    Description

    RunOptions Object

    interface RunOptions {
    	name: string;
    	apiKey?: string;
    	llmKey?: string;
    	messages: Message[];
    	variables?: Variable[];
    	threadId?: string;
    	rawResponse?: boolean;
    	tools?: Tool[];
    	memory?: Memory[];
    }
    

    Following are the properties of the options object.


name

  • Name
    name
    Type
    string
    Required
    Required
    Description

    The name of the pipe to run. E.g. ai-agent.

    Pipe name and the User/Org API key is used to run the pipe.


apiKey

  • Name
    apiKey
    Type
    string
    Description

    API key of the pipe you want to run.

    If provided, pipe.run() will use this key instead of user/org key to identify and run the pipe.


llmKey

  • Name
    llmKey
    Type
    string
    Description

    LLM API key for the pipe. If not provided, the LLM key from Pipe/User/Organization keyset will be used.

    Explore the example to learn more.


messages

  • Name
    messages
    Type
    Array<Message>
    Description

    A messages array including the following properties. Optional if variables are provided.

    Message Object

    interface Message {
    	role: 'user' | 'assistant' | 'system'| 'tool';
    	content: string | null;
    	name?: string;
    	tool_call_id?: string;
    	tool_calls?: ToolCall[];
    }
    

    • Name
      role
      Type
      'user' | 'assistant' | 'system'| 'tool'
      Description

      The role of the author of this message.

    • Name
      content
      Type
      string
      Description

      The contents of the chunk message.

    • Name
      name
      Type
      string
      Description

      The name of the tool called by LLM

    • Name
      tool_call_id
      Type
      string
      Description

      The id of the tool called by LLM

    • Name
      tool_calls
      Type
      Array<ToolCall>
      Description

      The array of tools sent to LLM.

      ToolCall Object

      interface ToolCall {
      	id: string;
      	type: 'function';
      	function: Function;
      }
      
    • Name
      function
      Type
      Function
      Description

      Function definition sent to LLM.

      Function Object

      export interface Function {
      	name: string;
      	arguments: string;
      }
      

variables

  • Name
    variables
    Type
    Array<Variable>
    Description

    A variables array including the name and value params. Optional if messages are provided.

    Variable Object

    interface Variable {
    	name: string;
    	value: string;
    }
    
    • Name
      name
      Type
      string
      Description

      The name of the variable.

    • Name
      value
      Type
      string
      Description

      The value of the variable.


threadId

  • Name
    threadId
    Type
    string | undefined | null
    Description

    The ID of the thread. Enable if you want to continue the conversation in the same thread from the second message onwards. Works only with deployed pipes.

    • If threadId is not provided, a new thread will be created. E.g. first message of a new chat will not have a threadId.
    • After the first message, a new threadId will be returned.
    • Use this threadId to continue the conversation in the same thread from the second message onwards.

rawResponse

  • Name
    rawResponse
    Type
    boolean | undefined
    Description

    Enable if you want to get complete raw LLM response.

    Default: false


tools

  • Name
    tools
    Type
    Array<Tools>
    Description

    A list of tools the model may call.

    Tools Object

    interface ToolsOptions {
    	type: 'function';
    	function: FunctionOptions
    }
    
    • Name
      type
      Type
      'function'
      Description

      The type of the tool. Currently, only function is supported.

    • Name
      function
      Type
      FunctionOptions
      Description

      The function that the model may call.

      FunctionOptions Object

      export interface FunctionOptions {
      	name: string;
      	description?: string;
      	parameters?: Record<string, unknown>
      }
      
    • Name
      name
      Type
      string
      Description

      The name of the function to call.

    • Name
      description
      Type
      string
      Description

      The description of the function.

    • Name
      parameters
      Type
      Record<string, unknown>
      Description

      The parameters of the function.


memory

  • Name
    memory
    Type
    Array<Memory>
    Description

    An array of memory objects that specify the memories your pipe should use at run time.

    If memories are defined here, they will override the default pipe memories, which will be ignored. All referenced memories must exist in your account.

    Run time Memory array example

    "memory": [
      { "name": "runtime-memory-1" },
      { "name": "runtime-memory-2" }
    ]
    

    If this property is not set or is empty, the pipe will fall back to using its default memories.

    Default: undefined

    Each memory in the array follows this structure:

    Memory Object

    interface Memory {
        name: string;
    }
    
    • Name
      name
      Type
      string
      Description

      The name of the memory.


options

    RunOptionsStream

  • Name
    options
    Type
    RunOptions
    Description

    RunOptions Object

    interface RunOptionsStream extends RunOptions {
    	stream: boolean;
    }
    

Usage example

Install the SDK

npm i langbase

Environment variables

.env file

LANGBASE_API_KEY="<USER/ORG-API-KEY>"

langbase.pipes.run() examples

langbase.pipes.run()

import {Langbase} from 'langbase';

const langbase = new Langbase({
	apiKey: process.env.LANGBASE_API_KEY!,
});

async function main() {
	const {completion} = await langbase.pipes.run({
		name: 'summary-agent',
		messages: [
			{
				role: 'user',
				content: 'Who is an AI Engineer?',
			},
		],
		stream: false
	});

	console.log('Summary agent completion:', completion);
}

main();

Response

Response of langbase.pipes.run() is a Promise<RunResponse | RunResponseStream> object.

RunResponse Object

RunResponse Object

interface RunResponse {
	completion: string;
	threadId?: string;
	id: string;
	object: string;
	created: number;
	model: string;
	choices: ChoiceGenerate[];
	usage: Usage;
	system_fingerprint: string | null;
	rawResponse?: {
		headers: Record<string, string>;
	};
}
  • Name
    completion
    Type
    string
    Description

    The generated text completion.

  • Name
    threadId
    Type
    string
    Description

    The ID of the thread. Useful for a chat pipe to continue the conversation in the same thread. Optional.

  • Name
    id
    Type
    string
    Description

    The ID of the raw response.

  • Name
    object
    Type
    string
    Description

    The object type name of the response.

  • Name
    created
    Type
    number
    Description

    The timestamp of the response creation.

  • Name
    model
    Type
    string
    Description

    The model used to generate the response.

  • Name
    choices
    Type
    ChoiceGenerate[]
    Description

    A list of chat completion choices. Can contain more than one elements if n is greater than 1.

    Choice Object for langbase.pipes.run() with stream off

    interface ChoiceGenerate {
    	index: number;
    	message: Message;
    	logprobs: boolean | null;
    	finish_reason: string;
    }
    
  • Name
    usage
    Type
    Usage
    Description

    The usage object including the following properties.

    Usage Object

    interface Usage {
    	prompt_tokens: number;
    	completion_tokens: number;
    	total_tokens: number;
    }
    

  • Name
    system_fingerprint
    Type
    string
    Description

    This fingerprint represents the backend configuration that the model runs with.

  • Name
    rawResponse
    Type
    Object
    Description

    The different headers of the response.


RunResponseStream Object

Response of langbase.pipes.run() with stream: true is a Promise<RunResponseStream>.

RunResponseStream Object

interface RunResponseStream {
	stream: ReadableStream<any>;
	threadId: string | null;
	rawResponse?: {
		headers: Record<string, string>;
	};
}
  • Name
    threadId
    Type
    string
    Description

    The ID of the thread. Useful for a chat pipe to continue the conversation in the same thread. Optional.

  • Name
    rawResponse
    Type
    Object
    Description

    The different headers of the response.

  • Name
    stream
    Type
    ReadableStream
    Description

    Stream is an object with a streamed sequence of StreamChunk objects.

    StreamResponse Object

    type StreamResponse = ReadableStream<StreamChunk>;
    

    StreamChunk

  • Name
    StreamChunk
    Type
    StreamChunk
    Description

    Represents a streamed chunk of a completion response returned by model, based on the provided input.

    StreamChunk Object

    interface StreamChunk {
    	id: string;
    	object: string;
    	created: number;
    	model: string;
    	choices: ChoiceStream[];
    }
    

    A StreamChunk object has the following properties.

    • Name
      id
      Type
      string
      Description

      The ID of the response.

    • Name
      object
      Type
      string
      Description

      The object type name of the response.

    • Name
      created
      Type
      number
      Description

      The timestamp of the response creation.

    • Name
      model
      Type
      string
      Description

      The model used to generate the response.

    • Name
      choices
      Type
      ChoiceStream[]
      Description

      A list of chat completion choices. Can contain more than one elements if n is greater than 1.

      Choice Object for langbase.pipes.run() with stream true

      interface ChoiceStream {
      	index: number;
      	delta: Delta;
      	logprobs: boolean | null;
      	finish_reason: string;
      }
      

RunResponse type of langbase.pipes.run()

{
	"completion": "AI Engineer is a person who designs, builds, and maintains AI systems.",
	"threadId": "thread_123",
	"id": "chatcmpl-123",
	"object": "chat.completion",
	"created": 1720131129,
	"model": "gpt-4o-mini",
	"choices": [
		{
			"index": 0,
			"message": {
				"role": "assistant",
				"content": "AI Engineer is a person who designs, builds, and maintains AI systems."
			},
			"logprobs": null,
			"finish_reason": "stop"
		}
	],
	"usage": {
		"prompt_tokens": 28,
		"completion_tokens": 36,
		"total_tokens": 64
	},
	"system_fingerprint": "fp_123"
}

RunResponseStream of langbase.pipes.run() with stream true

{
	"threadId": "string-uuid-123",
	"stream": StreamResponse // example of streamed chunks below.
}

StreamResponse has stream chunks

// A stream chunk looks like this …
{
	"id": "chatcmpl-123",
	"object": "chat.completion.chunk",
	"created": 1719848588,
	"model": "gpt-4o-mini",
	"system_fingerprint": "fp_44709d6fcb",
	"choices": [{
		"index": 0,
		"delta": { "content": "Hi" },
		"logprobs": null,
		"finish_reason": null
	}]
}

// More chunks as they come in...
{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1719848588,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{"content":"there"},"logprobs":null,"finish_reason":null}]}

{"id":"chatcmpl-123","object":"chat.completion.chunk","created":1719848588,"model":"gpt-4o-mini","system_fingerprint":"fp_44709d6fcb","choices":[{"index":0,"delta":{},"logprobs":null,"finish_reason":"stop"}]}