AutoFlow: Multi-Agent Inquiry Automation with LangGraph and Local Ollama

AutoFlow is a production-oriented, multi-agent inquiry automation platform designed for organizations that need fast intake, deterministic orchestration, and auditable outcomes rather than black-box prompt chains. The system accepts structured inbound inquiries over a versioned FastAPI webhook, acknowledges immediately with a durable `run_id`, and executes LangGraph orchestration asynchronously using local-first Ollama inference for classification and specialist behavior. Redis provides low-latency run state for live status and operator timelines, while PostgreSQL remains the durable system of record for compliance, analytics, and post-incident reconstruction. This split architecture is not accidental: it cleanly separates responsiveness from durability, and experimentation from governance. AutoFlow therefore serves two goals at once: excellent real-time operator experience and long-horizon operational correctness. For teams searching terms such as enterprise AI workflow orchestration, FastAPI LangGraph architecture, local LLM automation, or auditable multi-agent systems, AutoFlow demonstrates a practical reference pattern that can scale from pilot to production without discarding its original contracts.

Architectural goals

• Enforce separation of concerns so API routing, orchestration logic, domain tools, state management, and UI concerns can evolve independently with focused tests.
• Guarantee deterministic intent transitions by encoding routing as explicit graph nodes and conditional edges, not hidden prompt-side branching.
• Prefer local-first inference through Ollama to improve data-residency posture, reduce external dependency concentration, and preserve cost predictability.
• Split operational state into hot and durable planes: Redis for low-latency visibility and PostgreSQL for canonical historical truth.
• Acknowledge webhook traffic immediately with stable `run_id` correlation so upstream systems never block on downstream model latency.
• Apply progressive ingress hardening through optional API keys, idempotency windows, rate limits, origin controls, and admin-scoped deletion.
• Persist confidence, escalation rationale, and step-level chronology so outcomes remain inspectable by engineering, security, and operations.
• Allow scale evolution from single process to worker-queue architectures without changing edge API contracts.
• Unify observability by linking request IDs, run IDs, graph-node events, Redis snapshots, and database records.
• Retain architecture legibility so external reviewers can reason about failure domains and control points without reverse-engineering prompts.
• Make extension safe by keeping integration concerns isolated from orchestration logic and state semantics.

System context

The context view describes a deliberately narrow blast radius between external demand and internal execution. Integrations and forms only need one stable contract (`POST /api/v1/webhook`) to submit business inquiries, while operators use a separate Next.js control center for run health, timeline inspection, and historical review. FastAPI operates as the control plane at ingress: it validates payloads, enforces optional API security and idempotency policy, records initial state, and starts asynchronous graph execution. Downstream concerns are separated by purpose. PostgreSQL is the durable truth layer for final status, agent decisions, and reporting. Redis is the hot path for low-latency run state and step streams. Ollama is the local-first model substrate used by classification and specialist nodes. The resulting boundary map is intentionally SEO-relevant to enterprise buyers evaluating FastAPI microservice architecture, LangGraph production design, Redis plus Postgres dual-state patterns, and private LLM inference deployments. AutoFlow succeeds because each dependency has one clear reason to exist, and those reasons remain valid even as traffic, policy, and compliance requirements evolve.

Logical architecture layers

This layered model is the maintainability backbone of AutoFlow. In many AI systems, architecture erosion starts when route handlers absorb workflow logic, tool modules write persistence side effects directly, and UI assumptions leak into backend state semantics. AutoFlow avoids that drift by making responsibility explicit. API/edge owns ingress and contract discipline. Orchestration owns decision flow. Domain tools expose bounded actions without controlling lifecycle. Integration adapters isolate transport details for model calls. Hot and durable state encode speed-versus-governance tradeoffs as first-class design decisions. Presentation stays a contract consumer instead of a hidden backend dependency. For technical leadership, this separation translates to lower blast radius, safer upgrades, and clearer ownership boundaries across platform, AI, and frontend teams.

Logical flow diagram

The flow emphasizes that synchronous user contracts and asynchronous compute are intentionally decoupled. Webhook submission initializes run state and returns quickly, while `graph_execution.process_inquiry_run` performs expensive orchestration in background execution. Status and steps are served through Redis-first reads for speed, with durable fallback to PostgreSQL for historical truth. The WebSocket path is optional but valuable for operator ergonomics where real-time completion notifications reduce manual polling pressure. This architecture aligns with high-intent design goals common in enterprise automation: deterministic lifecycle semantics, bounded latency at ingress, and transparent eventual consistency between hot and durable stores.

LangGraph orchestration

• `classify_intent`: structured intent inference maps incoming payloads to the routing taxonomy and records confidence signals.
• `route_by_intent`: deterministic edge logic maps intents to FAQ, lead, or support specialist paths.
• `faq_node`, `lead_node`, and `support_node`: specialist nodes produce domain-specific enrichment and recommended actions.
• `route_after_agent`: post-specialist gate checks escalation flags and forwards to handoff or synthesis.
• `handoff_node`: emits operator-ready escalation context for high-risk, low-confidence, or policy-sensitive cases.
• `synthesize_response_node`: composes final customer-facing responses when escalation is unnecessary.
• `log_audit`: terminal state bookkeeping persists node-level chronology and final lifecycle artifacts.
• `thread_id=run_id`: execution correlation guarantees run-level traceability across retries, logs, and state stores.

The orchestration layer remains stable because state is explicit and typed. `AgentState` is implemented as a `TypedDict` describing shared lifecycle fields such as message history, inferred intent, confidence, escalation flags, resolution draft text, and specialist step chronology. This is a reliability control, not style preference. Typed state constrains accidental key drift between nodes, keeps serialization behavior predictable across Redis and PostgreSQL writes, and protects downstream analytics against silent schema mutation. The `messages` field uses `Annotated[list, add_messages]`, aligning with LangGraph merge semantics so node deltas compose correctly instead of overwriting prior context. Operationally, this produces reproducible debugging: teams can localize failures to classification quality, specialist reasoning, escalation policy, or synthesis behavior without reverse-engineering opaque prompt traces.

A critical caveat is checkpoint durability. The reference topology compiles LangGraph with `MemorySaver`, which is appropriate for local development, architecture demos, and single-process environments where restart boundaries are controlled. It is not a durable distributed checkpointer and should not be treated as one in multi-replica production systems. As throughput and reliability requirements increase, organizations should migrate checkpoint persistence to durable storage so replay semantics survive process crashes, autoscaling events, and cross-instance routing. AutoFlow intentionally preserves a clear seam for this migration, enabling teams to move from fast iteration to hardened operational replay guarantees without changing external API contracts.

Request lifecycle

• 1. Client submits a structured payload to `POST /api/v1/webhook`.
• 2. API applies schema validation plus optional API-key, idempotency, CORS, and rate-limit policy.
• 3. Ingress computes or reuses a stable `run_id` for traceability across every downstream artifact.
• 4. API writes initial `running` state into Redis for low-latency observability.
• 5. API persists initial run metadata to PostgreSQL for durable accountability.
• 6. API returns `200` immediately with `run_id` and `poll_url`, isolating callers from model latency.
• 7. `BackgroundTasks` dispatches `process_inquiry_run` for asynchronous graph execution.
• 8. LangGraph executes with `thread_id=run_id`, driving intent classification and specialist behavior through Ollama.
• 9. Terminal state, confidence, and step chronology are persisted back to PostgreSQL and Redis.
• 10. WebSocket subscribers receive completion notifications while REST clients poll status endpoints.
• 11. Historical queries and analytics consume durable records from PostgreSQL independent of Redis TTL behavior.

API surface

A compact API matrix is a strategic control point. It reduces integration ambiguity, improves contract governance, and keeps versioning overhead manageable as teams add capabilities. For reviewers, explicit method-path-purpose mapping accelerates threat modeling, test-case generation, and release approvals because ingress behavior is easy to audit. For client developers, a clear endpoint taxonomy prevents accidental coupling and simplifies failure handling: intake routes differ from status routes, and historical retrieval is cleanly separated from live subscription channels. The `/docs` contract further supports generated clients and policy review in CI pipelines.

Security model

Security posture in AutoFlow is progressive by design. Teams can start with key-based ingress protection and idempotency, then evolve toward stronger identity, network segmentation, and data-governance controls as risk tolerance tightens. This sequencing is operationally realistic: it preserves delivery velocity while establishing enforceable checkpoints for compliance and external assurance reviews.

Data and Redis keys

AutoFlow intentionally uses an eventual-consistency model tuned for both operator responsiveness and governance durability. Intake writes initial state to Redis for immediate visibility, then writes baseline run metadata to PostgreSQL for canonical traceability. Completion paths update both planes with terminal status and step chronology. Status reads are Redis-first for speed but can fall back to PostgreSQL when keys expire or when durable truth is required for reporting and audits. This pattern delivers a responsive UX without sacrificing compliance posture, but it requires active management: teams should monitor cache eviction, DB write latency, and divergence windows between state planes, then codify reconciliation runbooks for degraded dependency scenarios.

Observability

• Propagate `X-Request-ID` through responses and logs for fast client-to-backend incident correlation.
• Log in structured UTC format with stable logger semantics to simplify centralized ingestion and alert routing.
• Emit dependency-aware health semantics so Redis and database failures can signal degraded status explicitly.
• Instrument graph-node timing and model-call latency via OpenTelemetry spans for bottleneck isolation.
• Track intent confidence and escalation rates over time to detect routing drift and threshold instability.
• Measure webhook p50/p95/p99 latency, end-to-end completion duration, and per-intent error profiles for SLO design.
• Run synthetic probes against health and representative webhook payloads to catch regressions early.
• Correlate lifecycle artifacts by `run_id` across Redis snapshots, Postgres rows, and WebSocket completion events.
• Capture model-version and workflow-version labels per run for release-aware performance and quality analysis.
• Create quality dashboards linking route class, escalation outcome, and operator intervention rates.

Deployment topologies

A mature rollout often follows a staged progression: begin with a single-node reference deployment to stabilize contracts and operator workflow, move to replicated API plus shared infrastructure when ingress volume increases, then isolate orchestration into queue-backed workers as completion latency and burst variance become dominant constraints. This progression preserves architectural continuity while introducing reliability controls only when they pay for themselves operationally.

Extension roadmap

• Implement signed webhook verification with key rotation and tenant-scoped credential governance.
• Move orchestration from `BackgroundTasks` to queue-backed workers with idempotent consumers and DLQ replay.
• Replace process-local `MemorySaver` with durable LangGraph checkpoint persistence and migration playbooks.
• Introduce distributed WebSocket fan-out using Redis Streams or pub/sub for multi-replica correctness.
• Deploy full OpenTelemetry tracing plus SLO dashboards for latency, availability, and quality outcomes.
• Establish offline evaluation harnesses for intent precision, escalation quality, and draft-response regression gates.
• Adopt OIDC and RBAC for control-center access and sensitive administrative API operations.
• Expand analytics to include conversion lift, escalation deflection, and time-to-resolution by confidence bands.
• Treat `MODEL_VERSION` and `WORKFLOW_VERSION` as first-class release artifacts in rollback policy.
• Add policy-driven PII controls such as selective redaction, retention windows, and field-level encryption.
• Introduce tenant-aware partitioning strategies for data, cache keys, and observability dimensions.
• Add contract tests and chaos drills that validate behavior under Redis or model-provider partial outages.

AutoFlow demonstrates that production-ready AI orchestration is less about clever prompts and more about disciplined systems design: explicit contracts, typed state, clear dependency boundaries, and measurable operational behavior. That is why the architecture remains resilient under both engineering scrutiny and SEO-intent evaluation for enterprise buyers researching practical multi-agent automation patterns.