> ## 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. # Agents Overview > What a LoT agent is, how it relates to the TYPE LLM connector, and when to use one Preview > [!WARNING] > > `DEFINE AGENT` is a preview feature. It ships in broker **2.22**. The syntax and behaviour may still change. ## What an agent is Your broker already moves sensor data, drives equipment, and stores history. Two LoT pieces add a language model to that world. A **`TYPE LLM` connector** sends one prompt and returns text. Actions use it for a classification, a summary, or a short conversation. A **`DEFINE AGENT`** is a named assistant that runs on that connector. It can read topics, publish, run connector events, and hand work to other agents — only where you grant it. The connector holds the provider, the model, the key, and the price. Every agent that names it with `USES LLM CONNECTOR` picks up a change to that connector. An agent is its own LoT entity. It is deployed with `-addAgent`, and it does not appear in the connector list. > [!TIP] > > **Like a phone line and the people who answer it.** The `TYPE LLM` connector is the line to the model. Each `DEFINE AGENT` is a person you hire, with a job description and a set of keys. `CALL LLM` dials the line directly. `CALL AGENT` asks a specific person to do the job. ### When to use which * **Prompt in, text out** — a `TYPE LLM` connector and `CALL LLM` inside an Action * **An assistant that reads or changes the broker** — `DEFINE AGENT`, then `ADD TOOL` for each thing it may touch * **People and apps chatting over MQTT** — `WITH INTERACTION_TOPIC` on the agent * **Hands-off work** — `CALL AGENT` from an Action on a topic or a timer * **Several specialists** — one LLM connector, several agents, and `WITH AGENTS` for the peers a supervisor may call Both need a **Growth or Enterprise** license, the same row as **LLM / Agent** on [Licensing](/latest/mqtt-broker/licensing#plans). On Community, `-addAgent` is refused. An agent does not consume a connector slot. ## Agents and the LLM connector An agent never talks to a provider directly. `USES LLM CONNECTOR` names a [`TYPE LLM` connector](/latest/lot-language/routes/ai-routes#the-llm-connector), and that connector holds the provider (`ollama`, `openai`, `anthropic`, or `compatible`), the model, the key, and prices. The connector itself never calls tools. The agent adds the job description, the grants, the budgets, and the topics people and Actions use to reach it. | | `TYPE LLM` connector | `DEFINE AGENT` | | - | - | - | | Deployed with | `-addConnector` | `-addAgent` | | Listed by | `-listConnectors` | `-listAgents` | | Called from an Action | `CALL LLM` | `CALL AGENT` | | Calls tools | No | Only what `ADD TOOL` grants | | Counts as a connector | Yes | No | Agents and connectors share one namespace, so an agent can't take the name of a connector. Deploy order doesn't matter: an agent whose connector is missing waits in `error` and comes online when the connector starts. > **[Agent syntax](/latest/lot-language/agents/syntax)** > > `DEFINE AGENT`, its properties, `ADD TOOL`, delegation, topics, and `CALL AGENT`. > **[Agent examples](/latest/lot-language/agents/examples)** > > A chat agent, a reporting agent, and a supervisor with specialists. *** ## Best practices > **Give every agent its own service user** > > `DEFAULT_USER "root"` turns every grant into whatever root can do. Create a user that can do the job and nothing wider, and name that user. > **Keep keys on the LLM connector** > > `WITH API_KEY GET SECRET "OPENAI_API_KEY"`. A literal key is copied into every project export. > **Grant the narrowest topics that do the job** > > `write_mqtt` on `reports/line/#` with `WITH LEVEL "write"`. A grant of `#` lets the agent publish anywhere its user can. > **Say LEVEL write on anything the agent must do today** > > A writing grant without `LEVEL` is refused. Approvals are not available yet. > **Name peers in WITH AGENTS** > > An undeclared peer is not offered to the model. > **Watch the stream while you tune grants** > > Subscribe to `$SYS/Coreflux/Agents//task/+/stream`. Every refusal is a `tool_result` with an `outcome`. Guardrail text steers the model. `ADD TOOL` and RBAC are the limit. Anything the agent must never do stays outside its grants. *** ## Limits | Limit | Default | When you hit it | | - | - | - | | `MAX_IN_FLIGHT` | 4 per agent | New tasks are `rejected` with `agent_busy` | | `MAX_ITERATIONS` | 10 per run | Further tool calls are refused with `budget_exhausted` | | `MAX_TOKENS` | 50 000 per tree | Further tool calls are refused, then the task fails with `budget_exhausted` | | `TASK_TIMEOUT` | 600 seconds per tree | `deadline_exceeded` | | `MAX_CHAIN_DEPTH` | 4 hops | Delegation is refused with `hop_limit` | | Working memory | 256 sessions, 256 KiB, 40 messages | Oldest sessions and turns are dropped | Task work runs on the agent's own pool, so a slow model does not stall other connectors. *** ## Coming from TYPE AGENT `DEFINE ROUTE … WITH TYPE AGENT` and `ADD AGENT_CONFIG` are gone. `-addConnector` refuses the block. A connector file that still holds one is skipped at load and the log names the replacement. Nothing is migrated for you. Rewrite each one by hand. | Old `AGENT_CONFIG` setting | Where it goes | | - | - | | `PROVIDER`, `BASE_URL`, `MODEL`, `API_KEY`, `TEMPERATURE`, `MAX_TOKENS` | A `TYPE LLM` connector. `MAX_TOKENS` there caps one completion | | `SYSTEM_PROMPT`, `MAX_ITERATIONS`, `DEFAULT_USER`, `INTERACTION_TOPIC`, `DESCRIPTION` | The `DEFINE AGENT` | | `BROKER_TOOLS`, `ENABLED_COMMANDS` | `ADD TOOL` grants. Nothing is granted by default | | `ACTIONS` | `ADD TOOL "execute_actions"` with `WITH TARGET` for each action and `WITH LEVEL "write"` | | `MCP_ROUTES` | No direct replacement. MCP tools are not offered to the model. Fire an event on the MCP connector with `ADD TOOL "execute_routes"` (`WITH TARGET "."`, `WITH LEVEL "write"`) and read that event's `DESTINATION_TOPIC` with `read_mqtt` | | `MODELS`, `VECTOR_STORE`, `HISTORY_MODE` | Dropped. Working memory is per session (`WITH MEMORY`) | | `MAX_HISTORY_*` | `WITH MAX_HISTORY_TOKENS` on the agent caps the session history it keeps | | `INTERACTION_MODE`, `TOOL_EXECUTION_MODE`, `CONFIRM_TOPIC`, `AGENT_MODE` | Dropped. Confirmation in the broker is a later release. The HUB still asks before a write when the assistant runs in the HUB | | `TRACE`, `TRACE_TOPIC`, `DEBUG`, `ARTIFACT_FORMAT`, `TOOL_MODE` | Dropped. Every task streams on `…/task//stream` | Clients that published to `{InteractionTopic}/{agent}/{session}/input` and read `artifacts` or `stream` move to `{INTERACTION_TOPIC}/{session}/ask`, `…/response`, and `$SYS/Coreflux/Agents//task//stream`. `CALL AGENT ".execute"` keeps its call shape. The old `$SYS/Coreflux/Agents//Capabilities` and `…/Metrics` topics are not published. Read the card, the status topic, and the task stream. ```lot wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}} DEFINE CONNECTOR PlannerLlm WITH TYPE LLM ADD LLM_CONFIG WITH PROVIDER "anthropic" WITH MODEL "claude-sonnet-4-0" WITH API_KEY GET SECRET "ANTHROPIC_API_KEY" DEFINE AGENT Planner USES LLM CONNECTOR PlannerLlm WITH DEFAULT_USER "agent_svc" WITH INTERACTION_TOPIC "factory/agent/planner" ADD TOOL "read_lot" ``` *** ## Not available yet `-addAgent` refuses these, with a message that names what is missing, so a setting is never silently ignored. * `WITH LEVEL "write_confirm"` and any writing grant that omits `LEVEL` * `AGENT_MODE "insight"` as a default, and `TOOL_EXECUTION_MODE "confirm"`. Per-request `"mode": "insight"` works today * `WITH SKILLS` * Shared or long-term memory (`MEMORY "shared:…"`, `WITH LONG_TERM_MEMORY`) * Collaboration modes other than `delegate` * `EXTERNAL_ACCESS "true"` * `WITH OUTPUT_MODEL` * `ADD TOOL "run_lot_once"` *** ## Next steps > **[Creating Agents in Coreflux](/latest/quick-start/creating-agents)** > > Paste a site guide, a scheduled report, alert triage, or a shift handover and try them over MQTT. > **[AI Connectors](/latest/lot-language/routes/ai-routes)** > > Providers, `LLM_CONFIG`, and `CALL LLM`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.