• Python 3.12+
• uv
• just
• Azure CLI (logged in)
• Azure subscription with OpenAI access

# api/src/agents/finance/agent.py
class FinanceAgent(DomainAgent):
    @property
    def name(self) -> str:
        return "finance_agent"

    @property
    def description(self) -> str:
        return "Handles budget and procurement queries"

    @property
    def rag_scope(self) -> RAGScope:
        return RAGScope(domain="finance", document_types=["policy", "procedure"])

    @property
    def system_prompt(self) -> str:
        return "You are a finance specialist..."

That's it. No registration, no config changes. The framework discovers the subclass at startup, creates its RAG tool with domain-isolated filters, and adds it to the coordinator's handoff graph. See api/src/agents/_base.py for the full interface and api/src/agents/_discovery.py for the discovery mechanism.

The RAG tool (api/src/rag/tools.py) implements a multi-strategy search pipeline:

1. Primary hybrid search — BM25 + vector (text-embedding-3-large) with domain-scoped OData filters
2. Broadened filter fallback — relaxes non-identity filters when primary returns too few results
3. Keyword-only rescue — drops vector search entirely for edge cases where embeddings miss

Additional pipeline features:

• LLM query rewriting — rewrites conversational questions into keyword-rich search queries
• Chunk merging — consecutive chunks from the same document are merged to give the LLM complete context
• Score normalisation — normalises across BM25 and RRF score scales
• Quality gate — post-response validation catches infrastructure errors, skipped searches, ignored results, and missing sources (api/src/rag/quality_gate.py)
• Source recovery — extracts and deduplicates source references from raw agent output (api/src/agents/_output.py)
• Proofreading pass — a fast Haiku model fixes generation artefacts before final delivery (api/src/agents/_proofread.py)

phase(thinking) → agent(name) → phase(generating) → delta* → phase(verifying) →
confidence → verification → usage → done → [DONE]

• :keepalive comments every 5 seconds
• phase(waiting) after 10 seconds of no output (e.g. during upstream 429 retry)
• debug events with RAG search details (dev mode + X-Surf-Debug header)
• error events with structured codes for client-side handling

The chat endpoint accepts PDF file attachments with tiered processing (api/src/orchestrator/pdf.py):

• Tier 1 (direct vision): PDFs up to 30 pages are sent as native document content blocks
• Tier 2 (text extraction): Larger PDFs get text extracted and sent as text blocks
• Size limit: 100 MB with decompression bomb protection

Surf implements defence-in-depth. The full model is documented in docs/security-model.md.

Security tests in api/tests/security/ cover JWT bypass attempts, input injection vectors, and conversation isolation.

Telemetry configuration: api/src/middleware/telemetry.py. Langfuse integration: api/src/middleware/langfuse_utils.py.

Surf's Azure infrastructure is defined in a single infra/main.bicep orchestrator (1,200+ lines) using Azure Verified Modules:

Three environments: dev.bicepparam, staging.bicepparam, prod.bicepparam.

Both GitHub Actions and GitLab CI/CD pipelines are maintained:

Key properties:

• Zero stored secrets — GitHub uses OIDC federation; GitLab uses Workload Identity Federation via a dedicated CI managed identity provisioned in Bicep
• Path-filtered — only relevant pipelines run per commit
• Security scanning — Gitleaks secret scanning, pip-audit dependency auditing
• Docker builds with BuildKit and multi-platform support

The ingestion service (ingestion/) transforms raw documents into searchable index entries:

Run with: just test (unit + security), just test-integration, just eval, just smoke.