Farna Control
Read-only demoInstall

Agents

An agent is the atomic unit of work in a Farna Control pipeline. An agent is a stored, reusable entity that carries a prompt template, a model backend, input and output schemas, and optional evals. A pipeline node of type agent references it by agent_id, so one agent can serve several pipelines and every pipeline automatically picks up a new prompt version.

Agent configuration

Create agents at Agents (/agents) or through POST /api/v1/agents. A create request carries:

Agent configuration
Field Description
name Unique name in the workspace
description What the agent does
prompt_template The prompt the node renders when it runs
model_backend_id The model backend the agent routes large language model (LLM) calls through
input_schema_id, output_schema_id Schemas that validate the agent’s input and output
input_schema_version, output_schema_version Optional schema version pins
required_environment_capabilities Runtime capabilities the node needs, such as a language runtime or sandbox feature
template_id Composite template the agent belongs to, or null
is_executable Whether the agent can run; set false for a reusable template
token_budget, max_input_length Optional per-agent limits
retry_policy Retry behavior for this agent
agent_commands Commands a sandbox agent runs
schema_profile Schema translation profile: verbatim, provider-strict, or runtime-sdk
Pipeline config 
{
  "name": "draft-pr-description",
  "description": "Writes a pull request description from an attached diff.",
  "prompt_template": "Write a pull request description for the attached diff.",
  "model_backend_id": "11111111-1111-4111-8111-111111111111",
  "input_schema_id": "22222222-2222-4222-8222-222222222222",
  "output_schema_id": "33333333-3333-4333-8333-333333333333",
  "required_environment_capabilities": [],
  "template_id": null
}

The prompt lives on the agent, not on the pipeline node. A node only selects an agent and supplies the runtime position and any node-level overrides.

Node types

A pipeline node’s node_type declares how the node executes:

Node types
node_type Purpose
agent Runs the stored agent referenced by agent_id
connector Runs a connector operation through connector_binding
manual Pauses for a human to submit the output outside Farna Control
hitl Human review gate; requires hitl_config
composite Runs a reusable subgraph referenced by composite_ref
sandbox_agent Runs an agent in a sandbox, in llm mode or script mode
router Pure decision node that passes state through so conditional edges can route
join Joins parallel branches
dispatch Dispatches work to a connector’s CI-runner operation

Node-level fields include id, node_type, position, label, role, agent_id, connector_binding, output_schema_id, input_schema_pin, output_schema_pin, capability_scope, idempotent, timeout_seconds, hitl_config, and policy_gate.

Prompt versioning

Every prompt change appends an entry to the agent’s prompt_version_history and updates prompt_template. Farna Control preserves all versions and allows restoring a previous one. The audit log records which prompt version produced each run output.

Schema assignment

A schema turns an agent’s output into a typed artifact: it defines the expected shape and constraints. Schemas are versioned independently from agents, and an agent pins the input and output schema versions it expects, so a schema update can affect multiple agents at once.

Gate mechanisms

Gates are not a node type. Farna Control has two gate mechanisms:

  • A human review gate is a node with node_type: "hitl" and a hitl_config, or a gate configured on an edge. The gate pauses the run until a reviewer approves or rejects it.
  • A policy gate is a node-level policy_gate that references an eval definition. The eval runs after node completion and before any human review, with action set to warn or block.
Pipeline config 
{
  "id": "44444444-4444-4444-8444-444444444444",
  "node_type": "hitl",
  "position": { "x": 680, "y": 200 },
  "output_schema_id": "55555555-5555-4555-8555-555555555555",
  "hitl_config": {
    "label": "Human review",
    "description": "A reviewer must approve the drafted comment before it is posted.",
    "claim_expiry_minutes": 15,
    "human_only": true
  }
}

A human-in-the-loop (HITL) node runs like a normal node (it can carry an agent or a connector) and gates its outgoing edges. A pure approval step can also be configured on an edge with hitl_review_config, as shown in Pipelines.

Human-only gates

A review gate is human-only unless its hitl_config explicitly sets human_only: false; an omitted value fails safe to human-only. A human-only gate interrupts at every autonomy level, so the pipeline’s autonomy setting cannot auto-approve it. Only a browser session, or a consent-derived human-linked OAuth credential over Model Context Protocol (MCP), can decide one. See Human-in-the-Loop for the claim workflow and the credential rules.

Next: Human-in-the-Loop