- Essentials
- How flespi AI agents work
- Connectors
- Operation approvals
- Communicating with the agent
- Monitoring and logs
- Credits and limits
- Agents API
Essentials
A flespi AI agent is an autonomous AI worker living in your account. You describe what you need in natural language — the agent plans the work, uses the systems you connected it to, reports back, and asks for your approval before performing sensitive actions.
Compared to the AI assistant in the flespi support chat, an agent does more than answer questions: it acts on your behalf, proactively monitors what you entrust to it, and keeps its own memory and working state across days of work. Compared to general-purpose AI agents, it knows flespi and telematics deeply out of the box — and it is safe by design: every account-changing action passes through the platform security layers and your approval rules, so the agent cannot harm your account or act beyond its boundaries.
Typical work to hand over: keeping your flespi account in good shape, discussing and implementing your telematics project, watching the flespi changelog and surfacing only the changes that affect your setup, or running the correspondence with a device manufacturer's support on your behalf.
flespi AI agents are experimental and under active development: the functionality is currently available to selected accounts, and details described here may change.
How flespi AI agents work
An agent lives in a sleep-wake cycle. It sleeps until something wakes it up: your message, an event in a connected system (an incoming email or Telegram message, a change in your flespi account it watches), a wake-up it scheduled for itself, or your decision on a pending approval request.
Once awake, the agent thinks in reasoning steps. A reasoning step is one full turn of the AI model: the agent analyzes the situation, uses the tools of its connectors, and communicates the results. A task typically takes one reasoning step; a complex one, or one requiring the agent to switch on additional capabilities, may take 2–3. An agent settled into its work often handles a task in a single step — even several related requests at once, when they arrive together.
Within a step the agent works with data freely: it calls the flespi REST API, creates and runs scripts on demand, and processes the results computationally. The agent can also bind such scripts as handlers to MQTT topics or timers: a handler is not a reasoning step — it watches, filters, and computes on its own, and triggers a reasoning step only when the condition the agent defined for it is met. This computational processing is not charged: only reasoning steps consume AI credits.
Every action that changes the external environment — a flespi API call that modifies something, an outgoing email, a Wialon account change — passes through the agent operations ACL: depending on the rule you set, the operation executes automatically, is denied, or becomes an approval request. Read-only operations run free and unrestricted: the agent explores as much as it needs, while you control everything it changes.
Connectors
A freshly created agent has no access to anything — connectors give it capabilities. A connector holds the credentials and configuration for one external system and brings the agent the tools and expertise to work with it. Connectors are created separately and assigned to the agent; you can assign and unassign them at any time.
| Connector | What it gives the agent |
| flespi | Binds the agent to a flespi account: platform expertise plus API access with the provided token. The agent becomes a solutions architect and operator of the account. |
| telegram | A Telegram bot identity: talk to the agent in a private chat or invite it to groups; the private chat also delivers approval prompts. |
| slack | A Slack app identity: work with the agent in your Slack workspace, alone or with your team; direct messages also deliver approval prompts. |
| An email account: the agent runs correspondence on your behalf and can watch the inbox for incoming mail. | |
| wialon_hosting | Access to a Wialon Hosting account: Wialon expertise plus direct work with the account data. |
Each connector type is covered in detail in its dedicated article.
The flespi connector is the main one: it makes the agent an expert on the flespi platform and an operator of your account. Provide it with a token — a master token is appropriate here, because the agent works on your behalf and its account-changing API calls are guarded separately: reads run freely, while every modifying call requires your approval by default.
Operation approvals
Approvals are the safety mechanism that keeps you in control. Each connector declares its sensitive operation types — for example, a modifying flespi API call or an outgoing email — and for each one its configuration sets a rule: allow (execute silently), ask (request your approval), or deny. The defaults are conservative: account-changing operations ask for approval.
When an operation hits an "ask" rule, the agent pauses it and creates an approval request. Pending requests are visible in the flespi panel, in the "approvals" field of the agent, and as Approve/Reject prompts in the linked Telegram chat or Slack direct messages. A request resolved anywhere is resolved everywhere.
A granted operation is executed by the agent at its next reasoning step. A rejected one is discarded — the agent learns the outcome together with the reason you provide. A request left unresolved is rejected automatically once the approval window passes (one hour by default).
To follow approvals live over MQTT: each pending request is published to a retained flespi/state/ai/agents/{agent-id}/approvals/{timestamp} topic, cleared on resolution, and the flespi/log/ai/agents/{agent-id}/approvals/# topics stream the lifecycle records.
Communicating with the agent
Talk to the agent the way that suits you:
- in the flespi panel chat;
- via REST API: send with POST /ai/agents/{selector}/message, read the conversation history with GET /ai/agents/{selector}/messages;
- in Telegram or Slack, when the corresponding connector is assigned.
The conversation is also streamed over MQTT: the flespi/message/ai/agents/{agent-id}/history topic carries every history record — the messages exchanged and the operations performed.
Monitoring and logs
The agent continuously reports what it is up to via its runtime fields: title (the current task), status (what it is doing or waiting on), sleep (when it wakes up next), steps, and approvals_count. For example: GET /ai/agents/all?fields=id,name,status,approvals_count. The same fields are published as retained MQTT topics under flespi/state/ai/agents/{agent-id}/, one topic per field — subscribe to follow the agent state live.
Every important event is recorded in the agent logs, available in Toolbox and via GET /ai/agents/{selector}/logs: configuration changes, connector assignments, each reasoning step with its charge and outcome, and the approval lifecycle. The same records stream over MQTT in the flespi/log/ai/agents/{agent-id}/# topics.
Credits and limits
Each reasoning step costs 50 AI credits, charged before the step executes. Everything inside the step — AI model usage, tool calls, operations — costs no extra. The charge of a failed step is refunded automatically.
When the account has no credits available, the agent does not lose its task: the step is delayed and retried until the charge succeeds. Reasoning steps also count toward the per-minute ai_calls rate limit.
The number of agents in an account is a plan limit — see how flespi pricing works.
Agents API
Agents and connectors are regular flespi platform items managed via the /ai/agents and /ai/connectors REST APIs — everything described above is available programmatically. See flespi API basics for general API usage, and the flespi AI integration article for the other side of the AI story: connecting your own AI tools to flespi via MCP, REST tools, and skills.