> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/cli/it/guide/ai-agents/run-an-agent.md). # Dare una credenziale a un agente senza esporla Consentire a un agente IA di usare una credenziale della cassaforte tramite devo secret run, così il valore non compare mai nella sua conversazione né nella sua trascrizione. Un agente che legge una password la mette nel suo contesto: il valore può finire nella trascrizione, nei log o in una risposta successiva. Con Devolutions CLI l’agente non ha mai bisogno del valore. Lavora con riferimenti `devo://`, che dicono dove si trova un segreto e non aprono nulla da soli, e avvia i suoi strumenti tramite `devo secret run`, che consegna i valori solo a quello strumento. ## Prima di iniziare * Devolutions CLI è installato sul computer dove l’agente esegue i comandi, e lei ha eseguito l’accesso. L’agente usa il contesto corrente. Consulti [Avvio rapido](/cli/it/quick-start.md). * L’agente può eseguire comandi della shell, per esempio un agente di programmazione che lavora nel terminale. ## Come funziona 1. L’agente chiede a Devolutions CLI i riferimenti di una voce. La risposta non contiene alcun valore segreto. 2. L’agente scrive un comando che associa ogni riferimento a una variabile d’ambiente e lo esegue tramite `devo secret run`. 3. Devolutions CLI legge i valori dalla cassaforte, avvia lo strumento con quelle variabili e sostituisce ogni valore risolto con `` in ciò che lo strumento stampa. L’agente vede l’output dello strumento, mai il segreto. ## Lasciare che l’agente trovi i riferimenti Due comandi elencano i riferimenti di una voce senza restituire alcun valore. Restituiscono gli stessi dati, quindi usi quello che si legge meglio nelle istruzioni. Differisce solo il valore `command` della busta JSON: `secret.catalog.entry` o `entry.references`. ```bash devo secret catalog entry "" --vault-name "" --json devo entry references "" --vault-name "" --json ``` Con `--json`, ogni elemento di `data.references` ha un `field` (come `password`) e un `reference` da copiare. Consulti [Trovare il riferimento a un segreto](/cli/it/guide/secrets/find-a-reference.md). {% hint style="info" %} Può anche trovare i riferimenti da solo e metterli nelle istruzioni dell’agente o in un file `.env`. I riferimenti si possono condividere senza rischio: contengono nomi o ID, non valori. {% endhint %} ## Lasciare che l’agente avvii strumenti L’agente passa ogni riferimento con `--env-ref NAME=`. Tutto ciò che segue `--` è lo strumento da eseguire: ```bash devo secret run --env-ref DB_PASSWORD= -- ``` Alcune cose che l’agente deve sapere, perché Devolutions CLI le impone: * **I riferimenti vanno in `--env-ref`, mai negli argomenti del comando.** Devolutions CLI rifiuta un riferimento scritto dopo `--` con l’errore `secretLaunchArgumentReference`. * **Per più segreti, ripeta `--env-ref`**, oppure usi `--env-file` con un file `.env` che contiene riferimenti. Consulti [Togliere le password da un file .env](/cli/it/guide/secrets/replace-env-files.md). * **Per provare senza leggere alcun segreto,** aggiunga `--check`. Devolutions CLI verifica che il comando esista e che ogni riferimento sia ben formato, senza risolvere un valore né avviare lo strumento. Non dimostra che ogni campo possa essere letto. * **Per arrestare uno strumento che resta bloccato,** aggiunga `--timeout-seconds `. ## Scrivere le istruzioni dell’agente Metta regole come queste nel file di istruzioni dell’agente (per esempio le istruzioni dell’agente del progetto o `CLAUDE.md`) e adatti i nomi al progetto: ```markdown ## Credentials - Never read, print, or store a secret value. Never run `devo secret read`, `devo secret get`, `devo secret inject` or `devo secret shell`. - To find a credential, run `devo secret catalog entry "" --vault-name "" --json` and use the `reference` of the field you need. - To run a command that needs a credential, run: `devo secret run --env-ref NAME= -- ` and have the command read the value from the NAME environment variable. - Never put a `devo://` reference in the command's arguments. - Before a long or risky run, check it with `devo secret run --check ...`. ``` ## Perché non `devo secret read`? `devo secret read` e `devo secret get` stampano il valore. Qualunque cosa un agente stampi finisce nel suo contesto, quindi il segreto diventa parte della conversazione. `devo secret inject` consegna anch’esso il valore: scrive il testo compilato sullo standard output, oppure in un file con `--out-file`. Sullo standard output il valore arriva direttamente nel contesto dell’agente; in un file, l’agente può aprirlo. `devo secret shell enter` mette il valore nella shell dell’agente. `devo secret run` è l’unico comando che dà il valore a un programma senza mostrarlo a chi lo ha avviato. {% hint style="warning" %} Le istruzioni sono una guida, non un lucchetto. Un agente che può eseguire comandi di shell come lei può eseguire anche `devo secret read`, perché ha lo stesso accesso alla cassaforte. Per imporre la regola, usi le autorizzazioni dei comandi dell’agente: consenta `devo secret run` e blocchi `devo secret read`, `devo secret get`, `devo secret inject` e `devo secret shell`. {% endhint %} {% hint style="warning" %} Il mascheramento protegge ciò che lo strumento stampa, non ciò che fa. Uno strumento che riceve un segreto può comunque scriverlo in un file, inviarlo sulla rete o stamparlo in un’altra forma, per esempio codificato. Il mascheramento si può disattivare con `--no-masking`, quindi tenga quell’opzione fuori dai comandi consentiti all’agente. Consulti [Che cosa resta nascosto e che cosa no](/cli/it/guide/understand/security-model.md). {% endhint %} ## Buono a sapersi * `devo secret run` restituisce il codice di uscita dello strumento che ha avviato, così l’agente può capire se il suo comando è riuscito. * Un riferimento che non si risolve ferma l’avvio prima che lo strumento parta. Consulti [Un riferimento al segreto non si risolve](/cli/it/aiuto/troubleshooting/reference-does-not-resolve.md). * Se l’agente lavora su uno spazio di lavoro diverso da quello corrente, può aggiungere `--context ` a qualsiasi comando `devo`. Consulti [Passare da uno spazio di lavoro all’altro](/cli/it/guide/connect/switch-workspaces.md). ## Successivo * [Run a command with its secrets](/cli/it/guide/secrets/run-with-secrets.md) * [Connect an AI client with MCP](/cli/it/guide/ai-agents/connect-mcp.md) * [Limit what an agent can do](/cli/it/guide/ai-agents/limit-tools.md) --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.devolutions.net/cli/it/guide/ai-agents/run-an-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.