> 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/es/guias/ai-agents/run-an-agent.md). # Dar una credencial a un agente sin exponerla Permitir que un agente de IA use una credencial de su bóveda mediante devo secret run, de modo que el valor nunca aparezca en su conversación ni en su transcripción. Un agente que lee una contraseña la pone en su contexto: el valor puede acabar en la transcripción, en los registros o en una respuesta posterior. Con Devolutions CLI, el agente nunca necesita el valor. Trabaja con referencias `devo://`, que dicen dónde está un secreto y no abren nada por sí solas, e inicia sus herramientas mediante `devo secret run`, que entrega los valores solo a esa herramienta. ## Antes de empezar * Devolutions CLI está instalado en el ordenador donde el agente ejecuta los comandos, y usted ha iniciado sesión. El agente usa su contexto actual. Consulte [Inicio rápido](/cli/es/quick-start.md). * El agente puede ejecutar comandos de shell, por ejemplo un agente de programación que trabaja en su terminal. ## Cómo funciona 1. El agente pide a Devolutions CLI las referencias de una entrada. La respuesta no contiene ningún valor secreto. 2. El agente escribe un comando que asigna cada referencia a una variable de entorno y lo ejecuta a través de `devo secret run`. 3. Devolutions CLI lee los valores de su bóveda, inicia la herramienta con esas variables y sustituye cada valor resuelto por `` en lo que imprime la herramienta. El agente ve la salida de la herramienta, nunca el secreto. ## Dejar que el agente encuentre las referencias Dos comandos enumeran las referencias de una entrada sin devolver ningún valor. Devuelven los mismos datos, así que use el que se lea mejor en sus instrucciones. Solo difiere el valor `command` del sobre JSON: `secret.catalog.entry` o `entry.references`. ```bash devo secret catalog entry "" --vault-name "" --json devo entry references "" --vault-name "" --json ``` Con `--json`, cada elemento de `data.references` tiene un `field` (como `password`) y una `reference` para copiar. Consulte [Encontrar la referencia de un secreto](/cli/es/guias/secrets/find-a-reference.md). {% hint style="info" %} También puede encontrar las referencias usted mismo y ponerlas en las instrucciones del agente o en un archivo `.env`. Las referencias se pueden compartir sin riesgo: contienen nombres o identificadores, no valores. {% endhint %} ## Dejar que el agente inicie herramientas El agente pasa cada referencia con `--env-ref NAME=`. Todo lo que sigue a `--` es la herramienta que ejecutar: ```bash devo secret run --env-ref DB_PASSWORD= -- ``` Algunas cosas que el agente debe saber, porque Devolutions CLI las exige: * **Las referencias van en `--env-ref`, nunca en los argumentos del comando.** Devolutions CLI rechaza una referencia escrita después de `--` con el error `secretLaunchArgumentReference`. * **Para varios secretos, repita `--env-ref`**, o use `--env-file` con un archivo `.env` que contenga referencias. Consulte [Sacar las contraseñas de un archivo .env](/cli/es/guias/secrets/replace-env-files.md). * **Para probar sin leer ningún secreto,** añada `--check`. Devolutions CLI comprueba que el comando existe y que cada referencia está bien formada, sin resolver un valor ni iniciar la herramienta. No demuestra que cada campo se pueda leer. * **Para detener una herramienta que se queda colgada,** añada `--timeout-seconds `. ## Escribir las instrucciones del agente Ponga reglas como estas en el archivo de instrucciones del agente (por ejemplo las instrucciones de agente del proyecto o `CLAUDE.md`), y adapte los nombres a su proyecto: ```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 ...`. ``` ## ¿Por qué no `devo secret read`? `devo secret read` y `devo secret get` imprimen el valor. Todo lo que imprime un agente acaba en su contexto, así que el secreto pasa a formar parte de la conversación. `devo secret inject` también entrega el valor: escribe el texto rellenado en la salida estándar, o en un archivo con `--out-file`. En la salida estándar, el valor llega directamente al contexto del agente; en un archivo, el agente puede abrirlo. `devo secret shell enter` coloca el valor en el shell del agente. `devo secret run` es el único comando que da el valor a un programa sin mostrárselo a quien lo inició. {% hint style="warning" %} Las instrucciones son una orientación, no un cerrojo. Un agente que puede ejecutar comandos de shell como usted también puede ejecutar `devo secret read`, porque tiene el mismo acceso a su bóveda que usted. Para imponer la regla, use los permisos de comandos de su agente: permita `devo secret run`, y bloquee `devo secret read`, `devo secret get`, `devo secret inject` y `devo secret shell`. {% endhint %} {% hint style="warning" %} El enmascaramiento protege lo que imprime la herramienta, no lo que hace. Una herramienta que recibe un secreto puede aun así escribirlo en un archivo, enviarlo por la red o imprimirlo de otra forma, por ejemplo codificado. El enmascaramiento se puede desactivar con `--no-masking`, así que deje esa opción fuera de los comandos permitidos de su agente. Consulte [Qué permanece oculto y qué no](/cli/es/guias/understand/security-model.md). {% endhint %} ## Bueno saberlo * `devo secret run` devuelve el código de salida de la herramienta que inició, para que el agente pueda saber si su comando tuvo éxito. * Una referencia que no se resuelve detiene el inicio antes de que la herramienta arranque. Consulte [Una referencia de secreto no se resuelve](/cli/es/ayuda/troubleshooting/reference-does-not-resolve.md). * Si el agente trabaja en otro espacio de trabajo distinto del actual, puede añadir `--context ` a cualquier comando `devo`. Consulte [Cambiar entre espacios de trabajo](/cli/es/guias/connect/switch-workspaces.md). ## Siguiente * [Run a command with its secrets](/cli/es/guias/secrets/run-with-secrets.md) * [Connect an AI client with MCP](/cli/es/guias/ai-agents/connect-mcp.md) * [Limit what an agent can do](/cli/es/guias/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/es/guias/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.