Google ADK: Anlagen und AfA per MCP mit Bestätigung

Projekt anlegen

• pip install google-adk, dann adk create buchhaltung_agent. Das erzeugt agent.py, __init__.py und .env; ADK erkennt den Agenten an root_agent in agent.py.
• In .env steht der Gemini-Schlüssel als GOOGLE_API_KEY, wie in der ADK-Schnellstartanleitung. Den Buchhaltungsschlüssel setzen Sie vor dem Start in der Shell: export JAB_API_KEY="jab_live_…".
• Gestartet wird aus dem Ordner darüber mit adk web (Weboberfläche) oder adk run buchhaltung_agent (Kommandozeile). ADK Web ist laut Dokumentation nur für die Entwicklung gedacht.
• Der Schlüssel braucht das Recht write, sobald run_depreciation laufen soll; für die Lesesammlung genügt read. Er gilt für genau eine Gesellschaft.

agent.py: lesen ohne Rückfrage, AfA nur mit Bestätigung

Beide Sammlungen sprechen denselben Server an; nur die zweite verlangt eine Bestätigung:

import os
from google.adk.agents import LlmAgent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

def verbindung() -> StreamableHTTPConnectionParams:
    return StreamableHTTPConnectionParams(
        url="https://api.jahresabschluss.io/functions/v1/bookkeeping-mcp",
        headers={"Authorization": f"Bearer {os.environ['JAB_API_KEY']}"},
    )

lesen = McpToolset(
    connection_params=verbindung(),
    tool_filter=["get_entity", "list_fiscal_years", "list_fixed_assets",
                 "list_bookkeeping_periods", "get_saldenliste", "list_journal_entries"],
)
afa = McpToolset(
    connection_params=verbindung(),
    tool_filter=["run_depreciation"],
    require_confirmation=True,
)

root_agent = LlmAgent(
    model="gemini-flash-latest",
    name="anlagen_assistent",
    instruction="Prüfe das Anlagenverzeichnis und die bereits gebuchte AfA. "
                "Schlage einen AfA-Lauf nur vor, wenn das Geschäftsjahr nicht "
                "festgeschrieben ist, und nenne vorher Geschäftsjahr und Aufteilung.",
    tools=[lesen, afa],
)

Woher require_confirmation am McpToolset kommt

Die ADK-Dokumentation beschreibt die Bestätigung von Werkzeugen am Beispiel von FunctionTool(…, require_confirmation=True). McpToolset hat denselben Parameter: Laut Quelltext von ADK für Python gilt er für alle Werkzeuge der Sammlung und darf ein Wahrheitswert oder eine Funktion sein, die mit den Argumenten des Aufrufs entscheidet. Ohne Bestätigung antwortet das Werkzeug mit der Meldung, dass der Aufruf abgelehnt wurde.

Die Funktion bekommt die Argumente, aber nicht den Namen des Werkzeugs. Deshalb trennt das Beispiel lesende und schreibende Werkzeuge in zwei Sammlungen, statt in einer Funktion nach Namen zu unterscheiden.

Die Bestätigung ist laut ADK-Dokumentation ein experimentelles Merkmal, in Python seit ADK 1.14.0. Bekannte Grenze: Mit DatabaseSessionService und VertexAiSessionService funktioniert sie nicht. Ohne Oberfläche beantworten Sie die Rückfrage über die REST-Schnittstelle des ADK-Servers mit einer function_response namens adk_request_confirmation und confirmed: true oder false.

Was der Agent im Gespräch tut

• list_fiscal_years und list_bookkeeping_periods: Er bestimmt das Geschäftsjahr und prüft, ob Monate schon festgeschrieben sind.
• list_fixed_assets: das Anlagenverzeichnis mit Anschaffung, Methode und Nutzungsdauer; in der EÜR die Quelle der Abschreibung.
• list_journal_entries mit source_type und get_saldenliste: Er sieht, welche AfA schon gebucht ist und wie die Anlagekonten stehen.
• run_depreciation mit fiscal_year_id, neuer UUID als idempotency_key und granularity year, quarter oder month: In adk web erscheint jetzt der Bestätigungsdialog. Laut Werkzeugbeschreibung berücksichtigt der Lauf bereits gebuchte Perioden.
• Neue Anlagegüter nimmt create_fixed_asset ins Verzeichnis auf, erzeugt aber keine Zugangsbuchung; die Anschaffungsrechnung läuft über den Belegweg. Wollen Sie das Werkzeug zulassen, gehört es in die bestätigte Sammlung.

Ein Auftrag in adk web

Ihr Auftrag im Chat: „Ist für 2026 schon AfA gebucht? Falls nicht, buche sie quartalsweise.“ Der Agent liest Geschäftsjahre, Festschreibungsstand und Anlagenverzeichnis, vergleicht die gebuchten Abschreibungen im Journal und antwortet mit einer kurzen Übersicht je Anlagegut. Erst dann schlägt er run_depreciation mit granularity quarter vor.

In diesem Moment pausiert ADK den Werkzeugaufruf und zeigt in der Weboberfläche den Dialog mit dem Hinweis, den Aufruf zu bestätigen oder abzulehnen. Bestätigen Sie, läuft der AfA-Lauf auf dem Server mit denselben Prüfungen wie in der App: kein Buchen in festgeschriebene Zeiträume, bereits gebuchte Perioden werden berücksichtigt. Lehnen Sie ab, erhält das Modell als Ergebnis, dass der Aufruf abgelehnt wurde, und es wird nichts gebucht.

Die Antwort des Werkzeugs nennt, was gebucht wurde; Ihre Kanzlei sieht die AfA-Buchungen im Journal wie jede andere Buchung.

Produktion und Sitzungen

Die ADK-Dokumentation verlangt für bereitgestellte Agenten, dass McpToolset synchron in agent.py definiert ist, wie im Beispiel. Für Kopfzeilen, die sich je Anfrage ändern — etwa ein Schlüssel je Gesellschaft in einer Kanzlei-Anwendung —, kennt McpToolset zusätzlich header_provider, eine Funktion, die aus dem Kontext des Laufs die Kopfzeilen liefert.

Weil jeder Schlüssel genau eine Gesellschaft öffnet, braucht eine Anwendung für mehrere Gesellschaften mehrere Schlüssel und wählt je Lauf den richtigen. Eine Gesellschafts-ID als Argument gibt es bewusst nicht.

Grenzen: was in der App bleibt

• Der Jahresabschluss selbst: Die AfA ist Vorarbeit; Erstellen, Prüfen und Ausstellen des Abschlusses geschieht in der App, die Saldenliste übergibt publish_trial_balance.
• Festschreibung und Steuerübermittlung: eigenes Recht finalize bzw. Freigabe-Link in der App mit Ihrer PIN.
• Bankanbindung, Einstellungen der Gesellschaft und Bankverbindungen der Geschäftspartner sind nicht Teil der API.
• Gemini sieht, was die Werkzeuge zurückgeben. Wählen Sie die Liste in tool_filter so, wie Sie es mit dem Modellanbieter vereinbart haben.

Rechtlicher Bezug: planmäßige Abschreibung

Nach § 253 Abs. 3 Satz 1 HGB sind Vermögensgegenstände des Anlagevermögens, deren Nutzung zeitlich begrenzt ist, um planmäßige Abschreibungen zu vermindern; der Plan verteilt die Kosten auf die voraussichtliche Nutzungsdauer. run_depreciation bucht diesen Plan so, wie das Anlagenverzeichnis der App ihn rechnet. Ob Methode und Nutzungsdauer stimmen, entscheiden Sie oder Ihre Kanzlei — deshalb die Bestätigung vor dem Lauf.

Häufige Fragen

Welche Klassen verbinden ADK mit einem entfernten MCP-Server?

McpToolset aus google.adk.tools.mcp_tool mit StreamableHTTPConnectionParams aus google.adk.tools.mcp_tool.mcp_session_manager. In den Verbindungsparametern stehen url und headers.

Heißt die Klasse McpToolset oder MCPToolset?

In Python McpToolset. MCPToolset ist laut Quelltext veraltet und gibt eine Warnung aus. In ADK für TypeScript heißt sie MCPToolset.

Wie beschränke ich die Werkzeuge?

Mit tool_filter=[…] als Liste von Werkzeugnamen oder als Funktion. Die ADK-Dokumentation rät, tool_filter immer zu setzen.

Wie verlange ich eine Bestätigung vor einem Werkzeug?

Mit require_confirmation=True an der Werkzeugsammlung oder am FunctionTool. adk web zeigt dann einen Bestätigungsdialog; ohne Oberfläche antworten Sie mit adk_request_confirmation.

Kann der Agent die AfA doppelt buchen?

Laut Werkzeugbeschreibung berücksichtigt run_depreciation bereits gebuchte Perioden. Bei einer Wiederholung nach Netzwerkfehler sorgt dieselbe UUID als idempotency_key für dasselbe Ergebnis.

Welche Rechte braucht der Schlüssel?

Für die Lesesammlung genügt das Leserecht, das jeder Schlüssel hat. run_depreciation braucht write. Fehlt das Recht, listet der Server das Werkzeug nicht, und die bestätigte Sammlung bleibt leer.

Funktioniert die Bestätigung mit jeder Sitzungsablage?

Nein. Laut ADK-Dokumentation werden DatabaseSessionService und VertexAiSessionService von der Bestätigung derzeit nicht unterstützt.