Configure with the Smart Assistant

In this tutorial you will use the Smart Assistant app to build a working piece of configuration from a single sentence, watch the agent stream its reply live, approve a gated operation, and then diagnose an entity that is in an error state. By the end you will have produced a real dashboard card without opening a builder by hand, and you will know how to inspect what the agent did.

What you'll need

• A running ControlBird node where you can open the Smart Assistant app.
• An LLM provider credential. This tutorial uses Anthropic (the default), so you will need an ApiKey and a Model identifier such as claude-sonnet-4-20250514.
• At least one entity to work with, for example a pump or sensor, so the agent has something to attach a card to and, later, something to diagnose.
• A few minutes. A single build prompt typically completes in seconds.

Step-by-step

1. Open the Smart Assistant. Launch the Smart Assistant app from the ControlBird applications menu. It loads any provider configurations and saved sessions you already have.

   Expected result: the app opens. If no provider is configured yet, you are prompted to create one before you can send a message.

2. Configure a provider. Open the provider settings dialog (the Settings button, or press Ctrl/Cmd+,) and create a new provider. Set the provider type to Anthropic, paste your API key, and choose a model. Leave the temperature at its default of 0.3 for deterministic configuration generation, and leave the max-tokens and system-prompt fields at their defaults to use the built-in values.

   Expected result: for an Anthropic provider with a valid key, the available-models list populates automatically so you can pick a model from a dropdown.

3. Create or select a session. Pick an existing session from the sidebar, or start a fresh one with Ctrl/Cmd+N. Give it a meaningful name such as Pump Dashboard so you can find it again later. If you had no providers a moment ago, the app creates a session for you once one is configured.

   Expected result: a session appears in the sidebar, marked idle, with an empty conversation pane showing suggested prompts (Status Card, Gauge Display, Faceplate, Schematic, From Drawing).

4. Send your first build prompt. Type a plain-language request into the input area, for example:

   Create a status card for my pump

   Press Enter to send (use Shift+Enter for a new line, or Esc to clear the input).

   Expected result: the session moves to a processing state and your message is saved to the conversation.

5. Watch the response stream. As the model replies, the app renders the assistant message live, scrolling to the bottom as it grows. Behind the scenes the agent may call tools to do the work, for example creating a dashboard card. Each tool call and its result is recorded in the conversation.

   Expected result: when the turn finishes, the session returns to idle and a card now exists on your dashboard.

6. Approve a gated operation (if prompted). Some tools change infrastructure and require your approval, such as installing an extension, creating devices, or applying certain configuration patches. If the agent calls one, the session pauses and asks you to confirm. Read the risk explanation, then approve or reject the action.

   Expected result: if you approve, the agent resumes and runs the tool; if you reject, the operation is skipped and the conversation continues.

7. Refine in the same session. Configuration is conversational. Follow up with another prompt to adjust what you just built, for example:

   Make it a gauge from 0 to 5000 RPM instead

   The agent keeps the conversation context, so it understands "it" refers to the card from the previous turn.

   Expected result: the existing card is updated rather than a second one created.

8. Diagnose an entity in error. Switch tasks and ask a troubleshooting question, naming the entity you are worried about:

   Why is this entity in an error state?

   The agent walks the entity health chain, resolves error fields, and reports back in plain language. This is a read-only diagnostic flow, so no approval is required.

   Expected result: a written explanation of the fault and, often, a suggested fix you can ask the agent to apply.

9. Inspect what the agent did. Open the Database Browser and navigate to your session. The messages beneath it make up the whole conversation. Open one to review its content and token counts, and for tool calls the tool name, its input, and its output. The session also tracks total tokens used so you can see the running cost.

   Expected result: a complete, saved audit trail of every message and tool call.

If something goes wrong

• The session shows an error. The app surfaces the failure message as an error banner, and the session records the last error so you can review what went wrong.
• No models appear in the dropdown. The model list only auto-populates for Anthropic providers with a valid API key. For OpenAI, Ollama, GLM, and Custom providers you type the model name manually. You can also refresh the provider to re-fetch the list.
• Ollama or Custom provider fails to connect. Both need a base URL pointing at your endpoint; without it the provider cannot reach a model.
• A complex request stops part-way. Tool-call chains are bounded so a runaway request cannot loop forever. Break a very large request into smaller follow-up prompts.
• An attached image is rejected. Very large or high-resolution images can exceed the model's input limits. Keep sketches and photos reasonably sized.

Next steps

You have built and diagnosed configuration from natural language. From here:

• Read the Smart Assistant reference for the full list of tools and every provider option.
• Inspect agent activity and any other entity tree in the Database Browser.
• Try the From Drawing workflow: paste or drag a PNG/JPG sketch into the input and ask the agent to convert it into configuration.