Einen ADK-Rust-Agenten über ACP bereitstellen

Verwenden Sie den Serveransatz, wenn ein Editor oder ein anderer ACP-Client Ihre ADK-Rust-Binärdatei starten und ihren Agenten innerhalb einer Programmierschnittstelle verwenden soll. Ihr Rust-Prozess verwaltet den Agenten, das Modell, die Tools, Workflows, Sitzungen, den Speicher und die Betriebsrichtlinie. Der Client sieht nur die über ACP veröffentlichten Funktionen und den Lebenszyklus der Sitzung.

Die Serverfunktion installieren

[dependencies]
adk-acp = { version = "2.1.0", features = ["server"] }

Einen Agenten erstellen und bereitstellen

use adk_acp::server::{AcpServer, AcpServerConfigBuilder};
use adk_session::InMemorySessionService;
use std::sync::Arc;

let config = AcpServerConfigBuilder::new()
    .agent(Arc::new(repository_agent))
    .session_service(Arc::new(InMemorySessionService::new()))
    .agent_name("repository-guide")
    .agent_description("Explains and improves this Rust workspace")
    .max_sessions(16)
    .build()?;

let handle = AcpServer::run(config).await?;
handle.wait().await?;

Der Server verwendet den offiziellen SDK-Builder Agent und den stdio-Transport. Protokollverkehr wird ausschließlich in stdout geschrieben; konfigurieren Sie Tracing und Diagnose so, dass sie stderr verwenden.

Laufzeitzuordnung

Rendering architecture…

Der Handler validiert ein absolutes cwd, reserviert Sitzungskapazität, erstellt die ADK-Sitzung oder setzt sie fort und führt den konfigurierten Agenten aus. Typisierte ADK-Ereignisse werden während der aktiven Eingabeaufforderung in ACP-session/update-Benachrichtigungen übersetzt.

Implementierter Lebenszyklus

Nur eine Eingabeaufforderung darf gleichzeitig in einer Sitzung ausgeführt werden. Verschiedene Sitzungen können bis zu max_sessions gleichzeitig ausgeführt werden.

Ereigniszuordnung

• Modelltext wird zu agent_message_chunk;
• Gedankeninhalt des Modells wird zu agent_thought_chunk;
• Inhalt eingebetteter Ressourcen wird zu einer eingebetteten Ressourcen-agent_message_chunk von ACP;
• ADK Funktionsaufrufe werden zu ACP-Aktualisierungen zum Werkzeugstart mit einem abgeleiteten Werkzeug-kind;
• Funktionsantworten werden zu Aktualisierungen zum Werkzeugabschluss, die um den Ergebnisinhalt und alle betroffenen Dateispeicherorte angereichert und dem ursprünglichen Werkzeugaufruf zugeordnet werden;
• Ereignisse mit Nutzungsmetadaten werden zu UsageUpdate-Benachrichtigungen (Tokenanzahlen sowie Kosten in USD, sofern gemeldet);
• vom Agenten deklarierte Befehle werden zu einem AvailableCommandsUpdate, sobald eine Sitzung aktiv wird, und ein aufgezeichneter Sitzungstitel wird zu einem SessionInfoUpdate;
• Planeinträge würden zu einer Plan-Aktualisierung werden — diese Zuordnung ist vorhanden, bleibt jedoch inaktiv, bis ein ADK-Plan-Grundelement Planeinträge bereitstellt;
• Abbruch wird zu StopReason::Cancelled;
• normaler Abschluss wird zu StopReason::EndTurn.

Ein gemeinsam genutztes Inhaltsmodul verwaltet die Zuordnung ContentBlock ↔ adk_core::Part in beide Richtungen. Eingebettete Ressourceninhalte von Prompts werden Part::EmbeddedResource zugeordnet, wobei die ursprüngliche URI, der optionale MIME-Typ und die Inhalte erhalten bleiben; Textressourcen werden unverändert beibehalten, während binäre Ressourcen über die Leitung base64-codiert und intern in rohe Bytes decodiert werden. Bild- und Audioinhalte von Prompts werden Part::InlineData zugeordnet, wobei der MIME-Typ, die decodierten Bytes, Annotationen und die optionale Quelle URI eines Bildes erhalten bleiben. Diese Felder verbleiben in der Sitzung JSON und werden von session/load wiederhergestellt. Da der Prompt-Handler eingebettete Ressourcen, Bild- und Audioinhalte akzeptiert, gibt der Server die Prompt-Funktionen embedded_context, image und audio bekannt. Ein Prompt mit einem Inhaltstyp, den der Server nicht bekannt gegeben hat, wird mit einem aussagekräftigen Fehler abgelehnt, statt teilweise verarbeitet zu werden.

Laden und Wiedergeben des Verlaufs

session/load stellt den sichtbaren Verlauf einer gespeicherten Sitzung wieder her, wenn ein Client die Verbindung erneut herstellt. Der Handler aktiviert die Sitzung auf dieselbe Weise wieder, wie session/resume dies tut — er überprüft, dass der Aufrufer die ursprüngliche cwd angegeben hat, und gibt bei einer unbekannten Kennung einen Fehler für eine nicht gefundene Sitzung zurück — und führt anschließend einen Wiedergabedurchlauf aus. Er liest die gespeicherten Ereignisse über den Sitzungsdienst und ordnet jedes gespeicherte Benutzer-, Agenten-, Gedanken- und Tool-Ereignis der entsprechenden session/update-Benachrichtigung in der ursprünglichen chronologischen Reihenfolge zu, bevor die Ladeanforderung abgeschlossen wird. Der Server gibt die Funktion load_session bekannt, damit ein Client weiß, dass er die Verbindung erneut herstellen und die Ansicht der Unterhaltung wiederaufbauen kann.

Sitzungsmodi, Konfigurationsoptionen und Fork

Ein Agent aktiviert interaktive Sitzungssteuerungen, indem er über AcpServerConfigBuilder::session_controls einen SessionControls-Provider bereitstellt. Der Provider definiert die verfügbaren Modi (ein SessionModeState), Konfigurationsoptionen (Auswahlfelder und Schalter) sowie ACP-Slash-Befehle. Der Server kündigt genau das an, was der Provider definiert — ein Agent ohne Provider kündigt keine Modi und keine Optionen an — und stellt sie in den Antworten session/new, session/load, session/resume und session/fork bereit.

session/set_mode validiert die angeforderte Modus-ID anhand der angekündigten Menge, speichert sie und gibt ein CurrentModeUpdate aus; eine unbekannte ID wird abgelehnt und der aktuelle Modus bleibt unverändert. session/set_config_option validiert den Wert anhand der für die Option definierten Auswahlmöglichkeiten, speichert ihn und gibt ein ConfigOptionUpdate aus; eine unbekannte Option oder ein ungültiger Wert wird abgelehnt. Beide Auswahlen bleiben im Sitzungsstatus von ADK unter acp:mode und acp:config:<id> erhalten, sodass sie das Laden, Fortsetzen und Aufteilen überstehen.

session/fork erstellt eine Verzweigung einer gespeicherten Sitzung: Es liest die Quellsitzung, erstellt eine neue Sitzungs-ID, kopiert die gespeicherten Ereignisse und den relevanten Status (cwd, zusätzliche Verzeichnisse, Modus und Konfiguration) in diese und gibt die neue ID zurück. Der gespeicherte Verlauf der Quellsitzung bleibt Byte für Byte unverändert. Eine Verzweigung für eine unbekannte Sitzungskennung gibt einen Fehler zurück, dass die Sitzung nicht gefunden wurde. Der Server kündigt die Sitzungsfunktion fork an, da der Handler registriert ist.

Bei der Aktivierung einer Sitzung gibt der Server außerdem ein AvailableCommandsUpdate für alle vom Provider definierten Befehle aus (und keines, wenn er keine definiert) sowie ein SessionInfoUpdate, das den Sitzungstitel enthält, wenn einer unter acp:title aufgezeichnet wurde (gesetzt über set_session_title). Eine Zuordnung für Plan-Aktualisierungen ist vorhanden, bleibt jedoch inaktiv, bis ein ADK-Plan-Primitiv Planeinträge bereitstellt.

Vom Client bereitgestellte MCP-Server

Der Client kann stdio-MCP-Server in session/new oder session/resume einschließen. Der Server validiert Namen, Befehle, Argumente und Umgebungseinträge, bevor er einen Prozess startet. Anschließend:

1. startet er jedes untergeordnete Element im Arbeitsbereich der Sitzung;
2. wendet er einen zeitlich begrenzten Start-Handshake an;
3. kapselt er die Verbindung als ADK McpToolset;
4. injiziert er das Toolset in diesen Runner-Aufruf;
5. bricht er die MCP-Dienste beim Schließen, Löschen, bei einem fehlgeschlagenen Start oder beim Herunterfahren des Servers ab.

Aufrufbezogene Toolsets werden derzeit durch LlmAgent und CodeActAgent aufgelöst. Optionale HTTP- und SSE-MCP-Transporte werden vom Server nicht angekündigt.

Entscheidungen zur Persistenz

InMemorySessionService eignet sich für einen lokalen Editorprozess und Tests. Verwenden Sie einen dauerhaften Dienst, wenn Sitzungen Prozessneustarts überstehen müssen. Beim Fortsetzen wird validiert, dass der Aufrufer das ursprüngliche cwd bereitstellt; eine Sitzung kann nicht unbemerkt erneut mit einem anderen Projekt verbunden werden.

Grenze für die Toolgenehmigung

Der Server vermittelt ADK-Toolbestätigungen an native ACP-Berechtigungsanfragen. Wenn der konfigurierte Agent während einer Prompt-Runde bei einem ToolConfirmationRequest pausiert — auf event.actions.tool_confirmation sichtbar, wenn ein Agent auf die menschliche Genehmigung eines Toolaufrufs wartet — sendet der Server eine session/request_permission- Anfrage, die das Tool und seine Argumente beschreibt, wartet auf das Ergebnis des Clients und setzt die Ausführung mit der zugeordneten Entscheidung fort. Eine Genehmigung wird „zulassen“ zugeordnet, und sowohl eine Ablehnung als auch ein Abbruch werden „ablehnen“ zugeordnet, sodass eine abgebrochene Anfrage das Tool niemals ausführt. Jedes Ergebnis wird anhand der exakten Funktionaufrufkennung dem Aufruf zugeordnet und über RunConfig::tool_confirmation_decisions an den Runner zurückgegeben.

Die verschachtelte session/request_permission wird von der Aufgabe ausgeführt, die bereits session/prompt verarbeitet und über ConnectionTo::spawn gestartet wurde. Dadurch wird die Dispatch-Schleife der Verbindung nicht blockiert, und die Antwort auf die äußere Aufforderung wird weiterhin abgeschlossen. Eine frühere Befürchtung, dass das offizielle Rust-SDK die Antwort auf die äußere Aufforderung nach einer verschachtelten bidirektionalen Anfrage verliert, lässt sich mit diesem Pause-/Fortsetzungsablauf nicht reproduzieren; sie wird durch die Interoperabilitätstests im Speicher abgedeckt.

Die serverseitige Tool-Autorisierung, schreibgeschützte Tools, RBAC, Schutzmechanismen und Workflow-Unterbrechungen bleiben verfügbar, wenn die Genehmigung vollständig innerhalb des ADK-Rust-Prozesses erfolgen muss. Der clientseitige Berechtigungspfad für externe ACP-Agenten ist ebenfalls vollständig implementiert.

Sicher bereitstellen

• Starten Sie die Binärdatei mit dem vorgesehenen Projektarbeitsbereich.
• Behandeln Sie cwd und zusätzliche Stammverzeichnisse als Kontext, nicht als Betriebssystem-Isolierung.
• Verwenden Sie adk-sandbox, einen Container oder eine andere Prozessgrenze für nicht vertrauenswürdige Aufforderungen und Befehle.
• Bewahren Sie die Anmeldedaten für das Modell und MCP in einem sicheren Client-Speicher oder in der Prozessumgebung auf.
• Schreiben Sie niemals Banner, Debug-Objekte oder Protokolle auf die Protokoll-Standardausgabe.
• Verwenden Sie ein dauerhaftes SessionService, wenn die Fortsetzung einen Prozessneustart überstehen muss.
• Legen Sie ein endliches Sitzungslimit fest und schließen Sie inaktive Sitzungen.

Das ausführbare acp_server-Crate umfasst einen auf Gemini basierenden Agenten, auf den Arbeitsbereich begrenzte Lesewerkzeuge, Stderr-Tracing und die Konfiguration von Editorprozessen.

Als Nächstes

• Einen ACP-Client oder -Host erstellen
• Test- und Supportmatrix