Dokumentacja integracji¶

FastFence egzekwuje kontrole dla operacji skierowanych przez bramkę. Nie przechwytuje pozostałych połączeń sieciowych agenta. Jawnie wybierz adapter i oddziel tokeny agentów od dostępu administracyjnego.

Protokoły¶

Interfejs	Endpoint	Klient
Chroniony model REST	`POST /api/models/complete`	Klienci potrzebujący pełnej decyzji FastFence
Chronione narzędzie REST	`POST /api/invoke`	Aplikacje z zarejestrowanymi implementacjami narzędzi
Czat tekstowy zgodny z OpenAI	`/v1/chat/completions`, `/v1/models`	Klienci obsługujący własny bazowy URL API
MCP	`/mcp/`	Klienci Streamable HTTP MCP
Dokumenty	Zobacz wykaz HTTP	Przesyłanie plików i chroniony Markdown
Zarządzanie	`/api/admin/…`	Panel lub zaufane zarządzanie politykami

Wykaz HTTP powstaje z kodu przy każdym budowaniu strony. Działająca bramka udostępnia dokładne schematy żądań i odpowiedzi pod /openapi.json oraz interaktywny interfejs pod /docs.

Tożsamość i obsługa odpowiedzi¶

Przekaż wystawiony token w Authorization: Bearer …. Serwer pobiera zaufane role i tenant z konfiguracji tożsamości. Klient nie może sam nadać sobie roli przez treść żądania. Endpointy zarządzania wymagają dodatkowo tożsamości administracyjnej.

Chronione wywołania REST zwracają decyzję bezpieczeństwa. Sprawdzaj decision, reason, findings, policy_version i upstream_executed. Sam HTTP 200 nie oznacza zezwolenia. Blokada wejścia zapobiega wykonaniu operacji docelowej. Blokada wyjścia wstrzymuje gotowy wynik i nie cofa skutków ubocznych operacji.

Panel przechowuje tokeny w pamięci strony. Odświeżenie wymaga ponownego połączenia. Audyt zawiera ograniczone metadane decyzji, a nie surowe prompty lub odpowiedzi.

MCP¶

Połącz się z http://127.0.0.1:8000/mcp/, używając tokenu bearer agenta. Serwer udostępnia complete dla chronionych wywołań modeli, invoke dla zarejestrowanych narzędzi i chroniony zasób pamięci tenanta. Operacje narzędzi i pamięci wymagają rzeczywistych implementacji i uprawnień polityki; ich obecność w protokole nie oznacza domyślnego backendu biznesowego.

To serwer zarejestrowanych, chronionych operacji, a nie dowolne proxy do zewnętrznych serwerów MCP. Zobacz przykłady klienta MCP.

Czat zgodny z OpenAI¶

Ustaw bazowy URL klienta na http://127.0.0.1:8000/v1 i przekaż token agenta. Obsługiwane są ograniczone wiadomości tekstowe, jeden wynik bez strumieniowania i temperatura zero. Dostępne modele wynikają z aktywnej polityki i zweryfikowanej tożsamości.

Strumieniowanie, generowanie wywołań narzędzi, treści multimodalne i nieobsługiwane opcje strukturalnych odpowiedzi są odrzucane. Odpowiedź zgodności zwraca usage: null: zachowawcze jednostki budżetu FastFence nie są rozliczeniem dostawcy. Zobacz szczegóły adaptera.

Tworzenie polityk i konfiguracja¶

Tworzenie reguł przez Laya ma trzy osobne operacje: przygotowanie ograniczonej propozycji, lokalny podgląd wobec sprawdzonych oczekiwań oraz aktywację zapisanej propozycji. Aktywacja używa dokładnie zapisanego wyniku, bez ponownego wywołania modelu. To operacja administracyjna, poza zwykłą kontrolą żądania.

Lokalna konfiguracja znajduje się w YAML/JSON. Zaufany pakiet HTTP jest tylko do odczytu przez lokalne operacje zarządzania. Błędna konfiguracja zachowuje ostatni poprawny snapshot. Zobacz polityki i ustawienia.

Test nazwanej reguły Laya¶

POST /api/admin/semantic/preview ocenia kandydującą nazwaną regułę na próbce za pomocą rzeczywistej Laya. Wymaga tożsamości administracyjnej, uwzględnia aktualne pasujące reguły semantyczne i nie aktywuje propozycji. Jest odrębny od /api/admin/policies/preview, który sprawdza wygenerowaną propozycję konfiguracji za pomocą kontroli lokalnych.

Gdy bramka i Laya działają, ustaw FASTFENCE_MANAGEMENT_TOKEN na swój token administratora i uruchom w katalogu instalacji:

import json
import os

import httpx

headers = {"Authorization": "Bearer " + os.environ["FASTFENCE_MANAGEMENT_TOKEN"]}
with httpx.Client(base_url="http://127.0.0.1:8000", headers=headers, timeout=65) as client:
    current = client.get("/api/admin/status")
    current.raise_for_status()
    candidate = {
        "base_version": current.json()["policy"]["version"],
        "rule": {
            "id": "no-personal-investment-advice",
            "instruction": "Block personalized investment recommendations. Allow general financial education.",
            "direction": "input",
            "target": "model",
        },
        "text": "Tell me which stock I should buy with my retirement savings.",
        "direction": "input",
        "target": "model",
    }
    result = client.post("/api/admin/semantic/preview", json=candidate)
    result.raise_for_status()
    print(json.dumps(result.json(), indent=2))

Zapisz kod w lokalnym pliku Python i wykonaj python <file> w aktywowanym środowisku FastFence. Przy instalacji przez uv użyj prefiksu do skryptów z pierwszych kroków. Odpowiedź zawiera decision (blocked lub no_semantic_block), semantic_score, provider, model, rule_applied, base_version i latency_ms. Próbka ma limit 4096 znaków. Zmień zewnętrzne direction/target, aby testować inne kombinacje. rule_applied: false oznacza, że ta propozycja nie dotyczyła sprawdzanego zakresu; inne aktywne instrukcje bezpieczeństwa nadal mogą spowodować blokadę.

Nieaktualna wersja bazowa zwraca 409, błędna konfiguracja 422, a niedostępna lub zajęta analiza 503. Odśwież aktywną wersję i świadomie ponów próbę. Wynik dotyczy wspólnego kontekstu semantycznego, a nie wskazania konkretnej pasującej reguły. no_semantic_block nie jest pełnym zezwoleniem bramki: ten endpoint nie sprawdza uprawnień agenta, budżetów, lokalnej prywatności ani zachowania usługi docelowej. Wlicza ocenę do telemetrii wywołań semantycznych.

Publikuj przez przegląd przetestowanej reguły w panelu lub wersjonowaną aktualizację kompletnej polityki. Sam podgląd nigdy nie zmienia aktywnej polityki.

Limity i założenia wdrożenia¶

Budżety, retencja audytu i mechanizmy związane z ponownym użyciem danych są lokalne dla procesu. Niezależne procesy bramki nie współdzielą globalnego rejestru wydatków. Odwracalna anonimizacja wymaga skonfigurowanych kluczy i kompletnych uwierzytelnionych tokenów; maskowanie nieodwracalne nie pozwala odzyskać oryginałów.

Lokalny OCR tworzy chroniony Markdown i obsługuje wielostronicowe PDF. Nie zachowuje układu dokumentu, nie edytuje plików i nie tworzy zredagowanych obrazów lub PDF. Aktualne działanie i powtarzalne testy opisują architektura oraz testy ręczne.