<\/p>\n
Flock & Dapr: Resilient Cloud-Native Agent Swarms<\/p>\n
<\/h1><\/div>
Contents<\/p>\n\n\n\n
- \n
- What is Dapr?<\/a><\/li>\n\n\n\n
- Why we built this integration<\/a><\/li>\n\n\n\n
- The integration surface is small<\/a><\/li>\n\n\n\n
- One workflow, three backends<\/a><\/li>\n\n\n\n
- One-time setup<\/a><\/li>\n\n\n\n
- In-memory: the local baseline<\/a><\/li>\n\n\n\n
- PostgreSQL: durable and transactional<\/a><\/li>\n\n\n\n
- Redis encrypted: hardened for cloud-native deployment<\/a><\/li>\n\n\n\n
- Capabilities, not promises<\/a><\/li>\n\n\n\n
- Why this matters<\/a><\/li>\n\n\n\n
- Dapr or SQLite? A quick decision guide<\/a><\/li>\n\n\n\n
- Building production agent systems?<\/a><\/li>\n<\/ul>\n\n\n\n
Anyone who has pushed agent workflows past a demo runs into the same wall: building the agents is the easy part. Running them reliably in production is not. Shared state needs to survive restarts, there needs to be a clean path to distributed execution, retries and failures need to be handled without bespoke adapter code for every backend, and the storage story needs to evolve from local development to production without a rewrite. That is exactly the wall we hit as we pushed Flock<\/a> toward more serious workflows.<\/p>\n\n\n\n
Flock is built around a blackboard model<\/a>. Agents publish and consume typed artifacts, and the orchestration layer decides what should run next. That design already aligns with cloud-native thinking: low coupling, clear contracts, and small pieces that can be swapped independently. What it was missing was a production-grade home for the blackboard itself. That is exactly where Dapr fits, and it is what we shipped in Flock 0.5.600<\/a>, a Dapr integration, available as an optional
flock-core[dapr]<\/code> extra.<\/p>\n\n\n\nWhat is Dapr?<\/h3>\n\n\n\n
Dapr<\/a> is a portable, event-driven runtime that exposes cross-cutting building blocks, things like state management, pub\/sub, secrets, and resiliency, over a local sidecar. Your application talks to a stable Dapr API, and Dapr talks to the actual backend, so the application code never learns which database, key-value store, or secret manager sits underneath. It is a CNCF-graduated project with a large component ecosystem.<\/p>\n\n\n\n
More recently, Dapr has grown a set of first-class agent integrations<\/a> aimed squarely at agentic frameworks. They add the production concerns those frameworks tend to skip: durable execution, portable agent context and memory through the State Management API<\/a>, secure agent-to-agent communication, and secure agent identity. Flock uses one of those building blocks, the state store, as an optional distributed backend for the blackboard.<\/p>\n\n\n\n
Why we built this integration<\/strong><\/h3>\n\n\n\n
Agent systems look simple until the first production requirement shows up. Then the list starts growing quickly: shared state must survive restarts, multiple instances may need to see the same blackboard, secrets should not live in code, writes should be resilient, and different environments may prefer different storage backends.<\/p>\n\n\n\n
At that point, you have two options. You can write a bespoke storage adapter for every backend you want to support and own all of the retry logic, encryption, and secret handling that comes with each one. Or you can delegate that operational layer to something purpose-built. We chose the second because those are exactly the problems Dapr already solves for cloud-native systems.<\/p>\n\n\n\n
The result is a much cleaner boundary. Flock owns agent logic, typed artifacts, routing, and orchestration. Dapr owns state-store access, backend portability, retries, encryption, and backend-specific capabilities such as transactions, ETags, query support, or TTL where the chosen store supports them. Your application code stays mostly unchanged while the infrastructure underneath becomes more capable.<\/p>\n\n\n
\n![\"\"](\"https:\/\/whiteduck.de\/wp-content\/uploads\/flock-dapr-1-1024x819.png\")
<\/a>From agent output to durable storage: Flock’s Blackboard over Dapr<\/figcaption><\/figure>\n<\/div>\n\n\n For the teams building on Flock, that boundary turns into concrete benefits. You can start on a local sandbox and grow to production without rewriting the swarm. You do not have to pick a storage backend on day one and live with that decision forever. Secrets and resilience policies live in infrastructure instead of glue code. And the same workflow runs on an in-memory store, on PostgreSQL, or on encrypted Redis with almost no code churn. If your team is not ready for a distributed backend at all, Flock still ships a single-node persistent blackboard<\/a>, and we come back to when to use which at the end.<\/p>\n\n\n\n
The integration surface is small<\/strong><\/h3>\n\n\n\n
The best sign that an integration is healthy is that it stays small. In Flock, the Dapr integration is intentionally thin. The core pieces are
DaprStateBlackboardConfig<\/code>,DaprStateBlackboardStoreClientConfig<\/code>, andDaprStateBlackboardStore<\/code>. The swap point is thestore=<\/code> argument when you createFlock<\/code>.<\/p>\n\n\n\n\nfrom flock import Flock\n\nfrom flock.storage.dapr import (\n\nDaprStateBlackboardConfig,\n\nDaprStateBlackboardStore,\n\nDaprStateBlackboardStoreClientConfig,\n\n)\n\nclient_config = DaprStateBlackboardStoreClientConfig(\n\ndapr_grpc_endpoint=\"localhost:50001\",\n\n)\n\nstore_config = DaprStateBlackboardConfig(\n\nstore_name=\"flockstate\",\n\nsupports_transactions=True,\n\nsupports_etag=True,\n\nconsistency=\"strong\",\n\nclient_config=client_config,\n\n)\n\nstore = DaprStateBlackboardStore(config=store_config)\n\nflock = Flock(\n\nmodel=\"openai\/gpt-4.1\",\n\nstore=store,\n\n)\n<\/code><\/pre>\n\n\n\nThat is the architectural win in one snippet. The agents do not know which backend is underneath them. The blackboard contract stays the same. Only the Dapr component definition and a few capability flags change. You can read the full setup in the Dapr State Store guide<\/a>.<\/p>\n\n\n\n
One workflow, multiple backends<\/strong><\/h3>\n\n\n
\n![\"\"](\"https:\/\/whiteduck.de\/wp-content\/uploads\/flock-dapr-2-1024x614.png\")
<\/a>One codebase, three interchangeable backends: In-Memory, PostgreSQL, or encrypted Redis<\/figcaption><\/figure>\n<\/div>\n\n\n To make the portability claim concrete, we run one small agent team across three different backends without touching the application logic. The team is deliberately playful:<\/p>\n\n\n\n
- \n
- A
talent_scout<\/code> looks for promising musicians based on aBandConcept<\/code> and produces a cohesiveBandLineup<\/code>.<\/li>\n\n\n\n- A
music_producer<\/code> takes thatBandLineup<\/code> and designs anAlbum<\/code> around it.<\/li>\n\n\n\n- A
marketing_guru<\/code> turns theAlbum<\/code> intoMarketingCopy<\/code> and handles the PR side of things.<\/li>\n<\/ul>\n\n\n\nHere are the typed artifacts that pass through the blackboard as these three agents interact:<\/p>\n\n\n\n
\n@flock_type\nclass BandConcept(BaseModel):\n genre: str = Field(description=\"Musical genre (rock, jazz, metal, pop, etc.)\")\n vibe: str = Field(description=\"The band's vibe or aesthetic\")\n target_audience: str = Field(description=\"Who should love this band?\")\n\n\n@flock_type\nclass BandLineup(BaseModel):\n band_name: str = Field(description=\"Cool band name\")\n members: list[dict[str, str]] = Field(description=\"Members with their roles\")\n origin_story: str = Field(description=\"How the band formed\", min_length=100)\n signature_sound: str = Field(description=\"What makes their sound unique\")\n\n\n@flock_type\nclass Album(BaseModel):\n title: str = Field(description=\"Album title in ALL CAPS\")\n tracklist: list[dict[str, str]] = Field(\n description=\"Songs with titles and brief descriptions\",\n min_length=8, max_length=12,\n )\n genre_fusion: str = Field(description=\"How this album blends genres\")\n standout_track: str = Field(description=\"The track that'll be a hit\")\n production_notes: str = Field(description=\"Special production techniques\")\n\n\n@flock_type\nclass MarketingCopy(BaseModel):\n press_release: str = Field(description=\"Press release for the album\", min_length=200)\n social_media_hook: str = Field(description=\"Catchy social post\", max_length=280)\n billboard_tagline: str = Field(description=\"10-word tagline\", max_length=100)\n target_playlists: list[str] = Field(\n description=\"Playlists to pitch to\", min_length=3, max_length=5,\n )\n<\/code><\/pre>\n\n\n\nThe three agents are just as declarative:
<\/p>\n\n\n\n\ntalent_scout = (\n flock.agent(\"talent_scout\")\n .description(\"A legendary talent scout who assembles perfect band lineups\")\n .consumes(BandConcept)\n .publishes(BandLineup, visibility=PublicVisibility())\n)\nmusic_producer = (\n flock.agent(\"music_producer\")\n .description(\"A visionary music producer who creates debut album concepts\")\n .consumes(BandLineup)\n .publishes(Album, visibility=PublicVisibility())\n)\nmarketing_guru = (\n flock.agent(\"marketing_guru\")\n .description(\"A marketing genius who writes compelling promotional material\")\n .consumes(Album)\n .publishes(MarketingCopy, visibility=PublicVisibility())\n)\n<\/code><\/pre>\n\n\n\nThis is the whole agent. From here on, nothing in this code changes. The only thing that changes is the infrastructure Dapr sits on top of. We move through three backends: in-memory for fast local development, PostgreSQL for a durable test deployment, and encrypted Redis for a hardened production profile. As your swarm evolves, you can start small and swap the backend depending on your needs, without locking yourself into one path early.<\/p>\n\n\n\n
One-time setup<\/strong><\/h3>\n\n\n\n
Everything below runs through the Dapr CLI, so the local setup is two commands:<\/p>\n\n\n\n
\npip install \"flock-core[dapr]\"\ndapr init\n<\/code><\/pre>\n\n\n\nThe first command pulls in Flock plus the optional Dapr dependencies.
dapr init<\/code> then installs the Dapr runtime and its local control plane, the background services (placement and scheduler) that the sidecar relies on. From here, each backend is a small component file plus a couple of Flock capability flags. If you would rather wire the sidecar, placement, and scheduler yourself, the repository’s examples\/12-dapr<\/a> ships full Docker Compose stacks. We use the CLI here to keep the moving parts visible.<\/p>\n\n\n\nIn-memory: the local baseline<\/strong><\/h3>\n\n\n\n
The in-memory backend is the simplest version, and we use it here to establish the Dapr code path before attaching a real store. For actual single-node development, you would normally reach for Flock’s built-in SQLite blackboard instead, which we cover in the decision guide at the end; in-memory earns its place only as the smallest possible wiring example. The story is intentionally boring in the best way: no encryption, no transactions, no TTL, and no query API, with state living inside the Dapr sidecar.<\/p>\n\n\n\n
The component is only a few lines. Save it as `.\/components\/statestore.yaml`:<\/p>\n\n\n\n
\napiVersion: dapr.io\/v1alpha1\nkind: Component\nmetadata:\n name: flockstate\nspec:\n type: state.in-memory\n version: v1\n<\/code><\/pre>\n\n\n\nThe Flock application loads its configuration through Dapr and passes it to the blackboard store, so nothing is hardcoded in the source.<\/p>\n\n\n\n
\nfrom flock import Flock, PublicVisibility, flock_type\nfrom flock.storage.dapr import (\n DaprStateBlackboardConfig,\n DaprStateBlackboardStore,\n)\n\n# Load config and secrets from the Dapr secret store.\nsecrets = load_dapr_secrets(\"http:\/\/localhost:50001\")\n\nstore_config = DaprStateBlackboardConfig(\n store_name=secrets[\"store_name\"],\n supports_transactions=secrets[\"supports_transactions\"],\n supports_etag=secrets[\"supports_etag\"],\n supports_ttl=secrets[\"supports_ttl\"],\n supports_dapr_query_lang=secrets[\"supports_dapr_query_lang\"],\n encrypted_backend=secrets[\"encrypted_backend\"],\n backend_encryption_key=secrets[\"backend_encryption_key\"],\n consistency=secrets[\"consistency\"],\n)\ndapr_store = DaprStateBlackboardStore(config=store_config)\n\nflock = Flock(\n model=secrets[\"default_model\"],\n store=dapr_store, # Dapr-backed blackboard\n)\n\n# ... define artifacts and agents exactly as above ...\n\nawait flock.serve(dashboard=True)\n<\/code><\/pre>\n\n\n\nStart the app with a Dapr sidecar in a single command:<\/p>\n\n\n\n
\ndapr run --app-id flock-dev --dapr-grpc-port 50001 \\\n --resources-path .\/components -- python app.py\n<\/code><\/pre>\n\n\n\nThis launches the Dapr sidecar next to your process, loads every component from
.\/components<\/code> (theflockstate<\/code> store you just defined), and then runsapp.py<\/code>. Flock talks to that sidecar over gRPC on port 50001, which is the endpoint the store client connects to.<\/p>\n\n\n\nDapr now defines what the environment looks like and how it behaves. The application does not really know what kind of backend it is going to get, and it does not have to. All it does is ask Dapr what the store looks like. Flock adapts to the environment it is deployed to, not the other way around. Secrets, by the way, live where they belong: in a Dapr secret store<\/a>, not the source tree.<\/p>\n\n\n\n
PostgreSQL: durable and transactional<\/strong><\/h3>\n\n\n\n
The PostgreSQL backend is where the example starts to feel like production. The blackboard state is backed by a durable database, and the component enables transactional writes and ETags with strong consistency. Point a local PostgreSQL instance at Dapr with a one-line container:<\/p>\n\n\n\n
\ndocker run -d --name flock-postgres -p 5432:5432 \\\n -e POSTGRES_PASSWORD=your-password \\\n -e POSTGRES_DB=flock_dapr postgres:17\n<\/code><\/pre>\n\n\n\nThis starts a PostgreSQL container in the background, exposed on the standard port 5432, with an empty
flock_dapr<\/code> database ready for Dapr to use. The password and database name here have to match the connection string in the component below.<\/p>\n\n\n\nThen swap the component. Only the
spec<\/code> block changes:<\/p>\n\n\n\n\napiVersion: dapr.io\/v1alpha1\nkind: Component\nmetadata:\n name: flockstate\nspec:\n type: state.postgresql\n version: v2\n metadata:\n - name: connectionString\n value: \"host=localhost port=5432 user=postgres password=your-password dbname=flock_dapr\"\n<\/code><\/pre>\n\n\n\nNow the infrastructure is a little more capable. Does the Flock application need to change? Not at all, and this is exactly where Dapr shows its value. The Python is byte-for-byte identical to the in-memory version: the same artifacts, the same agents, the same
flock.serve(dashboard=True)<\/code>. Only the component file and a handful of capability flags in the secret store moved, and this time the application got transactions, ETags, and a durable database. You start it with the samedapr run<\/code> command as before.<\/p>\n\n\n\nRedis encrypted: hardened for cloud-native deployment<\/strong><\/h3>\n\n\n\n
The encrypted Redis profile is the most security-oriented one in the set. The state is encrypted at rest through the Flock configuration, which is a strong fit for environments where the blackboard holds real operational data. Run a Redis Stack container, which enables the query API out of the box, with a password:<\/p>\n\n\n\n
\ndocker run -d --name flock-redis -p 6379:6379 \\\n -e REDIS_ARGS=\"--requirepass your-password\" \\\n redis\/redis-stack:latest\n<\/code><\/pre>\n\n\n\nThis starts a Redis Stack container, which is Redis plus the RediSearch and RedisJSON modules, so the Dapr query API works without any extra setup. The `REDIS_ARGS` value sets a password on the instance, which the component then uses to authenticate.<\/p>\n\n\n\n
Then point the component at it:<\/p>\n\n\n\n
\napiVersion: dapr.io\/v1alpha1\nkind: Component\nmetadata:\n name: flockstate\nspec:\n type: state.redis\n version: v1\n metadata:\n - name: redisHost\n value: localhost:6379\n - name: redisPassword\n value: \"your-password\" # in production, reference a Dapr secret store instead\n<\/code><\/pre>\n\n\n\nEncryption is turned on through the Flock capability flags the app already reads from its secret store,
encrypted_backend<\/code> andbackend_encryption_key<\/code>. The application code, again, does not change.<\/p>\n\n\n\nThere is one important detail to call out clearly. Encrypted backends disable transactions in this integration because of a Dapr runtime serialization limitation. That is not a flaw in the Flock design; it is exactly the kind of infrastructure boundary that Dapr is meant to absorb. The application still gets a resilient, encrypted blackboard, but the integration is honest about what the backend can safely guarantee rather than pretending otherwise.<\/p>\n\n\n\n
Why this matters<\/h3>\n\n\n\n
The real win is not that Flock can talk to Dapr. The real win is that Flock and Dapr share the same philosophy. Flock already treats the blackboard as the center of the system. Dapr gives that blackboard a production-grade runtime boundary. Put together, agents stay declarative, state is externalized, secrets stay out of source control, resilience is handled consistently by infrastructure, and the backend can evolve without rewriting the swarm.<\/p>\n\n\n\n
That is the cloud-native story we wanted from the start. It removes friction from future development, keeps the agent implementation focused on domain logic, and lets the underlying state layer become someone else’s problem in the best possible way. If you are building Flock agents and you already think in terms of distributed systems, Dapr is a very natural fit. It gives the blackboard the infrastructure it deserves, while the agents stay small, declarative, and easy to reason about.<\/p>\n\n\n\n
Dapr or SQLite? A quick decision guide<\/strong><\/h3>\n\n\n\n
Not every project needs a distributed backend, and Flock ships a built-in SQLite-backed persistent blackboard for exactly that reason. Here is how we decide:<\/p>\n\n\n\n
- A
- Why we built this integration<\/a><\/li>\n\n\n\n