File Tools

Schnellstart

Füge einem Agent die File Tools hinzu. Agents wählen den Pfad beim Speichern, und Ordner erscheinen, sobald eine Datei darin liegt. Datenmodell und Limits stehen unter Dateien.

version: "1.0"

name: invoice-collector
model: connic/gpt-5.6-luna
description: "Lädt Rechnungen aus Lieferantenportalen und legt sie ab"
system_prompt: |
  Lade die Rechnung dieses Monats aus dem Lieferantenportal und speichere
  sie unter invoices/<lieferant>/. Markiere neue Rechnungen mit status "new".

tools:
  - web_browser_open
  - web_browser_observe
  - web_browser_act
  - web_browser_download
  - file_list
  - file_update

files:
  folders: [invoices]
  prevent_delete: true

Zugriffskontrolle

Der Block files legt fest, was ein Agent sehen und ändern darf. Ohne ihn nutzt der Agent den ganzen Dateibaum.

• folders umfasst jeden Ordner samt allem darunter: invoices schließt invoices/2026/acme.pdf ein. Mit gesetzten Ordnern sind Dateien außerhalb für den Agent unsichtbar.
• prevent_write blockiert file_write und file_update. Zum Verschieben braucht der Agent Schreibzugriff auf beide Ordner.
• prevent_delete blockiert file_delete.
• session_only zeigt dem Agent nur Dateien aus seiner aktuellen Session, damit die Dateien eines Endnutzers bei keinem anderen auftauchen. Setzt session voraus.
• Eine Ordner-Einstellung ersetzt die Einstellung auf oberster Ebene, und der spezifischste Ordner gewinnt.

session:
  key: context.customer_id

files:
  session_only: true          # jeder Kunde sieht nur seine eigenen Uploads
  prevent_delete: true
  folders:
    uploads: {}
    templates:
      session_only: false     # von allen Sessions geteilt
      prevent_write: true

Eine Datei, die der Agent nicht sieht, wird nie ersetzt. Ist ihr Pfad belegt, wird die neue Datei unter einem nummerierten Namen gespeichert.

In eigenen Tools nutzen

Eigene Tools importieren dieselben Funktionen aus connic.tools. Die Zugriffskontrolle des Agents gilt auch für diese Aufrufe.

from connic.tools import file_list, file_read, file_update

async def next_pending_invoice() -> dict:
    """Gibt die älteste noch offene Rechnung zurück."""
    result = await file_list(
        "invoices",
        recursive=True,
        filter={"status": "new", "_mime_type": "application/pdf"},
        sort={"_created_at": 1},
        limit=1,
    )
    if not result["files"]:
        return {"done": True}
    invoice = result["files"][0]
    await file_update(invoice["_path"], metadata={"status": "processing"})
    return invoice

Browser-Downloads und -Uploads

Die Browser-Tools verschieben Dateien in die und aus den Projektdateien. Ein save_to mit / am Ende ist ein Ordner, der den Namen des Downloads behält.

# Download direkt in die Dateien speichern (bis 100 MiB)
await web_browser_download("e12", include_content=False, save_to="invoices/acme/")

# Eine gespeicherte Datei in ein Upload-Feld laden
await web_browser_upload("e7", path="contracts/signed/acme.pdf")

Tool-Referenz

result = await file_list("invoices/2026")
# {"folder": "invoices/2026", "folders": ["acme"], "files": [...], "count": 3, "total": 3}

# Alles, was diese Session geschrieben hat, im ganzen Baum
result = await file_list(recursive=True, scope="session")

# In einem eigenen Tool
result = await file_read("reports/summary.md")
# {"file": {"_path": "reports/summary.md", ...}, "content": b"# Summary ..."}
text = result["content"].decode("utf-8")

result = await file_write(
    "reports/2026-10/summary.md",
    "# Zusammenfassung Oktober\n...",
    metadata={"status": "draft", "customer": "acme"},
)
# result["_path"] ist der gespeicherte Pfad, z. B. "reports/2026-10/summary (2).md", falls der Name belegt war

# Datei umbenennen und als erledigt markieren
await file_update("inbox/acme.pdf", new_path="done/acme.pdf", metadata={"status": "processed"})

# Einen ganzen Ordner verschieben
await file_update("inbox/2026-09", new_path="archive/2026-09")

await file_delete("tmp/scratch.txt")
await file_delete("tmp", recursive=True)