Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Deploy Your First Pipeline

This guide is for platform engineers who want to run a multi-agent pipeline end-to-end. You will define three agents, wire them into a sequential graph, submit a task, and inspect the results.

Prerequisites

  • Orloj server (orlojd) running (sequential mode with --embedded-worker is fine for this guide)
  • orlojctl available (or go run ./cmd/orlojctl)

If you have not set up Orloj yet, follow the Install and Quickstart guides first.

What You Will Build

A three-stage pipeline where each agent hands off to the next:

planner ──► researcher ──► writer

The planner breaks the task into research requirements, the researcher gathers evidence, and the writer produces the final output.

Step 1: Define the Agents

Create three agent manifests. Each agent has a model, a system prompt, and execution limits.

Planner agent (planner-agent.yaml):

apiVersion: orloj.dev/v1
kind: Agent
metadata:
  name: bp-pipeline-planner-agent
spec:
  model_ref: openai-default
  prompt: |
    You are the planning stage.
    Break the task into concrete research and writing requirements.
  limits:
    max_steps: 4
    timeout: 20s

Research agent (research-agent.yaml):

apiVersion: orloj.dev/v1
kind: Agent
metadata:
  name: bp-pipeline-research-agent
spec:
  model_ref: openai-default
  prompt: |
    You are the research stage.
    Produce concise, verifiable findings for the writer.
  limits:
    max_steps: 6
    timeout: 30s

Writer agent (writer-agent.yaml):

apiVersion: orloj.dev/v1
kind: Agent
metadata:
  name: bp-pipeline-writer-agent
spec:
  model_ref: openai-default
  prompt: |
    You are the writing stage.
    Synthesize prior handoffs into a polished final output.
  limits:
    max_steps: 4
    timeout: 20s

Apply all three:

orlojctl apply -f planner-agent.yaml
orlojctl apply -f research-agent.yaml
orlojctl apply -f writer-agent.yaml

Step 2: Define the Agent System

The AgentSystem wires the agents into a pipeline graph:

apiVersion: orloj.dev/v1
kind: AgentSystem
metadata:
  name: bp-pipeline-system
  labels:
    orloj.dev/pattern: pipeline
spec:
  agents:
    - bp-pipeline-planner-agent
    - bp-pipeline-research-agent
    - bp-pipeline-writer-agent
  graph:
    bp-pipeline-planner-agent:
      edges:
        - to: bp-pipeline-research-agent
    bp-pipeline-research-agent:
      edges:
        - to: bp-pipeline-writer-agent

The graph field defines a directed acyclic graph. Each node lists its outbound edges. The planner routes to the researcher, who routes to the writer. The writer has no outbound edges, making it the terminal node.

Apply the system:

orlojctl apply -f agent-system.yaml

Step 3: Submit a Task

Create a task that targets the pipeline system:

apiVersion: orloj.dev/v1
kind: Task
metadata:
  name: bp-pipeline-task
spec:
  system: bp-pipeline-system
  input:
    topic: state of enterprise AI copilots
  priority: high
  retry:
    max_attempts: 2
    backoff: 2s
  message_retry:
    max_attempts: 2
    backoff: 250ms
    max_backoff: 2s
    jitter: full

Apply the task:

orlojctl apply -f task.yaml

Step 4: Monitor Execution

Watch the task progress:

orlojctl get tasks -w

View agent logs:

orlojctl logs task/bp-pipeline-task

Trace the execution path through the graph:

orlojctl trace task bp-pipeline-task

Visualize the system graph:

orlojctl graph system bp-pipeline-system

What Happens at Runtime

  1. The scheduler assigns bp-pipeline-task to an available worker.
  2. The worker claims the task and acquires a lease.
  3. The planner agent runs first (entry node -- zero indegree in the graph).
  4. The planner's output is routed as a message to the research agent.
  5. The research agent processes the message and routes its output to the writer.
  6. The writer produces the final output. With no further edges, the task transitions to Succeeded.

If any agent fails, the message-level retry configuration kicks in. After max_attempts exhaustion, the message moves to deadletter. If the task-level retry is also exhausted, the task itself transitions to DeadLetter.

Using the Pre-Built Blueprint

The complete pipeline blueprint is available in the repository:

orlojctl apply -f examples/blueprints/pipeline/agents/
orlojctl apply -f examples/blueprints/pipeline/agent-system.yaml
orlojctl apply -f examples/blueprints/pipeline/task.yaml

Next Steps