Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: Tool Calling, Agenten-Loop und MCP – ops-agent

Ziel: Python-Funktionen als Tools für ein LLM bereitstellen, eine Agenten-Schleife mit Abbruchbedingungen und Guardrails bauen und dieselben Tools als MCP-Server anbieten · Dauer: ca. 150 min · Voraussetzung: Tag 11

Briefing

  • Tool Calling: Du schickst dem Modell JSON-Schemas deiner Funktionen. Es antwortet nicht mit Text, sondern mit „rufe disk_usage(path="/") auf”.
  • Ausführen tust du, nicht das Modell. Dein Code entscheidet, was erlaubt ist (Guardrails).
  • Agenten-Loop: Ergebnis zurück ans Modell, bis es antwortet – oder eine Grenze greift (Schritte, Aufrufe, Zeit).
  • MCP (Model Context Protocol): Standard, um Tools für beliebige Clients (Claude, IDEs, eigene Agenten) anzubieten. Einmal schreiben, überall nutzen.
  • Heute alles read-only: Ein Agent, der nur lesen darf, kann wenig kaputt machen.
ops-agent "Frage" ─> run_agent ─(tools=Schemas)─> ministral-3:3b
                        ▲                            │ tool_calls
                        └── Ergebnis ◄─ run_tool ◄───┘ (Allowlist, pydantic)
tools.py ──────────────────────────> mcp_server.py ──stdio──> MCP-Client

Drill 1: Projekt anlegen

cd ~/py-lab
uv init -q --package --name ops-agent tag12-ops-agent
cd tag12-ops-agent
uv add -q openai pydantic typer mcp
uv add -q --dev pytest ruff
cat >> pyproject.toml <<'EOF'

[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
EOF
uv tree --depth 1 | grep -E 'mcp|openai'
ls src

Erwartet (Versionen können abweichen):

├── mcp v2.3.0
├── openai v3.28.0
ops_agent

Achtung: Das mcp-SDK ist seit Version 2 umgebaut: FastMCP heißt jetzt MCPServer (from mcp.server.mcpserver import MCPServer), und es gibt eine High-Level-Klasse mcp.Client. Ältere Tutorials mit from mcp.server.fastmcp import FastMCP laufen nur mit mcp<2.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Read-only Tools mit Typ-Hints

Die Signatur ist der Vertrag: Aus Annotated[int, Field(ge=1, le=20)] werden später JSON-Schema und Validierung – für das LLM wie für MCP.

cat > src/ops_agent/tools.py <<'EOF'
"""Read-only System-Tools – genutzt vom Agenten und vom MCP-Server."""

import os
import shutil
import subprocess
from collections.abc import Callable
from typing import Annotated, Any

from openai.types.chat import ChatCompletionFunctionToolParam
from pydantic import Field, TypeAdapter

GB = 1024**3


def disk_usage(
    path: Annotated[
        str, Field(description="Absoluter Pfad, z. B. / oder /Users")
    ] = "/",
) -> dict[str, float]:
    """Belegung des Dateisystems, auf dem PATH liegt, in GB und Prozent."""
    if not os.path.isabs(path):
        raise ValueError("path muss absolut sein")
    total, used, free = shutil.disk_usage(path)
    return {
        "total_gb": round(total / GB, 1),
        "used_gb": round(used / GB, 1),
        "free_gb": round(free / GB, 1),
        "percent": round(used / total * 100, 1),
    }


def load_average() -> dict[str, float]:
    """Systemlast der letzten 1, 5 und 15 Minuten und Anzahl der CPUs."""
    one, five, fifteen = os.getloadavg()
    return {
        "load_1m": round(one, 2),
        "load_5m": round(five, 2),
        "load_15m": round(fifteen, 2),
        "cpus": os.cpu_count() or 1,
    }


def top_processes(
    n: Annotated[int, Field(ge=1, le=20, description="Anzahl Prozesse")] = 5,
) -> list[dict[str, Any]]:
    """Die N Prozesse mit der höchsten CPU-Last."""
    out = subprocess.run(
        ["ps", "-Ao", "pid=,pcpu=,comm="],
        capture_output=True,
        text=True,
        check=True,
        timeout=5,
        env={**os.environ, "LC_ALL": "C"},  # sonst "0,5" statt "0.5"
    ).stdout
    rows: list[dict[str, Any]] = []
    for line in out.splitlines():
        pid, cpu, cmd = line.split(None, 2)
        rows.append({"pid": int(pid), "cpu": float(cpu), "cmd": cmd.rsplit("/")[-1]})
    return sorted(rows, key=lambda r: r["cpu"], reverse=True)[:n]


TOOLS: dict[str, Callable[..., Any]] = {
    f.__name__: f for f in (disk_usage, load_average, top_processes)
}


def openai_tools() -> list[ChatCompletionFunctionToolParam]:
    """Beschreibt alle Tools im Format der Chat-Completions-API."""
    return [
        {
            "type": "function",
            "function": {
                "name": name,
                "description": fn.__doc__ or "",
                # TypeAdapter liest die Signatur; mypy kennt nur Typen als Argument
                "parameters": TypeAdapter(fn).json_schema(),  # type: ignore[arg-type]
            },
        }
        for name, fn in TOOLS.items()
    ]
EOF
uv run python -c "
from ops_agent.tools import TOOLS
print(TOOLS['disk_usage']('/'))
print(TOOLS['load_average']())
print(TOOLS['top_processes'](3))
"

Erwartet (Werte deines Rechners, gekürzt):

{'total_gb': 228.3, 'used_gb': 213.4, 'free_gb': 14.9, 'percent': 93.5}
{'load_1m': 7.83, 'load_5m': 11.22, 'load_15m': 9.51, 'cpus': 10}
[{'pid': 59263, 'cpu': 122.8, 'cmd': 'com.apple.Virtualization.VirtualMachine'},
 {'pid': 40972, 'cpu': 56.6, 'cmd': 'Python'}, ...]

Warum LC_ALL=C? Auf einem deutschen Mac schreibt ps 0,5 statt 0.5, und float() stürzt ab. subprocess.run bekommt eine feste Argumentliste ohne Shell – kein Modell-Text landet je in einem Befehl. Der Docstring wird zur Tool-Beschreibung, die das Modell liest: Schreib ihn für das Modell.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Das Modell wählt ein Tool

uv run python -c "
import json
from ops_agent.tools import openai_tools
print(json.dumps(openai_tools()[2]['function']['parameters']))
"
uv run python - <<'EOF'
from openai import OpenAI

from ops_agent.tools import openai_tools

client = OpenAI(base_url="http://127.0.0.1:11434/v1", api_key="ollama")
resp = client.chat.completions.create(
    model="ministral-3:3b",
    tools=openai_tools(),
    temperature=0,
    messages=[{"role": "user", "content": "Wie voll ist /System/Volumes/Data?"}],
)
print(resp.choices[0].finish_reason)
for call in resp.choices[0].message.tool_calls or []:
    print(call.function.name, call.function.arguments)
EOF

Erwartet:

{"additionalProperties": false, "properties": {"n": {"default": 5, "description":
"Anzahl Prozesse", "maximum": 20, "minimum": 1, "title": "N", "type": "integer"}},
"type": "object"}
tool_calls
disk_usage {"path":"/System/Volumes/Data"}

Warum finish_reason: tool_calls? Das Modell hat nicht geantwortet, sondern einen Funktionsaufruf als Daten geliefert. arguments ist ein JSON-String, den das Modell erzeugt hat – also unvalidierte Eingabe.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Guardrails – nur erlaubte Tools, nur gültige Argumente

cat > src/ops_agent/agent.py <<'EOF'
"""Agenten-Schleife: Das LLM wählt Tools, Python führt sie aus – mit Grenzen."""

import json
import logging
import os
import time
from dataclasses import dataclass
from typing import Any

from openai import OpenAI
from pydantic import ValidationError, validate_call

from ops_agent.tools import TOOLS, openai_tools

log = logging.getLogger("ops_agent")
BASE_URL = os.environ.get("OPS_AGENT_BASE_URL", "http://127.0.0.1:11434/v1")
MODEL = os.environ.get("OPS_AGENT_MODEL", "ministral-3:3b")
SYSTEM = (
    "Du bist ein Ops-Assistent für diesen Rechner. Hole Fakten mit den Tools, "
    "statt zu raten. Antworte auf Deutsch in max. 4 Sätzen mit konkreten Zahlen."
)
MAX_RESULT_CHARS = 2000


@dataclass(frozen=True)
class Limits:
    max_steps: int = 5
    max_tool_calls: int = 8
    timeout_s: float = 120.0


class AgentError(RuntimeError):
    """Der Agent hat eine Grenze erreicht."""


def make_client() -> OpenAI:
    key = os.environ.get("OPS_AGENT_API_KEY", "ollama")
    return OpenAI(base_url=BASE_URL, api_key=key, timeout=120, max_retries=1)


def run_tool(name: str, arguments: str) -> str:
    """Führt ein Tool aus. Fehler gehen als Text zurück ans Modell."""
    if name not in TOOLS:
        return f"Fehler: unbekanntes Tool {name!r}. Erlaubt: {', '.join(TOOLS)}"
    try:
        args = json.loads(arguments or "{}")
        result = validate_call(TOOLS[name])(**args)
    except (ValueError, TypeError, OSError, ValidationError) as exc:
        return f"Fehler: {type(exc).__name__}: {exc}"[:500]
    return json.dumps(result, ensure_ascii=False)[:MAX_RESULT_CHARS]
EOF
uv run python -c "
from ops_agent.agent import run_tool
print(run_tool('rm_rf', '{}'))
print(run_tool('top_processes', '{\"n\": 99}')[:88])
print(run_tool('disk_usage', '{\"path\": \"etc\"}'))
print(run_tool('disk_usage', '{}'))
"

Erwartet:

Fehler: unbekanntes Tool 'rm_rf'. Erlaubt: disk_usage, load_average, top_processes
Fehler: ValidationError: 1 validation error for top_processes
n
  Input should be less t
Fehler: ValueError: path muss absolut sein
{"total_gb": 228.3, "used_gb": 213.4, "free_gb": 14.9, "percent": 93.5}

Warum Fehler als Text statt Exception? Das Modell liest die Meldung im nächsten Schritt und kann sich korrigieren („n=20 statt 99”). Drei Schichten schützen: Allowlist (TOOLS), Validierung (validate_call prüft gegen die Typ-Hints) und Größenlimit (MAX_RESULT_CHARS), damit ein Tool das Kontextfenster nicht flutet.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die Agenten-Schleife

cat >> src/ops_agent/agent.py <<'EOF'


def run_agent(client: OpenAI, question: str, limits: Limits | None = None) -> str:
    limits = limits or Limits()
    messages: list[Any] = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": question},
    ]
    calls = 0
    deadline = time.monotonic() + limits.timeout_s
    for step in range(1, limits.max_steps + 1):
        if time.monotonic() > deadline:
            raise AgentError(f"Zeitbudget von {limits.timeout_s:.0f}s überschritten")
        resp = client.chat.completions.create(
            model=MODEL, messages=messages, tools=openai_tools(), temperature=0
        )
        msg = resp.choices[0].message
        if not msg.tool_calls:
            return msg.content or ""
        messages.append(msg.model_dump(exclude_none=True))
        for call in msg.tool_calls:
            if call.type != "function":
                continue
            calls += 1
            if calls > limits.max_tool_calls:
                raise AgentError(f"Mehr als {limits.max_tool_calls} Tool-Aufrufe")
            fn = call.function
            result = run_tool(fn.name, fn.arguments)
            log.info("Schritt %d: %s(%s) -> %.40s", step, fn.name, fn.arguments, result)
            messages.append(
                {"role": "tool", "tool_call_id": call.id, "content": result}
            )
    raise AgentError(f"Keine Antwort nach {limits.max_steps} Schritten")
EOF
uv run ruff check src

Erwartet:

All checks passed!

Warum drei Grenzen? max_steps stoppt Endlosschleifen („noch ein Tool, noch eins”), max_tool_calls stoppt Modelle, die pro Schritt zehn Aufrufe schicken, und timeout_s begrenzt die Gesamtzeit. Ein Agent ohne Abbruchbedingung ist ein Kostenleck. Die Assistant-Nachricht mit den tool_calls muss vor den tool-Antworten in der Historie stehen, sonst ordnet das Modell die Ergebnisse nicht zu (tool_call_id).

Fortschritt speichern? Kostenlos registrieren

Drill 6: Das CLI

cat > src/ops_agent/cli.py <<'EOF'
"""ops-agent – beantwortet Fragen über diesen Rechner mit read-only Tools."""

import logging
from typing import Annotated

import openai
import typer

from ops_agent.agent import AgentError, Limits, make_client, run_agent

app = typer.Typer(add_completion=False)


@app.command()
def main(
    question: str,
    verbose: Annotated[bool, typer.Option("--verbose", "-v")] = False,
    max_steps: Annotated[int, typer.Option(min=1, max=10)] = 5,
) -> None:
    """Stellt QUESTION an den Agenten. -v zeigt jeden Tool-Aufruf."""
    logging.basicConfig(format="  %(message)s", level=logging.WARNING)
    if verbose:
        logging.getLogger("ops_agent").setLevel(logging.INFO)
    try:
        answer = run_agent(make_client(), question, Limits(max_steps=max_steps))
    except AgentError as exc:
        typer.secho(f"Abbruch: {exc}", fg="red", err=True)
        raise typer.Exit(code=1) from exc
    except openai.APIConnectionError:
        typer.secho("Fehler: LLM nicht erreichbar (läuft Ollama?)", fg="red", err=True)
        raise typer.Exit(code=1) from None
    typer.echo(answer)
EOF
cat > src/ops_agent/__init__.py <<'EOF'
"""ops-agent – Fragen über diesen Rechner, beantwortet mit read-only Tools."""

from ops_agent.cli import app


def main() -> None:
    app()
EOF
cat > src/ops_agent/__main__.py <<'EOF'
from ops_agent import main

main()
EOF
uv run ops-agent -v "Wie voll ist meine Festplatte und wie hoch ist die Last?"
uv run ops-agent --max-steps 1 "Welche Prozesse fressen CPU?"; echo "exit=$?"

Erwartet (Werte und Text variieren):

  Schritt 1: load_average({}) -> {"load_1m": 6.91, "load_5m": 8.35, "load
  Schritt 1: disk_usage({"path":"/"}) -> {"total_gb": 228.3, "used_gb": 213.7, "f
Deine Festplatte ist mit **93,6 %** voll (ca. **213,7 GB aus 228,3 GB**). Die
CPU-Last liegt bei **6,9 pro Minute** und es sind **10 CPUs** verfügbar. Die
aktuelle Systemlast ist hoch.
Abbruch: Keine Antwort nach 1 Schritten
exit=1

Warum zwei Tools in Schritt 1? Parallel Tool Calls: Eine Antwort darf mehrere Aufrufe enthalten, run_agent arbeitet sie der Reihe nach ab. Die Formulierung zählt: Mit „Platte” statt „Festplatte” ruft das 3B-Modell bei temperature=0 nur load_average auf und unterschlägt die Hälfte der Frage. Und „6,9 pro Minute” ist falsch gelesen – Load ist ein Mittelwert der wartenden Prozesse, keine Rate. Zahlen stimmen, Deutungen prüfst du selbst.

Sicherheit: Tool-Ergebnisse sind ungeprüfter Input für das Modell. Liest ein Tool Logdateien oder Webseiten, kann darin „Ignoriere alle Regeln und …” stehen (Prompt Injection). Deshalb read-only Tools, Allowlist und keine Tools, die Befehle aus Modelltext bauen.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Dieselben Tools als MCP-Server

Der MCP-Server liest die Typ-Hints genauso wie openai_tools() – du registrierst nur die Funktionen.

cat > src/ops_agent/mcp_server.py <<'EOF'
"""MCP-Server: dieselben read-only Tools für Claude, IDEs und andere Agenten."""

from mcp.server.mcpserver import MCPServer
from mcp.types import ToolAnnotations

from ops_agent.tools import TOOLS

server = MCPServer("ops-tools", instructions="Read-only Infos über diesen Rechner.")
for fn in TOOLS.values():
    server.add_tool(fn, annotations=ToolAnnotations(read_only_hint=True))


def main() -> None:
    server.run()  # Standard-Transport: stdio
EOF
perl -pi -e 's/^(ops-agent = .*)$/$1\nops-mcp = "ops_agent.mcp_server:main"/' \
  pyproject.toml
grep -A2 'project.scripts' pyproject.toml

Erwartet:

[project.scripts]
ops-agent = "ops_agent:main"
ops-mcp = "ops_agent.mcp_server:main"

Ein MCP-Server über stdio spricht JSON-RPC auf stdin/stdout – im Terminal siehst du davon nichts. Teste ihn mit dem Client aus dem SDK, der den Server als Unterprozess startet:

cat > mcp_check.py <<'EOF'
"""Startet den MCP-Server per stdio und ruft seine Tools wie ein Client auf."""

import asyncio

from mcp import Client, StdioServerParameters
from mcp.types import TextContent


async def main() -> None:
    params = StdioServerParameters(command="uv", args=["run", "-q", "ops-mcp"])
    async with Client(params) as client:
        listing = await client.list_tools()
        for tool in listing.tools:
            ro = tool.annotations.read_only_hint if tool.annotations else None
            print(f"{tool.name:14} read_only={ro}  {(tool.description or '')[:40]}")
        ok = await client.call_tool("disk_usage", {"path": "/"})
        print("disk_usage:", ok.structured_content)
        bad = await client.call_tool("top_processes", {"n": 99})
        block = bad.content[0]
        text = block.text if isinstance(block, TextContent) else ""
        print("Fehlerfall:", bad.is_error, text[:60])


asyncio.run(main())
EOF
uv run python mcp_check.py 2>/dev/null

Erwartet (Werte gekürzt):

disk_usage     read_only=True  Belegung des Dateisystems, auf dem PATH
load_average   read_only=True  Systemlast der letzten 1, 5 und 15 Minut
top_processes  read_only=True  Die N Prozesse mit der höchsten CPU-Last
disk_usage: {'total_gb': 228.3, 'used_gb': 213.4, 'free_gb': 14.9, 'percent': 93.5}
Fehlerfall: True Error executing tool top_processes: 1 validation error for top_process

Warum 2>/dev/null? stdout gehört dem Protokoll, deshalb loggt der Server auf stderr (z. B. Tool 'top_processes' rejected arguments). In einem MCP-Server darfst du nie print() auf stdout schreiben – das zerstört den JSON-RPC-Strom. read_only_hint sagt Clients wie Claude, dass das Tool nichts verändert; manche fragen dann nicht mehr nach.

Fortschritt speichern? Kostenlos registrieren

Drill 8: Tests – Agent ohne Modell, MCP ohne Prozess

Der Fake-Client liefert echte ChatCompletionMessage-Objekte; der MCP-Test verbindet mcp.Client direkt mit dem Server-Objekt im selben Prozess.

mkdir -p tests
cat > tests/test_ops_agent.py <<'EOF'
import asyncio
import json
import subprocess
from types import SimpleNamespace as NS
from typing import Any
from unittest.mock import MagicMock

import pytest
from mcp import Client
from openai.types.chat import ChatCompletionMessage

from ops_agent import tools
from ops_agent.agent import AgentError, Limits, run_agent, run_tool
from ops_agent.mcp_server import server


def reply(content: str | None = None, calls: list[Any] | None = None) -> NS:
    msg = ChatCompletionMessage.model_validate(
        {"role": "assistant", "content": content, "tool_calls": calls}
    )
    return NS(choices=[NS(message=msg)])


def call(name: str, args: str = "{}") -> dict[str, Any]:
    fn = {"name": name, "arguments": args}
    return {"id": "c1", "type": "function", "function": fn}


def test_disk_usage_rejects_relative_path() -> None:
    with pytest.raises(ValueError):
        tools.disk_usage("etc")


def test_top_processes_parses_ps(monkeypatch: pytest.MonkeyPatch) -> None:
    out = "  1  0.5 /sbin/launchd\n 42 12.0 /usr/bin/python3 -m x\n"
    fake = MagicMock(return_value=NS(stdout=out))
    monkeypatch.setattr(subprocess, "run", fake)
    rows = tools.top_processes(n=1)
    assert rows == [{"pid": 42, "cpu": 12.0, "cmd": "python3 -m x"}]


@pytest.mark.parametrize(
    ("name", "args", "expected"),
    [
        ("rm_rf", "{}", "unbekanntes Tool"),
        ("top_processes", '{"n": 99}', "ValidationError"),
        ("disk_usage", "{kaputt", "JSONDecodeError"),
    ],
)
def test_run_tool_guardrails(name: str, args: str, expected: str) -> None:
    assert expected in run_tool(name, args)


def test_agent_calls_tool_then_answers() -> None:
    client = MagicMock()
    client.chat.completions.create.side_effect = [
        reply(calls=[call("load_average")]),
        reply("Last ist niedrig."),
    ]
    assert run_agent(client, "Last?") == "Last ist niedrig."
    messages = client.chat.completions.create.call_args.kwargs["messages"]
    assert messages[-1]["role"] == "tool"
    assert "load_1m" in json.loads(messages[-1]["content"])


def test_agent_stops_after_max_steps() -> None:
    client = MagicMock()
    client.chat.completions.create.return_value = reply(calls=[call("load_average")])
    with pytest.raises(AgentError, match="2 Schritten"):
        run_agent(client, "Endlos?", Limits(max_steps=2))


def test_mcp_server_lists_all_tools() -> None:
    async def names() -> set[str]:
        async with Client(server) as client:
            return {t.name for t in (await client.list_tools()).tools}

    assert asyncio.run(names()) == set(tools.TOOLS)
EOF
uv run pytest -q
uv run ruff check . && uv run --with mypy mypy --strict src

Erwartet:

........                                                                 [100%]
8 passed in 0.52s
All checks passed!
Success: no issues found in 6 source files

Warum asyncio.run im Test? Das MCP-SDK ist async. Für einen einzelnen Test brauchst du kein Plugin wie pytest-asyncio, eine kleine async def plus asyncio.run reicht. test_agent_stops_after_max_steps beweist die wichtigste Eigenschaft: Der Agent hört auf.

Fortschritt speichern? Kostenlos registrieren

Drill 9: Das Tool ist fertig

uv tool install --editable .
cd ~
ops-agent "Wie viel Platz ist auf / noch frei?"
ops-agent --help | head -3

Erwartet (Text variiert):

Installed 2 executables: ops-agent, ops-mcp
Auf dem Root-Pfad `/` sind noch **14,6 GB** frei, das entspricht etwa **6,4 %**
der Gesamtkapazität.

 Usage: ops-agent [OPTIONS] {question}

Den MCP-Server meldest du in Claude Code mit einem Befehl an (Syntax laut claude mcp add --help, hier nicht ausgeführt, weil er deine Claude-Konfiguration ändert):

claude mcp add ops-tools -- uv --directory ~/py-lab/tag12-ops-agent run -q ops-mcp

Erwartet (gekürzt, kann je nach Version abweichen):

Added stdio MCP server ops-tools with command: uv --directory ... run -q ops-mcp

Warum uv --directory? Der Client startet den Server aus einem beliebigen Arbeitsverzeichnis; so findet uv trotzdem das richtige Projekt und venv.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

cd ~/py-lab/tag12-ops-agent
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check ."
check "mypy --strict sauber" "uv run --with mypy mypy --strict src"
G='from ops_agent.agent import run_tool; print(run_tool("shell", "{}"))'
check "Guardrail: unbekanntes Tool" "uv run python -c '$G' | grep -q unbekannt"
check "MCP-Server antwortet" "uv run python mcp_check.py | grep -q read_only=True"
check "Agent antwortet" "uv run ops-agent 'Wie hoch ist die Last?' | grep -q ."
check "Abbruch mit Exit 1" "! uv run ops-agent --max-steps 1 'Prozesse?'"

Erwartet:

✔ Tests grün
✔ ruff sauber
✔ mypy --strict sauber
✔ Guardrail: unbekanntes Tool
✔ MCP-Server antwortet
✔ Agent antwortet
✔ Abbruch mit Exit 1

Challenge

Ergänze ein viertes read-only Tool file_age(path), das das Alter einer Datei in Stunden liefert – aber nur unter /var/log und ~/py-lab. Ein Pfad wie ~/py-lab/../.ssh/id_ed25519 muss scheitern. Agent und MCP-Server sollen das Tool ohne weitere Änderung kennen.

Hinweis: Erst Path.resolve(), dann is_relative_to() – in dieser Reihenfolge, sonst rutschen .. und Symlinks durch.

Lösung

In src/ops_agent/tools.py die Importe import time und from pathlib import Path ergänzen und TOOLS so ersetzen:

ALLOWED_ROOTS = [Path("/var/log"), Path.home() / "py-lab"]


def file_age(
    path: Annotated[str, Field(description="Datei unter /var/log oder ~/py-lab")],
) -> dict[str, Any]:
    """Alter einer Datei in Stunden (nur unter erlaubten Verzeichnissen)."""
    target = Path(path).expanduser().resolve()
    if not any(target.is_relative_to(r.resolve()) for r in ALLOWED_ROOTS):
        raise ValueError(f"{target} liegt außerhalb der erlaubten Verzeichnisse")
    hours = (time.time() - target.stat().st_mtime) / 3600
    return {"path": str(target), "age_h": round(hours, 1)}


TOOLS: dict[str, Callable[..., Any]] = {
    f.__name__: f for f in (disk_usage, load_average, top_processes, file_age)
}

Test ergänzen (from pathlib import Path oben in die Testdatei) und laufen lassen:

cat >> tests/test_ops_agent.py <<'EOF'


def test_file_age_blocks_escape(
    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
    monkeypatch.setattr(tools, "ALLOWED_ROOTS", [tmp_path])
    (tmp_path / "app.log").write_text("x")
    assert tools.file_age(str(tmp_path / "app.log"))["age_h"] == 0.0
    with pytest.raises(ValueError, match="außerhalb"):
        tools.file_age(str(tmp_path / ".." / "geheim.txt"))
EOF
uv run pytest -q
uv run ops-agent -v "Wie alt ist /var/log/system.log?"

Erwartet (Werte variieren):

.........                                                                [100%]
9 passed in 1.50s
  Schritt 1: file_age({"path":"/var/log/system.log"}) -> {"path": "/private/var/log/
Die Datei `/var/log/system.log` ist etwa **0,1 Stunden** (ca. **6 Minuten**) alt.

Warum /private/var/log? Unter macOS ist /var ein Symlink. resolve() zeigt den echten Pfad – genau deshalb wird auch jede erlaubte Wurzel vor dem Vergleich aufgelöst.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Tools nach Risiko trennen: read-only frei, schreibende nur mit Bestätigung durch einen Menschen (Human-in-the-Loop) und eigenem, minimal berechtigtem Service-Account.
  • Jeden Tool-Aufruf mit Argumenten, Ergebnisgröße und Nutzer auditieren (strukturierte Logs, OpenTelemetry-Spans pro Schritt).
  • MCP-Server über HTTP nur mit Authentifizierung (OAuth/Token), TLS und Rate-Limits betreiben; stdio-Server laufen mit den Rechten des Nutzers, der sie startet.
  • MCP-Server aus Fremdquellen wie Abhängigkeiten behandeln: Code prüfen, Version pinnen, Tool-Beschreibungen auf versteckte Anweisungen (Tool Poisoning) prüfen.
  • Kosten- und Zeitbudgets pro Anfrage zentral erzwingen, nicht nur im Client; Abbrüche als Metrik beobachten.