> 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/de/anleitungen/ai-agents/run-an-agent.md). # Einem Agenten eine Anmeldeinformation geben, ohne sie offenzulegen Einem KI-Agenten erlauben, eine Anmeldeinformation aus Ihrem Tresor über devo secret run zu verwenden, sodass der Wert nie in seiner Unterhaltung oder seinem Transkript erscheint. Ein Agent, der ein Passwort liest, legt es in seinen Kontext: Der Wert kann im Transkript, in Protokollen oder in einer späteren Antwort landen. Mit Devolutions CLI braucht der Agent den Wert nie. Er arbeitet mit Referenzen `devo://`, die sagen, wo ein Geheimnis liegt, und von sich aus nichts öffnen, und er startet seine Werkzeuge über `devo secret run`, das die Werte nur an dieses Werkzeug übergibt. ## Bevor Sie beginnen * Devolutions CLI ist auf dem Computer installiert, auf dem der Agent Befehle ausführt, und Sie sind angemeldet. Der Agent verwendet Ihren aktuellen Kontext. Siehe [Schnellstart](/cli/de/quick-start.md). * Der Agent kann Shell-Befehle ausführen, zum Beispiel ein Coding-Agent, der in Ihrem Terminal arbeitet. ## So funktioniert es 1. Der Agent fragt Devolutions CLI nach den Referenzen eines Eintrags. Die Antwort enthält keinen geheimen Wert. 2. Der Agent schreibt einen Befehl, der jede Referenz einer Umgebungsvariable zuordnet, und führt ihn über `devo secret run` aus. 3. Devolutions CLI liest die Werte aus Ihrem Tresor, startet das Tool mit diesen Variablen und ersetzt jeden aufgelösten Wert durch `` in der Ausgabe des Tools. Der Agent sieht die Ausgabe des Tools, nie das Geheimnis. ## Den Agenten Referenzen finden lassen Zwei Befehle listen die Referenzen eines Eintrags auf, ohne einen Wert zurückzugeben. Sie geben dieselben Daten zurück, verwenden Sie also den, der sich in Ihren Anweisungen besser liest. Nur der Wert `command` des JSON-Umschlags unterscheidet sich: `secret.catalog.entry` oder `entry.references`. ```bash devo secret catalog entry "" --vault-name "" --json devo entry references "" --vault-name "" --json ``` Mit `--json` hat jedes Element in `data.references` ein `field` (etwa `password`) und eine `reference` zum Kopieren. Siehe [Die Referenz zu einem Geheimnis finden](/cli/de/anleitungen/secrets/find-a-reference.md). {% hint style="info" %} Sie können die Referenzen auch selbst finden und sie in die Anweisungen des Agenten oder in eine `.env`-Datei setzen. Referenzen können gefahrlos weitergegeben werden: Sie enthalten Namen oder IDs, keine Werte. {% endhint %} ## Den Agenten Werkzeuge starten lassen Der Agent übergibt jede Referenz mit `--env-ref NAME=`. Alles nach `--` ist das auszuführende Werkzeug: ```bash devo secret run --env-ref DB_PASSWORD= -- ``` Ein paar Dinge, die der Agent wissen muss, weil Devolutions CLI sie erzwingt: * **Referenzen gehören in `--env-ref`, nie in die Argumente des Befehls.** Devolutions CLI lehnt eine nach `--` geschriebene Referenz mit dem Fehler `secretLaunchArgumentReference` ab. * **Wiederholen Sie `--env-ref` für mehrere Geheimnisse**, oder verwenden Sie `--env-file` mit einer `.env`-Datei, die Referenzen enthält. Siehe [Die Passwörter aus einer .env-Datei nehmen](/cli/de/anleitungen/secrets/replace-env-files.md). * **Zum Testen, ohne ein Geheimnis zu lesen,** fügen Sie `--check` hinzu. Devolutions CLI prüft, dass der Befehl vorhanden ist und dass jede Referenz wohlgeformt ist, ohne einen Wert aufzulösen oder das Tool zu starten. Es beweist nicht, dass jedes Feld gelesen werden kann. * **Um ein hängendes Werkzeug zu stoppen,** fügen Sie `--timeout-seconds ` hinzu. ## Die Anweisungen des Agenten schreiben Legen Sie Regeln wie diese in die Anweisungsdatei des Agenten (zum Beispiel die Agent-Anweisungen des Projekts oder `CLAUDE.md`) und passen Sie die Namen an Ihr Projekt an: ```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 ...`. ``` ## Warum nicht `devo secret read`? `devo secret read` und `devo secret get` geben den Wert aus. Was ein Agent ausgibt, landet in seinem Kontext, sodass das Geheimnis Teil der Unterhaltung wird. `devo secret inject` übergibt den Wert ebenfalls: Es schreibt den ausgefüllten Text auf die Standardausgabe oder in eine Datei mit `--out-file`. Auf der Standardausgabe landet der Wert direkt im Kontext des Agenten; in einer Datei kann der Agent sie öffnen. `devo secret shell enter` legt den Wert in die Shell des Agenten. `devo secret run` ist der einzige Befehl, der den Wert einem Programm übergibt, ohne ihn demjenigen zu zeigen, der es gestartet hat. {% hint style="warning" %} Anweisungen sind eine Orientierung, kein Schloss. Ein Agent, der Shell-Befehle wie Sie ausführen kann, kann auch `devo secret read` ausführen, weil er denselben Zugriff auf Ihren Tresor hat wie Sie. Um die Regel durchzusetzen, verwenden Sie die Befehlsberechtigungen Ihres Agenten: Erlauben Sie `devo secret run`, und blockieren Sie `devo secret read`, `devo secret get`, `devo secret inject` und `devo secret shell`. {% endhint %} {% hint style="warning" %} Die Maskierung schützt, was das Werkzeug ausgibt, nicht was es tut. Ein Werkzeug, das ein Geheimnis erhält, kann es trotzdem in eine Datei schreiben, über das Netzwerk senden oder in einer anderen Form ausgeben, zum Beispiel kodiert. Die Maskierung kann mit `--no-masking` ausgeschaltet werden, lassen Sie diese Option also aus den erlaubten Befehlen Ihres Agenten heraus. Siehe [Was verborgen bleibt und was nicht](/cli/de/anleitungen/understand/security-model.md). {% endhint %} ## Gut zu wissen * `devo secret run` gibt den Exitcode des Werkzeugs zurück, das es gestartet hat, damit der Agent erkennen kann, ob sein Befehl erfolgreich war. * Eine Referenz, die sich nicht auflöst, stoppt den Start, bevor das Werkzeug startet. Siehe [Eine Geheimnisreferenz wird nicht aufgelöst](/cli/de/hilfe/troubleshooting/reference-does-not-resolve.md). * Wenn der Agent an einem anderen Workspace als dem aktuellen arbeitet, kann er `--context ` zu einem beliebigen `devo`-Befehl hinzufügen. Siehe [Zwischen Workspaces wechseln](/cli/de/anleitungen/connect/switch-workspaces.md). ## Weiter * [Run a command with its secrets](/cli/de/anleitungen/secrets/run-with-secrets.md) * [Connect an AI client with MCP](/cli/de/anleitungen/ai-agents/connect-mcp.md) * [Limit what an agent can do](/cli/de/anleitungen/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/de/anleitungen/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.