Agents & Pipelines — Overview

Where a Topic answers questions from documents, an Agent does things: it works on a task, calls tools, takes different paths depending on results, and goes through several steps to reach an outcome.

Three ideas, and the difference matters:

Module Pipeline Agent

What it is

One building block, for example "AI model", "read a file", "call a web service"

A workflow: modules and the lines between them, drawn on a canvas

A server that runs pipelines

Where it lives

Inside a pipeline

Stored in this application’s database

A container this application starts

Analogy

One instruction

The program

The machine running it

Count

Many per pipeline

Many pipelines

One Agent can run several pipelines

You design a Pipeline in the visual editor (the Pipeline Designer), assign it to an Agent, and start the Agent. The Agent then offers the pipeline for chat, for timed runs (Scheduler) and to other programs.

1. Why not just use a Topic?

A Topic does one round trip: question → find matching document pieces → answer. That covers many real needs, and you should prefer it when it fits.

Use an Agent when the task needs more than one step, and especially when the steps are not known in advance:

Need Topic Agent + Pipeline

Answer from documents

✅

possible, but more work

Call an external web service during the answer

via MCP only

✅ API Call module

Read a database, change the data, write a file

❌

✅

Go different ways depending on a result

❌

✅ Validator / Guardrails

Repeat until a result is good enough

❌

✅ Loop

Run at fixed times with no user present

❌

✅ Scheduler

Ask a person for approval during a run

❌

✅ Human Approval

Run your own transformation code

❌

✅ Python Script

Use several knowledge bases together

via MCP

✅ AI Topic modules

Rule of thumb: if you can describe the job as one question, use a Topic. If you have to describe it as a procedure, use a Pipeline.

2. Use cases

Report at fixed times. Scheduler starts the run every night → SQL Database reads yesterday’s figures → Agent writes a summary → File Write saves a Markdown report to S3.

Ticket triage. Chat Input receives a ticket → Agent sorts it, using an AI Topic module with the support knowledge base → Validator goes different ways by severity → API Call posts to the ticket system.

Document enrichment. File Read loads a document → Text Splitter cuts it into pieces → Iterator goes through the pieces one by one → Embedding turns each into a vector → KV Store Write saves them.

Guarded assistant. Chat Input → Guardrails checks the request → Agent answers with MCP tools → Guardrails checks the answer → Chat Output. Anything that fails a check goes another way.

Quality loop. Loop → Agent writes a draft → Validator checks the draft → Pass ends the loop, Fail runs another round, up to the limit.

Human approval. Agent proposes an action → Human Approval pauses and asks the user → after an approval the real step runs, after a rejection the run goes another way.

Reading chat attachments. The user attaches a PDF in the agent chat → Agent calls an Attachment Tool → the tool server turns the file into text → Agent answers from that text.

3. Architecture

The same model as for Topics: this application does not run pipelines itself. It creates and controls containers.

┌──────────────────────────────────────────────────────────────┐
│  Management application                                      │
│  · Pipeline Designer — stores each pipeline in its database  │
│  · Converts a pipeline into the form the agent server reads  │
│  · Starts / stops the Agent container                        │
│  · Sends the assigned pipelines to the Agent                 │
└──────────────┬───────────────────────────────────────────────┘
               │ 1. start the container
               ▼
┌──────────────────────────────────────────────────────────────┐
│  Agent container  (cyrockai/knowledge-fabric-agent,          │
│                    one per Agent)                            │
│  · Keeps the pipelines it received, and saved values         │
│  · Runs pipelines, calls models and tools                    │
└──────────────┬───────────────────────────────────────────────┘
               │ 2. wait until it answers, then send pipelines
               │ 3. chat requests from users and programs
               ▼
   Models · MCP tool servers · Topics · web services · databases · files

What the container gets

The Agent’s settings are few. The pipelines carry almost all of the configuration. When you press Start, this application gives the container:

  • Its identity — the Agent’s id. The container uses it to check that a user was granted this Agent.

  • Secrets and keys — the key to check users' sign-in tokens, the license key, and the key for usage reports (metrics).

  • The public address, if one is set — see Public Endpoints.

  • The largest chat attachment — the setting Largest Chat Attachment (MB) on the Agent.

  • Storage:

Storage Docker Kubernetes

Pipeline store — the pipelines the Agent received

Kept (own volume)

Kept (own volume)

KV store — values saved with KV Store Write

Kept (own volume)

Not available — see below

Stop and Start keep both volumes. Deleting the Agent removes them.

On Kubernetes, KV Store Read and KV Store Write cannot be used, and neither can File Read or File Write with a folder on the server. The agent server refuses a pipeline that contains them, because the disk inside a pod is not kept. Use S3 or Azure Blob Storage for files there.

Changes to the Agent’s own settings (port, attachment size, public address) reach the container on its next start.

What happens when you press Start

  1. The container is started. The status is Starting…​.

  2. This application waits up to 120 seconds for the Agent to answer. On Kubernetes this time also covers downloading the container image.

  3. As soon as the Agent answers, every assigned pipeline is sent to it.

  4. Pipelines the Agent still holds but that are no longer assigned are deleted from it. The Agent keeps every pipeline it ever received, even across restarts. Without this step a pipeline you removed or renamed while the Agent was stopped could still be run.

  5. The Agent is Running.

What can go wrong:

What you see What it means

Status Error

The Agent did not answer within 120 seconds. No pipeline was sent. Check the Logs tab and start it again

Status Running plus a warning naming pipelines

The Agent is running, but refused the named pipelines. The warning says why. Fix the pipeline and push it again, or restart the Agent

Changing a pipeline

Configuration lives in the pipeline, not in the container. A changed pipeline does not need an Agent restart. When you save a pipeline that runs on a running Agent, the designer asks Deploy Changes? — choose Push Now to send the new version at once. With Not Now, the Agent keeps the old version until its next restart.

Removing a pipeline from a running Agent (on the Agent’s Pipelines tab) also deletes it from the Agent right away. If the Agent cannot be reached at that moment, it is deleted there on the next start.

From canvas to agent — what gets deployed

The canvas is not sent as it is. It is converted first:

On the canvas On the Agent

A module

One module of the deployed pipeline

A Description note

Nothing — it is only a note for people

A normal line between modules

One connection

A line into an Agent’s Tools port

That module becomes one of the Agent’s tools

A pipeline with an empty required field cannot be deployed. This application checks every pipeline before it reaches an Agent, and tells you which fields to fill in:

  • Assigning a pipeline to an Agent (also when creating an Agent) is refused, with the list of empty fields. The same check runs for every pipeline it calls.

  • Saving a pipeline that runs on a running Agent works, but the new version is not sent. A message names the empty fields. Fill them in and save again.

4. The module palette at a glance

29 module types, grouped by role:

Group Modules

Input & Output

Chat Input · Chat Output

Models & Agents

Agent · Embedding

Flow Control

Scheduler · Iterator · Loop · Validator · Guardrails

Data Sources

API Call · SQL Database · Data Faker · KV Store Read · KV Store Write · Structured Output

Files

File Read · File Write

Utilities

Template · Text Splitter · Text Format · Python Script · Web Search · Description

Human Interaction

Human Approval

Integration

AI Topic · MCP Tool · SSE Tool · Attachment Tool · Pipeline

Each has its own page in the module reference.

AI models in Agent, Embedding, Structured Output, Guardrails and Validator modules can come from OLLAMA, OPEN_AI, ANTHROPIC or GEMINI. ANTHROPIC offers no embedding models.

Three port kinds

Port Meaning

Input

Receives the previous module’s result

Output

Passes a result to the next module

Tool

Connects into an Agent’s Tools port, so the AI model can use the module

The Tool port is what makes this more than a flowchart: a module connected as a tool does not run in order. The AI model decides whether and when to use it, and with what input.

14 module types have a Tool port: MCP Tool, SSE Tool, Attachment Tool, API Call, AI Topic, SQL Database, Data Faker, KV Store Read, KV Store Write, File Read, File Write, Pipeline, Web Search, Python Script. Human Approval cannot be a tool: a paused run cannot hand control back to the model.

5. Two ways a module runs

Many modules can be used either way, and the difference is fundamental:

As a step As a tool

Connected to

Input/Output ports

An Agent’s Tools port

Runs

Always, in order

Only if the model decides to use it

Input from

The previous module

What the model sends

Needs a good description

No

Yes — it is how the model knows when to use it

An API Call used as a step runs in every run with its configured address. The same API Call used as a tool runs only when the model finds it useful.

When a module is a tool, its description is not a note — it is the instruction the model reads to decide whether to use it. A vague description means the tool is never used, or used at the wrong time. Where the description comes from depends on the module — see Integration.

6. Requirements before you start

Needed Where

An AI model address the Agent container can reach

Each module with a model has its own provider, model name and address

Docker or Kubernetes

Same as Topics

A port per Agent

Set when you create the Agent. Docker uses it to make the Agent reachable on the host

AGENT_* and PIPELINE_* permissions

Admin → Roles & Permissions

A valid license with room for the Agent and its Pipelines

Admin → License — without a license nothing can be created or started

The model settings in a pipeline are per module. They are not taken from the registered AI Servers automatically. The designer’s Select AI Server & Model button copies the values of a registered server into the module’s fields — the easy way to avoid typing errors. The address must work from inside the Agent container: with Docker use host.docker.internal (or 172.17.0.1 on plain Linux Docker), not localhost.

7. Typical workflow

  1. Design the pipeline — 5.3

  2. Create the Agent and assign the pipeline — 5.2. Pipelines it calls through a Pipeline module are assigned with it.

  3. Start the Agent — the pipelines are sent to it automatically

  4. Chat with it, choosing the pipeline — 5.6

  5. Improve: edit the pipeline, save, and choose Push Now to send the new version

Related