Gemini AI Assistant
The Gemini AI Assistant component integrates Google's Gemini generative AI models into the Banalytics Agent. It gives operators a chat-based interface for inspecting and controlling selected Components, Tasks, and Actions through natural language commands.
Natural language control for the running agent
Gemini component connects to the Google Generative Language API, builds a system prompt from the current Banalytics topology, keeps conversation history, and executes parsed command tags returned by the model. Users can ask about component state, open video streams, start and stop exposed components, invoke action tasks, and open configuration editors from the chat UI.
Gemini API
The component sends user messages and selected context to the configured Gemini model through the Generative Language REST endpoint.
Agent context
The prompt is generated from Components, Tasks, and Actions that have aiControlEnabled = true.
Action execution
Model responses can include structured action tags that the server parses and executes against the engine.
Adding a Gemini assistant
Provide a Google Gemini API key
Configure the API key and make sure the agent has outbound HTTPS access to generativelanguage.googleapis.com. Model discovery uses the same key.
Select the model
The model dropdown is populated from the Google model-list endpoint. Use a fast model for frequent operator chat, and a stronger model when the prompt includes many components or requires careful reasoning.
Define the AI-control boundary
Enable AI control only on Components, Tasks, and Actions that the assistant is allowed to inspect or operate. Keep risky infrastructure components hidden unless the use case requires them.
Start manually and test
The component is not autostarted by default. Start it after verifying the API key, selected model, permissions, and prompt exposure rules.
Use cases for controlled AI access
Operator assistant
Expose selected cameras, tasks, dashboards, and action tasks so operators can ask for status, open streams, start tasks, or stop components by name.
Read-only helper mode
Keep risky actions and infrastructure Things with aiControlEnabled = false, and expose only diagnostic components and safe views.
Maintenance console
Expose predefined recovery actions so the assistant can invoke approved procedures instead of receiving broad access to arbitrary low-level operations.
Useful local commands
List Things locally
Returns agent state without calling Gemini. Use it to verify visibility and component names.
List Tasks locally
Shows task state without sending a model request, useful when external AI access is slow or unavailable.
Show available chat commands
Displays built-in help and keeps the diagnostic path independent from the external API.
Tuning model behavior and context size
The assistant's usefulness depends on the selected model, the exposed topology, and the quality of component descriptions. Keep the prompt focused by exposing only the components that matter for the operational scenario.
systemPromptExtra for site vocabulary, naming conventions, safety rules, and operator preferences.maxHistoryMessages controls how much conversation is sent back to Gemini. Higher values increase memory use and request size.refreshContext after changing descriptions, AI-control flags, or topology while the assistant is running.Configuration parameters
| Parameter | Required | Description | Default |
|---|---|---|---|
ID | Yes | A unique identifier automatically generated for this component instance. Read-only. | Auto |
Title | Yes | Display name of the AI assistant instance inside Banalytics. GeminiThing is uniqueness-keyed by title. | None |
Gemini API Key | Yes | Google Gemini API key. It is entered as a password field and changing it restarts the component. | None |
Model | Yes | Fully qualified model name returned by the Generative Language API, for example models/gemini-.... The models/ prefix is stripped before use. Changing the model restarts the component. | From API |
Max conversation history messages | Yes | Maximum number of conversation messages retained for model context. Allowed range is 10-500. The visible chat log retains up to 3 * maxHistoryMessages entries. | 50 |
Additional system prompt instructions | Optional | Additional custom instructions appended to the generated system prompt. Use it for local terminology, safety constraints, and operator rules. | None |
Methods available through Thing call
| Method | Required input | Description | Notes |
|---|---|---|---|
command | command | Sends a user message to the assistant. Slash commands are handled locally; other messages are sent to Gemini. | Main chat entry point |
history | Optional | Returns chat history. Optional fromLine returns only entries with lineNumber > fromLine. | Incremental UI polling |
status | None | Returns assistant status including whether it is alive, current model, and history size. | Diagnostics |
clearHistory | None | Clears both model conversation history and visible chat log, then resets line numbering. | Does not change runtime state |
refreshContext | None | Rebuilds the system prompt from the current Things, Tasks, and Actions topology. | Does not clear history |
How model output becomes agent actions
The model is instructed to emit structured tags such as [ACTION:TYPE:parameters]. GeminiThing parses supported tags and executes them server-side.
uuid|method|key=value,... syntax for simple parameters.Operational notes and troubleshooting
API key or model errors
If Gemini returns an error, check API key validity, quota, outbound network access, and whether the selected model is available for the key.
History and memory use
Increasing maxHistoryMessages increases conversation context, visible chat log size, memory use, and request payload size.
Autostart carefully
The component defaults to autostart = false and STOP_ON_FAILURE. Enable autostart only after validating API access, permissions, and exposure rules.
Related automation and AI pages
Use these pages to decide what the assistant can see, which actions it may invoke, and how operators monitor the result.