Agents

Agents are autonomous workers that run your workflows on a schedule, reflect on each run against a stated goal, and can self‑patch broken workflows.

An agent = goal + workflows + schedule + model. Each run, the agent executes its workflows, then the reflection engine decides whether the run made progress. If it didn't, the engine can rewrite the workflow in place.

Creating an Agent

From the Agents tab

1. Open the Agents tab and click Create Agent.
2. Fill in:
   • Name and Role — e.g. News Notifier / News curator.
   • Goal — what success looks like, in one short paragraph. The reflection engine uses this to judge every run.
   • Workflows — check one or more existing workflows the agent will execute each tick.
   • Provider / Model — see Model Requirements.
   • Capabilities — feature gates the agent is allowed to use (browser, api, desktop, ai, workflows, credentials, filesystem).
3. Click Create Agent. If the agent has a schedule, it starts running immediately.

From chat

Ask Loopi in the Chat tab to build an agent. It emits two fenced blocks that the chat parser turns into real artifacts:

• ```workflow-create {...}``` — one per workflow the agent needs.
• ```agent-create {...}``` — the agent itself, referencing the workflows by name.

The chat UI creates the workflows first, then the agent, and links them together automatically.

The Reflection Loop

Every time an agent runs a workflow, the reflection engine is invoked with:

• The agent's goal.
• The workflow graph (nodes + edges).
• Per‑node outcomes (success / error + error message).
• A truncated snapshot of final variables (strings capped at 500 chars, arrays sampled).

It asks the agent's own LLM to return a single fenced block:

```agent-reflect
{
  "verdict": "ok" | "modify" | "fail",
  "reason": "one-sentence explanation",
  "patch": { "nodes": [...], "edges": [...] }
}
```

Verdicts

Safety rails

• If the LLM's output has no parseable block, or JSON is invalid → verdict falls back to ok. Bad reflections never break a run.
• A modify verdict with a malformed patch (missing/empty nodes, missing edges) is downgraded to ok.
• A patch must be a complete replacement graph, not a diff. The engine overwrites the stored workflow.
• If saving the patched workflow throws, the previous workflow is restored and the reflection is marked rolledBack: true.
• Each agent keeps the last 50 reflections (older ones are dropped).

Model Requirements

Reflection requires real reasoning — small models silently return ok or produce unusable patches. The create dialog validates the model and blocks creation if it's known to be too small.

Scheduling

Agents share the same scheduler as workflows. Supported schedule types:

Scheduled agents reactivate automatically on app startup.

Agent Shape

{
  id: string;
  name: string;
  role: string;
  description: string;
  status: "idle" | "running" | "failed";
  capabilities: AgentCapability[];
  goal: string;
  workflowIds: string[];
  reflections: AgentReflection[];  // capped at 50
  model: {
    provider: "openai" | "anthropic" | "ollama" | "claude-code";
    model: string;
    credentialId?: string;
    apiKey?: string;
    baseUrl?: string;
  };
  schedule?: {
    type: "manual" | "interval" | "cron" | "once";
    expression?: string;
    intervalMinutes?: number;
    datetime?: string;
  };
  credentialIds: string[];
  createdAt: string;
  updatedAt: string;
  lastRunAt?: string;
  logs: AgentLogEntry[];           // capped at 100
  parentAgentId?: string;
  createdBy: "user" | "loopi";
}

Storage

Agents persist as one JSON file per agent under the app's userData/agents/ directory. Logs are capped at 100 entries and reflections at 50 before each save.

Related

• Getting Started — Install Loopi and build a workflow first.
• CLI — Drive agents and workflows from the terminal.
• Credentials — How agents authenticate to services.
• Examples — Ready‑to‑import templates, including agent workflows.