Core
Agent IA v2.x
2

Kuzzle IA Agent 🚀 #

Kuzzle IA Agent is a conversational orchestrator embedded in the Kuzzle IoT Platform. It lets users interact with the platform in natural language: a user types a sentence in a chat box, and the agent classifies the request, runs the matching action, and returns the result.

Components #

The agent spans three services:

  • kuzzle-plugin-ag-ui — a Kuzzle plugin exposing the agent:run action. It relays front-end requests to the Python service and injects the security context (user identity, soft-tenants).
  • kuzzle-ai-agent — a Python service (FastAPI + LangGraph) that interprets the message, dispatches it to an intent handler, and renders the response.
  • kuzzle-iot-mcp-server — a FastMCP server exposing the tools the agent calls to read and write data in Kuzzle.
┌──────────────┐   agent:run   ┌──────────────┐   POST /agent/run   ┌──────────────────┐   MCP   ┌──────────────────────┐
│  Front (Vue) │ ────────────► │  kuzzle-api  │ ──────────────────► │ kuzzle-ai-agent  │ ──────► │ kuzzle-iot-mcp-server │
│  ChatLauncher│               │ (ag-ui plug) │                     │ (FastAPI + LG)   │         │ (FastMCP tools)       │
└──────────────┘               └──────────────┘                     └──────────────────┘         └──────────────────────┘

Conversation flow #

The agent graph has three core nodes:

  • understand — calls the LLM with a system prompt built dynamically from the registered intents, and classifies the message into an intent name with structured fields.
  • act — looks up the matching handler in the registry and invokes it. If the previous turn left a pending step, the registry resumes that step (multi-turn wizard).
  • respond — renders the result, including the dynamic help message.

State is persisted between turns by LangGraph's checkpointer, keyed by threadId.

Packs #

The agent boots with no capability. Features are added as packs, and a pack has two complementary halves:

  • An agent pack (loaded via KUZZLE_AGENT_PACKS) declares the intents: how the LLM recognises a request, the handler that runs it, optional multi-turn steps, and help entries.
  • An MCP pack (loaded via MCP_PACKS) declares the tools those intents call to interact with Kuzzle.

A pack may ship only one half — an intent that needs no new tool (it returns a static reply or reuses core tools) needs only the agent side; a tool reused by several intents may live in an MCP pack alone.

Both sides fail fast at boot: the agent registry rejects duplicate intent names, and the MCP server rejects duplicate tool names (on_duplicate_tools="error"). MCP tools are namespaced with the pack id (e.g. hello_say_hello) to avoid collisions.

Dynamic help #

When the user asks for help, the agent returns the list of built-in capabilities followed by the help entries declared by every loaded pack. Each pack contributes its own lines through Pack.help_entries, so the help message always reflects the features actually installed — no central list to maintain.