Agents and Agent Systems

An Agent is a declarative unit of work backed by a language model. An AgentSystem composes multiple agents into a directed graph that Orloj executes as a coordinated workflow.

Agents

An Agent manifest defines what the agent does (its prompt), what model powers it, what tools it can call, and what constraints bound its execution.

apiVersion: orloj.dev/v1
kind: Agent
metadata:
  name: research-agent
spec:
  model_ref: openai-default
  prompt: |
    You are a research assistant.
    Produce concise evidence-backed answers.
  tools:
    - web_search
    - vector_db
  memory:
    ref: research-memory
  roles:
    - analyst-role
  limits:
    max_steps: 6
    timeout: 30s

Key Fields

Field	Description
`model_ref`	Required reference to a ModelEndpoint resource for provider-aware routing.
`prompt`	The system instruction that defines the agent's behavior.
`tools`	List of Tool names this agent may call. Tool calls are subject to governance checks.
`roles`	Bound AgentRole names. Roles carry permissions that authorize tool usage.
`memory.ref`	Reference to a Memory resource. This attaches the memory backend to the agent.
`memory.allow`	Explicit list of built-in memory operations the agent may use: `read`, `write`, `search`, `list`, `ingest`.
`limits.max_steps`	Maximum execution steps per task turn. Defaults to `10`.
`limits.timeout`	Maximum wall-clock time per task turn.

How an Agent Executes

When the runtime activates an agent during a task, it:

Initializes the agent's conversation history with the system prompt and current task context.
If memory.ref is set, wires the backing memory store into the runtime. If memory.allow is also set, the runtime exposes only those built-in memory operations as available tools.
Routes the request to the configured model via the model gateway, sending the full conversation history.
If the model selects tool calls, the runtime checks governance (AgentPolicy, AgentRole, ToolPermission) and executes authorized tools. Memory tool calls are handled internally without network calls. Tool results are sent back using the provider's native structured tool protocol (role: "tool" with tool_call_id for OpenAI, tool_result content blocks for Anthropic).
Results are appended to the conversation history and sent back to the model for the next step. The agent completes when the model produces text output without requesting further tools, or when max_steps / timeout is reached. Already-called tools are removed from the available list to prevent duplicate calls.

Conversation history is maintained for the full duration of the agent's activation, giving the model continuity across reasoning and tool-use steps. See Memory for details on memory layers and built-in tools.

Agent Systems

An AgentSystem wires agents into a directed graph. The graph defines how messages flow between agents during task execution.

apiVersion: orloj.dev/v1
kind: AgentSystem
metadata:
  name: report-system
  labels:
    orloj.dev/domain: reporting
    orloj.dev/usecase: weekly-report
spec:
  agents:
    - planner-agent
    - research-agent
    - writer-agent
  graph:
    planner-agent:
      next: research-agent
    research-agent:
      next: writer-agent

Graph Topologies

The graph field supports three fundamental patterns:

Pipeline -- sequential stage-by-stage execution where each agent hands off to the next.

graph:
  planner-agent:
    edges:
      - to: research-agent
  research-agent:
    edges:
      - to: writer-agent

Hierarchical -- a manager delegates to leads, who delegate to workers, with a join gate that waits for all branches before proceeding.

graph:
  manager-agent:
    edges:
      - to: research-lead-agent
      - to: social-lead-agent
  research-lead-agent:
    edges:
      - to: research-worker-agent
  social-lead-agent:
    edges:
      - to: social-worker-agent
  research-worker-agent:
    edges:
      - to: editor-agent
  social-worker-agent:
    edges:
      - to: editor-agent
  editor-agent:
    join:
      mode: wait_for_all

Swarm with loop -- parallel scouts report back to a coordinator in iterative cycles, bounded by Task.spec.max_turns.

graph:
  coordinator-agent:
    edges:
      - to: scout-alpha-agent
      - to: scout-beta-agent
      - to: synthesizer-agent
  scout-alpha-agent:
    edges:
      - to: coordinator-agent
  scout-beta-agent:
    edges:
      - to: coordinator-agent

Fan-out and Fan-in

When a graph node has multiple outbound edges, messages fan out to all targets in parallel. Fan-in is handled through join gates:

Join Mode	Behavior
`wait_for_all`	Waits for every upstream branch to complete before activating the join node.
`quorum`	Activates after `quorum_count` or `quorum_percent` of upstream branches complete.

If an upstream branch fails, the on_failure policy determines behavior: deadletter (default), skip, or continue_partial.

Labels

Labels on AgentSystem metadata follow Kubernetes conventions and are useful for filtering, governance scoping, and operational grouping:

metadata:
  labels:
    orloj.dev/domain: reporting
    orloj.dev/usecase: weekly-report
    orloj.dev/env: dev