degov-agent-harness

Local-first agentic harness for German bureaucracy workflows.

degov-agent-harness is a Python framework for building auditable agents around German tax, bookkeeping, banking-evidence, and public-administration workflows. It is designed for workflows where APIs are incomplete, portals are still required, and a human must keep final authority over submissions, uploads, and other sensitive actions.

The project currently focuses on:

• ELSTER filing preparation and supervised submission boundaries
• DATEV / myDATEV / DATEV Unternehmen online staging workflows
• Invoice discovery, classification, and bookkeeping handoff
• Banking evidence collection for tax and accounting
• Multi-tenant, multi-entity, fiscal-year scoped workspaces
• Approval-gated browser and desktop automation contracts

This is not tax advice and it is not a finished tax-filing product. It is a safety-first harness for contributors who want to build those workflows without normalizing unsafe automation.

Why This Exists

German bureaucracy automation has an awkward integration surface: some official systems expose proprietary or restricted interfaces, many workflows still happen in portals or desktop apps, and final submissions need explicit human control.

This harness provides the control plane: tenant/entity/year isolation, modular workflow packs, staged actions, content-hash-bound approvals, final-action audit logs, and supervised browser/desktop automation contracts.

Status

The repository is early but functional as a harness foundation.

Implemented:

• FastAPI control API
• Tenant/entity/year workspace model
• Packaged workflow pack loader
• Typed tool registry and staging tools
• Append-only approval ledger
• Approval-gated final external action recording
• Browser and desktop guard contracts
• Workflow packs for tax.elster, tax.datev, invoice.ops, and finance.banking
• Unit tests for the core approval and workflow boundaries

Not implemented yet:

• Production ELSTER, DATEV, bank, or email adapters
• Tax-form-specific field mappings
• OCR and invoice extraction
• Real Computer Use / Chrome driver implementation
• Hosted multi-user UI
• Legal or tax correctness validation

Safety Model

Agents may collect, prepare, stage, and summarize. They must not perform sensitive final actions without scoped human approval.

Sensitive or final actions must build a deterministic payload, compute a stable content hash, request approval for tenant/entity/year/gate/hash, wait for human approval, validate the exact payload, execute, and record the final action.

If the dossier, field map, recipient, attachment set, or payload changes, the hash changes and the previous approval cannot be reused.

Banking Boundary

Banking workflows are evidence-only: statement downloads, transaction exports, account metadata, receipt capture, and reconciliation packages.

The harness must stop before transfers, standing orders, card changes, loan actions, permission changes, or any other money movement.

Authentication Boundary

Agents must not type or store passwords, TANs, app confirmations, or 2FA codes. For browser, mail, banking, DATEV, and ELSTER sessions, open the relevant portal or app, pause for manual authentication, then continue only inside the approved scope.

Installation

Requirements:

• Python 3.12+
• uv

git clone https://github.com/SebastianBoehler/degov-agent-harness.git
cd degov-agent-harness
uv sync

Verify the package:

uv run python -c "import degov_harness; print(degov_harness.__version__)"
uv run pytest -q
uv run ruff check .

Quick Start

List bundled workflow packs:

uv run python - <<'PY'
from degov_harness.core.workflow_packs import default_workflow_pack_root, load_workflow_packs

for pack in load_workflow_packs(default_workflow_pack_root()):
    print(f"{pack.name}: {pack.domain}")
PY

Start the local API:

uv run uvicorn degov_harness.api.app:create_app --factory --reload

Inspect available packs:

curl http://127.0.0.1:8000/workflow-packs

Stage an ELSTER filing payload:

curl -X POST http://127.0.0.1:8000/tools/stage_elster_filing \
  -H 'content-type: application/json' \
  -d '{
    "profile": "local",
    "payload": {
      "ref": {
        "tenant_id": "demo-tenant",
        "entity_id": "demo-entity",
        "fiscal_year": 2026
      },
      "payload": {
        "form": "ustva",
        "period": "2026-01",
        "fields": {}
      }
    }
  }'

By default, local artifacts are written under .degov/.

Core Concepts

Workspace

Workspace stores data under tenant, entity, and fiscal-year scoped paths:

.degov/
  tenants/
    demo-tenant/
      entities/
        demo-entity/
          years/
            2026/
              domains/
                tax/
                invoice/
                finance/
      audit/

Workflow Packs

Workflow packs describe domain capabilities as modular YAML plus instructions. Bundled packs live in src/degov_harness/workflow_packs.

Pack	Purpose
tax.elster	ELSTER dossier, field-map, staged filing, and final-submit approval boundary
tax.datev	DATEV document, booking, master-data, and mutation staging
invoice.ops	Invoice file intake, invoice facts, and booking/export handoff
finance.banking	Banking evidence collection for bookkeeping and tax reconciliation

Tools

Bundled staging tools:

• stage_datev_action
• stage_elster_filing
• stage_external_action
• render_review_summary
• record_final_external_action

Approvals

ApprovalLedger stores approval requests and approvals in append-only NDJSON. Approval records are scoped to tenant, entity, fiscal year, approval gate, and content hash. Final external actions must validate against this ledger.

Connectors

Connectors are the boundary between the harness and external systems.

• PortalSessionGuard validates browser portal actions.
• DesktopSessionGuard validates supervised browser, mail, file-manager, and installed-app actions.

Production adapters should use these guards before interacting with ELSTER, DATEV, banks, email clients, local files, or other external systems.

Supervised Desktop Automation

Some workflows do not have usable APIs. The intended fallback is visible desktop automation with a local machine or VM:

• OS with a browser profile and required apps installed
• Optional virtual display
• Browser sessions for ELSTER, DATEV, bank portals, and other services
• Mail and file-manager access for finding invoices and receipts
• Human login and 2FA handoff
• Approval checks before sensitive or final UI actions

The harness provides contracts and guards for this path. It does not yet ship a production Computer Use or Chrome driver.

Project Structure

src/degov_harness/
  api/                  FastAPI app factory
  connectors/           Browser and desktop automation guard contracts
  core/                 Workspace, approvals, models, workflow packs
  tools/                Tool context, registry, staging tools
  workflow_packs/       Bundled workflow packs
tests/                  Unit tests for safety and workflow behavior

Development

uv sync
uv run pytest -q
uv run ruff check .
uv build --wheel

Contributing

Contributions are welcome, especially around:

• New workflow packs for German bureaucracy workflows
• ELSTER and DATEV field-map scaffolding
• Invoice extraction and evidence packaging
• Safe portal automation adapters
• Better review summaries and approval UX
• Tests for approval and connector boundary cases

Guidelines:

• Keep modules small and focused.
• Add or update tests for behavior changes.
• Do not add mock fallbacks that look like real integrations.
• Do not bypass approval gates for external mutations.
• Do not add automation that types credentials, TANs, or 2FA codes.
• Keep banking workflows evidence-only.
• Prefer explicit errors over silent best-effort behavior.

Before opening a pull request:

uv run pytest -q
uv run ruff check .
uv build --wheel

Designing Workflow Packs

A workflow pack should define its name, domain, required connectors, roles, inputs, outputs, tools, approval gates, and human-readable operating instructions in SKILL.md. Use existing packs under src/degov_harness/workflow_packs as templates.

License

MIT. See LICENSE.