> For the complete documentation index, see [llms.txt](https://docs.kiloiot.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/ai-assistant/building-with-ai.md).
# Construir com o Assistente
Delegue o trabalho de configuração ao Assistente de IA do Kilo IoT — integre dispositivos, implemente regras com a sua CEL e configure alarmes.
O assistente pode configurar o Kilo por si, e não apenas responder a perguntas. Descreva o resultado de que precisa em linguagem simples e ele pode integrar dispositivos, criar regras, configurar alarmes e executar comandos de dispositivos existentes dentro das suas permissões. Esta página explica o que pode alterar e o que precisa de fornecer.
## Como funciona a execução
Quando pede ao assistente para configurar algo, ele não lhe dá uma lista de verificação para seguir. Executa a tarefa usando as operações reais da plataforma, em seu nome e dentro das suas permissões, e depois lê o resultado de volta para confirmar que funcionou. Dois princípios regem cada ação:
* **Aprova alterações com impacto.** Antes de qualquer coisa destrutiva ou difícil de reverter — eliminar um dispositivo ou regra, resolver um alarme — o assistente faz uma pausa e mostra uma confirmação com **Confirmar ação** e **Cancelar**. Quando precisa de uma decisão ou de um detalhe em falta a meio da tarefa, pergunta com um pedido estruturado em vez de adivinhar.
* **Verifica o próprio trabalho.** Depois de fazer uma alteração, volta a ler o objeto afetado para lhe poder dizer o que existe realmente agora, e não apenas o que pretendia fazer.
## Integrar um dispositivo
Descreva o dispositivo que quer adicionar e o assistente executa consigo o fluxo de integração — escolhendo o conector, atribuindo o nome ao dispositivo, capturando identificadores e selecionando o perfil certo. Para um dispositivo LoRaWAN, se fornecer o **DevEUI** e **AppKey** logo à partida, pode concluir a configuração automaticamente e depois executar diagnósticos para confirmar que o dispositivo está realmente a comunicar. Integra dispositivos MQTT e rastreadores da mesma forma.
### Endpoints MIOTY
O assistente pode comissionar um [endpoint MIOTY](/kilo-docs-pt/kilo-iot-server/devices/mioty-devices.md) numa ligação MIOTY existente e associar um [esquema](/kilo-docs-pt/kilo-iot-server/devices/mioty-blueprints.md), para que a sua carga útil seja descodificada em leituras nomeadas.
Antes de começar, crie a ligação MIOTY que irá transportar o endpoint. Depois, faça com que as informações do endpoint sejam fornecidas com o dispositivo:
* **EUI** — o identificador hexadecimal de 16 caracteres do dispositivo
* **Chave de sessão de rede** — o segredo hexadecimal de 32 caracteres usado para proteger a comunicação
* **Endereço curto**
* **Classe do endpoint** — **Z** para um endpoint apenas de uplink ou **A** para um endpoint bidirecional; o Kilo usa **Z** quando o omitir
* **Chave da aplicação**, se o endpoint usar uma
Diga ao assistente o que está a adicionar, que ligação MIOTY existente deve usar e onde o dispositivo pertence. Ele procura no catálogo do Sistema e no catálogo Personalizado da sua organização pelo fabricante, modelo e versões de blueprint disponíveis. Se houver mais do que uma correspondência possível, pede-lhe para escolher. Depois valida os detalhes do endpoint, resolve o Type EUI do modelo e regista o endpoint. Selecione um blueprint desse modelo quando a respetiva carga útil precisar de ser descodificada; o blueprint é opcional quando não é necessário nenhum descodificador.
> *"Registe o medidor de água MIOTY na Planta 2. O seu EUI é 70B3D5..., a sua Chave de sessão de rede é ..., o seu endereço curto é 0042 e é um endpoint de classe Z."*
> *"Adicione o novo sensor de CO2 no Lab 2. DevEUI 24E124..., AppKey ..."* O assistente provisiona o dispositivo, associa-o e verifica se os dados estão a chegar — assinalando-o se o dispositivo continuar em silêncio.
O resultado é um endpoint registado. Quando seleciona um blueprint, as respetivas leituras usam os nomes de campos definidos por esse blueprint. O assistente não inventa identificadores ou chaves em falta; pede qualquer valor necessário que não tenha fornecido.
## Criar e implementar uma automatização
Esta é a capacidade mais poderosa do assistente. Descreva o comportamento que quer em linguagem simples, e ele **redige a regra completa — incluindo as** [**CEL**](/kilo-docs-pt/kilo-iot-server/rules-engine/cel-reference.md) **expressões — constrói-a, testa-a e implementa-a.**
> *"Alerta o engenheiro de prevenção se qualquer congelador no Cold Storage A permanecer acima de −18 °C durante mais de dez minutos."* O assistente concebe a lógica da regra, escreve a condição como uma expressão CEL, simula-a com um valor correspondente e com um valor não correspondente para provar que dispara corretamente e, em seguida, implementa-a — mostrando-lhe cada passo.
Como a simula antes de afirmar sucesso, não está a confiar numa caixa-preta: vê a regra disparar no caso que deve corresponder e manter-se silenciosa no caso que não deve. A partir daí, pode refiná-la em conversa ("faz quinze minutos", "notifica também o gestor da instalação") e o assistente atualiza-a e volta a implementá-la.
Para conhecer o próprio motor de regras, consulte [Rules Engine](/kilo-docs-pt/kilo-iot-server/rules-engine.md). O assistente é uma forma rápida de produzir um primeiro rascunho correto — ou uma regra final — sem construir manualmente a tela.
## Configurar alarmes e acesso
* **Alarmes** — Peça-lhe para criar uma definição de alarme com severidade e uma cadeia de escalonamento, e ele configura os destinatários, canais e passos. Também pode resolver um evento de alarme (com a sua confirmação) quando lhe disser que a situação está tratada.
* **Equipa** — Pode convidar um utilizador e atribuir uma função, pelo que integrar um novo operador ou contratante é uma frase em vez de uma sequência de ecrãs.
* **Hardware** — Pergunte que sensor se adequa a um objetivo e ele recomenda opções compatíveis retiradas do catálogo do parceiro e das referências atuais, para que esteja a escolher hardware real e adequado em vez de uma lista genérica.
## Executar um comando de dispositivo
O assistente pode operar o seu equipamento, e não apenas descrevê-lo. Pergunte o que um dispositivo pode fazer e ele lista os comandos configurados nele; peça-lhe para executar um e ele executa-o — depois de lhe mostrar o que está prestes a enviar e de aguardar a sua confirmação.
> *"Que comandos estão disponíveis no controlador da câmara fria?"* *"Defina o intervalo de reporte para cinco minutos."* O assistente lista os comandos do dispositivo, mostra os parâmetros que vai usar, pede-lhe para confirmar, envia-os e depois indica se foi entregue.
Três coisas regem isto, e são elas que tornam seguro entregar a uma IA um edifício:
* **Executa comandos que já existem.** Os comandos são definidos uma vez no separador do dispositivo **Comandos e estados** com parâmetros tipados e verificação opcional. O assistente executa essas definições — não inventa novas nem improvisa uma carga útil.
* **Pergunta sempre primeiro.** A execução de comandos tem efeitos físicos reais, por isso cada um passa por uma confirmação explícita.
* **Verifica o resultado.** A entrega é assíncrona, por isso, depois de enviar, o assistente indica o estado da execução em vez de assumir sucesso. O dispositivo também tem de estar online para receber o comando.
Isto aplica-se a dispositivos que, à partida, podem receber downlinks — dispositivos MQTT, dispositivos LoRaWAN de Classe C e dispositivos emulados com **Comandos de suporte** ativados. Um sensor LoRaWAN de Classe A só abre uma breve janela de receção após cada uplink, pelo que não está disponível para controlo a pedido. Veja [Comandos de dispositivo](/kilo-docs-pt/kilo-iot-server/devices/commands.md).
## Configurar um gateway
Peça ao assistente para adicionar um gateway e ele trata da parte da plataforma por si — registando-o e produzindo os detalhes de ligação de que o hardware precisa. Depois diz-lhe exatamente o que introduzir no próprio gateway, uma vez que esse último passo acontece na configuração do gateway e não no Kilo.
## Conduzir o emulador
O assistente pode executar todo o [dispositivo emulado](/kilo-docs-pt/kilo-iot-server/devices/emulated-devices.md) fluxo de trabalho em conversa: listar as predefinições de dispositivo disponíveis, provisionar um dispositivo a partir de uma predefinição ou das métricas que descrever, ler e alterar a configuração e o intervalo de reporte, e enviar uma leitura única para testar uma regra. Também pode colocar o dispositivo em funcionamento numa ligação real **LoRaWAN** quando o hardware chegar, e mover um dispositivo real para o Emulador para reproduzir algo. Outros tipos de conector são uma troca manual no separador Ligação do dispositivo.
> *"Crie um sensor de qualidade do ar emulado no Cold Room 3 e envie uma temperatura de −20."* Um dispositivo que reporta por si, pronto para os painéis e regras que está prestes a criar.
## O que constrói versus o que opera
A distinção que vale a pena manter é entre as automatizações que o assistente *escreve* e os comandos que *executa*.
A **automatizações** que ele constrói monitorizam e alertam. Uma regra que atua por si fá-lo através do nó Execute Command do próprio Rules Engine, que adiciona deliberadamente — o assistente não faz com que uma regra atue como efeito colateral de lhe pedir uma.
E nada aqui substitui o caminho manual: o separador do dispositivo e um widget de controlo num painel continuam disponíveis para operação com um toque. **Comandos e estados** separador [widget de controlo](/kilo-docs-pt/kilo-iot-server/dashboards/adding-widgets/control-widget.md) continuam disponíveis para operação com um toque.
## Dicas para delegar bem
* **Indique o resultado, não os cliques.** "Integrar este sensor e colocá-lo no painel do Lab 2" é melhor do que uma instrução passo a passo — o assistente conhece os passos.
* **Dê-lhe os detalhes de que precisa.** Identificadores, limiares, durações e destinatários antecipadamente significam menos idas e voltas.
* **Leia a confirmação antes de aprovar.** O cartão de confirmação detalha a alteração; é a sua última verificação antes de acontecer alguma coisa.
* **Itere.** Trate o primeiro resultado como um rascunho que pode refinar na mesma conversa.
## Ver também
* [Trabalhar com o Assistente](/kilo-docs-pt/kilo-iot-server/ai-assistant/querying-your-data.md) — o lado de pedir e analisar
* [Comandos de dispositivo](/kilo-docs-pt/kilo-iot-server/devices/commands.md) — definir os comandos que o assistente pode executar e executá-los manualmente
* [Rules Engine](/kilo-docs-pt/kilo-iot-server/rules-engine.md) — a superfície de automatização que o assistente constrói
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.kiloiot.io/kilo-docs-pt/kilo-iot-server/ai-assistant/building-with-ai.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
