> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Creating Agents in Coreflux

> Add AI to Coreflux in minutes — talk to live data and put intelligence inside LoT automations, bringing AI to your solutions.

## Turn Your Broker Into a Teammate — and Your Automations Into Thinkers

Your devices, integrations, and databases already run on Coreflux — whether you monitor a factory, a solar site, a building portfolio, or a mobile fleet. **AI agents** live in LoT on that same broker: no separate AI platform, no copy-paste into another chat app.

**Talk with live data and automate with judgment.** Teams ask in plain language and get answers from what the broker sees *right now*. Your **Actions** already react to MQTT and timers; with agents they can also **reason** on a schedule or when an event fires — a status digest, a plain-language take on an alarm, a handover brief — all through `CALL AGENT` in LoT.

| What you gain                               | Example (any vertical)                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Ask the system, don't only chart it**     | *"Which zones are offline?"* · *"What's output at site B?"* · *"Any inverters under target?"*     |
| **Smarter automations, not more scripts**   | A timer or topic wakes an agent; LoT publishes the result — no babysitting a workflow             |
| **Reports while you sleep**                 | Hourly or daily digest on MQTT for supervisors, facility managers, or NOC staff                   |
| **Specialists, not one overloaded chatbot** | A guide for people, a reporter on a schedule, an analyst when alarms fire — each with its own job |

You define agents once in LoT (alongside your Actions and Routes). Below are **ready-to-use use cases** you can paste and deploy — pick one to prove value in minutes, or combine several on the same broker. Full options — multi-agent teams, MCP tools, safety rails — are in [AI Routes](/v2.0/lot-language/routes/ai-routes).

<Tip>
  **Like a supervisor on the floor *and* a analyst on the line.** People get answers when they ask; your automations get judgment when something changes — all on the broker you already run.
</Tip>

***

## Ready-to-Use Use Cases (Copy & Deploy)

Each tab is a full recipe: agent Route, LoT Action where needed, and MQTT topics to try. Adapt names to your vertical — examples in the table.

| Use case                | Who benefits            | How it runs                                        |
| ----------------------- | ----------------------- | -------------------------------------------------- |
| **Talk with your data** | Operators, support, NOC | Ask on `agents/site/ask`, read `agents/site/reply` |
| **Automatic report**    | Supervisors, managers   | Scheduled summary on `reports/operations/hourly`   |
| **Alert triage**        | On-call, maintenance    | Each alert gets a short AI explanation             |
| **Shift handover**      | Shift leads, crews      | Plain-language brief before the next rotation      |

Some examples of use-cases for your industry:

| Vertical              | Typical data topics                 | Automatic report might cover              |
| --------------------- | ----------------------------------- | ----------------------------------------- |
| **Manufacturing**     | `production/`, `lines/`, `quality/` | Throughput, downtime, batch issues        |
| **Solar & energy**    | `solar/`, `inverters/`, `grid/`     | Generation, underperformance, curtailment |
| **Smart buildings**   | `buildings/`, `hvac/`, `occupancy/` | Comfort, energy, fault patterns           |
| **Fleet & logistics** | `fleet/`, `vehicles/`, `routes/`    | Utilisation, delays, asset health         |

### Before you start

* A **running broker** — [Installation](/v2.0/quick-start/installation) and [Getting Started](/v2.0/quick-start/getting-started) if you are new
* A **model provider** — OpenAI, Anthropic, Mistral, or **local Ollama** on your network. Every recipe in the tabs below uses **OpenAI**; swap `PROVIDER`, `MODEL`, and the secret name if you prefer another cloud provider or edge inference (see [Picking a Provider](/v2.0/lot-language/routes/ai-routes#picking-a-provider)).

  For these examples, store an [OpenAI API key](https://platform.openai.com/api-keys) once on the broker:

```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
KEEP SECRET "OPENAI_KEY" WITH "sk-..."
```

<Note>
  The **[HUB AI Assistant](/v2.0/coreflux-hub/ai-assistant)** (Coreflux icon in the dock) is a separate built-in helper for drafting LoT and dashboards. This guide is about **your** agents — the ones you own in LoT.
</Note>

<Tabs>
  <Tab title="Talk with your data" icon="comments">
    **Outcome:** Anyone with MQTT access can ask questions; answers use **live broker data** (topics, Routes, recent payloads).

    Paste into the LoT Editor (Routes, then Actions) or your notebook:

    ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    DEFINE ROUTE SiteGuide WITH TYPE AGENT
        ADD AGENT_CONFIG
            WITH PROVIDER "openai"
            WITH MODEL "gpt-5.5"
            WITH API_KEY GET SECRET "OPENAI_KEY"
            WITH BROKER_TOOLS "true"
            WITH INTERACTION_MODE "interactive"
            WITH INTERACTION_TOPIC "agents/site/interact"
            WITH SYSTEM_PROMPT "You are a site operations guide. Use broker tools to answer from live MQTT data for this deployment. Be concise."

    DEFINE ACTION AskSiteGuide
    ON TOPIC "agents/site/ask" DO
        CALL AGENT "SiteGuide.execute"
            WITH (task = PAYLOAD)
            RETURN AS {reply}

        PUBLISH TOPIC "agents/site/reply" WITH {reply}
    ```

    <Steps>
      <Step title="Deploy and confirm">
        In HUB **Routes**, check **SiteGuide** (AGENT). In **Actions**, check **AskSiteGuide**. Both should show healthy.
      </Step>

      <Step title="Ask a real question">
        In MQTT Explorer or HUB [Data Viewer](/v2.0/coreflux-hub/mqtt/data-viewer), publish to `agents/site/ask` and subscribe to `agents/site/reply`. Try a question that fits your data, for example:

        ```text theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
        Which sensors have been updated in the last few minutes?
        ```

        ```text theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
        What is the latest data on telemetry/zone1/status?
        ```

        (Rename `telemetry/` to `production/`, `solar/`, `buildings/`, or your own tree.)
      </Step>

      <Step title="Read the answer on reply">
        The reply topic carries the agent's answer — grounded in what your broker actually sees.
      </Step>
    </Steps>

    <Check>
      You just **talked with your data**. No extra AI server — the agent runs where your MQTT already lives.
    </Check>
  </Tab>

  <Tab title="Automatic report" icon="clock">
    **Outcome:** **LoT automation with AI** — on a schedule, an Action calls the agent and publishes an **operations summary** to MQTT. No chat window.

    ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    DEFINE ROUTE OperationsReporter WITH TYPE AGENT
        ADD AGENT_CONFIG
            WITH PROVIDER "openai"
            WITH MODEL "gpt-5.4-mini"
            WITH API_KEY GET SECRET "OPENAI_KEY"
            WITH BROKER_TOOLS "true"
            WITH INTERACTION_MODE "autonomous"
            WITH SYSTEM_PROMPT "You write operations reports from live MQTT. Use broker tools on telemetry/ and related topics. Bullet points: current status, anomalies, items needing follow-up. Plain language for managers. Adapt wording to what the data represents (production, energy, facilities, fleet, etc.)."

    DEFINE ACTION HourlyOperationsReport
    ON EVERY 1 HOUR DO
        CALL AGENT "OperationsReporter.execute"
            WITH (task = "Hourly operations report: summarise key signals from telemetry/ topics, flag anything off-norm or stale, note follow-ups before the next review period.", use_history = "false")
            RETURN AS {report}

        PUBLISH TOPIC "reports/operations/hourly" WITH {report}
    ```

    <Steps>
      <Step title="Deploy Route and Action">
        Add **OperationsReporter** and **HourlyOperationsReport** in the LoT Editor. No public chat line — only the schedule triggers this agent.
      </Step>

      <Step title="Subscribe to the report">
        Subscribe to `reports/operations/hourly` in MQTT Explorer, a dashboard, or the HUB Data Viewer.
      </Step>

      <Step title="See the first report">
        Publish sample payloads under your data tree (`telemetry/`, `solar/site1/power`, `buildings/tower/hvac`, etc.), then wait for the next run — or temporarily use `ON EVERY 30 SECONDS` and change it back when done.
      </Step>
    </Steps>

    <Check>
      **Scheduled insight on autopilot** — the report speaks your operation's language, not broker diagnostics.
    </Check>
  </Tab>

  <Tab title="Alert triage" icon="bell">
    **Outcome:** When something hits your alerts topic, the broker adds a **plain-language triage note** — what it might mean and what to check first.

    Works for any alert source: equipment faults, threshold breaches, connectivity, security events.

    ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    DEFINE ROUTE AlertAnalyst WITH TYPE AGENT
        ADD AGENT_CONFIG
            WITH PROVIDER "openai"
            WITH MODEL "gpt-5.4-mini"
            WITH API_KEY GET SECRET "OPENAI_KEY"
            WITH BROKER_TOOLS "true"
            WITH INTERACTION_MODE "autonomous"
            WITH SYSTEM_PROMPT "You triage operational alerts from MQTT. In 3 short sentences: what happened, likely cause, recommended first check. Be direct."

    DEFINE ACTION TriageAlert
    ON TOPIC "alerts/#" DO
        CALL AGENT "AlertAnalyst.execute"
            WITH (task = "Alert on topic " + TOPIC + ": " + PAYLOAD, use_history = "false")
            RETURN AS {triage}
        PUBLISH TOPIC "agents/site/alerts/analysis" WITH {triage}
    ```

    <Steps>
      <Step title="Wire your alerts">
        Ensure your existing logic still publishes under `alerts/` — for example `alerts/inverter/fault`, `alerts/building/leak`, or `alerts/line2/quality`.
      </Step>

      <Step title="Deploy triage">
        Add **AlertAnalyst** and **TriageAlert**. Subscribe to `agents/site/alerts/analysis`.
      </Step>

      <Step title="Trigger once">
        Publish a test alert to `alerts/test/manual` with any message. Read the analysis on the triage topic.
      </Step>
    </Steps>

    <Check>
      On-call gets **context with the alarm**, not only a raw payload.
    </Check>
  </Tab>

  <Tab title="Shift handover" icon="clipboard-list">
    **Outcome:** Before each rotation, a **handover brief** lands on MQTT — what changed, what looks odd, what the incoming team should watch. Common in manufacturing, utilities, and 24/7 operations centers.

    ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    DEFINE ROUTE HandoverBrief WITH TYPE AGENT
        ADD AGENT_CONFIG
            WITH PROVIDER "openai"
            WITH MODEL "gpt-5.5"
            WITH API_KEY GET SECRET "OPENAI_KEY"
            WITH BROKER_TOOLS "true"
            WITH INTERACTION_MODE "autonomous"
            WITH SYSTEM_PROMPT "You write handover notes for operations teams. Use broker tools. Bullet points: status, anomalies, open items. Max 8 bullets."

    DEFINE ACTION ShiftHandover
    ON EVERY 8 HOURS DO
        CALL AGENT "HandoverBrief.execute"
            WITH (task = "Prepare handover for the next shift: current operational status, active alarms, and anything unusual in the last 8 hours.", use_history = "false")
            RETURN AS {brief}
        PUBLISH TOPIC "agents/site/shift/handover" WITH {brief}
    ```

    <Steps>
      <Step title="Deploy">
        Add **HandoverBrief** and **ShiftHandover**. Subscribe to `agents/site/shift/handover`.
      </Step>

      <Step title="Test faster">
        Temporarily use `ON EVERY 2 MINUTES`, read one brief, then restore `ON EVERY 8 HOURS` for production.
      </Step>
    </Steps>

    <Check>
      **Crew change becomes a story**, not a scramble through dashboards.
    </Check>
  </Tab>
</Tabs>

<Tip>
  **Starter pack:** **SiteGuide** + **HourlyOperationsReport** + **AlertAnalyst** — ask your deployment, get scheduled insight, enrich every alarm. Rename topics to `production/`, `solar/`, or `buildings/` when you copy the prompts.
</Tip>

***

## When You're Ready to Grow

You already have the building blocks: **chat** (ask/reply topics), **schedules** (`ON EVERY`), and **event-driven** (`ON TOPIC`) automations with `CALL AGENT`. Next level is tuning models per job, adding [MCP Routes](/v2.0/lot-language/routes/mcp-routes) for Slack or databases, and naming agents by role so LoT stays readable.

For multi-agent patterns (operator, specialist, watchdog, reader), see [Multi-Agent Deployments](/v2.0/lot-language/routes/ai-routes#multi-agent-deployments).

***

## Stay Safe While You Experiment

<AccordionGroup>
  <Accordion title="Try read-only first">
    Add `WITH AGENT_MODE "insight"` on a Route so it can explore but not publish or trigger downstream equipment. Switch to full mode when you trust the prompt.
  </Accordion>

  <Accordion title="Keep API keys off the clipboard in LoT files">
    Always use `GET SECRET "OPENAI_KEY"` — never paste keys into Route definitions that get saved or shared.
  </Accordion>

  <Accordion title="Match the agent to the audience">
    Chat for people; timed Actions for machines. Do not put a public chat line on agents that should only run in the background.
  </Accordion>
</AccordionGroup>

***

## What to Explore Next

<CardGroup cols={2}>
  <Card title="AI Routes (full reference)" icon="brain" href="/v2.0/lot-language/routes/ai-routes">
    Providers, MCP tools, multi-agent teams, and deployment settings when you outgrow this tutorial.
  </Card>

  <Card title="Using AI with Coreflux" icon="wand-magic-sparkles" href="/v2.0/quick-start/using-ai">
    Use MCP in your editor to write LoT faster — separate from agents running on the broker.
  </Card>
</CardGroup>