Concepts

The SDK exposes four primitives. They compose, but each has a clear job.

At a glance

Primitive	What it is	Reach for it when…
Pipeline	A graph of nodes (LLMs, loaders, transforms, knowledge readers). Build → save → run.	You have a fixed flow: input → transforms → output. Includes RAG, batch jobs, scheduled triggers.
Agent	An LLM + tools + typed I/O. Runs autonomously or holds a conversation.	The flow is not fixed — the model decides which tool to call next.
Session	A live, multi-turn handle on an Agent or Chatbot, streaming events back.	You need turn-by-turn streaming, tool events, or human-in-the-loop approvals.
Knowledge Base	A managed vector + document store you query directly or via a Pipeline/Agent.	Documents need to be searchable across many Pipelines or Agents.

How they compose

Pipelines and Agents are top-level objects you save to the platform. Sessions live on top of conversational Agents and Chatbots. Knowledge Bases are referenced from either.

       ┌────────────┐
       │ Pipeline   │──run / stream──▶ outputs
       └──────┬─────┘
              │ reads
              ▼
       ┌────────────┐
       │ Knowledge  │
       │   Base     │
       └──────┬─────┘
              │ reads
              ▼
       ┌────────────┐    create_session    ┌──────────┐
       │  Agent     │─────────────────────▶│ Session  │──events──▶ your code
       └────────────┘                      └──────────┘

Pipeline

Pipeline overview

Build with p.add.input / .llm / .output / …, then save() and run() or stream().

A Pipeline is the right primitive when the steps are known up front. The add builder is fluent and typed — the mypy plugin catches wiring mistakes statically.

from vectorshift import Pipeline, KnowledgeBase

p = Pipeline.new(name="RAG")
query = p.add(name="q").input(input_type="string")
kb    = p.add(name="kb").knowledge_base(query=query.text, knowledge_base=KnowledgeBase.fetch(name="my-docs"), format_context_for_llm=True)
llm   = p.add(name="llm").llm(provider="openai", model="gpt-4o", prompt=f"Context: {kb.formatted_text}\n\nQuestion: {query.text}")
p.add(name="answer").output(value=llm.response)
p.save()

Agent

Agent overview

An LLM with tools, instructions, and typed inputs/outputs.

Agents come in two shapes:

Functional — single call. You pass inputs, the agent decides which tools to call, you get outputs.
Conversational — multi-turn. The agent holds a Session and emits streaming events.

from vectorshift import Agent, LLMInfo

agent = Agent.new(
    name="Researcher",
    llm_info=LLMInfo(provider="openai", model_id="gpt-4o"),
    instructions="You are a helpful research assistant.",
)

Session

Session overview

Multi-turn streaming handle returned by agent.create_session() or chatbot.create_session().

A Session is an async context manager. You send() and listen() for events — message deltas, tool calls, tool results, approval requests, errors.

async with await agent.create_session() as session:
    await session.send("Summarise the Pinecone whitepaper.")
    async for event in session.listen():
        if event.is_complete:
            print(event.text)
            break

Knowledge Base

Knowledge Base reference

Create, query, index documents from Python.

A KnowledgeBase is a managed store of documents (files, URLs, Wikipedia, YouTube, Arxiv) with vector + keyword search. Query it directly, or reference it from a Pipeline node or an Agent tool.

from vectorshift import KnowledgeBase

kb = KnowledgeBase.fetch(name="my-docs")
hits = kb.query(text="What is VectorShift?")

Picking the right primitive

Is the flow fixed?

If yes → Pipeline. If no (the model decides next step) → Agent.

Do you need turn-by-turn streaming?

If yes → put the Agent behind a Session. If no, call agent.run() once.

Are you reading documents?

Use a Knowledge Base. Reference it from a Pipeline node, an Agent tool, or query it directly.

What’s next

Quickstart

Ship a pipeline in 60 seconds.

Pipeline overview

Build your first graph.

Agent overview

Tools, sessions, streaming.

Get started

Guides

Pipeline

Agent

Knowledge Base

Integrations

Table

Transformation

Session

Analytics

Workspace

At a glance

How they compose

Pipeline

Pipeline overview

Agent

Agent overview

Session

Session overview

Knowledge Base

Knowledge Base reference

Picking the right primitive

What’s next

Quickstart

Pipeline overview

Agent overview

​At a glance

​How they compose

​Pipeline

Pipeline overview

​Agent

Agent overview

​Session

Session overview

​Knowledge Base

Knowledge Base reference

​Picking the right primitive

​What’s next

Quickstart

Pipeline overview

Agent overview

At a glance

How they compose

Pipeline

Agent

Session

Knowledge Base

Picking the right primitive

What’s next