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

Core Concepts

This page introduces Orloj's key building blocks and how they fit together. Read this before diving into the individual concept pages.

Resource Map

                  TaskSchedule ──creates──▶ Task ◀──creates── TaskWebhook
                                             │
                                          triggers
                                             ▼
                                        AgentSystem
                                        ╱          ╲
                                   composes      composes
                                     ╱                ╲
                                Agent A ─────────── Agent B
                               ╱   │   ╲           ╱   │
                          calls  invokes reads  calls invokes
                            ╱      │    ╲       ╱      │
                   ModelEndpoint  Tool  Memory  │      │
                        │          │            │      │
                   resolves    resolves          │      │
                    auth via    auth via         │      │
                        ╲       ╱               │      │
                         Secret                 │      │
                                                │      │
              ┄┄┄┄┄┄┄┄ Governance ┄┄┄┄┄┄┄┄┄┄┄┄┄┤┄┄┄┄┄┄┤
              ┆                                 ┆      ┆
        AgentPolicy ┄┄ constrains ┄┄▶ Agent A, Agent B
        AgentRole   ┄┄ grants permissions to ┄▶ Agents
        ToolPermission ┄ controls access to ┄▶ Tools
 
              Worker ──claims and executes──▶ Task

Agents

An Agent is a declarative unit of work backed by a language model. You define its prompt, model, tools, and constraints in YAML.

kind: Agent
metadata:
  name: research-agent
spec:
  model_ref: openai-default
  prompt: "You are a research assistant."
  tools: [web_search]
  limits:
    max_steps: 6

Agent Systems

An AgentSystem composes agents into a directed graph -- pipelines, hierarchies, or swarm loops.

kind: AgentSystem
metadata:
  name: report-system
spec:
  agents: [planner, researcher, writer]
  graph:
    planner:
      edges: [{to: researcher}]
    researcher:
      edges: [{to: writer}]

Tasks

A Task is a request to execute an AgentSystem. Tasks track lifecycle state (Pending -> Running -> Succeeded), support retry, and produce output.

kind: Task
metadata:
  name: weekly-report
spec:
  system: report-system
  input:
    topic: AI startups

Tools

A Tool is an external capability agents can invoke. Six transport types (HTTP, external, gRPC, webhook-callback, MCP, queue) and four isolation modes (none, sandboxed, container, WASM).

kind: Tool
metadata:
  name: web_search
spec:
  type: http
  endpoint: https://api.search.com
  auth:
    secretRef: search-api-key

Model Endpoints

A ModelEndpoint configures a connection to a model provider (OpenAI, Anthropic, Azure OpenAI, Ollama). Agents reference endpoints by name, decoupling agent definitions from provider details.

kind: ModelEndpoint
metadata:
  name: openai-default
spec:
  provider: openai
  default_model: gpt-4o-mini
  auth:
    secretRef: openai-api-key

Memory

Memory gives agents persistent storage across execution steps and task runs. Three layers: conversation history, task-scoped shared state, and persistent backends (in-memory, pgvector, HTTP).

Governance

The governance layer controls what agents can do at runtime:

Governance is fail-closed: unauthorized tool calls are denied, not silently ignored.

Automation

Infrastructure

  • Worker -- execution unit that claims and runs tasks
  • Secret -- stores API keys and credentials
  • McpServer -- connects to MCP servers and auto-discovers tools

Next Steps