<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:dc="http://purl.org/dc/elements/1.1/">
  <channel>
    <title>DEV Community: Mehdi Mohseni</title>
    <description>The latest articles on DEV Community by Mehdi Mohseni (@mehdimohseni82).</description>
    <link>https://dev.to/mehdimohseni82</link>
    <image>
      <url>https://media2.dev.to/dynamic/image/width=90,height=90,fit=cover,gravity=auto,format=auto/https:%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Fuser%2Fprofile_image%2F3995225%2Fbc07aed1-ad2b-4ece-bb50-e3be3cb43a0f.jpg</url>
      <title>DEV Community: Mehdi Mohseni</title>
      <link>https://dev.to/mehdimohseni82</link>
    </image>
    <atom:link rel="self" type="application/rss+xml" href="https://dev.to/feed/mehdimohseni82"/>
    <language>en</language>
    <item>
      <title>Idempotent Bulk Ingestion into NebulaGraph from .NET: Solving the Duplicate Problem at the VID Level</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Fri, 30 Oct 2026 19:46:50 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/idempotent-bulk-ingestion-into-nebulagraph-from-net-solving-the-duplicate-problem-at-the-vid-level-1cfg</link>
      <guid>https://dev.to/mehdimohseni82/idempotent-bulk-ingestion-into-nebulagraph-from-net-solving-the-duplicate-problem-at-the-vid-level-1cfg</guid>
      <description>&lt;h2&gt;
  
  
  Why 'Duplicates' Mean Something Different in a Graph DB
&lt;/h2&gt;

&lt;p&gt;If you come from a relational background, or from the ArangoDB migration covered earlier, your first instinct for duplicate prevention is a unique index or an &lt;code&gt;ON CONFLICT DO NOTHING&lt;/code&gt; clause. NebulaGraph has no unique index to lean on, and that difference is behind a lot of ingestion bugs.&lt;/p&gt;

&lt;p&gt;In NebulaGraph, vertices are keyed by &lt;strong&gt;VID&lt;/strong&gt; (vertex identifier) and edges are keyed by &lt;strong&gt;(src_vid, dst_vid, edge_type, rank)&lt;/strong&gt;. There are no uniqueness constraints apart from these keys. A plain &lt;code&gt;INSERT VERTEX&lt;/code&gt; behaves like a key-value &lt;code&gt;PUT&lt;/code&gt;: if you insert a vertex with an existing VID and tag, the later write &lt;strong&gt;overwrites&lt;/strong&gt; the earlier one. &lt;code&gt;INSERT VERTEX IF NOT EXISTS&lt;/code&gt; and &lt;code&gt;INSERT EDGE IF NOT EXISTS&lt;/code&gt; do exist, but they compare only the key (VID and tag, or the edge key), not the properties, and the documentation warns that the extra read has a significant cost.&lt;/p&gt;

&lt;p&gt;So idempotency is built into the storage model, but only if your VIDs are deterministic. Non-deterministic VIDs (UUIDs generated at insert time, counters handed out by the loader) create genuine duplicates, because each write lands on a different key.&lt;/p&gt;

&lt;p&gt;The fix is architectural, not operational. You don't add a dedup step after ingestion; you design the VID scheme so the same logical entity always resolves to the same VID, which makes repeated inserts safe by construction.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Golden Rule: Deterministic VIDs from Business Keys
&lt;/h2&gt;

&lt;p&gt;The VID type, &lt;code&gt;FIXED_STRING(&amp;lt;N&amp;gt;)&lt;/code&gt; or &lt;code&gt;INT64&lt;/code&gt;, is fixed at &lt;code&gt;CREATE SPACE&lt;/code&gt; time and cannot be changed later. A good fit for bulk ingestion from .NET is a string VID derived by hashing the natural business key with &lt;strong&gt;FNV-1a&lt;/strong&gt;. FNV-1a is fast, deterministic and trivial to implement without an extra dependency, and the result always has the same length.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;VidGenerator&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="c1"&gt;// FNV-1a 64-bit: the same business key always gives the same 16-character VID&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;const&lt;/span&gt; &lt;span class="kt"&gt;ulong&lt;/span&gt; &lt;span class="n"&gt;FnvPrime&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;0x00000100000001B3U&lt;/span&gt;&lt;span class="n"&gt;L&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;const&lt;/span&gt; &lt;span class="kt"&gt;ulong&lt;/span&gt; &lt;span class="n"&gt;FnvOffset&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;0xCBF29CE484222325U&lt;/span&gt;&lt;span class="n"&gt;L&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;FromBusinessKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;businessKey&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;ulong&lt;/span&gt; &lt;span class="n"&gt;hash&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;FnvOffset&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;byte&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UTF8&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetBytes&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;businessKey&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;hash&lt;/span&gt; &lt;span class="p"&gt;^=&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="n"&gt;hash&lt;/span&gt; &lt;span class="p"&gt;*=&lt;/span&gt; &lt;span class="n"&gt;FnvPrime&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="c1"&gt;// 16 hex characters, so the space needs vid_type = FIXED_STRING(16) or wider&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;hash&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"x16"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="c1"&gt;// Composite keys: namespace the input so "user:42" != "order:42"&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;FromCompositeKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;type&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;FromBusinessKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;type&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;:&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Why FNV-1a and not &lt;code&gt;GetHashCode()&lt;/code&gt; or MD5? &lt;code&gt;string.GetHashCode()&lt;/code&gt; is randomized per process in .NET, so the same key gets a different value after every restart. MD5 works, but it's more than you need. FNV-1a is deterministic and runs in a tight loop.&lt;/p&gt;

&lt;p&gt;Partition spread is not the reason to hash. NebulaGraph does that itself: a string VID is hashed with MurmurHash2, and the partition is &lt;code&gt;vid % numParts + 1&lt;/code&gt;. Integer VIDs go through the same modulo, so sequential integers are spread round robin across partitions. What hashing gives you is a key with a fixed length that fits the space's &lt;code&gt;FIXED_STRING(N)&lt;/code&gt;, whatever the length of the business key.&lt;/p&gt;

&lt;h2&gt;
  
  
  Edge Duplication and the Role of Rank
&lt;/h2&gt;

&lt;p&gt;Vertices are the easy part. Edges are where silent duplication tends to sneak in.&lt;/p&gt;

&lt;p&gt;An edge in NebulaGraph is uniquely identified by &lt;strong&gt;(src_vid, dst_vid, edge_type, rank)&lt;/strong&gt;. The default rank is &lt;code&gt;0&lt;/code&gt;. If your import pipeline sets rank to a timestamp or an auto-increment counter, &lt;strong&gt;every import run creates a new edge&lt;/strong&gt;, even though the business relationship has not changed. The graph accumulates phantom edges that look correct to a casual query but inflate degree counts and traversal results.&lt;/p&gt;

&lt;p&gt;The fix: pin rank to &lt;code&gt;0&lt;/code&gt; for relationships that have no natural ordering dimension, or compute a deterministic rank from the business relationship key:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# nGQL: idempotent edge insert with explicit rank 0
INSERT EDGE FOLLOWS () VALUES "a1b2c3d4e5f60718"-&amp;gt;"e5f6a7b8c9d00112"@0:();

# If rank carries business meaning (e.g., version number), derive it deterministically
INSERT EDGE ORDERED_BY () VALUES "a1b2c3d4e5f60718"-&amp;gt;"e5f6a7b8c9d00112"@42:();
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In .NET, this means your edge-building code must never use &lt;code&gt;DateTimeOffset.UtcNow.ToUnixTimeMilliseconds()&lt;/code&gt; as a rank. Decide at schema design time: either rank is always &lt;code&gt;0&lt;/code&gt;, or it is computed from an immutable attribute of the relationship (invoice sequence number, order index, and so on).&lt;/p&gt;

&lt;h2&gt;
  
  
  Choosing an Import Path at Scale
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Volume&lt;/th&gt;
&lt;th&gt;Source type&lt;/th&gt;
&lt;th&gt;Recommended path&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Driver-side, any size&lt;/td&gt;
&lt;td&gt;Structured data in .NET process&lt;/td&gt;
&lt;td&gt;Batched nGQL over Thrift (port 9669)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&amp;lt; tens of millions rows&lt;/td&gt;
&lt;td&gt;CSV files&lt;/td&gt;
&lt;td&gt;NebulaGraph Importer (Go binary)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Tens of millions&lt;/td&gt;
&lt;td&gt;RDBMS, HDFS, mixed&lt;/td&gt;
&lt;td&gt;Nebula Exchange (Spark, direct write)&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Hundreds of millions+&lt;/td&gt;
&lt;td&gt;Any&lt;/td&gt;
&lt;td&gt;Nebula Exchange → SST bulk ingest&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;For a .NET team owning the data pipeline end-to-end, driver-side batched INSERT is the natural starting point. For very large datasets produced by an ETL process, export to CSV and let NebulaGraph Importer handle it. It supports S3, GCS, HDFS and SFTP sources, and handles retry and load balancing across graph hosts internally. When you're moving hundreds of millions of records and storage compute is a concern, Nebula Exchange's SST bulk ingest moves that work to the Spark cluster.&lt;/p&gt;

&lt;p&gt;Note: Exchange 3.4.0 shipped without Kafka and Pulsar support. Current Exchange (3.8.0) reads from both, so a streaming source only needs you to avoid that one release.&lt;/p&gt;

&lt;h2&gt;
  
  
  A .NET Idempotent Ingestion Pipeline
&lt;/h2&gt;

&lt;p&gt;The driver-side pattern: stream the source, batch into fixed-size chunks, send each batch as one nGQL statement, checkpoint completed batch offsets so a failed run resumes, and retry transient failures with exponential backoff.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;NebulaIngestionPipeline&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;INebulaClient&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ICheckpointStore&lt;/span&gt; &lt;span class="n"&gt;checkpoint&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;const&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;BatchSize&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;256&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;IngestVerticesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;IAsyncEnumerable&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;UserRecord&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;source&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;batchIndex&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;checkpoint&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetLastCompletedBatchAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;batch&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;source&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Chunk&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;BatchSize&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;WithCancellation&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;current&lt;/span&gt;&lt;span class="p"&gt;++;&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="n"&gt;batchIndex&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="k"&gt;continue&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// skip already-committed batches on resume&lt;/span&gt;

            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;ngql&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;BuildVertexInsert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;batch&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

            &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;Policy&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Handle&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;NebulaTransientException&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;()&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;WaitAndRetryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;3&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;attempt&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;TimeSpan&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromSeconds&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Pow&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;2&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;attempt&lt;/span&gt;&lt;span class="p"&gt;)))&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteAsync&lt;/span&gt;&lt;span class="p"&gt;(()&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ngql&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;

            &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;checkpoint&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CommitAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;current&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;BuildVertexInsert&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;UserRecord&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="n"&gt;batch&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="c1"&gt;// Build a multi-value INSERT for the entire batch&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;values&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Join&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;",\n"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;batch&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;vid&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;VidGenerator&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromCompositeKey&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"user"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UserId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
                &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s"&gt;$"\"&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;vid&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;\":(&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="s"&gt;, &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Age&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;)"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="p"&gt;}));&lt;/span&gt;

        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s"&gt;$"""
&lt;/span&gt;            &lt;span class="n"&gt;INSERT&lt;/span&gt; &lt;span class="n"&gt;VERTEX&lt;/span&gt; &lt;span class="nf"&gt;Person&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;age&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;VALUES&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;values&lt;/span&gt;&lt;span class="p"&gt;};&lt;/span&gt;
            &lt;span class="s"&gt;""";
&lt;/span&gt;    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="c1"&gt;// nGQL string literal: escape the backslash first, then the double quote&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="s"&gt;"\""&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"\\"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s"&gt;"\\\\"&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;Replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"\""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s"&gt;"\\\""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt; &lt;span class="s"&gt;"\""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;INebulaClient&lt;/code&gt;, &lt;code&gt;ICheckpointStore&lt;/code&gt; and &lt;code&gt;NebulaTransientException&lt;/code&gt; are your own small abstractions: the client wraps a NebulaNet &lt;code&gt;NebulaConnection&lt;/code&gt;, and the checkpoint store can be a single row in your own database. NebulaNet's &lt;code&gt;ExecuteAsync&lt;/code&gt; throws a plain &lt;code&gt;Exception&lt;/code&gt; whose message ends in "execute failed." for any failed statement, a syntax error as much as a timeout, so the wrapper should turn only the retryable ones into &lt;code&gt;NebulaTransientException&lt;/code&gt;. Otherwise Polly retries a syntax error three times. &lt;code&gt;source.Chunk&lt;/code&gt; on an &lt;code&gt;IAsyncEnumerable&lt;/code&gt; comes with .NET 10's built-in &lt;code&gt;System.Linq.AsyncEnumerable&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Because VIDs are deterministic, &lt;strong&gt;replaying any batch is safe&lt;/strong&gt;: re-inserting a vertex with an existing VID overwrites it with the same data. The checkpoint exists only for efficiency (skip already-sent batches), not for correctness. After a crash you don't need to reconcile partial state; you resume from the last committed batch.&lt;/p&gt;

&lt;p&gt;Be disciplined about escaping. NebulaGraph's graph service does have an &lt;code&gt;executeWithParameter&lt;/code&gt; call, but the NebulaNet client's &lt;code&gt;NebulaConnection&lt;/code&gt; exposes only &lt;code&gt;ExecuteAsync(session, statement)&lt;/code&gt;, so with it you build nGQL strings by hand. Wrap every string property in double quotes and escape the backslash before the quote, as &lt;code&gt;Quote&lt;/code&gt; does above; a name like &lt;code&gt;O'Brien "Bob"&lt;/code&gt; then goes through intact.&lt;/p&gt;

&lt;h2&gt;
  
  
  INSERT vs UPSERT: When to Use Each
&lt;/h2&gt;

&lt;p&gt;Use &lt;code&gt;INSERT&lt;/code&gt; (overwrite-by-key) for bulk loads. &lt;code&gt;UPSERT&lt;/code&gt; in NebulaGraph is, in the documentation's words, a read-modify-write serialization operation at the partition level. It reads the current state, applies the mutation and writes back, one operation at a time per partition. At bulk-load volume that serialization becomes the bottleneck.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;UPSERT&lt;/code&gt; earns its place in &lt;strong&gt;incremental update&lt;/strong&gt; scenarios where you genuinely need conditional semantics:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# Conditional UPSERT: only update if score is still below 100
UPSERT VERTEX ON Player "a1b2c3d4e5f60718"
    SET score = score + 10
    WHEN score &amp;lt; 100
    YIELD score AS newScore;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For counters, max-wins merges, or partial property updates during live operation: &lt;code&gt;UPSERT&lt;/code&gt;. For a bulk load pipeline processing millions of records: &lt;code&gt;INSERT&lt;/code&gt;.&lt;/p&gt;

&lt;h2&gt;
  
  
  Pre-Import Deduplication of the Source
&lt;/h2&gt;

&lt;p&gt;Deterministic VIDs handle re-import idempotency, but they do not handle the case where your &lt;strong&gt;source data itself&lt;/strong&gt; contains two rows that represent the same business entity with conflicting property values. Both rows hash to the same VID; the second write wins, which may not be the right outcome.&lt;/p&gt;

&lt;p&gt;Before ingestion, group source rows by the business key and apply a deterministic merge strategy. Last write wins by source timestamp is usually fine, but document it explicitly. In LINQ:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;deduped&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;sourceRows&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GroupBy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;BusinessKey&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;g&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;g&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;OrderByDescending&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UpdatedAt&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;First&lt;/span&gt;&lt;span class="p"&gt;())&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToList&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For very large sources that don't fit in memory, do this deduplication in the ETL stage (SQL &lt;code&gt;DISTINCT ON&lt;/code&gt;, Spark &lt;code&gt;dropDuplicates("business_key")&lt;/code&gt;) before writing the CSV or streaming records to the .NET pipeline.&lt;/p&gt;

&lt;h2&gt;
  
  
  Verifying Integrity After Load
&lt;/h2&gt;

&lt;p&gt;After a full or incremental load, run a stats job against your graph space and compare its vertex and edge counts with &lt;code&gt;COUNT(DISTINCT business_key)&lt;/code&gt; from your source:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;# Trigger async stats collection
USE my_graph;
SUBMIT JOB STATS;

# Poll until the job shows FINISHED, then read the counts
SHOW JOB &amp;lt;job_id&amp;gt;;
SHOW STATS;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;SHOW STATS&lt;/code&gt; returns per-tag vertex counts, per-edge-type edge counts and the space totals from the last finished stats job. If the counts match your source distinct counts, your VID scheme is working. If edge counts exceed the distinct relationships in your source, something is generating non-deterministic ranks and creating extra edges. If vertex counts are lower, you likely have a key collision in the hash function (exceedingly rare with FNV-1a 64-bit, but worth checking with a quick collision test on your key space).&lt;/p&gt;

&lt;p&gt;Also run &lt;code&gt;SHOW HOSTS&lt;/code&gt; to confirm all storage nodes are &lt;code&gt;ONLINE&lt;/code&gt; before you trust the stats, because a node that went offline mid-import will skew the counts.&lt;/p&gt;

&lt;h2&gt;
  
  
  Gotchas Worth Calling Out
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Super-nodes&lt;/strong&gt;: A vertex with millions of edges keeps its outgoing edges on its own partition. Traversals touching a super-node become single-partition read hotspots. Design your schema to avoid super-nodes, or apply degree limits in queries (&lt;code&gt;LIMIT&lt;/code&gt; on &lt;code&gt;GO&lt;/code&gt; traversals).&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Dangling edges&lt;/strong&gt;: NebulaGraph allows inserting edges before their source or destination vertices exist. Writes are not atomic across vertices and edges, so a batch that fails halfway can leave dangling edges. Since INSERT is idempotent, the correct response is always to retry the full batch, not to attempt a surgical rollback.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Keyword tag names&lt;/strong&gt;: &lt;code&gt;USER&lt;/code&gt; is a non-reserved keyword in nGQL. In our test NebulaGraph accepted &lt;code&gt;CREATE TAG User&lt;/code&gt; without backticks but stored the tag as &lt;code&gt;user&lt;/code&gt;, so &lt;code&gt;SHOW STATS&lt;/code&gt; listed &lt;code&gt;user&lt;/code&gt; and code looking for &lt;code&gt;User&lt;/code&gt; found nothing. Pick tag and edge names that are not keywords (this article uses &lt;code&gt;Person&lt;/code&gt;), or wrap them in backticks.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Business key stability&lt;/strong&gt;: Idempotency breaks the moment a business key changes. If your source system reassigns natural keys (rare, but it happens with legacy RDBMS migrations), your VID scheme will generate a new vertex for what is conceptually the same entity, and the old vertex becomes an orphan. Audit key stability before committing to a VID strategy.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;UPSERT at scale.&lt;/strong&gt; Once more: bulk UPSERT is a trap. Measure throughput with a small batch before committing to it for a million-row load.&lt;/p&gt;

&lt;p&gt;The code in this article was run against NebulaGraph 3.8.0 (the current Community Edition) with the NebulaNet 3.0.0 client on .NET 10.&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>nebulagraph</category>
      <category>graphdatabases</category>
      <category>csharp</category>
    </item>
    <item>
      <title>Graphs as Agent Memory: Why Vectors Alone Are Not Enough</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Fri, 30 Oct 2026 15:38:37 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/graphs-as-agent-memory-why-vectors-alone-are-not-enough-da8</link>
      <guid>https://dev.to/mehdimohseni82/graphs-as-agent-memory-why-vectors-alone-are-not-enough-da8</guid>
      <description>&lt;h2&gt;
  
  
  The Failure Mode Nobody Talks About
&lt;/h2&gt;

&lt;p&gt;Ask an LLM-powered agent: &lt;em&gt;"Which services will break if we remove the &lt;code&gt;orders.created&lt;/code&gt; queue?"&lt;/em&gt; Feed it a vector store built from your architecture documents, runbooks, and Confluence pages. You will get a confident, well-written paragraph. It will probably name two or three services. It will almost certainly be incomplete, and the agent has no way to know that.&lt;/p&gt;

&lt;p&gt;This is the core limitation of treating an embedding store as your agent's memory. Vector search performs approximate nearest-neighbor (ANN) retrieval. It finds chunks that are &lt;em&gt;semantically similar&lt;/em&gt; to the query. It cannot follow a chain. The question above needs a multi-hop traversal: find every service with a &lt;code&gt;CONSUMES&lt;/code&gt; edge to &lt;code&gt;orders.created&lt;/code&gt;, then follow the &lt;code&gt;CALLS&lt;/code&gt; edges into those services to find the callers that depend on them, and so on. An ANN index cannot express that walk, because it has no edges to follow.&lt;/p&gt;

&lt;p&gt;Here is how the two answers differ on a small example:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Vector result:&lt;/strong&gt; &lt;em&gt;"The &lt;code&gt;billing-service&lt;/code&gt; and &lt;code&gt;fulfillment-api&lt;/code&gt; both process order events. Removing the queue may cause downstream processing delays."&lt;/em&gt; Plausible, and incomplete. The &lt;code&gt;audit-logger&lt;/code&gt;, which consumes every queue in the namespace, is missing because its documentation never mentions &lt;code&gt;orders.created&lt;/code&gt; by name.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Graph traversal result:&lt;/strong&gt; &lt;code&gt;audit-logger&lt;/code&gt;, &lt;code&gt;billing-service&lt;/code&gt;, &lt;code&gt;fulfillment-api&lt;/code&gt;, and &lt;code&gt;reporting-job&lt;/code&gt;, a weekly job that calls &lt;code&gt;billing-service&lt;/code&gt;. Four services, because the edges exist. The C# code later in this article returns exactly this list against a real NebulaGraph instance.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;This article looks at knowledge graphs as structured agent memory. If you have not read the &lt;a href="https://dotnet-talk.com/blog/graph-native-csharp-part-1-foundations" rel="noopener noreferrer"&gt;Graph-Native Data Structures series&lt;/a&gt; on this site, that is a good place to start, because the traversal mechanics here build on it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Belongs Where
&lt;/h2&gt;

&lt;p&gt;Before writing a single line of schema, decide what should live in the graph and what should stay in the embedding store. The two are complementary, not competing.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Put in the graph:&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Explicit entity to entity relationships, &lt;code&gt;ServiceA CALLS ServiceB&lt;/code&gt;, &lt;code&gt;ServiceB CONSUMES QueueC&lt;/code&gt;
&lt;/li&gt;
&lt;li&gt;Multi-hop dependency chains that need to be walked, not recalled&lt;/li&gt;
&lt;li&gt;Temporal fact evolution: when a dependency was added, removed, or changed&lt;/li&gt;
&lt;li&gt;Contradiction resolution: when Service B no longer consumes Queue C, you retire the edge with a timestamp rather than leaving two conflicting embedding chunks that both rank highly on the same query&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;strong&gt;Keep in the embedding store:&lt;/strong&gt;&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;Unstructured prose: runbooks, incident reports, architecture decision records&lt;/li&gt;
&lt;li&gt;Fuzzy semantic recall: &lt;em&gt;"what did we decide about retry logic?"&lt;/em&gt;
&lt;/li&gt;
&lt;li&gt;Cold-start lookup before the graph is populated&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A vector store plus a knowledge graph is a common pattern in agent memory frameworks. Zep builds its memory on Graphiti, a temporal knowledge graph that it searches together with embeddings, and Mem0 (which raised $24M in seed and Series A funding in October 2025) offers a graph memory option next to its vector store. The split also helps the graph itself: traversals slow down around very high-degree vertices, so letting the embedding store take the unstructured text keeps the graph to typed, queryable relationships.&lt;/p&gt;

&lt;h2&gt;
  
  
  Modeling the Dependency Graph in NebulaGraph
&lt;/h2&gt;

&lt;p&gt;NebulaGraph 3.8.0 (Apache 2.0, released May 2024) is the latest open-source release. It is a distributed system, with &lt;code&gt;metad&lt;/code&gt;, &lt;code&gt;storaged&lt;/code&gt; and &lt;code&gt;graphd&lt;/code&gt; processes, and it is not embeddable. Even in development, plan for Docker Compose.&lt;/p&gt;

&lt;p&gt;One schema constraint catches people coming from other graph databases: by default, every vertex must carry at least one tag. NebulaGraph 3.8.0 can store vertices without tags, but only after you set &lt;code&gt;--graph_use_vertex_key=true&lt;/code&gt; on every Graph service and &lt;code&gt;--use_vertex_key=true&lt;/code&gt; on every Storage service.&lt;/p&gt;

&lt;p&gt;NebulaGraph supports both native nGQL and openCypher-compatible syntax. Do not mix them in one composite statement, because the behaviour is undefined. The schema below is plain nGQL, and the traversal uses the openCypher-style &lt;code&gt;MATCH&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  nGQL Schema
&lt;/h3&gt;



&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="o"&gt;#&lt;/span&gt; &lt;span class="n"&gt;Run&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;NebulaGraph&lt;/span&gt; &lt;span class="n"&gt;Console&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="n"&gt;Studio&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="n"&gt;nGQL&lt;/span&gt; &lt;span class="n"&gt;comments&lt;/span&gt; &lt;span class="k"&gt;start&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="o"&gt;#&lt;/span&gt; &lt;span class="k"&gt;or&lt;/span&gt; &lt;span class="o"&gt;//&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;not&lt;/span&gt; &lt;span class="c1"&gt;--&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;SPACE&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;infra_memory&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;vid_type&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;FIXED_STRING&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;128&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
  &lt;span class="n"&gt;partition_num&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;10&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;replica_factor&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;USE&lt;/span&gt; &lt;span class="n"&gt;infra_memory&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="o"&gt;#&lt;/span&gt; &lt;span class="n"&gt;Tags&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;vertex&lt;/span&gt; &lt;span class="n"&gt;types&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;TAG&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;Service&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;     &lt;span class="n"&gt;string&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="k"&gt;language&lt;/span&gt; &lt;span class="n"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;team&lt;/span&gt;     &lt;span class="n"&gt;string&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;TAG&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;Queue&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;      &lt;span class="n"&gt;string&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;broker&lt;/span&gt;    &lt;span class="n"&gt;string&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="nv"&gt;"rabbitmq"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;durable&lt;/span&gt;   &lt;span class="nb"&gt;bool&lt;/span&gt;   &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;TAG&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="k"&gt;Database&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt;   &lt;span class="n"&gt;string&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;engine&lt;/span&gt; &lt;span class="n"&gt;string&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;TAG&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;Deployment&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="k"&gt;cluster&lt;/span&gt;     &lt;span class="n"&gt;string&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;namespace&lt;/span&gt;   &lt;span class="n"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;replicas&lt;/span&gt;    &lt;span class="nb"&gt;int&lt;/span&gt;    &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="o"&gt;#&lt;/span&gt; &lt;span class="n"&gt;Edge&lt;/span&gt; &lt;span class="n"&gt;types&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;EDGE&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;CONSUMES&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;since&lt;/span&gt;    &lt;span class="nb"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;retired&lt;/span&gt;  &lt;span class="nb"&gt;datetime&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="nb"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nv"&gt;"9999-12-31T00:00:00"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;EDGE&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;CALLS&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;protocol&lt;/span&gt; &lt;span class="n"&gt;string&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="nv"&gt;"http"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;timeout_ms&lt;/span&gt; &lt;span class="nb"&gt;int&lt;/span&gt; &lt;span class="k"&gt;DEFAULT&lt;/span&gt; &lt;span class="mi"&gt;5000&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;EDGE&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;DEPLOYED_TO&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;deployed_at&lt;/span&gt; &lt;span class="nb"&gt;datetime&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;EDGE&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;READS_FROM&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="n"&gt;EDGE&lt;/span&gt; &lt;span class="n"&gt;IF&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;EXISTS&lt;/span&gt; &lt;span class="n"&gt;WRITES_TO&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Tags and edge types are created asynchronously. NebulaGraph's documentation says to wait two heartbeat cycles, 20 seconds with the default &lt;code&gt;heartbeat_interval_secs&lt;/code&gt; of 10, before inserting data that uses them, so a setup script should pause or retry between the schema and the first &lt;code&gt;INSERT&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;The &lt;code&gt;retired&lt;/code&gt; field on &lt;code&gt;CONSUMES&lt;/code&gt; is the contradiction-resolution mechanism. When a dependency is removed, you set &lt;code&gt;retired&lt;/code&gt; to the current time rather than deleting the edge. History is preserved, and the traversal keeps only edges where &lt;code&gt;retired &amp;gt; datetime()&lt;/code&gt;. Note that it has to be &lt;code&gt;datetime()&lt;/code&gt;: in nGQL, &lt;code&gt;now()&lt;/code&gt; returns an integer Unix timestamp, and comparing a &lt;code&gt;datetime&lt;/code&gt; property with it matches nothing.&lt;/p&gt;

&lt;h2&gt;
  
  
  C# Client Wiring
&lt;/h2&gt;

&lt;p&gt;The .NET client is &lt;strong&gt;NebulaNet&lt;/strong&gt; (&lt;code&gt;nebula-contrib/nebula-net&lt;/code&gt;, NuGet version 3.0.0, published March 2022, targeting &lt;code&gt;netstandard2.1&lt;/code&gt;). NebulaGraph's documentation lists it only as a community-contributed client, with no support guarantee, and its README maps 3.0.0 to "3.x" without naming a minor version. The code below runs against 3.8.0. The official documentation describes thread-safe pools only for the Java and Go clients. NebulaNet hands out pooled sessions through &lt;code&gt;NebulaPool&lt;/code&gt;; take one per query and release it, as the repository does.&lt;/p&gt;

&lt;p&gt;The client sends plain statement strings and has no parameter binding, so every value that goes into a query has to be escaped. That is what &lt;code&gt;Quote&lt;/code&gt; does. When a statement fails, &lt;code&gt;ExecuteAsync&lt;/code&gt; throws a plain &lt;code&gt;Exception&lt;/code&gt; whose message is the server's error followed by the full statement, so be careful about where those messages get logged.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;System.Text&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;Nebula.Common&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;NebulaNet&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;NebulaInfraRepository&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;NebulaPool&lt;/span&gt; &lt;span class="n"&gt;_pool&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nf"&gt;NebulaInfraRepository&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;NebulaPool&lt;/span&gt; &lt;span class="n"&gt;pool&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;_pool&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;pool&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="c1"&gt;/// &amp;lt;summary&amp;gt;&lt;/span&gt;
    &lt;span class="c1"&gt;/// Services with an active CONSUMES edge to the queue, plus the services&lt;/span&gt;
    &lt;span class="c1"&gt;/// that CALL those consumers. A two-hop walk that a vector index cannot do.&lt;/span&gt;
    &lt;span class="c1"&gt;/// &amp;lt;/summary&amp;gt;&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;IReadOnlyList&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;GetDependantsAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;QueryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"""
&lt;/span&gt;            &lt;span class="n"&gt;USE&lt;/span&gt; &lt;span class="n"&gt;infra_memory&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="nf"&gt;MATCH&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;Service&lt;/span&gt;&lt;span class="p"&gt;)-[&lt;/span&gt;&lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;CONSUMES&lt;/span&gt;&lt;span class="p"&gt;]-&amp;gt;(&lt;/span&gt;&lt;span class="n"&gt;q&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;Queue&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="n"&gt;WHERE&lt;/span&gt; &lt;span class="nf"&gt;id&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;q&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt; &lt;span class="n"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;c&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;retired&lt;/span&gt; &lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
            &lt;span class="n"&gt;OPTIONAL&lt;/span&gt; &lt;span class="nf"&gt;MATCH&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;caller&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="n"&gt;Service&lt;/span&gt;&lt;span class="p"&gt;)-[:&lt;/span&gt;&lt;span class="n"&gt;CALLS&lt;/span&gt;&lt;span class="p"&gt;]-&amp;gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="n"&gt;RETURN&lt;/span&gt; &lt;span class="n"&gt;DISTINCT&lt;/span&gt; &lt;span class="nf"&gt;id&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;AS&lt;/span&gt; &lt;span class="n"&gt;direct_consumer&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="nf"&gt;id&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;caller&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;AS&lt;/span&gt; &lt;span class="n"&gt;indirect_caller&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="s"&gt;""");
&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;dependants&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;SortedSet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;(&lt;/span&gt;&lt;span class="n"&gt;StringComparer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Ordinal&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Rows&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Values&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="c1"&gt;// A service with no callers comes back with a null indirect_caller.&lt;/span&gt;
                &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;SVal&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="n"&gt;not&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;dependants&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Encoding&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UTF8&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;SVal&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
            &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;dependants&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToList&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="c1"&gt;/// &amp;lt;summary&amp;gt;&lt;/span&gt;
    &lt;span class="c1"&gt;/// Adds an active CONSUMES edge unless one already exists. Each edge gets its&lt;/span&gt;
    &lt;span class="c1"&gt;/// own rank, so retired edges stay in the graph as history.&lt;/span&gt;
    &lt;span class="c1"&gt;/// &amp;lt;/summary&amp;gt;&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;AddConsumesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;ActiveRanksAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)).&lt;/span&gt;&lt;span class="n"&gt;Count&lt;/span&gt; &lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;rank&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;DateTimeOffset&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UtcNow&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToUnixTimeMilliseconds&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;QueryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"""
&lt;/span&gt;            &lt;span class="n"&gt;USE&lt;/span&gt; &lt;span class="n"&gt;infra_memory&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="n"&gt;INSERT&lt;/span&gt; &lt;span class="n"&gt;EDGE&lt;/span&gt; &lt;span class="nf"&gt;CONSUMES&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;since&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;retired&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="n"&gt;VALUES&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;)}-&amp;gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="err"&gt;@&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;rank&lt;/span&gt;&lt;span class="p"&gt;}:(&lt;/span&gt;&lt;span class="nf"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt; &lt;span class="nf"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"9999-12-31T00:00:00"&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
            &lt;span class="s"&gt;""");
&lt;/span&gt;    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="c1"&gt;/// &amp;lt;summary&amp;gt;Retires every active CONSUMES edge from the service to the queue.&amp;lt;/summary&amp;gt;&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;RetireConsumesAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;rank&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;ActiveRanksAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;QueryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"""
&lt;/span&gt;                &lt;span class="n"&gt;USE&lt;/span&gt; &lt;span class="n"&gt;infra_memory&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
                &lt;span class="n"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;EDGE&lt;/span&gt; &lt;span class="n"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;CONSUMES&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;)}-&amp;gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt;&lt;span class="err"&gt;@&lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;rank&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;
                &lt;span class="n"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;retired&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="nf"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
                &lt;span class="s"&gt;""");
&lt;/span&gt;        &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;ActiveRanksAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;QueryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"""
&lt;/span&gt;            &lt;span class="n"&gt;USE&lt;/span&gt; &lt;span class="n"&gt;infra_memory&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="n"&gt;GO&lt;/span&gt; &lt;span class="n"&gt;FROM&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;serviceId&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt; &lt;span class="n"&gt;OVER&lt;/span&gt; &lt;span class="n"&gt;CONSUMES&lt;/span&gt;
            &lt;span class="n"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;CONSUMES&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;_dst&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;queueId&lt;/span&gt;&lt;span class="p"&gt;)}&lt;/span&gt; &lt;span class="n"&gt;AND&lt;/span&gt; &lt;span class="n"&gt;CONSUMES&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;retired&lt;/span&gt; &lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;datetime&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
            &lt;span class="n"&gt;YIELD&lt;/span&gt; &lt;span class="n"&gt;CONSUMES&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;_rank&lt;/span&gt; &lt;span class="n"&gt;AS&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="s"&gt;""");
&lt;/span&gt;        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;data&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Rows&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;row&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;row&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Values&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;].&lt;/span&gt;&lt;span class="n"&gt;IVal&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;ToList&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;DataSet&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;QueryAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;ngql&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;_pool&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetSessionAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;try&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="c1"&gt;// NebulaNet throws on any non-zero error code, so there is nothing to check here.&lt;/span&gt;
            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ngql&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Data&lt;/span&gt; &lt;span class="p"&gt;??&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;DataSet&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Rows&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Row&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;()&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;finally&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;session&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Release&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="c1"&gt;// NebulaNet has no bound parameters, so every string literal is escaped here.&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="nf"&gt;Quote&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="s"&gt;"\""&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"\\"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s"&gt;"\\\\"&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;Replace&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"\""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s"&gt;"\\\""&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt; &lt;span class="s"&gt;"\""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Calling &lt;code&gt;AddConsumesAsync&lt;/code&gt; twice leaves one active edge, not two. Retiring an edge and adding it again leaves two edges: the retired one, which records when the dependency was dropped, and a new active one.&lt;/p&gt;

&lt;p&gt;Register it in your DI container. &lt;code&gt;AddNebulaGraph&lt;/code&gt; comes with NebulaNet and registers &lt;code&gt;NebulaPool&lt;/code&gt; as a singleton:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AddNebulaGraph&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;config&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Ip&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"127.0.0.1"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Port&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;9669&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UserName&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"root"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="n"&gt;config&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Password&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"nebula"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;AddSingleton&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;NebulaInfraRepository&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  The Cost of Keeping the Graph Current
&lt;/h2&gt;

&lt;p&gt;Here is the part that vendor demos skip. A fresh graph is empty. Something has to build it: extract entities and relationships from your architecture docs, Terraform outputs, and service manifests, resolve duplicates, and keep edges current as the system evolves. That extraction step is typically an LLM call, which means it is slow, costs tokens, and can hallucinate edges.&lt;/p&gt;

&lt;p&gt;Entity resolution is genuinely hard. &lt;code&gt;orders-created-queue&lt;/code&gt;, &lt;code&gt;orders.created&lt;/code&gt;, and &lt;code&gt;OrdersCreatedQueue&lt;/code&gt; may all refer to the same vertex. Unresolved, they fragment your graph and break traversals.&lt;/p&gt;

&lt;p&gt;The practical approach for a codebase-and-infrastructure graph:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Seed from machine-readable sources first.&lt;/strong&gt; Parse &lt;code&gt;docker-compose.yml&lt;/code&gt;, Kubernetes service manifests, AsyncAPI specs, and OpenAPI documents. These give you high-confidence edges without LLM inference.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Use the LLM for prose sources only&lt;/strong&gt;, runbooks, ADRs and incident post mortems. Accept lower confidence; flag edges with a &lt;code&gt;source: llm&lt;/code&gt; property and a confidence score.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Run reconciliation on deploy.&lt;/strong&gt; When a service is deployed, re-examine its manifest edges and retire anything that disappeared.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The third step has its own pitfalls, and &lt;a href="https://dotnet-talk.com/blog/knowledge-graph-maintenance-reconciliation-worker" rel="noopener noreferrer"&gt;Keep Your Knowledge Graph Current Without a Team&lt;/a&gt; walks through a reconciliation worker that does it.&lt;/p&gt;

&lt;p&gt;Keep watching how many edges each vertex collects. If you start storing every log line as an edge, a handful of vertices end up with huge fan-out and traversals through them slow down. The embedding store absorbs that unstructured load; the graph stays focused on typed, queryable relationships.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where This Is Heading
&lt;/h2&gt;

&lt;p&gt;NebulaGraph Enterprise v5.2 (November 2025) added graph, vector and full-text retrieval in a single query, and NebulaGraph claims up to 100 times faster path queries along with wider ISO GQL support. That is the commercial edition. The open-source 3.8.0 used here is the version you can run today without a licence, and it has no built-in vector search, which is why the embedding store stays a separate system in this design.&lt;/p&gt;

&lt;p&gt;In August 2025, Gartner predicted that up to 40% of enterprise applications would include task-specific AI agents by the end of 2026, up from less than 5% in 2025. Most of those agents will start with a pure vector store because it is fast and has no cold-start cost. The failure mode at the top of this article is what they will hit next. A knowledge graph does not replace the embedding store. It is the layer that answers the questions the embedding store cannot.&lt;/p&gt;

&lt;p&gt;To see the two stores working together on one query, read &lt;a href="https://dotnet-talk.com/blog/hybrid-retrieval-csharp-vector-graph-rerank" rel="noopener noreferrer"&gt;Hybrid Vector + Graph Retrieval in C# for Agent Memory&lt;/a&gt;.&lt;/p&gt;

</description>
      <category>vectorsearch</category>
      <category>architecture</category>
      <category>nebulagraph</category>
      <category>graphdatabases</category>
    </item>
    <item>
      <title>Sharing State Across Sessions and Agents: Memory, MCP, and Handoffs in .NET</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Fri, 30 Oct 2026 11:38:05 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/sharing-state-across-sessions-and-agents-memory-mcp-and-handoffs-in-net-41lo</link>
      <guid>https://dev.to/mehdimohseni82/sharing-state-across-sessions-and-agents-memory-mcp-and-handoffs-in-net-41lo</guid>
      <description>&lt;h2&gt;
  
  
  The Problem: Agents That Forget and Cannot See Each Other
&lt;/h2&gt;

&lt;p&gt;If you followed &lt;a href="https://dotnet-talk.com/blog/context-engineering-net-coding-agent" rel="noopener noreferrer"&gt;Part 2 of this series&lt;/a&gt;, you know how much effort goes into getting the right context into one agent's window. Now run two agents in parallel and ask one what the other found. It has no idea, because each one has its own context and nothing connects them unless you build that connection.&lt;/p&gt;

&lt;p&gt;The protocol layer has moved in the same direction. The &lt;a href="https://modelcontextprotocol.io/specification/2026-07-28/changelog" rel="noopener noreferrer"&gt;MCP 2026-07-28 specification&lt;/a&gt; removes the &lt;code&gt;initialize&lt;/code&gt; handshake (SEP-2575) and protocol-level sessions, including the &lt;code&gt;Mcp-Session-Id&lt;/code&gt; header (SEP-2567). Every request now carries its own protocol version and client capabilities, so each HTTP request is independent and ordinary round-robin load balancing works without sticky sessions. A stateless protocol does not make your application stateless, though. Servers that need state across calls now pass explicit handles as ordinary tool arguments, and remembering things becomes the job of your code.&lt;/p&gt;

&lt;p&gt;On the Anthropic side, &lt;a href="https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration" rel="noopener noreferrer"&gt;Claude Managed Agents&lt;/a&gt; runs each agent in its own session thread, a context-isolated event stream with its own conversation history. The agents in a session share a sandbox and its filesystem, but not their conversations. The coordinator knows what it sent each subagent; it only knows what they found when they report back or write it somewhere it can read.&lt;/p&gt;

&lt;p&gt;Three patterns address this:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Persistent memory.&lt;/strong&gt; Store state where any agent can read and write it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Model Context Protocol (MCP).&lt;/strong&gt; Expose that state and your internal tooling through a standard interface any agent can call.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Structured handoffs.&lt;/strong&gt; Pass tasks and results across an agent boundary in a way that preserves context.&lt;/li&gt;
&lt;/ol&gt;




&lt;h2&gt;
  
  
  Persistent Memory: What to Store and What to Discard
&lt;/h2&gt;

&lt;p&gt;Claude Code's &lt;a href="https://code.claude.com/docs/en/agent-teams" rel="noopener noreferrer"&gt;agent teams&lt;/a&gt; show how far a simple shared store can go. The feature is experimental and off by default (you turn it on with &lt;code&gt;CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1&lt;/code&gt;). One session is the lead; it creates a shared task list, stored on disk under &lt;code&gt;~/.claude/tasks/{team-name}/&lt;/code&gt;. Tasks are pending, in progress, or completed, and a task that depends on others stays blocked until they are completed. Teammates claim the next unblocked task themselves, and Claude Code uses file locking so two teammates cannot claim the same task. Teammates can also message each other directly through per-agent mailbox files.&lt;/p&gt;

&lt;p&gt;The task-list part is easy to build in C#. Here is a minimal version backed by a JSON file:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;System.Text.Json&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;AgentTask&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Description&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;[]&lt;/span&gt; &lt;span class="n"&gt;DependsOn&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="c1"&gt;// pending | in-progress | complete | failed&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;ClaimedBy&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;DateTimeOffset&lt;/span&gt; &lt;span class="n"&gt;UpdatedAt&lt;/span&gt;
&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="c1"&gt;// One process, one lock: safe for a single server instance only.&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;FileTaskStore&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;SemaphoreSlim&lt;/span&gt; &lt;span class="n"&gt;_lock&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;AgentTask&lt;/span&gt;&lt;span class="p"&gt;?&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;ClaimNextAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;agentId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;_lock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;WaitAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;try&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;tasks&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;ReadAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;completedIds&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;tasks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="s"&gt;"complete"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                                    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                                    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToHashSet&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;next&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;tasks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FirstOrDefault&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
                &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="s"&gt;"pending"&lt;/span&gt; &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt;
                &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;DependsOn&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;All&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dep&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;completedIds&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dep&lt;/span&gt;&lt;span class="p"&gt;)));&lt;/span&gt;

            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;next&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;next&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"in-progress"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;ClaimedBy&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;agentId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;UpdatedAt&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;DateTimeOffset&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UtcNow&lt;/span&gt;
            &lt;span class="p"&gt;};&lt;/span&gt;
            &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;WriteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;tasks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;next&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;claimed&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;claimed&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;finally&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;_lock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Release&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;CompleteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;taskId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;_lock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;WaitAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;try&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;tasks&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;ReadAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
            &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;WriteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;tasks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;t&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;taskId&lt;/span&gt;
                &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt; &lt;span class="k"&gt;with&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Status&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"complete"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Result&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;UpdatedAt&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;DateTimeOffset&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UtcNow&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
                &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;t&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;finally&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;_lock&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Release&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;AgentTask&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;ReadAsync&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Deserialize&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;AgentTask&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;(&lt;/span&gt;
            &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;File&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ReadAllTextAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="p"&gt;??&lt;/span&gt; &lt;span class="p"&gt;[];&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;WriteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IEnumerable&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;AgentTask&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;tasks&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="n"&gt;File&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;WriteAllTextAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;path&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Serialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;tasks&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;JsonSerializerOptions&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;WriteIndented&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt; &lt;span class="p"&gt;}));&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;ClaimedBy&lt;/code&gt; and &lt;code&gt;UpdatedAt&lt;/code&gt; are there so you can see who holds a task and how old an entry is. The &lt;code&gt;SemaphoreSlim&lt;/code&gt; only protects the file inside one process, which matters in the next section.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;What belongs in persistent memory:&lt;/strong&gt; summaries of findings, intermediate artefacts (generated code, analysis reports), task status, and links to authoritative sources. &lt;strong&gt;What does not belong:&lt;/strong&gt; raw conversation turns (they bloat the file and age badly), credentials, or anything an agent should re-derive fresh each run. Keep entries time-stamped so you can judge freshness before injecting them into a new session.&lt;/p&gt;




&lt;h2&gt;
  
  
  Model Context Protocol: A Standard Bridge to Your Systems
&lt;/h2&gt;

&lt;p&gt;MCP gives any agent, whatever the vendor or runtime, a standard way to call your tools and read your data. The official C# SDK (&lt;code&gt;ModelContextProtocol&lt;/code&gt;) shipped 2.0 on 28 July 2026, the same day as the new spec, and the current release is 2.3.0. It targets .NET 8, .NET 9, .NET 10 and &lt;code&gt;netstandard2.0&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;Install it:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;dotnet add package ModelContextProtocol.AspNetCore
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Here is a minimal ASP.NET Core MCP server that exposes the task store as two tools. Since SDK 2.0, &lt;code&gt;HttpServerTransportOptions.Stateless&lt;/code&gt; defaults to &lt;code&gt;true&lt;/code&gt; for the 2026-07-28 protocol revision, so the endpoint keeps no session between requests:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;System.ComponentModel&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;ModelContextProtocol.Server&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;builder&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;WebApplication&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CreateBuilder&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;args&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AddSingleton&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;FileTaskStore&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Configuration&lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s"&gt;"TaskFile"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;??&lt;/span&gt; &lt;span class="s"&gt;"tasks.json"&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;

&lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Services&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AddMcpServer&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;WithHttpTransport&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="c1"&gt;// stateless by default since SDK 2.0&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;WithTools&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TaskTools&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;();&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;app&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Build&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;MapMcp&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"/mcp"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;app&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Run&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;McpServerToolType&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;TaskTools&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;FileTaskStore&lt;/span&gt; &lt;span class="n"&gt;store&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nf"&gt;McpServerTool&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Name&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"claim_task"&lt;/span&gt;&lt;span class="p"&gt;)]&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nf"&gt;Description&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Claim the next pending task whose dependencies are complete."&lt;/span&gt;&lt;span class="p"&gt;)]&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;AgentTask&lt;/span&gt;&lt;span class="p"&gt;?&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;ClaimTask&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nf"&gt;Description&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Id of the agent claiming the task"&lt;/span&gt;&lt;span class="p"&gt;)]&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;agentId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="n"&gt;store&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ClaimNextAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;agentId&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nf"&gt;McpServerTool&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Name&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"complete_task"&lt;/span&gt;&lt;span class="p"&gt;)]&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nf"&gt;Description&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Mark a task complete and store its result."&lt;/span&gt;&lt;span class="p"&gt;)]&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;CompleteTask&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;taskId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;store&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CompleteAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;taskId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="s"&gt;"ok"&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The SDK builds each tool's input schema from the method signature (&lt;code&gt;claim_task&lt;/code&gt; takes a required &lt;code&gt;agentId&lt;/code&gt; string) and returns the &lt;code&gt;AgentTask&lt;/code&gt; as camelCase JSON, or &lt;code&gt;null&lt;/code&gt; when nothing is claimable. The tool class gets &lt;code&gt;FileTaskStore&lt;/code&gt; through constructor injection.&lt;/p&gt;

&lt;p&gt;Point your agents at &lt;code&gt;http://your-mcp-host/mcp&lt;/code&gt; in their tool configuration and they coordinate through the store without knowing about each other. The same server can front any shared resource, a SQL database, an internal API, a documentation index, through one protocol that Claude, GitHub Copilot and other MCP clients speak.&lt;/p&gt;

&lt;p&gt;One caution before you put this behind a load balancer. The protocol no longer needs session affinity, but this store does: its lock lives in one process. We ran two instances of this exact server against one task file, with 30 concurrent claims split between them, ten times. Every run failed at least one call on a half-written file. A single instance handed out 30 tasks to 30 concurrent callers without a duplicate. For more than one instance, move the store into a database and claim rows atomically, for example with PostgreSQL's &lt;code&gt;SELECT ... FOR UPDATE SKIP LOCKED&lt;/code&gt;.&lt;/p&gt;




&lt;h2&gt;
  
  
  Multi-Agent Coordination: Subagents, Handoffs, and the Shared Bus
&lt;/h2&gt;

&lt;p&gt;Two topologies matter in practice:&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Hierarchical, or subagent, model.&lt;/strong&gt; One coordinator dispatches tasks to specialised subagents, collects results, and synthesises. Claude Managed Agents makes the threads explicit: a subagent's thread persists until it is archived, so the coordinator can send it a follow-up and the subagent still has everything from its earlier turns. Delegation there is one level deep, with at most 25 child threads per session. Anthropic's own &lt;a href="https://www.anthropic.com/engineering/multi-agent-research-system" rel="noopener noreferrer"&gt;research system&lt;/a&gt; used Claude Opus 4 as the lead and Claude Sonnet 4 as subagents, and it outperformed single-agent Claude Opus 4 by 90.2% on their internal research evaluation.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Team model.&lt;/strong&gt; A group of agents that pick up work from a shared list and talk to each other directly. Claude Code's agent teams work this way: the lead creates the task list, teammates claim unblocked tasks on their own and message each other by name, and the lead synthesises at the end instead of routing every step.&lt;/p&gt;

&lt;p&gt;For .NET teams, &lt;strong&gt;Microsoft Agent Framework 1.0&lt;/strong&gt; (generally available since 3 April 2026), the successor to Semantic Kernel and AutoGen, is the native option. It supports both topologies and can use MCP servers as tool sources.&lt;/p&gt;

&lt;p&gt;Handoffs in the OpenAI Agents SDK follow a transfer-tool pattern: agent A calls a &lt;code&gt;transfer_to_&amp;lt;agent&amp;gt;&lt;/code&gt; tool, and control moves to agent B along with the conversation history. That is clean for sequential pipelines but needs extra work when you want parallel coordination or a shared stream of results.&lt;/p&gt;

&lt;p&gt;The 2026-07-28 spec also adds Multi Round-Trip Requests (MRTR, SEP-2322). Instead of the server sending its own requests for sampling or elicitation in the middle of a call, it returns an &lt;code&gt;InputRequiredResult&lt;/code&gt; listing what it needs, and the client retries the original request with &lt;code&gt;inputResponses&lt;/code&gt;. Interactive tools no longer need a long-lived connection, which fits the request-per-call model of ASP.NET Core well.&lt;/p&gt;




&lt;h2&gt;
  
  
  Pitfalls to Anticipate
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Stale memory is worse than no memory.&lt;/strong&gt; An agent injecting a six-week-old analysis into its context will act on it confidently. Timestamp every entry and require agents to check freshness before relying on cached findings. Treat memory like a cache, not a database of truth.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Context bleed between tasks.&lt;/strong&gt; When an agent completes task A and immediately picks up task B, framing from A can shape how it approaches B. An explicit reset, an instruction that describes task B from scratch, is more reliable than hoping the model reframes itself.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Securing shared tools.&lt;/strong&gt; An MCP server exposed to multiple agents is a shared attack surface. Scope tools to specific agent identities where your infrastructure allows, and do not expose broad write permissions through a tool that subagents can call without coordinator approval. The 2026-07-28 spec tightens authorization in concrete ways: clients must validate the &lt;code&gt;iss&lt;/code&gt; parameter against the recorded issuer (RFC 9207, SEP-2468), must key stored client credentials by the authorization server that issued them (SEP-2352), and Dynamic Client Registration is now deprecated in favour of Client ID Metadata Documents.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Two Anthropic beta headers, and they don't stack.&lt;/strong&gt; If you call Claude Managed Agents directly from .NET, agent and session endpoints need &lt;code&gt;managed-agents-2026-04-01&lt;/code&gt;. Memory store endpoints use &lt;code&gt;agent-memory-2026-07-22&lt;/code&gt; instead, and sending both headers on a memory store call returns a 400. Attaching a memory store to a session is a session call, so it still uses &lt;code&gt;managed-agents-2026-04-01&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Humans must stay in the loop.&lt;/strong&gt; Agent teams that distribute tasks among themselves are efficient and hard to interrupt. Define explicit pause points, stages where the coordinator shows a summary and waits for human confirmation before the next wave of tasks starts. For production systems this is a requirement, not a nice-to-have.&lt;/p&gt;




&lt;h2&gt;
  
  
  Where This Fits in the Series
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://dotnet-talk.com/blog/claude-code-dotnet-practical-workflow" rel="noopener noreferrer"&gt;Part 1&lt;/a&gt; set up the agentic workflow and &lt;a href="https://dotnet-talk.com/blog/context-engineering-net-coding-agent" rel="noopener noreferrer"&gt;Part 2&lt;/a&gt; covered getting the right context into a single agent. This part handles the state and coordination layer that makes multi-session, multi-agent work coherent. &lt;a href="https://dotnet-talk.com/blog/function-calling-csharp-ai-agent-tools" rel="noopener noreferrer"&gt;Part 4&lt;/a&gt; goes one level down, to the function-calling loop that every tool call in this article runs on.&lt;/p&gt;

&lt;p&gt;A stateless protocol is the right call for scalability, and it moves the memory problem into your code. A small MCP server in front of a shared store, a JSON file for a prototype on one instance and a database once you run more than one, is a practical answer for .NET teams today. Keep the state surface small, timestamp everything, and put a human checkpoint before agents act on what they remember.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>dotnet</category>
      <category>mcp</category>
      <category>claude</category>
    </item>
    <item>
      <title>Context Engineering: Getting the Right Information to Your .NET Coding Agent</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Fri, 30 Oct 2026 07:48:28 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/context-engineering-getting-the-right-information-to-your-net-coding-agent-46kb</link>
      <guid>https://dev.to/mehdimohseni82/context-engineering-getting-the-right-information-to-your-net-coding-agent-46kb</guid>
      <description>&lt;p&gt;&lt;em&gt;This is Part 2 of the "Agentic Engineering for .NET Teams" series. &lt;a href="https://dotnet-talk.com/blog/claude-code-dotnet-practical-workflow" rel="noopener noreferrer"&gt;Part 1&lt;/a&gt; covers setting up a coding agent for a .NET solution. &lt;a href="https://dotnet-talk.com/blog/agentic-dotnet-memory-mcp-handoffs" rel="noopener noreferrer"&gt;Part 3&lt;/a&gt; covers sharing state across sessions and agents.&lt;/em&gt;&lt;/p&gt;

&lt;h2&gt;
  
  
  The Bottleneck Is Not the Model
&lt;/h2&gt;

&lt;p&gt;Context windows are large now. In Claude Code, the Fable models, Sonnet 5 and later, Haiku 5.5, Opus 4.6 and later, and Sonnet 4.6 all support a 1 million token window. That number tempts you into a "just paste everything" approach. Resist it.&lt;/p&gt;

&lt;p&gt;Chroma's Context Rot study (July 2025) tested 18 models, including GPT-4.1, Claude 4 and Gemini 2.5, and found that every one of them got worse as the input grew, even on simple tasks and well before the window was full. The older "Lost in the Middle" paper (Liu et al., 2023) showed where it hurts most: with 20 documents in the prompt, GPT-3.5 answered correctly about 76% of the time when the relevant document came first, and about 54% when it sat in the middle.&lt;/p&gt;

&lt;p&gt;So there are two numbers to keep apart. The context window is how many tokens you can send. Effective context is how many of those tokens the model uses reliably, and it is always the smaller one.&lt;/p&gt;

&lt;p&gt;Anthropic describes context engineering, in its September 2025 post "Effective context engineering for AI agents", as "the set of strategies for curating and maintaining the optimal set of tokens (information) during LLM inference". It treats it as the natural next step after prompt engineering, and that is the discipline this article is about.&lt;/p&gt;

&lt;h2&gt;
  
  
  Anatomy of an Agent's Context
&lt;/h2&gt;

&lt;p&gt;When your agent processes a request, its context is assembled from several distinct layers:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;System and project instructions.&lt;/strong&gt; CLAUDE.md, AGENTS.md or &lt;code&gt;.github/copilot-instructions.md&lt;/code&gt;, depending on your toolchain. Loaded at session start.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Files in scope.&lt;/strong&gt; What the agent has read, been given, or retrieved from your repo.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Tool results.&lt;/strong&gt; Output from shell commands, test runners, linters, search tools and MCP connectors.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Conversation history.&lt;/strong&gt; Every earlier turn in the session, which keeps growing.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Each layer competes for the same finite budget. A bloated conversation history crowds out your project instructions, and a large file dump crowds out the tool output that contains the actual error. In Claude Code, &lt;code&gt;/context&lt;/code&gt; shows the live breakdown by category, so you can see which layer is taking the space instead of guessing.&lt;/p&gt;

&lt;h2&gt;
  
  
  Techniques That Actually Work
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Project Instruction Files: CLAUDE.md and AGENTS.md
&lt;/h3&gt;

&lt;p&gt;CLAUDE.md is a plain Markdown file that Claude Code loads at session start. AGENTS.md is the cross-tool format that started in OpenAI's Codex and that OpenAI contributed to the Linux Foundation's Agentic AI Foundation in December 2025. Since v2.1.277, Claude Code reads AGENTS.md as well, but by default only when there is no CLAUDE.md in the working directory or above it. If you have both, either import AGENTS.md from a one-line CLAUDE.md (&lt;code&gt;@AGENTS.md&lt;/code&gt;) or set the &lt;strong&gt;Project instructions&lt;/strong&gt; option to load both.&lt;/p&gt;

&lt;p&gt;Anthropic's own guidance is to keep each CLAUDE.md under about 200 lines, because longer files cost more context and reduce adherence. You will not see an error when a file gets too long, you will just see the agent following some conventions and ignoring others. Two features help keep the file short:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Path-scoped rules.&lt;/strong&gt; A Markdown file in &lt;code&gt;.claude/rules/&lt;/code&gt; with &lt;code&gt;paths:&lt;/code&gt; frontmatter loads only when Claude works with matching files, so the EF Core migration rules stay out of the context while it edits a Razor page.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Imports.&lt;/strong&gt; &lt;code&gt;@path&lt;/code&gt; lines pull other files in, up to four hops deep. They help you organise a long file, but they do not save context, because imported files load together with the file that imports them.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;A practical CLAUDE.md for a .NET solution looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# Project: Payments Platform&lt;/span&gt;

&lt;span class="gu"&gt;## Build &amp;amp; Test&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Build: &lt;span class="sb"&gt;`dotnet build src/Payments.sln`&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Test: &lt;span class="sb"&gt;`dotnet test src/Payments.sln --no-build --logger trx`&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Lint: &lt;span class="sb"&gt;`dotnet format --verify-no-changes`&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Always run tests before considering a task complete.

&lt;span class="gu"&gt;## Architecture&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Clean Architecture: Domain → Application → Infrastructure → API
&lt;span class="p"&gt;-&lt;/span&gt; Domain layer has zero external dependencies. Do not add NuGet refs to Domain.
&lt;span class="p"&gt;-&lt;/span&gt; Use MediatR for CQRS. Commands in Application/Commands/, Queries in Application/Queries/.
&lt;span class="p"&gt;-&lt;/span&gt; EF Core DbContext lives in Infrastructure only. Never inject it into Application directly.

&lt;span class="gu"&gt;## Conventions&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Result&lt;span class="nt"&gt;&amp;lt;T&amp;gt;&lt;/span&gt; pattern (no exceptions for flow control). See src/SharedKernel/Result.cs.
&lt;span class="p"&gt;-&lt;/span&gt; Nullable reference types enabled globally. Do not suppress NRT warnings.
&lt;span class="p"&gt;-&lt;/span&gt; Integration tests use TestContainers; unit tests use xUnit + NSubstitute.

&lt;span class="gu"&gt;## Do Not&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Do not modify migration files directly, run &lt;span class="sb"&gt;`dotnet ef migrations add &amp;lt;Name&amp;gt;`&lt;/span&gt;.
&lt;span class="p"&gt;-&lt;/span&gt; Do not add business logic to API controllers.
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Every line here is something the agent would otherwise have to guess. A new team member, human or model, reading this knows the rules without opening a single source file.&lt;/p&gt;

&lt;h3&gt;
  
  
  Scoping the Task and Curating Files
&lt;/h3&gt;

&lt;p&gt;The habit with the most leverage is giving the agent the &lt;strong&gt;minimum relevant file set&lt;/strong&gt; for each task. If you are adding a new query handler, the agent needs the query contract, the relevant entity, the DbContext registration and one existing handler as a reference pattern. It does not need the whole solution.&lt;/p&gt;

&lt;p&gt;In Claude Code you control this with &lt;code&gt;@&lt;/code&gt; file references in your prompt. In GitHub Copilot's agent mode, workspace indexing handles much of this, but you can still attach files explicitly.&lt;/p&gt;

&lt;p&gt;For large codebases, retrieving the relevant snippets through search or an MCP connector works better than stuffing everything in. A search tool can return the three files that matter for a query instead of giving the agent all 400.&lt;/p&gt;

&lt;h3&gt;
  
  
  Summarization and Compaction
&lt;/h3&gt;

&lt;p&gt;Long sessions accumulate context rot. Three techniques help, and they work best together:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Compaction.&lt;/strong&gt; Summarise the conversation, keeping architectural decisions and dropping resolved back-and-forth. Claude Code compacts automatically as the window fills, and &lt;code&gt;/autocompact&lt;/code&gt; with a token count, for example &lt;code&gt;/autocompact 500k&lt;/code&gt;, sets how full it gets first. You can also run &lt;code&gt;/compact&lt;/code&gt; with a focus, like &lt;code&gt;/compact focus on the payment retry bug&lt;/code&gt;, so the summary keeps what you choose. After compaction the project-root CLAUDE.md and auto memory are re-read from disk, which is one more reason to put lasting rules there and not only in the chat.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Structured external memory.&lt;/strong&gt; Write progress notes, checkpoint files or a &lt;code&gt;PROGRESS.md&lt;/code&gt; that the agent reads at the start of each new session. Claude Code's auto memory does a version of this on its own: it loads the first 200 lines or 25KB of its &lt;code&gt;MEMORY.md&lt;/code&gt; into every session. Either way, the notes survive a context reset.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Subagent delegation.&lt;/strong&gt; Break a large task into bounded subtasks handled by separate agents. In Claude Code a subagent works in its own context window, so its file reads stay out of yours, and it returns a compact summary instead of its full transcript.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Repo Hygiene That Pays Off
&lt;/h2&gt;

&lt;p&gt;Context engineering is not only a prompt problem, it is a repo design problem. A well-structured .NET solution is easier for an agent to reason about.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Clear module boundaries&lt;/strong&gt; matter more than ever. A solution where &lt;code&gt;Infrastructure&lt;/code&gt; has no circular references to &lt;code&gt;Application&lt;/code&gt;, and where each project has a single clear purpose, lets the agent reason about a change without reading half the repo.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;READMEs at every module boundary&lt;/strong&gt; are not just for humans. A two-paragraph README in &lt;code&gt;src/Payments.Infrastructure/&lt;/code&gt; explaining what lives there and what doesn't gives the agent structural context it cannot reliably infer from code.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Machine-readable build and test commands&lt;/strong&gt; in CLAUDE.md or AGENTS.md let the agent verify its own output. The loop of write, build, test and fix catches most regressions before they reach review.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Example: Result&amp;lt;T&amp;gt; pattern referenced in CLAUDE.md&lt;/span&gt;
&lt;span class="c1"&gt;// The agent knows this pattern exists and where to find it.&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;T&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="n"&gt;T&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;Value&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;Error&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;bool&lt;/span&gt; &lt;span class="n"&gt;IsSuccess&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="nf"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;T&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Value&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;IsSuccess&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="nf"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Error&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;IsSuccess&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;false&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="n"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;T&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;Ok&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;T&lt;/span&gt; &lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;value&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="n"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;T&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;Fail&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="n"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TOut&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;Map&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TOut&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;(&lt;/span&gt;&lt;span class="n"&gt;Func&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;T&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;TOut&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;map&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="n"&gt;IsSuccess&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TOut&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;.&lt;/span&gt;&lt;span class="nf"&gt;Ok&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="nf"&gt;map&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Value&lt;/span&gt;&lt;span class="p"&gt;!))&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Result&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TOut&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;.&lt;/span&gt;&lt;span class="nf"&gt;Fail&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Error&lt;/span&gt;&lt;span class="p"&gt;!);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;When the agent sees &lt;code&gt;Result&amp;lt;T&amp;gt;&lt;/code&gt; in a contract and your CLAUDE.md says "Result&amp;lt;T&amp;gt; pattern, see src/SharedKernel/Result.cs", it reads the implementation instead of inventing a different error-handling pattern.&lt;/p&gt;

&lt;h2&gt;
  
  
  Context Anti-Patterns
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Stale instruction files.&lt;/strong&gt; A CLAUDE.md that describes last year's architecture is worse than no file at all. If it says "use Dapper for data access" but the codebase moved to EF Core six months ago, you will spend your time correcting the agent's choices instead of reviewing correct output. Treat the file as living documentation. Since v2.1.283, &lt;code&gt;/doctor prompt-audit&lt;/code&gt; checks your CLAUDE.md, CLAUDE.local.md, AGENTS.md and the rules and skills under &lt;code&gt;.claude/&lt;/code&gt; for instructions written for older models, references to files or commands that no longer exist, and files that contradict each other, and proposes edits without changing anything until you ask.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Contradictory docs.&lt;/strong&gt; The &lt;code&gt;.cursorrules&lt;/code&gt; file says one thing, the CLAUDE.md says another, and the README says a third. The model picks one and you don't know which. Make AGENTS.md the single source, and have the tool-specific files import or point to it instead of repeating it.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Dumping huge files.&lt;/strong&gt; Giving the agent an entire 3,000-line service class when it only needs one method puts the important part in the middle of a long input, which is exactly where the studies above found the losses. Give it the method, its direct dependencies and the relevant interface.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Losing the thread over long sessions.&lt;/strong&gt; After 30 or more turns, early instructions are buried deep in history. The agent starts producing output that contradicts decisions made at the start of the session. That is not a model failure, it is a session management failure.&lt;/p&gt;

&lt;h2&gt;
  
  
  Measuring and Resetting
&lt;/h2&gt;

&lt;p&gt;The signs that an agent has lost context are recognisable once you know to look for them: it ignores conventions it followed earlier in the session, it asks questions it already answered, it brings back a pattern you explicitly ruled out, or it is confident about something that is plainly wrong.&lt;/p&gt;

&lt;p&gt;When you see those signals, stop prompting and reset. Run &lt;code&gt;/clear&lt;/code&gt; or start a fresh session, let the CLAUDE.md load, give it the minimal relevant file set, and write a one-paragraph summary of the decisions made so far. That paragraph is denser and more reliable than 40 turns of accumulated history.&lt;/p&gt;

&lt;p&gt;Better models narrow the problem but do not remove it. When Anthropic released Opus 4.6, it reported 76% on the MRCR v2 benchmark, which hides eight facts across 1 million tokens, against 18.5% for Sonnet 4.5. That is a large improvement, and it still means a quarter of the facts were missed. The answer to context rot is architectural: structure your sessions and keep memory outside the conversation, instead of hoping the next model solves it.&lt;/p&gt;

&lt;p&gt;Iterating on your CLAUDE.md based on observed failures is usually the best return on time in context engineering. If an agent keeps misapplying the same pattern, that pattern needs a clearer description in the instruction file, or a reference example. Note which additions removed which kinds of errors, so the file grows from evidence and not from guesses.&lt;/p&gt;

&lt;p&gt;&lt;em&gt;&lt;a href="https://dotnet-talk.com/blog/agentic-dotnet-memory-mcp-handoffs" rel="noopener noreferrer"&gt;Part 3&lt;/a&gt; of this series covers sharing state across sessions and agents: memory, MCP and handoffs in .NET.&lt;/em&gt;&lt;/p&gt;

</description>
      <category>ai</category>
      <category>dotnet</category>
      <category>claude</category>
      <category>developertools</category>
    </item>
    <item>
      <title>Claude Code for .NET Developers: A Practical Agentic Workflow</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Thu, 29 Oct 2026 20:39:07 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/claude-code-for-net-developers-a-practical-agentic-workflow-429c</link>
      <guid>https://dev.to/mehdimohseni82/claude-code-for-net-developers-a-practical-agentic-workflow-429c</guid>
      <description>&lt;p&gt;&lt;em&gt;This is Part 1 of the "Agentic Engineering for .NET Teams" series. &lt;a href="https://dotnet-talk.com/blog/context-engineering-net-coding-agent" rel="noopener noreferrer"&gt;Part 2&lt;/a&gt; covers context engineering, &lt;a href="https://dotnet-talk.com/blog/agentic-dotnet-memory-mcp-handoffs" rel="noopener noreferrer"&gt;Part 3&lt;/a&gt; covers sharing state across sessions and agents, and &lt;a href="https://dotnet-talk.com/blog/function-calling-csharp-ai-agent-tools" rel="noopener noreferrer"&gt;Part 4&lt;/a&gt; covers function calling in C#.&lt;/em&gt;&lt;/p&gt;




&lt;p&gt;&lt;em&gt;Updated 9 November 2026: an earlier version described Copilot as next-line completion only. It has agent features too, and a reader on Medium was right to point that out.&lt;/em&gt;&lt;/p&gt;

&lt;p&gt;GitHub Copilot started as next-line completion and now also runs as an agent, in agent mode in VS Code, Visual Studio and JetBrains, in the Copilot CLI and as a cloud agent on GitHub. Claude Code is built around the same kind of loop, but it starts from the terminal: it reads your repository, proposes a plan, writes files, runs &lt;code&gt;dotnet build&lt;/code&gt;, reads the compiler errors, fixes them, runs &lt;code&gt;dotnet test&lt;/code&gt; and iterates on the failures. Understanding that loop is what this article is about.&lt;/p&gt;

&lt;p&gt;Claude Code launched as a research preview in February 2025 and became generally available in May 2025. It now runs in the terminal, a desktop app, VS Code, JetBrains IDEs and Slack. Adoption has moved quickly: a JetBrains Research survey of more than 15,000 developers, published in August 2026, puts Claude Code at 39% use at work, up from 18% in the company's January survey. The reason is architectural rather than cosmetic, because this is an agent with filesystem and shell access, not an autocomplete.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Claude Code Is, and How It Differs
&lt;/h2&gt;

&lt;p&gt;A rough mental model helps. &lt;strong&gt;Copilot&lt;/strong&gt; began as inline completion and now has an agent mode in the IDE, a CLI and a cloud agent, and it reads project skills from &lt;code&gt;.github/skills&lt;/code&gt;, &lt;code&gt;.claude/skills&lt;/code&gt; or &lt;code&gt;.agents/skills&lt;/code&gt;. &lt;strong&gt;Chat tools&lt;/strong&gt; brainstorm and explain, but they cannot touch your repo. &lt;strong&gt;Cursor&lt;/strong&gt; does multi-file edits inside a VS Code style editor. &lt;strong&gt;Claude Code&lt;/strong&gt; is an agent that starts from the terminal: it searches your tree, plans, edits several files, runs shell commands and corrects itself based on the real output.&lt;/p&gt;

&lt;p&gt;The building blocks it exposes are &lt;code&gt;CLAUDE.md&lt;/code&gt;, skills, subagents, slash commands, hooks and MCP servers, and plugins bundle several of those into one installable unit. You do not need all of them on the first day, but knowing they exist stops you from treating the tool as a smarter autocomplete.&lt;/p&gt;

&lt;p&gt;In February 2026, a year after he coined "vibe coding", Andrej Karpathy proposed the name "agentic engineering" for the professional version of this work: agents do much of the typing, and people keep the oversight. That is also the idea behind this series.&lt;/p&gt;

&lt;h2&gt;
  
  
  Setting Up Claude Code for a .NET Repo
&lt;/h2&gt;

&lt;h3&gt;
  
  
  Installing the CLI
&lt;/h3&gt;

&lt;p&gt;The recommended install is the native installer, which updates itself in the background. Homebrew and WinGet also work, and the npm package is still available. All of them install the same native binary, so &lt;code&gt;claude&lt;/code&gt; does not depend on Node.js at runtime.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;# macOS, Linux and WSL&lt;/span&gt;
curl &lt;span class="nt"&gt;-fsSL&lt;/span&gt; https://claude.ai/install.sh | bash

&lt;span class="c"&gt;# or: brew install --cask claude-code&lt;/span&gt;
&lt;span class="c"&gt;# or: winget install Anthropic.ClaudeCode&lt;/span&gt;
&lt;span class="c"&gt;# or: npm install -g @anthropic-ai/claude-code   (needs Node.js 22 or later)&lt;/span&gt;

claude &lt;span class="nt"&gt;--version&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Claude Code is included with a paid Claude subscription. There is a 5-hour usage limit plus weekly limits, shared across claude.ai, Claude Code and the desktop app, and how fast you use them depends on the model and on how much context each request carries. Run &lt;code&gt;/usage&lt;/code&gt; inside a session to see where you stand.&lt;/p&gt;

&lt;h3&gt;
  
  
  Writing CLAUDE.md
&lt;/h3&gt;

&lt;p&gt;This is the most important part of the setup, and it is the part most teams write once and then forget. Anthropic's own guidance is to keep each &lt;code&gt;CLAUDE.md&lt;/code&gt; under 200 lines, because a longer file costs more context and is followed less reliably. Instructions that only matter for part of the codebase can go into path-scoped rule files under &lt;code&gt;.claude/rules/&lt;/code&gt;, which load only when Claude works with matching files.&lt;/p&gt;

&lt;p&gt;Two files are worth separating. &lt;strong&gt;AGENTS.md&lt;/strong&gt; is an open format that several coding agents read, so it is a good home for things every tool should know: target framework, coding conventions, forbidden APIs and architectural rules. &lt;strong&gt;CLAUDE.md&lt;/strong&gt; is specific to Claude Code and holds workflow instructions. Since v2.1.277, Claude Code can read &lt;code&gt;AGENTS.md&lt;/code&gt; directly, but by default only when the repository has no &lt;code&gt;CLAUDE.md&lt;/code&gt;. If you keep both, import one into the other with a line such as &lt;code&gt;@AGENTS.md&lt;/code&gt;, so both always load.&lt;/p&gt;

&lt;p&gt;A practical structure for a Clean Architecture ASP.NET Core service:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight markdown"&gt;&lt;code&gt;&lt;span class="gh"&gt;# CLAUDE.md&lt;/span&gt;

@AGENTS.md

&lt;span class="gu"&gt;## What this repo is&lt;/span&gt;
ASP.NET Core Web API, Clean Architecture. Target: net10.0.
Conventions and forbidden APIs are in AGENTS.md (imported above).

&lt;span class="gu"&gt;## Build and test commands&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Build: dotnet build src/MyService.slnx
&lt;span class="p"&gt;-&lt;/span&gt; Test: dotnet test src/MyService.slnx --no-build
&lt;span class="p"&gt;-&lt;/span&gt; Format: dotnet format src/MyService.slnx

&lt;span class="gu"&gt;## Workflow&lt;/span&gt;
&lt;span class="p"&gt;-&lt;/span&gt; Use plan mode for any change touching src/Billing/ or src/Domain/
&lt;span class="p"&gt;-&lt;/span&gt; Always add or update xUnit tests in the same PR as domain changes
&lt;span class="p"&gt;-&lt;/span&gt; Prefer record types for value objects
&lt;span class="p"&gt;-&lt;/span&gt; Do not use MediatR pipeline behaviours for cross-cutting concerns;
  use middleware instead (see ADR-004)
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The solution file ends in &lt;code&gt;.slnx&lt;/code&gt; because that is what &lt;code&gt;dotnet new sln&lt;/code&gt; creates from the .NET 10 SDK onwards; older repositories may still have a &lt;code&gt;.sln&lt;/code&gt;, and both work with the commands above.&lt;/p&gt;

&lt;p&gt;A structure that works well is what, why and how: what the project is, why certain conventions exist, and how to run the workflow. Claude can also update the file for you, so "add this rule to CLAUDE.md" works in conversation. The old &lt;code&gt;#&lt;/code&gt; shortcut for quick memory entries was removed in December 2025, so asking Claude directly is now the way to do it. If you want to see what actually loaded into a session, &lt;code&gt;/context&lt;/code&gt; shows the memory files alongside everything else in the context window.&lt;/p&gt;

&lt;h3&gt;
  
  
  Configuring PostToolUse Hooks
&lt;/h3&gt;

&lt;p&gt;Hooks are what turn Claude Code from a tool that writes code into one that also checks it. A &lt;code&gt;PostToolUse&lt;/code&gt; hook runs after a tool call succeeds, so a hook on &lt;code&gt;Edit&lt;/code&gt; and &lt;code&gt;Write&lt;/code&gt; can build the solution after every change. When the hook exits with code 2, Claude sees its stderr and fixes the problem before moving on.&lt;/p&gt;

&lt;p&gt;Add the hook to &lt;code&gt;.claude/settings.json&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"hooks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"PostToolUse"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="nl"&gt;"matcher"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Edit|Write"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="nl"&gt;"hooks"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="w"&gt;
          &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"type"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"command"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="nl"&gt;"command"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"${CLAUDE_PROJECT_DIR}/.claude/hooks/dotnet-build.sh"&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
        &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
      &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And the script it calls:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;&lt;span class="c"&gt;#!/usr/bin/env bash&lt;/span&gt;
&lt;span class="c"&gt;# .claude/hooks/dotnet-build.sh: builds only when a C# file or project changed.&lt;/span&gt;
&lt;span class="nv"&gt;input&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;&lt;span class="nb"&gt;cat&lt;/span&gt;&lt;span class="si"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;case&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$input&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt;
  &lt;span class="k"&gt;*&lt;/span&gt;&lt;span class="s1"&gt;'.cs"'&lt;/span&gt;&lt;span class="k"&gt;*&lt;/span&gt;&lt;span class="p"&gt;|&lt;/span&gt;&lt;span class="k"&gt;*&lt;/span&gt;&lt;span class="s1"&gt;'.csproj"'&lt;/span&gt;&lt;span class="k"&gt;*&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;;;&lt;/span&gt;
  &lt;span class="k"&gt;*&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="nb"&gt;exit &lt;/span&gt;0 &lt;span class="p"&gt;;;&lt;/span&gt;
&lt;span class="k"&gt;esac&lt;/span&gt;
&lt;span class="nb"&gt;cd&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$CLAUDE_PROJECT_DIR&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; &lt;span class="o"&gt;||&lt;/span&gt; &lt;span class="nb"&gt;exit &lt;/span&gt;0
&lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="o"&gt;!&lt;/span&gt; &lt;span class="nv"&gt;out&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="si"&gt;$(&lt;/span&gt;dotnet build src/MyService.slnx &lt;span class="nt"&gt;--no-restore&lt;/span&gt; &lt;span class="nt"&gt;-v&lt;/span&gt; q &lt;span class="nt"&gt;-nologo&lt;/span&gt; 2&amp;gt;&amp;amp;1&lt;span class="si"&gt;)&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;then
  &lt;/span&gt;&lt;span class="nb"&gt;echo&lt;/span&gt; &lt;span class="s2"&gt;"&lt;/span&gt;&lt;span class="nv"&gt;$out&lt;/span&gt;&lt;span class="s2"&gt;"&lt;/span&gt; | &lt;span class="nb"&gt;grep&lt;/span&gt; &lt;span class="nt"&gt;-E&lt;/span&gt; &lt;span class="s2"&gt;"error [A-Z]+[0-9]+"&lt;/span&gt; | &lt;span class="nb"&gt;sort&lt;/span&gt; &lt;span class="nt"&gt;-u&lt;/span&gt; | &lt;span class="nb"&gt;head&lt;/span&gt; &lt;span class="nt"&gt;-20&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt;&amp;amp;2
  &lt;span class="nb"&gt;exit &lt;/span&gt;2
&lt;span class="k"&gt;fi&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The script reads the hook input from stdin, skips edits to files that cannot break the build, and passes only the compiler errors back to Claude. A full build after every edit can be slow on a large solution, so many teams point the hook at the nearest project instead, or run the tests from a &lt;code&gt;Stop&lt;/code&gt; hook once Claude has finished a turn.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Core Loop: Plan, Act, Iterate
&lt;/h2&gt;

&lt;p&gt;For any non-trivial change, start in plan mode. In plan mode Claude reads the relevant code and proposes changes without editing your files. You review the plan, push back on anything wrong, and only then let it act.&lt;/p&gt;

&lt;p&gt;Running example: adding a &lt;code&gt;PATCH /orders/{id}/status&lt;/code&gt; endpoint to an existing ASP.NET Core service, with request validation and integration tests.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--permission-mode&lt;/span&gt; plan &lt;span class="s2"&gt;"Add a PATCH /orders/{id}/status endpoint.
  - Accept { status: string } body. Validate against the OrderStatus enum.
  - Return 400 if the transition is invalid (see Domain/OrderStateMachine.cs).
  - Add FluentValidation validator.
  - Add integration tests in tests/MyService.IntegrationTests using the
    existing WebApplicationFactory&amp;lt;Program&amp;gt; fixture."&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Inside a running session, &lt;code&gt;/plan&lt;/code&gt; followed by the same description does the same thing. Claude reads &lt;code&gt;OrderStateMachine.cs&lt;/code&gt;, the existing endpoint pattern, the test fixture and the validator convention, then produces a numbered plan. If step 3 is wrong, for example because it adds a MediatR handler that your &lt;code&gt;CLAUDE.md&lt;/code&gt; forbids, you correct it before a single file changes.&lt;/p&gt;

&lt;p&gt;Once you approve, Claude acts. It edits files, the &lt;code&gt;PostToolUse&lt;/code&gt; hook builds the solution, Claude reads any compiler errors and fixes them, then it runs &lt;code&gt;dotnet test&lt;/code&gt; and works through the failures. How many rounds that takes depends on the change and on how clear the plan was.&lt;/p&gt;

&lt;p&gt;For changes that touch dozens of files, such as a rename or a layer extraction, start the session in its own git worktree with &lt;code&gt;--worktree&lt;/code&gt;:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight shell"&gt;&lt;code&gt;claude &lt;span class="nt"&gt;--worktree&lt;/span&gt; rename-customer-to-client &lt;span class="se"&gt;\&lt;/span&gt;
  &lt;span class="s2"&gt;"Rename the Customer domain entity to Client across the whole solution.
   Update all references, namespaces, tests, and migration names."&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The worktree is created under &lt;code&gt;.claude/worktrees/rename-customer-to-client/&lt;/code&gt; on a new branch named &lt;code&gt;worktree-rename-customer-to-client&lt;/code&gt;, so your main working tree stays untouched until you review and merge.&lt;/p&gt;

&lt;h2&gt;
  
  
  Working Effectively
&lt;/h2&gt;

&lt;p&gt;A few patterns matter in practice.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Scope tasks tightly.&lt;/strong&gt; "Refactor the service layer" is too broad. "Extract &lt;code&gt;OrderFulfillmentService&lt;/code&gt; from &lt;code&gt;OrderService&lt;/code&gt; and move the three shipping-related methods" is something Claude can act on. The plan step helps here, because a vague task produces a vague plan.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Reference files explicitly.&lt;/strong&gt; Writing &lt;code&gt;@src/Billing/InvoiceService.cs&lt;/code&gt; in your prompt puts that file's content into the conversation straight away. Claude will find related files by searching the repository, but naming the starting points saves it the search.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Review diffs before moving on.&lt;/strong&gt; &lt;code&gt;/rewind&lt;/code&gt; can roll the conversation and the code back to an earlier point, because Claude Code checkpoints the files it edits with its own tools. It does not track files that only shell commands changed, so a &lt;code&gt;git diff&lt;/code&gt; before you commit is still the habit that protects you. Claude Code produces the code, and you own the result.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Know when to intervene.&lt;/strong&gt; If the plan heads somewhere you do not want, for example towards an abstraction you have no use for, interrupt and type your correction. Claude takes it into account and replans. Treating the loop as a black box is where teams get into trouble.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Review before merging.&lt;/strong&gt; &lt;code&gt;/code-review&lt;/code&gt; checks the current diff for correctness bugs inside your session. For security-sensitive code, such as a billing or auth module, &lt;code&gt;/code-review ultra&lt;/code&gt; (also available as &lt;code&gt;/ultrareview&lt;/code&gt;) runs a deeper multi-agent review in a cloud sandbox. Pro and Max plans include 3 free ultra runs, after which it uses usage credits.&lt;/p&gt;

&lt;h2&gt;
  
  
  Guardrails for Teams
&lt;/h2&gt;

&lt;p&gt;The permission model has changed twice this year, and both changes matter for teams.&lt;/p&gt;

&lt;p&gt;In &lt;strong&gt;v2.1.200 (3 July 2026)&lt;/strong&gt;, the mode that asks before every action was renamed &lt;strong&gt;Manual&lt;/strong&gt; in the CLI, VS Code and JetBrains. Its config value is still &lt;code&gt;default&lt;/code&gt;, and &lt;code&gt;manual&lt;/code&gt; is accepted as an alias, so &lt;code&gt;--permission-mode manual&lt;/code&gt; and &lt;code&gt;"defaultMode": "manual"&lt;/code&gt; both work. In Manual mode, Claude reads files freely but asks before edits, shell commands and network requests.&lt;/p&gt;

&lt;p&gt;In &lt;strong&gt;v2.1.283 (25 September 2026)&lt;/strong&gt;, auto mode became the built-in starting mode for interactive terminal and VS Code sessions. In auto mode a second model, the classifier, reviews actions instead of you. If your team wants every action approved by a person, set &lt;code&gt;"defaultMode": "default"&lt;/code&gt; (or &lt;code&gt;"manual"&lt;/code&gt;) in settings rather than relying on the built-in default.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Do not rely on permission mode alone to enforce hard rules.&lt;/strong&gt; A permission mode is a session-wide setting for how much supervision you want. Rules that must always hold belong in permission rules and hooks: deny rules apply in every mode, including &lt;code&gt;bypassPermissions&lt;/code&gt;, and a &lt;code&gt;PreToolUse&lt;/code&gt; hook runs before the tool does, so it can block the call. A &lt;code&gt;PostToolUse&lt;/code&gt; hook, by contrast, runs after the tool has already done its work, which makes it right for checking and wrong for blocking.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Clarifying questions now wait for you.&lt;/strong&gt; Also in v2.1.200, the &lt;code&gt;AskUserQuestion&lt;/code&gt; dialog stopped continuing on its own after a timeout. That is safer for supervised work. If a workflow of yours relied on the old timeout to keep going unattended, you can opt back into an idle timeout through &lt;code&gt;/config&lt;/code&gt;.&lt;/p&gt;

&lt;p&gt;For organisations, managed settings sit above every other settings level, so no user or project file can override them. They can be delivered as a &lt;code&gt;managed-settings.json&lt;/code&gt; file in a system directory, through MDM, or as server-managed settings from the Claude admin console. That is where you enforce organisation-wide rules: blocked reads, disabled bypass mode and required hooks.&lt;/p&gt;

&lt;p&gt;Keep secrets out of context. Claude Code does not hide &lt;code&gt;.env&lt;/code&gt; or &lt;code&gt;appsettings.*.json&lt;/code&gt; files from its own file tools by default. Add &lt;code&gt;Read&lt;/code&gt; deny rules for them in your settings, and keep real secrets in environment variables or a secret store rather than in files inside the repository:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight json"&gt;&lt;code&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="nl"&gt;"permissions"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="w"&gt;
    &lt;/span&gt;&lt;span class="nl"&gt;"deny"&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s2"&gt;"Read(.env)"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;&lt;span class="w"&gt; &lt;/span&gt;&lt;span class="s2"&gt;"Read(appsettings.*.json)"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;&lt;span class="w"&gt;
  &lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="w"&gt;
&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Next: Context, Shared State and Tools
&lt;/h2&gt;

&lt;p&gt;Everything above runs within a single Claude Code session. &lt;a href="https://dotnet-talk.com/blog/context-engineering-net-coding-agent" rel="noopener noreferrer"&gt;Part 2&lt;/a&gt; of this series looks at context engineering: what Claude actually sees in its context window, and how to get the right information in front of it for a .NET codebase. &lt;a href="https://dotnet-talk.com/blog/agentic-dotnet-memory-mcp-handoffs" rel="noopener noreferrer"&gt;Part 3&lt;/a&gt; moves beyond one session to memory, MCP servers, subagents and handoffs between agents. &lt;a href="https://dotnet-talk.com/blog/function-calling-csharp-ai-agent-tools" rel="noopener noreferrer"&gt;Part 4&lt;/a&gt; builds the function calling loop in C# with the Anthropic SDK.&lt;/p&gt;




&lt;p&gt;The gains from Claude Code come from the feedback loop more than from clever prompts. Set that loop up deliberately: a &lt;code&gt;CLAUDE.md&lt;/code&gt; with your real conventions, hooks that run &lt;code&gt;dotnet build&lt;/code&gt; and your tests, plan mode for anything non-trivial, and a habit of reviewing the diff before it is merged.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>dotnet</category>
      <category>claudecode</category>
      <category>developertools</category>
    </item>
    <item>
      <title>Function Calling in C#: Building Tools Your AI Agent Can Call</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Sun, 25 Oct 2026 07:26:36 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/function-calling-in-c-building-tools-your-ai-agent-can-call-5hm2</link>
      <guid>https://dev.to/mehdimohseni82/function-calling-in-c-building-tools-your-ai-agent-can-call-5hm2</guid>
      <description>&lt;p&gt;The gap between a chatbot and an agent is function calling. Without it, the model can only generate text, so you have to parse that text, guess the intent and hope the format holds. With function calling, the model emits a structured call: a tool name and arguments that match a schema you gave it. Your code runs it, the model sees the result and continues. That loop is the engine behind every serious agentic application.&lt;/p&gt;

&lt;p&gt;This article builds that loop in C# with the official Anthropic SDK: defining a tool, running the loop, dispatching to real code, handling failures, and the production concerns around it. All the code here was compiled and run against &lt;code&gt;Anthropic&lt;/code&gt; 13.2.0 and a PostgreSQL 18 database.&lt;/p&gt;

&lt;h2&gt;
  
  
  What Function Calling Actually Is
&lt;/h2&gt;

&lt;p&gt;In the Messages API, tool use is part of the message exchange, not a side channel. When the model decides to call a tool, the response has &lt;code&gt;stop_reason: "tool_use"&lt;/code&gt; and one or more &lt;code&gt;tool_use&lt;/code&gt; content blocks. Each block has an id, a tool name and a JSON input that follows the schema you provided.&lt;/p&gt;

&lt;p&gt;Your application runs the tool, locally, against a database or an internal API, and sends the outcome back as a &lt;code&gt;tool_result&lt;/code&gt; block in the next user message. The model continues from there, maybe calling more tools, until it returns &lt;code&gt;stop_reason: "end_turn"&lt;/code&gt; with a final answer.&lt;/p&gt;

&lt;p&gt;This beats parsing text for three reasons. The input comes as structured JSON shaped by your schema, not as prose you have to regex. Failures are part of the protocol: you return an error result and the model can reason about it and try again. And the model can ask for several tools in one turn, which you can run in parallel.&lt;/p&gt;

&lt;h2&gt;
  
  
  Setting Up: The SDK
&lt;/h2&gt;

&lt;p&gt;Since version 10, the &lt;code&gt;Anthropic&lt;/code&gt; package on NuGet is the official Claude SDK for C#, from &lt;code&gt;anthropics/anthropic-sdk-csharp&lt;/code&gt;. Versions 3.x and below of that package name were the community tryAGI SDK, which now lives at &lt;code&gt;tryAGI.Anthropic&lt;/code&gt;. If a project has an old &lt;code&gt;Anthropic&lt;/code&gt; reference, check which one it is before you copy any code, because the APIs are completely different.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;dotnet add package Anthropic
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The SDK models the API closely. Content blocks are union types (&lt;code&gt;ContentBlock&lt;/code&gt; wraps a &lt;code&gt;TextBlock&lt;/code&gt;, a &lt;code&gt;ToolUseBlock&lt;/code&gt; and so on, and you reach the concrete block through &lt;code&gt;.Value&lt;/code&gt;), and &lt;code&gt;MessageParam&lt;/code&gt; accepts a &lt;code&gt;UserMessageParam&lt;/code&gt; or an &lt;code&gt;AssistantMessageParam&lt;/code&gt;. That's more ceremony than a hand-written client, but the compiler tells you when you build a message the API would reject.&lt;/p&gt;

&lt;p&gt;You could use Semantic Kernel or Microsoft.Extensions.AI here instead. For learning the loop, or debugging a tool that isn't being called, it's worth being close to the wire first. Layering an abstraction on top is easy once you know what it sends.&lt;/p&gt;

&lt;h2&gt;
  
  
  Defining a Tool in C
&lt;/h2&gt;

&lt;p&gt;A tool has a name, a description and a JSON Schema for its input. The description isn't documentation for people. It's what the model reads to decide whether and when to call the tool, and vague descriptions lead to missed or wrong calls.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;getOrderTool&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;Tool&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;Name&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"get_order_details"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="n"&gt;Description&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"""
&lt;/span&gt;        &lt;span class="n"&gt;Retrieves&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;current&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;line&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;shipping&lt;/span&gt; &lt;span class="n"&gt;information&lt;/span&gt; &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;
        &lt;span class="n"&gt;specific&lt;/span&gt; &lt;span class="n"&gt;customer&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="n"&gt;Use&lt;/span&gt; &lt;span class="k"&gt;this&lt;/span&gt; &lt;span class="k"&gt;when&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;user&lt;/span&gt; &lt;span class="n"&gt;asks&lt;/span&gt; &lt;span class="n"&gt;about&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="n"&gt;status&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;delivery&lt;/span&gt; &lt;span class="n"&gt;dates&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;or&lt;/span&gt; &lt;span class="n"&gt;what&lt;/span&gt; &lt;span class="n"&gt;items&lt;/span&gt; &lt;span class="n"&gt;are&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="n"&gt;an&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;
        &lt;span class="s"&gt;""",
&lt;/span&gt;    &lt;span class="n"&gt;InputSchema&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;InputSchema&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;Properties&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;Dictionary&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;JsonElement&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s"&gt;"order_id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SerializeToElement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"string"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"The order identifier, e.g. ORD-20261234"&lt;/span&gt;
            &lt;span class="p"&gt;}),&lt;/span&gt;
            &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s"&gt;"include_line_items"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SerializeToElement&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="n"&gt;type&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"boolean"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;description&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"Whether to include individual line items in the response"&lt;/span&gt;
            &lt;span class="p"&gt;})&lt;/span&gt;
        &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="n"&gt;Required&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="s"&gt;"order_id"&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;MessageCreateParams.Tools&lt;/code&gt; takes a list of &lt;code&gt;ToolUnion&lt;/code&gt;, because the same list also holds Anthropic's built-in tools. A &lt;code&gt;Tool&lt;/code&gt; converts to it implicitly, so &lt;code&gt;[getOrderTool]&lt;/code&gt; works.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Agentic Loop in C
&lt;/h2&gt;

&lt;p&gt;The loop is simple in concept and easy to get wrong. The two common mistakes: handling only the first &lt;code&gt;tool_use&lt;/code&gt; block when the model asked for several, and sending the results back in separate messages. The API expects one user message that contains a &lt;code&gt;tool_result&lt;/code&gt; for every &lt;code&gt;tool_use&lt;/code&gt; id of the previous turn.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;System.Text.Json&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;Anthropic&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;Anthropic.Models.Messages&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AgentLoop&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;RunAgentLoopAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="n"&gt;AnthropicClient&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;userMessage&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;IReadOnlyList&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;ToolUnion&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;tools&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;Func&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;IReadOnlyDictionary&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;JsonElement&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;,&lt;/span&gt; &lt;span class="n"&gt;CancellationToken&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;dispatcher&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
        &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;messages&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;MessageParam&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;UserMessageParam&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Content&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;userMessage&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="p"&gt;};&lt;/span&gt;

        &lt;span class="k"&gt;const&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;maxTurns&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;10&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// guard against infinite loops&lt;/span&gt;
        &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;turn&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;turn&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;&lt;/span&gt; &lt;span class="n"&gt;maxTurns&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;turn&lt;/span&gt;&lt;span class="p"&gt;++)&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Messages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;MessageCreateParams&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="n"&gt;Model&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"claude-sonnet-5-5"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;MaxTokens&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;4096&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;Tools&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;tools&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;Messages&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;messages&lt;/span&gt;
            &lt;span class="p"&gt;},&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

            &lt;span class="c1"&gt;// Send the assistant turn back as it came, tool_use blocks included&lt;/span&gt;
            &lt;span class="n"&gt;messages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;AssistantMessageParam&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="n"&gt;Content&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Content&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ToParam&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;ToList&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
            &lt;span class="p"&gt;});&lt;/span&gt;

            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;StopReason&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;StopReason&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;EndTurn&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Concat&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Content&lt;/span&gt;
                    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;block&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OfType&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TextBlock&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;()&lt;/span&gt;
                    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;text&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Text&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
            &lt;span class="p"&gt;}&lt;/span&gt;

            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;StopReason&lt;/span&gt; &lt;span class="p"&gt;!=&lt;/span&gt; &lt;span class="n"&gt;StopReason&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ToolUse&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;InvalidOperationException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"Unexpected stop_reason: &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;StopReason&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

            &lt;span class="c1"&gt;// Fan-out: execute all tool_use blocks in parallel&lt;/span&gt;
            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;toolUseBlocks&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Content&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;block&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Value&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OfType&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;ToolUseBlock&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;()&lt;/span&gt;
                &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToList&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;resultTasks&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;toolUseBlocks&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="k"&gt;try&lt;/span&gt;
                &lt;span class="p"&gt;{&lt;/span&gt;
                    &lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;var&lt;/span&gt; &lt;span class="n"&gt;cts&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;CancellationTokenSource&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CreateLinkedTokenSource&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
                    &lt;span class="n"&gt;cts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CancelAfter&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;TimeSpan&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromSeconds&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;30&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt; &lt;span class="c1"&gt;// per-tool timeout&lt;/span&gt;

                    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;dispatcher&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cts&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Token&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
                    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;ToolResultBlockParam&lt;/span&gt;
                    &lt;span class="p"&gt;{&lt;/span&gt;
                        &lt;span class="n"&gt;ToolUseID&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ID&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                        &lt;span class="n"&gt;Content&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Serialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                    &lt;span class="p"&gt;};&lt;/span&gt;
                &lt;span class="p"&gt;}&lt;/span&gt;
                &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Exception&lt;/span&gt; &lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;{&lt;/span&gt;
                    &lt;span class="c1"&gt;// Return a structured error, do NOT throw, let the model recover&lt;/span&gt;
                    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;ToolResultBlockParam&lt;/span&gt;
                    &lt;span class="p"&gt;{&lt;/span&gt;
                        &lt;span class="n"&gt;ToolUseID&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ID&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                        &lt;span class="n"&gt;Content&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Serialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Message&lt;/span&gt; &lt;span class="p"&gt;}),&lt;/span&gt;
                        &lt;span class="n"&gt;IsError&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt;
                    &lt;span class="p"&gt;};&lt;/span&gt;
                &lt;span class="p"&gt;}&lt;/span&gt;
            &lt;span class="p"&gt;});&lt;/span&gt;

            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;toolResults&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;WhenAll&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;resultTasks&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

            &lt;span class="c1"&gt;// All results go back in one user message, one block per tool_use id&lt;/span&gt;
            &lt;span class="n"&gt;messages&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;UserMessageParam&lt;/span&gt;
            &lt;span class="p"&gt;{&lt;/span&gt;
                &lt;span class="n"&gt;Content&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;toolResults&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ContentBlockParam&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;ToList&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
            &lt;span class="p"&gt;});&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;

        &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;InvalidOperationException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Agent exceeded maximum turn limit without reaching end_turn."&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="n"&gt;ContentBlockParam&lt;/span&gt; &lt;span class="nf"&gt;ToParam&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ContentBlock&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Value&lt;/span&gt; &lt;span class="k"&gt;switch&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;TextBlock&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;TextBlockParam&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;Text&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;text&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Text&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="n"&gt;ToolUseBlock&lt;/span&gt; &lt;span class="n"&gt;use&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;ToolUseBlockParam&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;ID&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;use&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ID&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Name&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;use&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Input&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;use&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Input&lt;/span&gt; &lt;span class="p"&gt;},&lt;/span&gt;
        &lt;span class="n"&gt;_&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;NotSupportedException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"Block type &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;block&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Value&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;GetType&lt;/span&gt;&lt;span class="p"&gt;().&lt;/span&gt;&lt;span class="n"&gt;Name&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt; is not sent back here"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;A few details that matter:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;The assistant turn goes back in the history.&lt;/strong&gt; The response is a &lt;code&gt;Message&lt;/code&gt; with &lt;code&gt;ContentBlock&lt;/code&gt;s, but the request needs &lt;code&gt;ContentBlockParam&lt;/code&gt;s, so &lt;code&gt;ToParam&lt;/code&gt; converts the text and &lt;code&gt;tool_use&lt;/code&gt; blocks. Without them, the &lt;code&gt;tool_result&lt;/code&gt; ids in the next message refer to calls the API has never seen. If you turn on extended thinking, the thinking blocks have to go back as well, and &lt;code&gt;ToParam&lt;/code&gt; needs a case for them.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The error JSON is serialized, not concatenated.&lt;/strong&gt; An exception message with a quote in it would otherwise produce invalid JSON in the tool result.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The per-tool timeout&lt;/strong&gt; uses a linked &lt;code&gt;CancellationTokenSource&lt;/code&gt;. A tool that hangs, because a downstream API is slow or a query has no index, would otherwise block the whole turn.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;We ran this loop against a local server that answered in the Messages API format: a first response with two &lt;code&gt;tool_use&lt;/code&gt; blocks, one for &lt;code&gt;get_order_details&lt;/code&gt; and one for a tool that doesn't exist, then an &lt;code&gt;end_turn&lt;/code&gt;. The second request carried the assistant turn with both &lt;code&gt;tool_use&lt;/code&gt; blocks, followed by one user message with two &lt;code&gt;tool_result&lt;/code&gt; blocks. The unknown tool came back with &lt;code&gt;"is_error": true&lt;/code&gt; instead of crashing the loop.&lt;/p&gt;

&lt;h2&gt;
  
  
  Doing It Well: Validation, Errors, and Idempotency
&lt;/h2&gt;

&lt;p&gt;The model follows your schema well, but the input is still untrusted. Validate &lt;code&gt;order_id&lt;/code&gt; before it reaches the database, and apply a default when an optional field like &lt;code&gt;include_line_items&lt;/code&gt; is missing.&lt;/p&gt;

&lt;p&gt;When something goes wrong, return a result the model can reason about: &lt;code&gt;"Order ORD-99999999 not found"&lt;/code&gt; is actionable, &lt;code&gt;"NullReferenceException at line 42"&lt;/code&gt; isn't. The model will often retry with corrected arguments or explain the failure to the user.&lt;/p&gt;

&lt;p&gt;Idempotency matters as soon as you have write tools. If the model retries &lt;code&gt;cancel_order&lt;/code&gt; because a timeout made the first result unclear, the handler has to be safe to call twice. Design write tools with idempotency keys or check-then-act semantics from the start. Retrofitting that is painful.&lt;/p&gt;

&lt;h2&gt;
  
  
  Real Tools: Querying a Database
&lt;/h2&gt;

&lt;p&gt;Here's a dispatcher that routes tool names to typed handlers, including an EF Core query:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;OrderToolDispatcher&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;OrderDbContext&lt;/span&gt; &lt;span class="n"&gt;_db&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;ILogger&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;OrderToolDispatcher&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;_logger&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nf"&gt;OrderToolDispatcher&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;OrderDbContext&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ILogger&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;OrderToolDispatcher&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;_db&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="n"&gt;_logger&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;logger&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;DispatchAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;toolName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;IReadOnlyDictionary&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;JsonElement&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;_logger&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;LogInformation&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Executing tool {ToolName} with input {Input}"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;toolName&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;JsonSerializer&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Serialize&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;

        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;toolName&lt;/span&gt; &lt;span class="k"&gt;switch&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="s"&gt;"get_order_details"&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;GetOrderDetailsAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
                &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;TryGetValue&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"order_id"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;out&lt;/span&gt; &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetString&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt; &lt;span class="p"&gt;??&lt;/span&gt; &lt;span class="s"&gt;""&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;""&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;input&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;TryGetValue&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"include_line_items"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;out&lt;/span&gt; &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;ilv&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                    &lt;span class="p"&gt;&amp;amp;&amp;amp;&lt;/span&gt; &lt;span class="n"&gt;ilv&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ValueKind&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;JsonValueKind&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;True&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
                &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
            &lt;span class="n"&gt;_&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;NotSupportedException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"Unknown tool: &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;toolName&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;};&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;object&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;GetOrderDetailsAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
        &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;bool&lt;/span&gt; &lt;span class="n"&gt;includeLineItems&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(!&lt;/span&gt;&lt;span class="n"&gt;Regex&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;IsMatch&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s"&gt;@"^ORD-\d{8}$"&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"Invalid order_id format. Expected ORD- followed by 8 digits."&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;

        &lt;span class="n"&gt;IQueryable&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Order&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;query&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;_db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Orders&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AsNoTracking&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;includeLineItems&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="n"&gt;query&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Include&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LineItems&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;query&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FirstOrDefaultAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;o&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;o&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OrderId&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;order&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;$"Order &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;orderId&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt; not found."&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;

        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;order_id&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;OrderId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;status&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToString&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
            &lt;span class="n"&gt;estimated_delivery&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;EstimatedDelivery&lt;/span&gt;&lt;span class="p"&gt;?.&lt;/span&gt;&lt;span class="nf"&gt;ToString&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"yyyy-MM-dd"&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
            &lt;span class="n"&gt;line_items&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;includeLineItems&lt;/span&gt;
                &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;order&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;LineItems&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Select&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;li&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;li&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Sku&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;li&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Quantity&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;li&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UnitPrice&lt;/span&gt; &lt;span class="p"&gt;})&lt;/span&gt;
                &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;
        &lt;span class="p"&gt;};&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Two things in it are easy to get wrong:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;A conditional &lt;code&gt;Include&lt;/code&gt; has to be built outside the lambda.&lt;/strong&gt; &lt;code&gt;Include(o =&amp;gt; includeLineItems ? o.LineItems : null)&lt;/code&gt; looks reasonable and compiles, but EF Core throws &lt;code&gt;InvalidOperationException&lt;/code&gt; at runtime, because the include path must be a plain navigation. Add the &lt;code&gt;Include&lt;/code&gt; to the query only when you need it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;&lt;code&gt;input&lt;/code&gt; is a dictionary of &lt;code&gt;JsonElement&lt;/code&gt;.&lt;/strong&gt; That's what the SDK's &lt;code&gt;ToolUseBlock.Input&lt;/code&gt; gives you. Read optional fields with &lt;code&gt;TryGetValue&lt;/code&gt;, and check &lt;code&gt;ValueKind&lt;/code&gt; instead of calling &lt;code&gt;GetBoolean()&lt;/code&gt;, which throws if the model sent the value as a string.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Return anonymous objects or DTOs, which serialize cleanly. Don't leak entity graphs or stack traces into tool results.&lt;/p&gt;

&lt;h2&gt;
  
  
  Safety and Production Concerns
&lt;/h2&gt;

&lt;p&gt;&lt;strong&gt;Least-privilege tools.&lt;/strong&gt; Each tool should do one thing with only the permissions it needs. A read-only &lt;code&gt;get_order_details&lt;/code&gt; tool should connect with a read-only database credential. Don't give a query tool a connection string that can write.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Authentication.&lt;/strong&gt; Tools run in the context of your application, not the user's session. If your internal API needs a service token, inject it through DI when the tool is registered, and never let it flow through the tool schema or the conversation.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Log every dispatch.&lt;/strong&gt; You need to know which tools the model called, with which inputs, how long they took and whether they succeeded. Structure those logs (tool name, duration, success or error) so you can alert on anomalies.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Cost.&lt;/strong&gt; Every tool result goes back into the context window. A tool that returns 50 KB of JSON burns tokens on every later turn. Return the minimum useful data, and if the full result is large, offer a summary tool and a detail tool the model can call selectively.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Human approval for risky actions.&lt;/strong&gt; For any tool that sends an email, charges a card, cancels an order or changes production data, put a human in the loop. A practical pattern: the tool returns &lt;code&gt;{"status": "pending_approval", "approval_id": "..."}&lt;/code&gt;, the agent tells the user, and the action only runs after someone confirms.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;Show the model good inputs.&lt;/strong&gt; The SDK's &lt;code&gt;Tool&lt;/code&gt; type also has an &lt;code&gt;InputExamples&lt;/code&gt; property, where you can give a few realistic argument sets. For tools with a strict format, like the &lt;code&gt;ORD-&lt;/code&gt; ids here, that's a way to show the format instead of only describing it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Wrapping Up
&lt;/h2&gt;

&lt;p&gt;Building real agentic .NET applications is engineering, not magic. The pieces that get you to a production-ready agent are the ones in this article: the official &lt;code&gt;Anthropic&lt;/code&gt; SDK, a tool schema written for the model, a bounded loop that returns every result in one message, structured error results, per-tool timeouts and handlers that are safe to call twice. The rest is domain work: which tools your system actually needs to expose, and which invariants they have to keep.&lt;/p&gt;

</description>
      <category>ai</category>
      <category>llm</category>
      <category>dotnet</category>
      <category>csharp</category>
    </item>
    <item>
      <title>PostgreSQL jsonb with EF Core 10: Mapping, Indexing and Querying Document Columns</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Sat, 24 Oct 2026 20:22:04 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/postgresql-jsonb-with-ef-core-10-mapping-indexing-and-querying-document-columns-2no6</link>
      <guid>https://dev.to/mehdimohseni82/postgresql-jsonb-with-ef-core-10-mapping-indexing-and-querying-document-columns-2no6</guid>
      <description>&lt;h2&gt;
  
  
  The Problem Worth Solving
&lt;/h2&gt;

&lt;p&gt;You have a &lt;code&gt;Product&lt;/code&gt; entity with fifteen optional specification fields. Half of them are null for most rows. Adding a new field means a migration. Querying by any combination of them means either a bloated WHERE clause or an EAV table that turns into a JOIN nightmare. PostgreSQL's &lt;code&gt;jsonb&lt;/code&gt; column exists for exactly this case, and EF Core 10 with &lt;code&gt;Npgsql.EntityFrameworkCore.PostgreSQL&lt;/code&gt; 10 maps it as a real part of the model.&lt;/p&gt;

&lt;p&gt;This article covers the mapping, what LINQ translates to, which indexes the planner actually uses, and when a &lt;code&gt;jsonb&lt;/code&gt; column beats a separate table. Every snippet here was run against PostgreSQL 18 with &lt;code&gt;Npgsql.EntityFrameworkCore.PostgreSQL&lt;/code&gt; 10.0.3, and a few things that look obvious turned out not to work. Those are called out where they come up.&lt;/p&gt;




&lt;h2&gt;
  
  
  Mapping: Complex Types with &lt;code&gt;ToJson()&lt;/code&gt;
&lt;/h2&gt;

&lt;p&gt;In EF Core 10 the recommended approach is to map a .NET complex type to a &lt;code&gt;jsonb&lt;/code&gt; column with &lt;code&gt;ComplexProperty(...).ToJson()&lt;/code&gt;. EF knows the structure of the document, so it can translate property access in LINQ into PostgreSQL JSON operators and it tracks changes to the document.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Domain types&lt;/span&gt;
&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;ProductSpecs&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;CPU&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;RamGB&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;FormFactor&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;decimal&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;WeightKg&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;Product&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Name&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;!;&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;decimal&lt;/span&gt; &lt;span class="n"&gt;Price&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Category&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;!;&lt;/span&gt;  &lt;span class="c1"&gt;// normalised column, queried constantly&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="n"&gt;ProductSpecs&lt;/span&gt; &lt;span class="n"&gt;Specs&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;!;&lt;/span&gt; &lt;span class="c1"&gt;// goes into jsonb&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="c1"&gt;// DbContext configuration&lt;/span&gt;
&lt;span class="k"&gt;protected&lt;/span&gt; &lt;span class="k"&gt;override&lt;/span&gt; &lt;span class="k"&gt;void&lt;/span&gt; &lt;span class="nf"&gt;OnModelCreating&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ModelBuilder&lt;/span&gt; &lt;span class="n"&gt;modelBuilder&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;modelBuilder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Entity&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;Product&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;(&lt;/span&gt;&lt;span class="n"&gt;b&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToTable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"products"&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Property&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Category&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="nf"&gt;HasMaxLength&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;100&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

        &lt;span class="c1"&gt;// Emits: specs jsonb NOT NULL&lt;/span&gt;
        &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ComplexProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Specs&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;cp&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;cp&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToJson&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"specs"&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
    &lt;span class="p"&gt;});&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Pass the column name to &lt;code&gt;ToJson&lt;/code&gt;. Without it, the column is called &lt;code&gt;"Specs"&lt;/code&gt;, with a capital letter and quotes, and every piece of raw SQL you write later has to quote it. With &lt;code&gt;ToJson("specs")&lt;/code&gt; the generated table has a plain &lt;code&gt;specs jsonb NOT NULL&lt;/code&gt; column.&lt;/p&gt;

&lt;p&gt;Before EF Core 10, the same thing was done with owned entities (&lt;code&gt;OwnsOne(p =&amp;gt; p.Specs, o =&amp;gt; o.ToJson())&lt;/code&gt;), which had rough edges around identity and required navigations. Before EF 8, the Npgsql provider had its own POCO mapping that handed the column straight to &lt;code&gt;System.Text.Json&lt;/code&gt;, so EF knew nothing about the document. On a current stack, use complex types.&lt;/p&gt;




&lt;h2&gt;
  
  
  What LINQ Translates To
&lt;/h2&gt;

&lt;p&gt;Property access on the complex type is translated to the &lt;code&gt;-&amp;gt;&amp;gt;&lt;/code&gt; operator, with a cast when the property isn't a string:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;LINQ expression&lt;/th&gt;
&lt;th&gt;Generated SQL&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;p.Specs.CPU == "Intel i9"&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;p.specs -&amp;gt;&amp;gt; 'CPU' = 'Intel i9'&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;&lt;code&gt;p.Specs.RamGB &amp;gt; 16&lt;/code&gt;&lt;/td&gt;
&lt;td&gt;&lt;code&gt;CAST(p.specs -&amp;gt;&amp;gt; 'RamGB' AS integer) &amp;gt; 16&lt;/code&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;That's convenient, and it matters for indexing, which is the next section.&lt;/p&gt;

&lt;p&gt;What doesn't translate is the containment and existence family. &lt;code&gt;EF.Functions.JsonContains&lt;/code&gt;, &lt;code&gt;JsonExists&lt;/code&gt; and &lt;code&gt;JsonExistAny&lt;/code&gt; work on columns mapped as a string or a &lt;code&gt;JsonDocument&lt;/code&gt;, but on a complex type mapped with &lt;code&gt;ToJson()&lt;/code&gt;, EF 10 throws "could not be translated". For those operators, write the condition in SQL with &lt;code&gt;FromSql&lt;/code&gt; and keep composing in LINQ:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="c1"&gt;// Containment and existence: raw SQL over the mapped entity&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;cpu&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;"""{"&lt;/span&gt;&lt;span class="n"&gt;CPU&lt;/span&gt;&lt;span class="s"&gt;": "&lt;/span&gt;&lt;span class="n"&gt;Intel&lt;/span&gt; &lt;span class="n"&gt;i9&lt;/span&gt;&lt;span class="s"&gt;"}"""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;highEnd&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Products&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromSql&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"SELECT * FROM products WHERE specs @&amp;gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;cpu&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;::jsonb"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToListAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="c1"&gt;// FromSql composes with LINQ: EF wraps the raw SQL as a subquery&lt;/span&gt;
&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;cheapHighEnd&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Products&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromSql&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;$"SELECT * FROM products WHERE specs @&amp;gt; &lt;/span&gt;&lt;span class="p"&gt;{&lt;/span&gt;&lt;span class="n"&gt;cpu&lt;/span&gt;&lt;span class="p"&gt;}&lt;/span&gt;&lt;span class="s"&gt;::jsonb"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Price&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;&lt;/span&gt; &lt;span class="m"&gt;2500&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;OrderBy&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Price&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToListAsync&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The interpolated &lt;code&gt;{cpu}&lt;/code&gt; becomes a parameter, not string concatenation, so this is safe.&lt;/p&gt;

&lt;p&gt;One trap with existence checks: EF writes every property of the record into the document, including the null ones. A product with no form factor is stored as &lt;code&gt;{"FormFactor": null, ...}&lt;/code&gt;, so &lt;code&gt;specs ? 'FormFactor'&lt;/code&gt; is true for every row. If you mean "has a value", test the value:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="o"&gt;*&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;products&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;specs&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&amp;gt;&lt;/span&gt;&lt;span class="s1"&gt;'FormFactor'&lt;/span&gt; &lt;span class="k"&gt;IS&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;






&lt;h2&gt;
  
  
  Indexing: The Part Most Teams Get Wrong
&lt;/h2&gt;

&lt;p&gt;EF Core doesn't create any index on a JSON column for you, and you can't add one through the model either. &lt;code&gt;b.HasIndex(p =&amp;gt; p.Specs)&lt;/code&gt; fails when the model is built, because &lt;code&gt;Specs&lt;/code&gt; is a complex property. Create the indexes in a migration with &lt;code&gt;migrationBuilder.Sql(...)&lt;/code&gt;.&lt;/p&gt;

&lt;h3&gt;
  
  
  GIN with &lt;code&gt;jsonb_ops&lt;/code&gt; (Default)
&lt;/h3&gt;

&lt;p&gt;Supports &lt;code&gt;@&amp;gt;&lt;/code&gt;, &lt;code&gt;?&lt;/code&gt;, &lt;code&gt;?|&lt;/code&gt; and &lt;code&gt;?&amp;amp;&lt;/code&gt;. The general-purpose choice when you query many different keys with those operators.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_product_specs_gin&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;products&lt;/span&gt; &lt;span class="k"&gt;USING&lt;/span&gt; &lt;span class="n"&gt;gin&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;specs&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  GIN with &lt;code&gt;jsonb_path_ops&lt;/code&gt;
&lt;/h3&gt;

&lt;p&gt;For workloads that are almost all containment (&lt;code&gt;@&amp;gt;&lt;/code&gt;), &lt;code&gt;jsonb_path_ops&lt;/code&gt; gives a smaller and faster index than the default. It doesn't support the existence operators (&lt;code&gt;?&lt;/code&gt;, &lt;code&gt;?|&lt;/code&gt;, &lt;code&gt;?&amp;amp;&lt;/code&gt;).&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_product_specs_pathops&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;products&lt;/span&gt;
    &lt;span class="k"&gt;USING&lt;/span&gt; &lt;span class="n"&gt;gin&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;specs&lt;/span&gt; &lt;span class="n"&gt;jsonb_path_ops&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h3&gt;
  
  
  Expression B-Tree for What LINQ Generates
&lt;/h3&gt;

&lt;p&gt;Here is the catch: a GIN index only serves the containment and existence operators. The &lt;code&gt;-&amp;gt;&amp;gt;&lt;/code&gt; comparisons that LINQ generates can't use it. We checked the plans with sequential scans disabled: &lt;code&gt;specs @&amp;gt; '{"CPU": "Intel i9"}'&lt;/code&gt; used the GIN index, while EF's &lt;code&gt;p.Specs.CPU == "Intel i9"&lt;/code&gt; still had no index to use.&lt;/p&gt;

&lt;p&gt;For a field you filter on through LINQ, create an expression index that matches the generated SQL. Note the three parentheses: one pair for the index column list and one around the expression, because a cast isn't allowed bare there.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;idx_product_ram&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;products&lt;/span&gt;
    &lt;span class="p"&gt;(((&lt;/span&gt;&lt;span class="n"&gt;specs&lt;/span&gt;&lt;span class="o"&gt;-&amp;gt;&amp;gt;&lt;/span&gt;&lt;span class="s1"&gt;'RamGB'&lt;/span&gt;&lt;span class="p"&gt;)::&lt;/span&gt;&lt;span class="nb"&gt;integer&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;With this index, the LINQ query &lt;code&gt;p.Specs.RamGB &amp;gt; 16&lt;/code&gt; uses an index scan on &lt;code&gt;idx_product_ram&lt;/code&gt;. The same kind of index on &lt;code&gt;(specs-&amp;gt;&amp;gt;'CPU')&lt;/code&gt; serves the equality query.&lt;/p&gt;

&lt;p&gt;PostgreSQL 18 makes virtual generated columns the default, which looks like a neat way to expose a JSON field as a column. They can't be indexed, though: &lt;code&gt;CREATE INDEX&lt;/code&gt; on one fails with "indexes on virtual generated columns are not supported". For an indexed field, stay with the expression index or use a &lt;code&gt;STORED&lt;/code&gt; generated column.&lt;/p&gt;




&lt;h2&gt;
  
  
  When &lt;code&gt;jsonb&lt;/code&gt; Beats a Separate Table
&lt;/h2&gt;

&lt;p&gt;The right mental model is the &lt;strong&gt;hybrid&lt;/strong&gt;: core fields that appear in most queries stay as typed, normalized columns, and the flexible remainder goes into &lt;code&gt;jsonb&lt;/code&gt;. &lt;code&gt;Category&lt;/code&gt; and &lt;code&gt;Price&lt;/code&gt; on &lt;code&gt;Product&lt;/code&gt; are normalized because every product-list query filters or sorts on them. &lt;code&gt;Specs&lt;/code&gt; is &lt;code&gt;jsonb&lt;/code&gt; because it's sparse, varies by category and changes without schema migrations.&lt;/p&gt;

&lt;p&gt;&lt;code&gt;jsonb&lt;/code&gt; wins when:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Keys are sparse or optional across rows.&lt;/strong&gt; Per-tenant custom fields in a B2B SaaS product are the classic example. Adding a new custom field is a data change, not a migration.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The main access pattern is containment or existence&lt;/strong&gt;, not aggregation. &lt;code&gt;SUM((specs-&amp;gt;&amp;gt;'WeightKg')::numeric)&lt;/code&gt; across millions of rows isn't what &lt;code&gt;jsonb&lt;/code&gt; is built for.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The shape changes independently of the core schema.&lt;/strong&gt; Event payloads, product specifications by category, configuration blobs.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;You want to avoid an EAV table.&lt;/strong&gt; An EAV table with a string-typed value column loses type safety, makes multi-key filters ugly and is often slower than a GIN-indexed &lt;code&gt;jsonb&lt;/code&gt; column for the same access pattern.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;&lt;code&gt;jsonb&lt;/code&gt; loses when a field appears in most queries in a typed, comparable way. If most of your queries filter on &lt;code&gt;specs-&amp;gt;&amp;gt;'Status'&lt;/code&gt;, promote &lt;code&gt;Status&lt;/code&gt; to a proper column.&lt;/p&gt;




&lt;h2&gt;
  
  
  Updates: Whole Document or One Property
&lt;/h2&gt;

&lt;p&gt;&lt;code&gt;SaveChanges&lt;/code&gt; writes the whole document. With an immutable record like &lt;code&gt;ProductSpecs&lt;/code&gt;, changing one value means assigning a new record (&lt;code&gt;p.Specs = p.Specs with { RamGB = 12 }&lt;/code&gt;), and EF sends &lt;code&gt;UPDATE products SET specs = @p0&lt;/code&gt;. For small documents that's fine.&lt;/p&gt;

&lt;p&gt;For a targeted change, EF Core 10 translates &lt;code&gt;ExecuteUpdate&lt;/code&gt; on a property inside the document into &lt;code&gt;jsonb_set&lt;/code&gt;, without loading the row:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;db&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Products&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Where&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Id&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;productId&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ExecuteUpdateAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;s&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;s&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SetProperty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Specs&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;RamGB&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;32&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The SQL it sends:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;UPDATE&lt;/span&gt; &lt;span class="n"&gt;products&lt;/span&gt; &lt;span class="k"&gt;AS&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;
&lt;span class="k"&gt;SET&lt;/span&gt; &lt;span class="n"&gt;specs&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;jsonb_set&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;specs&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s1"&gt;'{RamGB}'&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;to_jsonb&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
&lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;p&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nv"&gt;"Id"&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;productId&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The other properties of the document are left as they were.&lt;/p&gt;




&lt;h2&gt;
  
  
  Practical Checklist
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;Use &lt;code&gt;Npgsql.EntityFrameworkCore.PostgreSQL&lt;/code&gt; 10 with EF Core 10, and map the document with &lt;code&gt;ComplexProperty(...).ToJson("specs")&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Give the column a lowercase name in &lt;code&gt;ToJson&lt;/code&gt;, or every raw SQL statement has to quote it.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;EF.Functions.JsonContains&lt;/code&gt; and its relatives don't translate on a complex type. Use &lt;code&gt;FromSql&lt;/code&gt; for &lt;code&gt;@&amp;gt;&lt;/code&gt; and &lt;code&gt;?&lt;/code&gt;, and compose LINQ on top.&lt;/li&gt;
&lt;li&gt;Test values with &lt;code&gt;-&amp;gt;&amp;gt; ... IS NOT NULL&lt;/code&gt;, because &lt;code&gt;?&lt;/code&gt; also matches keys stored as null.&lt;/li&gt;
&lt;li&gt;Create indexes in a migration with &lt;code&gt;migrationBuilder.Sql&lt;/code&gt;. GIN serves &lt;code&gt;@&amp;gt;&lt;/code&gt; and &lt;code&gt;?&lt;/code&gt;, and expression B-tree indexes serve the &lt;code&gt;-&amp;gt;&amp;gt;&lt;/code&gt; comparisons that LINQ generates.&lt;/li&gt;
&lt;li&gt;Don't plan on indexing a virtual generated column in PostgreSQL 18. It isn't supported.&lt;/li&gt;
&lt;li&gt;Use &lt;code&gt;ExecuteUpdate&lt;/code&gt; with &lt;code&gt;SetProperty(p =&amp;gt; p.Specs.X, ...)&lt;/code&gt; for single-property changes. EF 10 turns it into &lt;code&gt;jsonb_set&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;Always prefer &lt;code&gt;jsonb&lt;/code&gt; over &lt;code&gt;json&lt;/code&gt;, because binary storage means no reparsing on read.&lt;/li&gt;
&lt;li&gt;Promote any field queried on most rows to a typed column. The hybrid model is the goal, not a pure document approach.&lt;/li&gt;
&lt;/ul&gt;

</description>
      <category>postgres</category>
      <category>dotnet</category>
      <category>efcore</category>
      <category>npgsql</category>
    </item>
    <item>
      <title>Relationships in a Relational Database: MySQL vs NebulaGraph from 1 Million to 500 Million Rows</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Fri, 23 Oct 2026 21:20:14 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/relationships-in-a-relational-database-mysql-vs-nebulagraph-from-1-million-to-500-million-rows-195</link>
      <guid>https://dev.to/mehdimohseni82/relationships-in-a-relational-database-mysql-vs-nebulagraph-from-1-million-to-500-million-rows-195</guid>
      <description>&lt;p&gt;About three years ago I started to build what was really a graph inside a relational database. My thinking at the time was quite simple: every connection between two nodes is a kind of many-to-many relationship, so if I have a table for the nodes and a table for the relationships between them, it should work. When we got to around 500 million rows, nodes and relationships together, the system completely collapsed. We were running it on the largest virtual machine we could get on AWS, which cost about 15 to 20 thousand dollars per month, and a simple query to find one relationship between two nodes was taking about 15 minutes.&lt;/p&gt;

&lt;p&gt;After that we moved to graph databases, first ArangoDB, then Neo4j, and now we are using NebulaGraph (I wrote about the move from ArangoDB to NebulaGraph in &lt;a href="https://dotnet-talk.com/blog/arangodb-to-nebula-graph-migration" rel="noopener noreferrer"&gt;an earlier article&lt;/a&gt;). The same kind of query now takes a few seconds, and at most 7 to 10 seconds, depending on how well the query is optimised.&lt;/p&gt;

&lt;p&gt;A story from production is not something you can check, so for this article I built a benchmark that anyone can run on their own machine: the same graph loaded into MySQL and into NebulaGraph, the same questions asked to both, and every answer compared before any timing is trusted. All of the code and the raw results are on GitHub: &lt;a href="https://github.com/MehdiMohseni82/graph-vs-relational-benchmark" rel="noopener noreferrer"&gt;MehdiMohseni82/graph-vs-relational-benchmark&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;The benchmark confirms part of that story, but it also separates two things that the story mixes together, and I think that difference is the most useful thing in this article.&lt;/p&gt;

&lt;h2&gt;
  
  
  The model most of us start with
&lt;/h2&gt;

&lt;p&gt;When a SQL developer models a graph, the first design is almost always the same, and it's the design I used three years ago. There is one table for the things, and one table for the relationships, where each row says that one node is connected to another node.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;nodes&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;id&lt;/span&gt;   &lt;span class="nb"&gt;BIGINT&lt;/span&gt;      &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt; &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="nb"&gt;VARCHAR&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="mi"&gt;32&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;ENGINE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;InnoDB&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;CREATE&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
  &lt;span class="n"&gt;src&lt;/span&gt; &lt;span class="nb"&gt;BIGINT&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="n"&gt;dst&lt;/span&gt; &lt;span class="nb"&gt;BIGINT&lt;/span&gt; &lt;span class="k"&gt;NOT&lt;/span&gt; &lt;span class="k"&gt;NULL&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
  &lt;span class="k"&gt;PRIMARY&lt;/span&gt; &lt;span class="k"&gt;KEY&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;src&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;dst&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;ENGINE&lt;/span&gt;&lt;span class="o"&gt;=&lt;/span&gt;&lt;span class="n"&gt;InnoDB&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;ALTER&lt;/span&gt; &lt;span class="k"&gt;TABLE&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="k"&gt;ADD&lt;/span&gt; &lt;span class="k"&gt;INDEX&lt;/span&gt; &lt;span class="n"&gt;ix_edges_dst_src&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;dst&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;src&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;This is not a bad design, and I want to be fair to it. In InnoDB the primary key is the clustered index, so all the relationships of one node are stored next to each other, and the reverse index &lt;code&gt;(dst, src)&lt;/code&gt; does the same for the other direction. Finding the direct neighbours of a node is one index lookup, and it is very fast. The problem doesn't start with one hop, it starts when the question needs many hops.&lt;/p&gt;

&lt;h2&gt;
  
  
  The questions
&lt;/h2&gt;

&lt;p&gt;The benchmark asks questions that are very common in real systems, for example in fraud detection, recommendations, access control or any knowledge graph. A relationship always counts in both directions.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;The relationship question:&lt;/strong&gt; are node A and node B related, and if yes, how many hops apart are they, up to 6 hops? This is the "simple relationship" query from my own story.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The neighbourhood question:&lt;/strong&gt; how many different nodes can be reached from this node in 1, 2, 3 or 4 hops?&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The neighbourhood without hubs:&lt;/strong&gt; the same question, but the search may never enter a hub, a node with more than 1,000 relationships. I added this one after looking at a real identity graph, where a few placeholder values are connected to almost everything, and every useful search has to walk around them.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;In MySQL 8 the natural way to ask a multi-hop question is a recursive CTE. This is the query for the neighbourhood question:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;WITH&lt;/span&gt; &lt;span class="k"&gt;RECURSIVE&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;depth&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;AS&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="k"&gt;start&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
    &lt;span class="k"&gt;UNION&lt;/span&gt;
    &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;dst&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="k"&gt;JOIN&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;src&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;hops&lt;/span&gt;
    &lt;span class="k"&gt;UNION&lt;/span&gt;
    &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;src&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="k"&gt;JOIN&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;dst&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;hops&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="k"&gt;COUNT&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;DISTINCT&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;&amp;gt;&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;And this is the query for the relationship question, which is almost the same:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;WITH&lt;/span&gt; &lt;span class="k"&gt;RECURSIVE&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;depth&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;AS&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="mi"&gt;0&lt;/span&gt;
    &lt;span class="k"&gt;UNION&lt;/span&gt;
    &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;dst&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="k"&gt;JOIN&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;src&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;maxHops&lt;/span&gt;
    &lt;span class="k"&gt;UNION&lt;/span&gt;
    &lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;src&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;+&lt;/span&gt; &lt;span class="mi"&gt;1&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt; &lt;span class="k"&gt;JOIN&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt; &lt;span class="k"&gt;ON&lt;/span&gt; &lt;span class="n"&gt;e&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;dst&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;r&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt; &lt;span class="o"&gt;&amp;lt;&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;maxHops&lt;/span&gt;
&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="k"&gt;MIN&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;depth&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;reach&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;id&lt;/span&gt; &lt;span class="o"&gt;=&lt;/span&gt; &lt;span class="o"&gt;@&lt;/span&gt;&lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;In NebulaGraph the first two questions are written in nGQL, and they are much shorter, because traversal is the main job of the language:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight plaintext"&gt;&lt;code&gt;GO 1 TO 4 STEPS FROM 42 OVER related BIDIRECT YIELD DISTINCT id($$) AS v | YIELD COUNT(*) AS n;

FIND SINGLE SHORTEST PATH FROM 42 TO 1337 OVER related BIDIRECT UPTO 6 STEPS YIELD path AS p | YIELD length($-.p) AS len;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;h2&gt;
  
  
  Why the recursive CTE gets so expensive
&lt;/h2&gt;

&lt;p&gt;It's important to understand what the CTE actually does, because the reason is not that MySQL is slow. Every recursive step joins the whole result of the previous step with the edges table again, twice, once for each direction. &lt;code&gt;UNION&lt;/code&gt; removes duplicate rows, but a row here is the pair &lt;code&gt;(id, depth)&lt;/code&gt;, not the node alone. That means a node that was reached at depth 2 is reached again at depth 4, because you can walk to a neighbour and come straight back, and every time it is expanded again. The CTE has no memory of "I have already visited this node", it only knows "I have not produced this exact row yet".&lt;/p&gt;

&lt;p&gt;The relationship question has a second problem, which is even bigger. A recursive CTE cannot stop when it finds B. It first builds every node within 6 hops of A, at every depth, and only after that the outer &lt;code&gt;SELECT&lt;/code&gt; looks for B in the result. So the cost of the question "are these two nodes related?" does not depend on how close they are, it depends on how big the neighbourhood of A is.&lt;/p&gt;

&lt;h2&gt;
  
  
  The third method: a breadth-first search in C
&lt;/h2&gt;

&lt;p&gt;I also added a third method, because I think it is the most honest comparison. It is the solution that a good SQL developer would build after the CTE becomes too slow: keep the same MySQL tables, but do the breadth-first search in C#, one level at a time, with a &lt;code&gt;HashSet&lt;/code&gt; of visited nodes and a bidirectional search for the shortest path.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt;&lt;span class="p"&gt;?&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;ShortestPathAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;long&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;maxHops&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;TimeSpan&lt;/span&gt; &lt;span class="n"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;a&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;deadline&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;DateTime&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;UtcNow&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt; &lt;span class="n"&gt;timeout&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;seenFromA&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;HashSet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;seenFromB&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;HashSet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;frontierA&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;a&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;
    &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;frontierB&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="n"&gt;b&lt;/span&gt; &lt;span class="p"&gt;};&lt;/span&gt;

    &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;length&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="n"&gt;maxHops&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="n"&gt;length&lt;/span&gt;&lt;span class="p"&gt;++)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;bool&lt;/span&gt; &lt;span class="n"&gt;expandA&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;frontierA&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Count&lt;/span&gt; &lt;span class="p"&gt;&amp;lt;=&lt;/span&gt; &lt;span class="n"&gt;frontierB&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Count&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;frontier&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;seen&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;other&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;expandA&lt;/span&gt;
            &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;frontierA&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;seenFromA&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;seenFromB&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;frontierB&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;seenFromB&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;seenFromA&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;frontier&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Count&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;next&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;long&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;();&lt;/span&gt;
        &lt;span class="k"&gt;foreach&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;neighbour&lt;/span&gt; &lt;span class="k"&gt;in&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="nf"&gt;NeighboursAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;frontier&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;deadline&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Queries&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;MySqlNeighboursOf&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;other&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Contains&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;neighbour&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;length&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
            &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;seen&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;neighbour&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt; &lt;span class="n"&gt;next&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Add&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;neighbour&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;expandA&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="n"&gt;frontierA&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;next&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;else&lt;/span&gt; &lt;span class="n"&gt;frontierB&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;next&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;NeighboursAsync&lt;/code&gt; sends the frontier to MySQL in batches of 2,000 ids and reads the neighbours in both directions with one query per batch:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight sql"&gt;&lt;code&gt;&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;dst&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;src&lt;/span&gt; &lt;span class="k"&gt;IN&lt;/span&gt; &lt;span class="p"&gt;({&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;})&lt;/span&gt;
&lt;span class="k"&gt;UNION&lt;/span&gt; &lt;span class="k"&gt;ALL&lt;/span&gt;
&lt;span class="k"&gt;SELECT&lt;/span&gt; &lt;span class="n"&gt;src&lt;/span&gt; &lt;span class="k"&gt;FROM&lt;/span&gt; &lt;span class="n"&gt;edges&lt;/span&gt; &lt;span class="k"&gt;WHERE&lt;/span&gt; &lt;span class="n"&gt;dst&lt;/span&gt; &lt;span class="k"&gt;IN&lt;/span&gt; &lt;span class="p"&gt;({&lt;/span&gt;&lt;span class="mi"&gt;0&lt;/span&gt;&lt;span class="p"&gt;});&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;For the third question the BFS uses the same query with one extra condition per direction, &lt;code&gt;NOT EXISTS (SELECT 1 FROM hubs h WHERE h.id = e.dst)&lt;/code&gt;, so MySQL never returns a hub. The CTE gets the same condition inside its recursion. The exact queries are in the repository.&lt;/p&gt;

&lt;h2&gt;
  
  
  The setup
&lt;/h2&gt;

&lt;p&gt;Everything runs in Docker on one machine, and the repository has a runbook and a script that runs one size from empty databases to the final table.&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Hardware:&lt;/strong&gt; Mac Studio, Apple M3 Ultra, 96 GB RAM. Docker had 80 GB of memory and 24 CPUs, and nothing else was running.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The same memory for both engines:&lt;/strong&gt; MySQL 8.4 in a 30 GB container with a 24 GB InnoDB buffer pool. NebulaGraph 3.8 with 30 GB in total: the storage service in a 24 GB container with a 16 GB RocksDB block cache, and the graph service in a 6 GB container. One storage node and 36 partitions.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Loading:&lt;/strong&gt; MySQL with &lt;code&gt;LOAD DATA INFILE&lt;/code&gt; and the reverse index built after the load. NebulaGraph with nebula-importer from exactly the same CSV files, followed by a compaction.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The data:&lt;/strong&gt; a deterministic generator in C#. Every node gets on average 9 relationships, and half of the targets come from a skewed distribution, so some nodes become hubs. The sizes are 1M, 10M, 100M and 500M rows, nodes and relationships together, which is the way I counted the rows in my own system.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The measurement:&lt;/strong&gt; 10 cases per question, one warm-up run and 3 measured runs, and the tables show the median. Half of the pairs for the relationship question are close to each other, the other half are two random nodes. The timeout is 15 minutes per query.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Validity:&lt;/strong&gt; after every size the run checks that no container was killed or restarted, that the kernel killed nothing for lack of memory, that no query returned an engine error, and that all methods returned the same answers. Every size passed.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  Results: the relationship question
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Size (rows)&lt;/th&gt;
&lt;th&gt;MySQL recursive CTE&lt;/th&gt;
&lt;th&gt;MySQL + BFS in C#&lt;/th&gt;
&lt;th&gt;NebulaGraph&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1M&lt;/td&gt;
&lt;td&gt;5.68 s&lt;/td&gt;
&lt;td&gt;1.1 ms&lt;/td&gt;
&lt;td&gt;2.1 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10M&lt;/td&gt;
&lt;td&gt;1.2 min&lt;/td&gt;
&lt;td&gt;1.6 ms&lt;/td&gt;
&lt;td&gt;18.7 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;100M&lt;/td&gt;
&lt;td&gt;9.7 min, 2 of 10 timed out&lt;/td&gt;
&lt;td&gt;1.5 ms&lt;/td&gt;
&lt;td&gt;8.6 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;500M&lt;/td&gt;
&lt;td&gt;no answer in 15 minutes (10 of 10)&lt;/td&gt;
&lt;td&gt;2.7 ms&lt;/td&gt;
&lt;td&gt;23.6 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;This is the result from my story. At 500 million rows the recursive CTE didn't answer a single one of the ten pairs within 15 minutes, while the other two methods answered in milliseconds. The pairs were between 2 and 6 hops apart, so this is not a question of a long path, it's the CTE building the whole 6-hop neighbourhood before it looks for B.&lt;/p&gt;

&lt;p&gt;But look at the other two columns. The bidirectional search in C#, on the same MySQL tables, was faster than NebulaGraph at every size. So for this question, the problem was not the relational database. It was the recursive CTE.&lt;/p&gt;

&lt;h2&gt;
  
  
  Results: the neighbourhood question
&lt;/h2&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Size (rows)&lt;/th&gt;
&lt;th&gt;MySQL recursive CTE&lt;/th&gt;
&lt;th&gt;MySQL + BFS in C#&lt;/th&gt;
&lt;th&gt;NebulaGraph&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;1M&lt;/td&gt;
&lt;td&gt;180 ms&lt;/td&gt;
&lt;td&gt;177 ms&lt;/td&gt;
&lt;td&gt;72.4 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;10M&lt;/td&gt;
&lt;td&gt;2.65 s&lt;/td&gt;
&lt;td&gt;508.5 ms&lt;/td&gt;
&lt;td&gt;288.1 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;100M&lt;/td&gt;
&lt;td&gt;10.61 s&lt;/td&gt;
&lt;td&gt;1.70 s&lt;/td&gt;
&lt;td&gt;1.13 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;500M&lt;/td&gt;
&lt;td&gt;3.18 s&lt;/td&gt;
&lt;td&gt;579.6 ms&lt;/td&gt;
&lt;td&gt;529.1 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;These are 4 hops. At 1, 2 and 3 hops all three methods answer in at most about 130 ms at every size, and at 1 and 2 hops in a few milliseconds or less.&lt;/p&gt;

&lt;p&gt;Two things are worth explaining here. First, NebulaGraph is the fastest at every size, but the BFS in C# is never far behind, between 1.1 and 2.4 times slower, and the CTE is between 2.5 and 9.4 times slower than NebulaGraph.&lt;/p&gt;

&lt;p&gt;Second, 500M is faster than 100M for every method, which looks wrong. It isn't: the time of this query depends on how many nodes it reaches, not on the size of the table. With 10 million nodes, the median start node reached 3.9 million nodes in 4 hops, but with 50 million nodes the median start node reached 2.3 million, because the same number of relationships is spread over five times more nodes. Less work, less time, for all three engines in the same way.&lt;/p&gt;

&lt;h2&gt;
  
  
  Results: a graph with hubs
&lt;/h2&gt;

&lt;p&gt;The graph above is friendly. Real graphs often have hubs, and in an identity graph a single placeholder value, like a default phone number, can be connected to hundreds of thousands of records. So I generated a second graph: 1 million nodes with on average 50 relationships, plus 20 hubs connected to about 630,000 nodes each. 904 nodes have more than 1,000 relationships. It's 63.5 million rows, and the timeout here is 5 minutes.&lt;/p&gt;

&lt;p&gt;The first thing this graph shows is why hubs matter: from a median start node, &lt;strong&gt;2 hops reach 999,991 of the 1,000,000 nodes&lt;/strong&gt;. Every search goes through a hub, and after that it has the whole graph.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Question&lt;/th&gt;
&lt;th&gt;MySQL recursive CTE&lt;/th&gt;
&lt;th&gt;MySQL + BFS in C#&lt;/th&gt;
&lt;th&gt;NebulaGraph&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;relationship, up to 6 hops&lt;/td&gt;
&lt;td&gt;no answer in 5 minutes (10 of 10)&lt;/td&gt;
&lt;td&gt;0.5 ms&lt;/td&gt;
&lt;td&gt;1.1 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;neighbourhood, 2 hops&lt;/td&gt;
&lt;td&gt;8.49 s&lt;/td&gt;
&lt;td&gt;1.07 s&lt;/td&gt;
&lt;td&gt;575.6 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;neighbourhood, 3 hops&lt;/td&gt;
&lt;td&gt;3.6 min&lt;/td&gt;
&lt;td&gt;20.58 s&lt;/td&gt;
&lt;td&gt;5.95 s&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;neighbourhood, 4 hops&lt;/td&gt;
&lt;td&gt;no answer in 5 minutes (10 of 10)&lt;/td&gt;
&lt;td&gt;20.59 s&lt;/td&gt;
&lt;td&gt;11.27 s&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Here the difference between the BFS in C# and NebulaGraph becomes real: when a query touches the whole graph, NebulaGraph is 1.8 to 3.5 times faster. The BFS has to pull every level of the search over the network into the application, batch by batch, and NebulaGraph does the same work next to the data.&lt;/p&gt;

&lt;p&gt;But nobody wants the whole graph. The useful question on this graph is the third one, the neighbourhood that walks around the hubs:&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Hops&lt;/th&gt;
&lt;th&gt;MySQL recursive CTE&lt;/th&gt;
&lt;th&gt;MySQL + BFS in C#&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;2&lt;/td&gt;
&lt;td&gt;6.8 ms&lt;/td&gt;
&lt;td&gt;5.5 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;3&lt;/td&gt;
&lt;td&gt;2.55 s&lt;/td&gt;
&lt;td&gt;479.6 ms&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;4&lt;/td&gt;
&lt;td&gt;2.6 min&lt;/td&gt;
&lt;td&gt;22.91 s&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;Avoiding the hubs, the median start node reaches about 12,000 nodes in 2 hops and 730,000 in 3 hops, so this is still a big search, but it is one the user actually asked for.&lt;/p&gt;

&lt;p&gt;This question shows the most about NebulaGraph, because I couldn't write it as one nGQL statement that is both correct and usable:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;code&gt;GO 1 TO 3 STEPS ... WHERE NOT "hub" IN tags($$)&lt;/code&gt; runs, but it returned more nodes than the SQL version. In our check on a small graph it found 5,821 nodes at 2 hops where the correct answer was 463, because the filter doesn't stop the walk from going through a hub.&lt;/li&gt;
&lt;li&gt;
&lt;code&gt;MATCH&lt;/code&gt; with a condition that no node on the path is a hub returns the correct answer, but it enumerates paths, and on a 20,000-node test graph the 4-hop version used up the 1 GB the graph service had in that test.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;What an application does in this case is to walk one &lt;code&gt;GO&lt;/code&gt; step per level from C# and remove the hubs between the levels. That is the same small graph engine in the application as the BFS on MySQL, just on top of a different database. I measured a version of it, but my implementation filtered the hubs with &lt;code&gt;WHERE NOT "hub" IN tags($$)&lt;/code&gt; in every step, which makes NebulaGraph read the tags of every destination node, and a version that filtered in C# was about twice as fast in a small test. Because I don't have a fair measurement of that approach at full size, I leave NebulaGraph out of this table rather than show a number that makes it look worse than it is.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the numbers say
&lt;/h2&gt;

&lt;p&gt;I think the honest summary has three parts.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;The recursive CTE is what breaks.&lt;/strong&gt; In every table it is the slowest method, from about 1.2 times slower on the smallest searches to several thousand times slower on the relationship question, and at 500M rows it didn't answer a single relationship question within 15 minutes. It can't remember visited nodes, can't search from both sides and can't stop early. The query in my story was this kind of relationship question, and the benchmark suggests that the way such a query is written matters at least as much as where the data lives.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A breadth-first search on MySQL is a real alternative, and for paths it was the fastest.&lt;/strong&gt; With the same tables and the same indexes, the BFS in C# answered the relationship question in under 3 milliseconds at every size, faster than NebulaGraph's &lt;code&gt;FIND SHORTEST PATH&lt;/code&gt;, and on the 4-hop neighbourhood it stayed within 2.4 times of NebulaGraph on the normal graph. On the hub-avoiding question it was more than five times faster than the CTE at 3 hops. But it's important to be clear what it is: you are writing a small graph engine inside your application, with the visited set, the frontier, the batching, the bidirectional search and the timeouts, and every new kind of question means more code.&lt;/p&gt;

&lt;p&gt;&lt;strong&gt;A graph database pays off when the traversal itself is big.&lt;/strong&gt; On the hub graph, when a query really had to walk a large part of the graph, NebulaGraph was 1.8 to 3.5 times faster than the BFS, because it does the work next to the data instead of pulling every level into the application. It also gives you a language where the first two questions are one line each. What it didn't give me, in this test, is a single statement for a traversal that has to avoid certain nodes, and that is exactly the kind of question real graphs need.&lt;/p&gt;

&lt;h2&gt;
  
  
  Limits of this benchmark
&lt;/h2&gt;

&lt;ul&gt;
&lt;li&gt;It runs on one machine with local disks and one NebulaGraph storage node. NebulaGraph is designed to spread partitions over many machines, and this test doesn't measure that at all. If your graph doesn't fit on one machine, that is a different question, and a benchmark on one machine can't answer it.&lt;/li&gt;
&lt;li&gt;The data is generated. It has the right shape (skewed degrees, hubs), but it is not production data with production query patterns and other traffic.&lt;/li&gt;
&lt;li&gt;The MySQL schema and queries are the common approach, not the only one. If you can make the relational side faster, a pull request with the numbers is very welcome.&lt;/li&gt;
&lt;/ul&gt;

&lt;h2&gt;
  
  
  When a relational database is still the right choice
&lt;/h2&gt;

&lt;p&gt;If your queries are one or two hops, for example "the orders of this customer" or "the members of this group", a relational database with the right indexes is very fast, much simpler to operate, and you already have it. In every table above, 1 and 2 hops on the normal graph stayed in the range of a few milliseconds for all three methods.&lt;/p&gt;

&lt;p&gt;In my view, the signal to look at a graph database is the shape of the questions, not the number of rows. When you start to write recursive CTEs, first replace them with a search in your application: in this benchmark that alone turned minutes into milliseconds. When the traversals become large, when the business keeps asking new kinds of graph questions, or when the graph grows beyond one machine, that's the point where a graph database earns its place.&lt;/p&gt;

&lt;h2&gt;
  
  
  Run it yourself
&lt;/h2&gt;

&lt;p&gt;The repository has everything needed to reproduce these numbers: the Docker Compose file for MySQL and NebulaGraph, the C# generator, the C# benchmark with all methods, the runbook with the validity checks, and the raw CSV of every single run.&lt;/p&gt;

&lt;p&gt;&lt;a href="https://github.com/MehdiMohseni82/graph-vs-relational-benchmark" rel="noopener noreferrer"&gt;github.com/MehdiMohseni82/graph-vs-relational-benchmark&lt;/a&gt;&lt;/p&gt;

</description>
      <category>graphdatabase</category>
      <category>dotnet</category>
      <category>mysql</category>
      <category>database</category>
    </item>
    <item>
      <title>Are Coding Agents Getting Worse, or Have They Lost Their Teachers?</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Tue, 20 Oct 2026 07:10:46 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/are-coding-agents-getting-worse-or-have-they-lost-their-teachers-52bh</link>
      <guid>https://dev.to/mehdimohseni82/are-coding-agents-getting-worse-or-have-they-lost-their-teachers-52bh</guid>
      <description>&lt;p&gt;When coding agents like Claude Code, Codex and Copilot's agent mode became part of the daily work of many teams, the first reactions were very positive, and a lot of developers were surprised how well an agent could add a feature to an existing project. Now, one or two years later, a different complaint is very common in discussions between developers: the code that the agents write seems to be getting worse. It has more duplication, the structure doesn't follow the architecture of the project, and fixes are added next to old code instead of improving it. The most popular explanation is that the models themselves are getting worse, because the vendors save money on compute, because of new safety restrictions, or because a newer model is simply less careful than the one before.&lt;/p&gt;

&lt;p&gt;In my view the model is not the main reason in most of these cases, and the real reason is closer to us. When teams started to use agents, almost all of the code in their repositories had been written by humans and had passed through quality gates like pull requests, peer review and static analysis tools such as SonarQube. The agent was working inside a codebase of reviewed code, and that code was the example it learned from while it worked. Over time, more and more of the codebase has been written by the agent itself, and in many teams with fewer of those gates, so the agent is now learning more and more from its own unreviewed output. In this article I want to look at what the research actually says about this, both the part that supports this view and the part that doesn't, and then at what a team can do about it.&lt;/p&gt;

&lt;h2&gt;
  
  
  First, is the code really getting worse?
&lt;/h2&gt;

&lt;p&gt;Before looking for a cause it's important to check if the effect is real, because developers are not always good at judging this from their own experience. The METR study from July 2025 is a good warning here: experienced open source developers expected AI tools to make them 24% faster, the measured result was that they took 19% longer, and after the study they still believed the tools had made them about 20% faster [14]. Our feeling about AI and productivity, and probably also about AI and quality, is not a reliable measurement.&lt;/p&gt;

&lt;p&gt;There are, however, several measurements that point in the same direction. GitClear analysed about 153 million changed lines of code from 2020 to 2023 and found that the share of "moved" lines, which is their signal for refactoring, dropped from 25.0% in 2020 to 16.9% in 2023, while copy/pasted lines grew from 8.3% to 10.5% and churn, code that is changed again shortly after it was written, grew from 3.3% to 5.5% [1]. Their follow-up report with 211 million lines found that refactored lines fell to less than 10% in 2024 and that copy/pasted code was higher than moved code for the first time in their data [2]. It's important to say that GitClear itself only shows a correlation with the adoption of AI assistants, not a cause, but the direction is very clear.&lt;/p&gt;

&lt;p&gt;Google's DORA research gives a similar picture from a different angle. The 2024 report estimated that for every 25% increase in AI adoption, delivery stability decreased by 7.2% and throughput by 1.5%, even though code quality as reported by the respondents went up by 3.4% [3]. In the 2025 report the relationship with throughput became positive, but AI adoption still had a negative relationship with delivery stability, and the authors summarised their finding in one sentence that is very relevant for this article: "AI doesn't fix a team; it amplifies what's already there" [4].&lt;/p&gt;

&lt;p&gt;Reports that compare AI-written and human-written changes directly point the same way. CodeRabbit analysed 470 open source pull requests and found 10.83 issues per AI co-authored pull request against 6.45 per human one, which is about 1.7 times more, with readability issues more than three times as common [5]. Sonar evaluated leading models on more than 4,400 Java tasks and found that more than 90% of the issues were code smells, the kind of problem that doesn't break a test today but makes the code more difficult to change tomorrow [6]. So yes, there is a real problem, and it is mostly a problem of maintainability and structure, not of code that doesn't compile.&lt;/p&gt;

&lt;h2&gt;
  
  
  Is it the model?
&lt;/h2&gt;

&lt;p&gt;Sometimes, yes, and it would be dishonest to write this article without saying that. In September 2025 Anthropic published a postmortem about three infrastructure bugs that degraded Claude's responses in August and early September of that year. One of them was a routing error that at its peak affected 16% of Sonnet 4 requests, and about 30% of Claude Code users had at least one message sent to the wrong server configuration [7]. Users who said that Claude had become worse in those weeks were right, although the reason was not the model weights but the serving infrastructure. Anthropic also wrote that they "never reduce model quality due to demand, time of day, or server load", and that their own evaluations "simply didn't capture the degradation users were reporting" [7].&lt;/p&gt;

&lt;p&gt;The other well-known example is the 2023 paper by Chen, Zaharia and Zou, which reported that the share of directly executable code generated by GPT-4 dropped from 52.0% in March to 10.0% in June [8]. This result was shared very widely as proof that the models were getting worse, but the authors themselves explained that the June model had started to wrap its code in markdown code fences, which made it "not executable" for their test, and Narayanan and Kapoor pointed out that the study didn't check if the code was correct at all [9]. What changed was the behaviour and the format, not the ability to write code.&lt;/p&gt;

&lt;p&gt;Both examples are useful, because they show what a model or platform problem usually looks like: it starts at a specific moment, it affects many users at the same time, and when it's found it can be fixed or explained. The complaint about agent code quality is different. It is a slow decline, it's described by teams working in their own codebases over months, and it continues across several model releases that are better than their predecessors on every public benchmark. That pattern is very difficult to explain with the model alone, so it makes sense to look at the other input the agent uses: the code it's working in.&lt;/p&gt;

&lt;h2&gt;
  
  
  The codebase is the agent's example
&lt;/h2&gt;

&lt;p&gt;An agent doesn't write code in a vacuum. Before it changes anything it reads files around the place where it works, it searches for similar code, and it follows what it finds. Anthropic's own best practices for Claude Code recommend exactly this as a technique: "Point Claude to patterns in your codebase", with an example where the developer tells the agent which existing widget is a good example to follow [13]. The same document also says that CLAUDE.md should not contain "anything Claude can figure out by reading code", which assumes that the agent learns the conventions of a project from the code itself [13]. That is a strength when the code around it is good, but the same mechanism works in the other direction too.&lt;/p&gt;

&lt;p&gt;Research shows quite clearly that the code in the context has a strong effect on what a model writes. Dinh and his colleagues tested code models with partial code that contained small potential bugs, for example a &lt;code&gt;+=&lt;/code&gt; that was changed to &lt;code&gt;-=&lt;/code&gt;. With clean partial code, CodeGen-2B reached a pass rate of 54.9%, but with the buggy partial code it dropped to 3.1%, which was even worse than the 9.3% it reached with no partial code at all [10]. The authors' explanation is that the model "fails to react" to the problem in most of the failed cases, so it doesn't copy the bug on purpose, it continues the code it was given as if it was correct. These were small models from 2023, but the direction of the effect is what matters for this article.&lt;/p&gt;

&lt;p&gt;For security the effect is similar. Snyk demonstrated in 2024 that GitHub Copilot suggested a parameterised SQL query in a clean project, but suggested string concatenation, which means SQL injection, after vulnerable code was placed in a neighbouring open file that Copilot uses as context [11]. That was a demonstration and not a measured study, but a peer-reviewed study by Asare, Nagappan and Asokan found that when Copilot was given the situations where human developers had introduced real vulnerabilities, it reproduced the vulnerable code about 33% of the time [12]. Their main conclusion was actually positive for Copilot, which was "not as bad as human developers", but it also confirms that the surrounding code shapes the suggestion.&lt;/p&gt;

&lt;p&gt;So the code that is already in the repository works like a very large prompt that we never write explicitly. When that prompt was written by people and reviewed by other people, the agent continued good code. When the prompt is more and more the agent's own earlier output, the agent continues that instead.&lt;/p&gt;

&lt;h2&gt;
  
  
  The loop: when the agent learns from itself
&lt;/h2&gt;

&lt;p&gt;Now let's examine what happens over time. In the first months of using an agent, almost all of the code it reads was written by humans, and every line had passed review, static analysis and the discussions in pull requests. The agent copies patterns that people agreed on. Every change the agent makes adds a small amount of its own code to the repository, and if that code is reviewed carefully, nothing changes. But in practice many teams review agent code less carefully than human code, because there is much more of it, because it looks clean and confident, and because the tests are green. Every unreviewed change becomes part of the example for the next change, so small deviations from the architecture are not corrected, they are copied and multiplied.&lt;/p&gt;

&lt;p&gt;This is not a new idea in software engineering. Already in 1980 Lehman described the law of increasing complexity: "As an evolving program is continually changed, its complexity, reflecting deteriorating structure, increases unless work is done to maintain or reduce it" [15]. In 1997 he and his colleagues added the law of declining quality, which says that the quality of such systems "will appear to be declining unless they are rigorously maintained" [16]. Hunt and Thomas called the same thing software entropy and gave the advice "Don't live with broken windows", because one bad design that nobody fixes makes the next one easier to accept [18]. The agent doesn't change these laws. It only makes the changes much faster and in much larger numbers, so the decline that took a human team years can happen in months.&lt;/p&gt;

&lt;p&gt;There is a related effect in model training that is often mentioned in these discussions. Shumailov and his colleagues showed in Nature that models trained again and again on data generated by models suffer "irreversible defects", and the rare parts of the original distribution disappear [17]. I want to be careful here, because that research is about training new weights, while in our case the weights don't change at all, only the code the agent reads changes. So model collapse is an analogy and not an explanation, but the shape is the same: a system that learns from its own output without an external reference slowly loses the quality of the original.&lt;/p&gt;

&lt;p&gt;The most direct evidence for this loop at the level of a project is a 2026 preprint by Zhu, Tsantalis and Rigby, who analysed projects generated by LLMs and by a multi-agent system. In the multi-agent projects the total number of lines correlated with architectural smells at ρ=0.94, and the authors write that "neither functional correctness nor detailed prompting mitigates this decay" [19]. To be fair, the same study also found smells that humans produced and the models didn't, and it only tested one multi-agent framework on 90 programming problems, so it is not a final answer. As far as the published research goes, there is no study yet that measures exactly what this article describes: the share of agent-written code in a real repository over time and the quality of the next change. That is a gap in the research, and until somebody fills it, this explanation is a hypothesis that fits the evidence, not a proven fact.&lt;/p&gt;

&lt;h2&gt;
  
  
  A child who learns from the people around it
&lt;/h2&gt;

&lt;p&gt;The picture I find most helpful is a child who is growing up. A child learns a very large part of its behaviour by looking at the adults around it, how they speak, how they solve problems and how they react when something goes wrong. When a child grows up with parents who show it good examples and correct it when it goes in the wrong direction, it learns those examples. When a child is left alone, it doesn't become less intelligent, but it has nothing to compare its behaviour with, and it develops its own habits, good and bad, without anybody noticing.&lt;/p&gt;

&lt;p&gt;An agent in a codebase is in a very similar situation. At the beginning the reviewed human code was the parent: it showed which patterns to use, where each responsibility belongs and how errors are handled in this project. The pull request reviewer and the static analysis tool were the correction. When we stopped reviewing carefully and the agent wrote more and more of the code, we didn't make the agent less capable, but we took away its examples and its corrections, and then we were surprised that it developed its own habits.&lt;/p&gt;

&lt;h2&gt;
  
  
  What a team can do
&lt;/h2&gt;

&lt;p&gt;If this explanation is right, the good news is that the solution is mostly in our hands and doesn't depend on the next model release. These are the steps that follow from the evidence above.&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;
&lt;strong&gt;Keep the same quality gates for agent code as for human code.&lt;/strong&gt; A pull request written by an agent should be reviewed by a human with the same care, and static analysis such as SonarQube or the .NET analyzers should run on it in the build, not only on the human changes. Anthropic's documentation says it very directly: "If you can't verify it, don't ship it" [13].&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Write the architecture down where the agent reads it.&lt;/strong&gt; Decisions that live only in the heads of senior developers can't be learned from the code, especially when the code has started to drift. A short CLAUDE.md or AGENTS.md file, architecture decision records and explicit rules about where things belong give the agent a reference that doesn't change with every commit.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Point the agent to reference code on purpose.&lt;/strong&gt; Choose a few modules that were written and reviewed by humans and are good examples, and tell the agent to follow them, as the Claude Code documentation recommends [13]. Protect these modules from casual changes, because they are the parents in the analogy above.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Make the rules deterministic where you can.&lt;/strong&gt; Instructions in a markdown file are advice, and Anthropic's documentation describes hooks as the deterministic alternative [13]. In .NET, analyzers with build errors, architecture tests and code style rules that are enforced in the build do the same job: the agent can't ignore them, and they don't get tired after the fiftieth pull request.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Review agent code with a fresh context.&lt;/strong&gt; The Claude Code documentation notes that a new session reviews code better because it "won't be biased toward code it just wrote" [13]. A second agent or a human reviewer who didn't see the conversation is a better check than the same agent reviewing itself.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Measure the trend in your own repository.&lt;/strong&gt; Duplication, churn and the share of refactoring changes are exactly the signals GitClear used [1][2], and you can measure them in your own repository over time. If you also track which changes were written by an agent, you can check this hypothesis on your own code instead of trusting my opinion or anybody else's.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Plan time for refactoring.&lt;/strong&gt; Lehman's law says that complexity grows "unless work is done to maintain or reduce it" [15]. Agents are very good at refactoring when they are asked to do it with clear rules, so the same tool that creates the drift can help to remove it, but somebody has to decide that it's needed.&lt;/li&gt;
&lt;/ol&gt;

&lt;h2&gt;
  
  
  Conclusion
&lt;/h2&gt;

&lt;p&gt;Whether we like it or not, the share of code that agents write will continue to grow, and the question is not whether we use them but what we give them to learn from. The models are not perfect, and sometimes the platform really does get worse for a few weeks, as Anthropic's postmortem shows. But when the quality of agent code declines slowly over months in the same repository, while the models get better on every benchmark, it makes sense to look at the codebase first, because that is the example the agent copies every day. In short, if we want the agent to write code like a careful senior developer, the codebase has to keep looking like the work of careful senior developers, and that is still our job.&lt;/p&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Harding, W. and Kloster, M. &lt;em&gt;Coding on Copilot: 2023 Data Shows Downward Pressure on Code Quality&lt;/em&gt;, GitClear, January 2024. &lt;a href="https://www.gitclear.com/coding_on_copilot_data_shows_ais_downward_pressure_on_code_quality" rel="noopener noreferrer"&gt;https://www.gitclear.com/coding_on_copilot_data_shows_ais_downward_pressure_on_code_quality&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;GitClear. &lt;em&gt;AI Copilot Code Quality: 2025 Look Back at 12 Months of Data&lt;/em&gt;, 2025. &lt;a href="https://www.gitclear.com/ai_assistant_code_quality_2025_research" rel="noopener noreferrer"&gt;https://www.gitclear.com/ai_assistant_code_quality_2025_research&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Harvey, N. and DeBellis, D. &lt;em&gt;Announcing the 2024 DORA report&lt;/em&gt;, Google Cloud blog, 23 October 2024. &lt;a href="https://cloud.google.com/blog/products/devops-sre/announcing-the-2024-dora-report" rel="noopener noreferrer"&gt;https://cloud.google.com/blog/products/devops-sre/announcing-the-2024-dora-report&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Harvey, N. and DeBellis, D. &lt;em&gt;Announcing the 2025 DORA Report: State of AI-Assisted Software Development&lt;/em&gt;, Google Cloud blog, 23 September 2025. &lt;a href="https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report" rel="noopener noreferrer"&gt;https://cloud.google.com/blog/products/ai-machine-learning/announcing-the-2025-dora-report&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Loker, D. &lt;em&gt;AI vs Human Code Generation Report&lt;/em&gt;, CodeRabbit, 17 December 2025. &lt;a href="https://www.coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report" rel="noopener noreferrer"&gt;https://www.coderabbit.ai/blog/state-of-ai-vs-human-code-generation-report&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Sonar. &lt;em&gt;The Coding Personalities of Leading LLMs&lt;/em&gt;, August 2025. &lt;a href="https://www.sonarsource.com/the-coding-personalities-of-leading-llms/" rel="noopener noreferrer"&gt;https://www.sonarsource.com/the-coding-personalities-of-leading-llms/&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Anthropic. &lt;em&gt;A postmortem of three recent issues&lt;/em&gt;, Anthropic Engineering, 17 September 2025. &lt;a href="https://www.anthropic.com/engineering/a-postmortem-of-three-recent-issues" rel="noopener noreferrer"&gt;https://www.anthropic.com/engineering/a-postmortem-of-three-recent-issues&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Chen, L., Zaharia, M. and Zou, J. &lt;em&gt;How is ChatGPT's behavior changing over time?&lt;/em&gt;, arXiv:2307.09009, 2023. &lt;a href="https://arxiv.org/abs/2307.09009" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2307.09009&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Narayanan, A. and Kapoor, S. &lt;em&gt;Is GPT-4 getting worse over time?&lt;/em&gt;, AI Snake Oil, 19 July 2023. &lt;a href="https://www.aisnakeoil.com/p/is-gpt-4-getting-worse-over-time" rel="noopener noreferrer"&gt;https://www.aisnakeoil.com/p/is-gpt-4-getting-worse-over-time&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Dinh, T. et al. &lt;em&gt;Large Language Models of Code Fail at Completing Code with Potential Bugs&lt;/em&gt;, NeurIPS 2023. &lt;a href="https://arxiv.org/abs/2306.03438" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2306.03438&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Degges, R. &lt;em&gt;Copilot amplifies insecure codebases by replicating vulnerabilities in your projects&lt;/em&gt;, Snyk Labs, 22 February 2024. &lt;a href="https://labs.snyk.io/resources/copilot-amplifies-insecure-codebases-by-replicating-vulnerabilities/" rel="noopener noreferrer"&gt;https://labs.snyk.io/resources/copilot-amplifies-insecure-codebases-by-replicating-vulnerabilities/&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Asare, O., Nagappan, M. and Asokan, N. &lt;em&gt;Is GitHub's Copilot as Bad as Humans at Introducing Vulnerabilities in Code?&lt;/em&gt;, Empirical Software Engineering, 2023. &lt;a href="https://arxiv.org/abs/2204.04741" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2204.04741&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Anthropic. &lt;em&gt;Best practices for Claude Code&lt;/em&gt;, Claude Code documentation, accessed 19 October 2026. &lt;a href="https://code.claude.com/docs/en/best-practices" rel="noopener noreferrer"&gt;https://code.claude.com/docs/en/best-practices&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;METR. &lt;em&gt;Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity&lt;/em&gt;, 10 July 2025. &lt;a href="https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/" rel="noopener noreferrer"&gt;https://metr.org/blog/2025-07-10-early-2025-ai-experienced-os-dev-study/&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Lehman, M. M. &lt;em&gt;Programs, Life Cycles, and Laws of Software Evolution&lt;/em&gt;, Proceedings of the IEEE 68(9), September 1980, pp. 1060-1076.&lt;/li&gt;
&lt;li&gt;Lehman, M. M., Ramil, J. F., Wernick, P. D., Perry, D. E. and Turski, W. M. &lt;em&gt;Metrics and Laws of Software Evolution: The Nineties View&lt;/em&gt;, Proceedings of the 4th International Software Metrics Symposium, 1997, pp. 20-32.&lt;/li&gt;
&lt;li&gt;Shumailov, I. et al. &lt;em&gt;AI models collapse when trained on recursively generated data&lt;/em&gt;, Nature 631, 755-759, 2024. &lt;a href="https://www.nature.com/articles/s41586-024-07566-y" rel="noopener noreferrer"&gt;https://www.nature.com/articles/s41586-024-07566-y&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Hunt, A. and Thomas, D. &lt;em&gt;The Pragmatic Programmer&lt;/em&gt;, Addison-Wesley, 1999, section "Software Entropy". Tip list: &lt;a href="https://pragprog.com/tips/" rel="noopener noreferrer"&gt;https://pragprog.com/tips/&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Zhu, Tsantalis and Rigby. &lt;em&gt;AI-Generated Smells: An Analysis of Code and Architecture in LLM- and Agent-Driven Development&lt;/em&gt;, arXiv:2605.02741, 2026 (preprint). &lt;a href="https://arxiv.org/abs/2605.02741" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2605.02741&lt;/a&gt;
&lt;/li&gt;
&lt;/ol&gt;

</description>
      <category>claudecode</category>
      <category>ai</category>
      <category>codequality</category>
      <category>technicaldebt</category>
    </item>
    <item>
      <title>The Narrow Sidewalk: Where Developers Stand When Agents Write the Code</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Sun, 18 Oct 2026 10:44:39 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/the-narrow-sidewalk-where-developers-stand-when-agents-write-the-code-4o0c</link>
      <guid>https://dev.to/mehdimohseni82/the-narrow-sidewalk-where-developers-stand-when-agents-write-the-code-4o0c</guid>
      <description>&lt;p&gt;When coding agents such as Claude Code and Codex became good enough to take whole tasks, the first reaction in our industry was very loud: developers would be replaced, and soon. A year later the picture is more interesting than that. Agents write a large share of the code now, and that is not going back. But it is also becoming clear that someone still has to know what correct code looks like, and that this someone is a developer with a critical mindset. In my view we are close to the point where the balance between agents and humans becomes visible, and the honest description of that balance is a narrow sidewalk.&lt;/p&gt;

&lt;p&gt;On one side of the sidewalk is the developer who keeps working as before, writing every line by hand and treating agents as a toy. On the other side is the developer who hands everything to the agent and stops learning, because the code compiles and the tests are green. Both of them fall off. The path in the middle is narrow, and in this article I want to describe what walking on it actually requires, with real code.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the Numbers Say About Both Sides
&lt;/h2&gt;

&lt;p&gt;METR ran a randomized controlled trial in early 2025 with 16 experienced open-source developers working on 246 real issues in their own repositories. With AI tools they took 19% longer. The more interesting part is the perception: before the study they expected AI to make them 24% faster, and even after the slowdown they still believed it had made them 20% faster. So our feeling about how much the agent helps is not a reliable measurement.&lt;/p&gt;

&lt;p&gt;In February 2026 METR reported that it had to change the design of its follow-up study, mainly because many developers no longer wanted to work without AI at all, and that developers are likely faster now than in early 2025. Taken together, these two results describe the sidewalk very well. Going back to the old way of working is not realistic, but trusting our own impression of the agent's output is also not safe.&lt;/p&gt;

&lt;h2&gt;
  
  
  Green Checks, Wrong Meaning
&lt;/h2&gt;

&lt;p&gt;When coding agents work on real systems, one failure shows up again and again. The code type-checks, the tests pass, the build is green, and the behaviour is still wrong, because the mistake is in the meaning and not in the syntax. A check can only verify what somebody told it to verify, and the agent writes both the code and, very often, the checks.&lt;/p&gt;

&lt;p&gt;Let us take a concrete example. An endpoint asks an external access service which permissions a user has, and refuses the request when the user has none. A typical generated version looks like this:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;interface&lt;/span&gt; &lt;span class="nc"&gt;IPermissionClient&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;IReadOnlySet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;GetPermissionsAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;NaiveAccessCheck&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IPermissionClient&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;IResult&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;CheckAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;IReadOnlySet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
        &lt;span class="k"&gt;try&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;permissions&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetPermissionsAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;HttpRequestException&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="n"&gt;permissions&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;HashSet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;();&lt;/span&gt; &lt;span class="c1"&gt;// fail closed&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;

        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Count&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;
            &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;StatusCode&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;StatusCodes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status403Forbidden&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Ok&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;It compiles, it reads naturally, and it even carries a comment about failing closed, which is the correct security instinct. A test that gives the stub an empty permission set and expects 403 passes. The problem is that an outage of the access service also produces an empty set, so during an outage every user gets a 403 and the UI tells them they have no access. They contact support about permissions, and nobody looks at the access service, which is the thing that is actually broken.&lt;/p&gt;

&lt;p&gt;Seeing this requires knowing that "the user is refused" and "the authority could not be asked" are two different answers, and that they lead to different status codes, different messages and different alerts. No type and no test inside this class encodes that knowledge. The fix is to make the difference impossible to lose:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;System.Diagnostics&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;abstract&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;AccessDecision&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;Allowed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IReadOnlySet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;Permissions&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;Denied&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Reason&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;Unavailable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Exception&lt;/span&gt; &lt;span class="n"&gt;Cause&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AccessCheck&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IPermissionClient&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;CheckAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;try&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;permissions&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;client&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetPermissionsAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Count&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="m"&gt;0&lt;/span&gt;
                &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Denied&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"No permissions granted"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
                &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Allowed&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
        &lt;span class="k"&gt;catch&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;HttpRequestException&lt;/span&gt; &lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
        &lt;span class="p"&gt;{&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Unavailable&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ex&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
        &lt;span class="p"&gt;}&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AccessResults&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="n"&gt;IResult&lt;/span&gt; &lt;span class="nf"&gt;ToHttpResult&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;AccessDecision&lt;/span&gt; &lt;span class="n"&gt;decision&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;decision&lt;/span&gt; &lt;span class="k"&gt;switch&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Allowed&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Ok&lt;/span&gt;&lt;span class="p"&gt;(),&lt;/span&gt;
        &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Denied&lt;/span&gt; &lt;span class="n"&gt;d&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Problem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;d&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Reason&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;statusCode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;StatusCodes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status403Forbidden&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
        &lt;span class="n"&gt;AccessDecision&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Unavailable&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;Results&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Problem&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Access service unavailable"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
            &lt;span class="n"&gt;statusCode&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;StatusCodes&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Status503ServiceUnavailable&lt;/span&gt;&lt;span class="p"&gt;),&lt;/span&gt;
        &lt;span class="n"&gt;_&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="k"&gt;throw&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;UnreachableException&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;};&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;Now a refusal and an outage are different types, and the switch makes the caller handle each one. An outage becomes a 503, which a monitoring system will page on, instead of a 403, which nobody pages on.&lt;/p&gt;

&lt;h2&gt;
  
  
  Fail-Open Defaults Hide Behind Healthy Deployments
&lt;/h2&gt;

&lt;p&gt;The second pattern is a check that passes because it was never active. Verification code is often written so that it is skipped when its settings are missing, which is convenient on a developer machine:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;System.ComponentModel.DataAnnotations&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;Microsoft.Extensions.Options&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;TokenOptions&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;Required&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt; &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Issuer&lt;/span&gt; &lt;span class="p"&gt;{&lt;/span&gt; &lt;span class="k"&gt;get&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="k"&gt;set&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="p"&gt;}&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="s"&gt;""&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;NaiveTokenCheck&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IOptions&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TokenOptions&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="kt"&gt;bool&lt;/span&gt; &lt;span class="nf"&gt;IsTrusted&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;issuer&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="k"&gt;if&lt;/span&gt; &lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;IsNullOrEmpty&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Issuer&lt;/span&gt;&lt;span class="p"&gt;))&lt;/span&gt;
            &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="k"&gt;true&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt; &lt;span class="c1"&gt;// verification not configured yet&lt;/span&gt;

        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;issuer&lt;/span&gt; &lt;span class="p"&gt;==&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Value&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Issuer&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;If the deployment never passes the issuer setting, every token is trusted, the service starts, health checks are green and nothing in the logs looks wrong. Only a negative test against the deployed service, a request that should be refused, shows that nothing is checked. In .NET the better default is to refuse to start at all when security settings are missing:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;TokenOptionsSetup&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;static&lt;/span&gt; &lt;span class="n"&gt;IServiceCollection&lt;/span&gt; &lt;span class="nf"&gt;AddTokenOptions&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;this&lt;/span&gt; &lt;span class="n"&gt;IServiceCollection&lt;/span&gt; &lt;span class="n"&gt;services&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="n"&gt;services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;AddOptions&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;TokenOptions&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;()&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;BindConfiguration&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Token"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ValidateDataAnnotations&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
            &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ValidateOnStart&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;return&lt;/span&gt; &lt;span class="n"&gt;services&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;&lt;code&gt;ValidateOnStart&lt;/code&gt; runs the data annotation validation when the host starts, so a missing issuer becomes an &lt;code&gt;OptionsValidationException&lt;/code&gt; at startup instead of a silent hole in production.&lt;/p&gt;

&lt;h2&gt;
  
  
  Test Both Directions
&lt;/h2&gt;

&lt;p&gt;Both fixes are only worth something if the tests prove the negative case as carefully as the positive one. These are the tests that matter here, and the outage test is the one a generated suite usually leaves out:&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;Microsoft.AspNetCore.Http.HttpResults&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;Microsoft.Extensions.Options&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;StubClient&lt;/span&gt; &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;IPermissionClient&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;IReadOnlySet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;?&lt;/span&gt; &lt;span class="n"&gt;_permissions&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;private&lt;/span&gt; &lt;span class="k"&gt;readonly&lt;/span&gt; &lt;span class="n"&gt;Exception&lt;/span&gt;&lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;_error&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nf"&gt;StubClient&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IReadOnlySet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;_permissions&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;permissions&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="nf"&gt;StubClient&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;Exception&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;_error&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;error&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;IReadOnlySet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;GetPermissionsAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;userId&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;CancellationToken&lt;/span&gt; &lt;span class="n"&gt;ct&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="n"&gt;_error&lt;/span&gt; &lt;span class="k"&gt;is&lt;/span&gt; &lt;span class="k"&gt;null&lt;/span&gt;
            &lt;span class="p"&gt;?&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;FromResult&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;_permissions&lt;/span&gt;&lt;span class="p"&gt;!)&lt;/span&gt;
            &lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;FromException&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;IReadOnlySet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;(&lt;/span&gt;&lt;span class="n"&gt;_error&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;AccessCheckTests&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;Fact&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;Refused_user_gets_403&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;AccessCheck&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;StubClient&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;HashSet&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;()));&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;AccessResults&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToHttpResult&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CheckAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"u1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
        &lt;span class="n"&gt;Assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;403&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="n"&gt;IStatusCodeHttpResult&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="n"&gt;StatusCode&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;Fact&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;Outage_gets_503_not_403&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;AccessCheck&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;StubClient&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;HttpRequestException&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"down"&lt;/span&gt;&lt;span class="p"&gt;)));&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;result&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;AccessResults&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;ToHttpResult&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;check&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CheckAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"u1"&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;default&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
        &lt;span class="n"&gt;Assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Equal&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="m"&gt;503&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="p"&gt;((&lt;/span&gt;&lt;span class="n"&gt;IStatusCodeHttpResult&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;&lt;span class="n"&gt;result&lt;/span&gt;&lt;span class="p"&gt;).&lt;/span&gt;&lt;span class="n"&gt;StatusCode&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;

    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;Fact&lt;/span&gt;&lt;span class="p"&gt;]&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;async&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt; &lt;span class="nf"&gt;Missing_token_settings_fail_at_startup&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;{&lt;/span&gt;
        &lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;builder&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;Host&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;CreateApplicationBuilder&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AddTokenOptions&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;var&lt;/span&gt; &lt;span class="n"&gt;host&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;builder&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Build&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;
        &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;Assert&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;ThrowsAsync&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;OptionsValidationException&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;(()&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;host&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;StartAsync&lt;/span&gt;&lt;span class="p"&gt;());&lt;/span&gt;
    &lt;span class="p"&gt;}&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;All the code in this article was run on .NET 10 before publishing, including the naive versions, to confirm that the first one really answers 403 during an outage and the second one really trusts any issuer when it is not configured.&lt;/p&gt;

&lt;h2&gt;
  
  
  The Same Patterns, Again and Again
&lt;/h2&gt;

&lt;p&gt;The two examples above are not special. In practice, the mistakes that survive into production with agent-written code tend to follow a small number of shapes:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Tests mock exactly the boundary where the bug lives.&lt;/strong&gt; Each side of an integration is tested against a stub of the other side, so a mismatch between them, for example 401 where 403 was meant, is invisible to both suites.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The premise is wrong, and every check agrees with it.&lt;/strong&gt; A feature flag read with the wrong polarity, or a coordinate system assumed to point the other way, produces code and tests that are perfectly consistent with each other and wrong about the world.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A green check measures less than its name.&lt;/strong&gt; A release step joined with &lt;code&gt;;&lt;/code&gt; instead of &lt;code&gt;&amp;amp;&amp;amp;&lt;/code&gt; ignores the CI result it was supposed to wait for. A test that discovers components with a type check can silently skip the ones that do not match, so coverage shrinks while every run stays green.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;The producer is verified instead of the consumer.&lt;/strong&gt; Checking a value in the data you serve proves nothing if the consumer reads a different copy of it.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Readable and proportionate are not testable.&lt;/strong&gt; A page can be correct and fully tested and still show thirty nearly identical rows for one file.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;A guardrail stops the agent.&lt;/strong&gt; When a policy blocks an action, the right move is to give the decision back to a human, not to find another route around the block.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;What these have in common is that none of them is caught by more automation alone. They are caught by someone who knows what the system is supposed to mean: the domain, the architecture, and who reads what.&lt;/p&gt;

&lt;h2&gt;
  
  
  Walking the Sidewalk
&lt;/h2&gt;

&lt;p&gt;So what does staying on the sidewalk look like in practice? In my view it has two parts, and both of them need continuous learning.&lt;/p&gt;

&lt;p&gt;The first part is to keep learning how code works. Not because we will write most of it by hand again, but because the knowledge of HTTP semantics, failure modes, type design and the platform we work on is exactly what lets us recognise when a plausible answer is wrong. A developer who stops learning here can no longer review the agent, and then the agent is not supervised at all.&lt;/p&gt;

&lt;p&gt;The second part is to learn how to work with the agent: how to give it the context and constraints it cannot infer, how to put checks around it that test the negative case, and how to critique its output instead of accepting a green build as proof. That is a skill of its own, and it is still very young.&lt;/p&gt;

&lt;p&gt;The developers who will do well in the next years are, I think, the ones who keep both of these going at the same time. The sidewalk is narrow, but it is the only path that does not end in either irrelevance or a production incident that nobody can explain.&lt;/p&gt;

</description>
      <category>dotnet</category>
      <category>aspnetcore</category>
      <category>ai</category>
      <category>testing</category>
    </item>
    <item>
      <title>Why Agents Need a Knowledge Base: The Gaps an LLM Can't Fill by Itself</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Fri, 16 Oct 2026 16:26:16 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/why-agents-need-a-knowledge-base-the-gaps-an-llm-cant-fill-by-itself-49pa</link>
      <guid>https://dev.to/mehdimohseni82/why-agents-need-a-knowledge-base-the-gaps-an-llm-cant-fill-by-itself-49pa</guid>
      <description>&lt;p&gt;When a team starts building an agent, the first version is very often only a model, a system prompt and a few tools, and for a demo that is usually enough, because the questions in a demo are general questions and a large language model knows a surprising amount about general things. The problems start when the agent is put in front of real work and the questions become specific: which services depend on this database, what we decided about retries last spring, whether the version of a library we use already has the fix, or how to apply a rule from a specialised engineering field that the model only knows from the textbook level. In my view, when an agent disappoints, the reason is very often that the model is asked to know things it never had any chance to learn, much more often than any weakness of the model itself. In this article I want to explain what those gaps are, why a bigger context window doesn't close them, and what role a knowledge base plays in an agentic system, so that the more technical articles on dotnet-talk.com about RAG, agent memory and knowledge graphs have a place to start from.&lt;/p&gt;

&lt;h2&gt;
  
  
  What the model actually knows
&lt;/h2&gt;

&lt;p&gt;Everything a model knows on its own is stored in its weights, and it got there during training. The authors of the original RAG paper, Patrick Lewis and his colleagues at Facebook AI Research, called this &lt;em&gt;parametric memory&lt;/em&gt;, and already in 2020 they pointed out the two problems with it which are still the important ones today: for these models, "providing provenance for their decisions and updating their world knowledge remain open research problems" [1]. Their answer was to combine the parametric memory of the model with a &lt;em&gt;non-parametric&lt;/em&gt; memory, which in their case was a dense vector index of Wikipedia that a retriever searched before the model generated an answer.&lt;/p&gt;

&lt;p&gt;That distinction is very useful, because it gives us a clean way to think about what belongs where. Parametric memory is very good at language, reasoning, code patterns and widely published general knowledge. Non-parametric memory, which is the knowledge base, is for everything that is specific, private, recent or has to be traceable to a source.&lt;/p&gt;

&lt;h2&gt;
  
  
  The first gap: time
&lt;/h2&gt;

&lt;p&gt;Every model has a date after which it knows nothing, and model providers publish that date. Anthropic's model overview, for example, lists two dates for each model: a &lt;em&gt;reliable knowledge cutoff&lt;/em&gt;, which it describes as "the date through which the model's knowledge is most extensive and reliable", and a &lt;em&gt;training data cutoff&lt;/em&gt;, which is the broader range of data that was used [2]. For the whole current Claude lineup, from Haiku 5.5 to Fable 5.1, both dates are June 2026 [2].&lt;/p&gt;

&lt;p&gt;That sounds recent, and it is, but it also means that a model you call today in October 2026 has never seen anything from the last four months: not the NuGet packages released since then, not the breaking changes in the SDK you upgraded last week, and not the security advisory that was published yesterday. Additionally, the knowledge close to the cutoff is the thinnest, because the internet had not yet written much about those events when the data was collected. So the newest things are exactly the things the model knows least well, and these are very often the things a developer is asking about.&lt;/p&gt;

&lt;h2&gt;
  
  
  The second gap: knowledge that is too specialised
&lt;/h2&gt;

&lt;p&gt;The gap that surprises people most is not about time at all. Many fields are old and stable, so the cutoff doesn't matter for them, and still the model's knowledge of them is very thin, simply because not much has been written about them in public. A model learns a fact roughly in proportion to how often that fact appears in its training data, and this has been measured. Nikhil Kandpal and his colleagues found that "a language model's ability to answer a fact-based question relates to how many documents associated with that question were seen during pre-training", and that models "must be scaled by many orders of magnitude" to answer well the questions with little support in that data [3]. Alex Mallen and his co-authors reached the same conclusion from a different direction: language models "struggle with less popular factual knowledge", and "scaling fails to appreciably improve memorization of factual knowledge in the long tail" [4].&lt;/p&gt;

&lt;p&gt;That means there is a difference between &lt;em&gt;general&lt;/em&gt; knowledge of a field and &lt;em&gt;enough&lt;/em&gt; knowledge to do real work in it. A model has read the textbook level of almost everything, so it can explain the concepts of a specialised field very well, and this is exactly what makes the gap difficult to notice. When the question goes one level deeper, to the details that are needed to actually design or build something, the model answers in the same fluent and confident tone, but the answer is now built from general patterns and not from knowledge of that field. Some examples of areas where this happens:&lt;/p&gt;

&lt;ul&gt;
&lt;li&gt;
&lt;strong&gt;Designing a production line.&lt;/strong&gt; The concepts, takt time, line balancing, bottlenecks and buffers, are in every operations management book, and a model explains them very well. But turning them into a line that works for a specific product needs the cycle times and changeover behaviour of specific machines, the constraints of a specific factory floor and the judgment of engineers who have commissioned such lines before, and most of that lives in vendor datasheets, simulation models and people's heads, not on the public internet.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;3D modelling and design for manufacturing.&lt;/strong&gt; A model can explain what a mesh, a B-rep solid or a tolerance stack is, but the rules that decide whether a part can actually be produced, such as the minimum wall thickness or the draft angle for one process and one material, or the scripting API of one particular CAD system, are mostly found in paid courses, vendor documentation and supplier guidelines, and there are very few public forum answers for the model to learn from.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Industrial automation.&lt;/strong&gt; PLC programs written in the IEC 61131-3 languages, like Structured Text and ladder logic, run a very large part of the world's factories, but almost all of that code is proprietary and stays inside the plant, so the amount of public example code is tiny compared with C# or Python, and each vendor adds its own dialect and function block libraries on top.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Standards and regulation.&lt;/strong&gt; Most ISO and IEC standards are sold as paid documents, so a model has usually seen blog posts and summaries about a standard but not the text of the standard itself. Local regulation has a similar problem when it is published only in a smaller language, for example national building or tax rules in Swedish, where the amount of text is a small fraction of what exists in English.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Legacy and small software ecosystems.&lt;/strong&gt; The customisation language of an old ERP system, the job control of a mainframe, or an open source library with a few hundred users all have very little public code. This is where a model very often invents method names and configuration keys that look completely plausible but don't exist.&lt;/li&gt;
&lt;li&gt;
&lt;strong&gt;Tacit knowledge.&lt;/strong&gt; How one particular machine behaves when the humidity changes, or what an experienced operator listens for before a failure, was never written down anywhere, so no model can learn it, however large it becomes.&lt;/li&gt;
&lt;/ul&gt;

&lt;p&gt;Some of these gaps will become smaller as models grow and as more is written in public, but in my view many of them will not close, because the knowledge is not missing from the training data by accident: it is paid, proprietary, in a small language, or never written down at all, and the research above shows that scaling the model alone is a very expensive way to fix the long tail. The same research also points to the solution. Kandpal and his colleagues note that retrieval "can reduce the dependence on relevant pre-training information" [3], and Mallen and his co-authors found that retrieval-augmented models "largely outperform orders of magnitude larger LMs" on less popular knowledge [4]. In other words, for a specialised field the knowledge base is where the depth comes from: the vendor manuals, the licensed standards, the internal design rules, the commissioning reports and the notes of experts, while the model contributes the reasoning and the language.&lt;/p&gt;

&lt;h2&gt;
  
  
  The third gap: knowledge that was never public
&lt;/h2&gt;

&lt;p&gt;The specialised fields above are at least partly public, so a model has seen something about them, but a model is trained only on public data, and most of what an agent needs to know inside a company has never been public and never will be. The model doesn't know that your &lt;code&gt;billing-api&lt;/code&gt; writes to the same PostgreSQL cluster as &lt;code&gt;invoicing-worker&lt;/code&gt;, it doesn't know which team owns the &lt;code&gt;notifications&lt;/code&gt; service, it doesn't know the architecture decision record in which you chose at-least-once delivery and explained why, and it doesn't know about an incident last March whose root cause was a connection pool that was too small.&lt;/p&gt;

&lt;p&gt;No future model will close this gap by being trained on more data, because the data is not available to anyone who trains models, and that's exactly how it should be. The only way the agent gets this knowledge is if we give it to the agent at the moment it needs it.&lt;/p&gt;

&lt;h2&gt;
  
  
  The fourth gap: knowing where an answer came from
&lt;/h2&gt;

&lt;p&gt;The fourth gap is the one from the RAG paper: provenance [1]. When a model answers from its weights, it can't tell you which document the answer came from, because there was no document, there were only weights. For a casual question that is fine, but for an agent that is going to change a configuration, open a pull request or tell an on-call engineer which service to restart, an answer without a source is very difficult to trust and impossible to check.&lt;/p&gt;

&lt;p&gt;A knowledge base changes this, because every piece of knowledge that is retrieved comes with a source, a date and an owner. The agent can say "according to ADR-0042, updated on 3 September" and a human can open ADR-0042 and see if the agent understood it correctly. In my view this is the most underrated benefit of a knowledge base, because besides giving the agent more knowledge it also makes that knowledge &lt;em&gt;checkable&lt;/em&gt; by the people who have to act on it.&lt;/p&gt;

&lt;h2&gt;
  
  
  Why a bigger context window doesn't solve it
&lt;/h2&gt;

&lt;p&gt;The natural question is whether we still need any of this, now that context windows are so large. All current Claude models have a 1M token context window, which Anthropic estimates at roughly 555k words on the current tokenizer [2]. Why not put all the documentation into the prompt and let the model find what it needs?&lt;/p&gt;

&lt;p&gt;There are three reasons why this doesn't work as well as it sounds. The first one is that long context is not read evenly. In the paper &lt;em&gt;Lost in the Middle&lt;/em&gt;, Nelson Liu and his co-authors showed that "performance is often highest when relevant information occurs at the beginning or end of the input context, and significantly degrades when models must access relevant information in the middle of long contexts" [5]. The paper is from 2023 and models have changed since then, but the lesson is still valid: putting more text in front of the model doesn't guarantee that the model actually uses all of it.&lt;/p&gt;

&lt;p&gt;The second reason is cost and latency, because every token in the context is paid for on every call, and an agent makes many calls in a single task. &lt;a href="https://dotnet-talk.com/blog/ai-cost-model-tokenizers-context-cliffs-dotnet" rel="noopener noreferrer"&gt;Your AI Cost Model Is Already Wrong&lt;/a&gt; shows how quickly this adds up, and a context that is mostly irrelevant documentation is the most expensive way to make an agent slower.&lt;/p&gt;

&lt;p&gt;The third reason is that even a 1M token window has to be filled by &lt;em&gt;something&lt;/em&gt;, and that something has to decide what is relevant, what is current and what is allowed to be seen by this user. That something is a knowledge base with a retrieval step, whether we call it that or not.&lt;/p&gt;

&lt;h2&gt;
  
  
  The three shapes a knowledge base takes
&lt;/h2&gt;

&lt;p&gt;"Knowledge base" can mean very different things, and in my view a lot of confusion comes from treating them as one. In an agentic system it's very useful to separate three shapes, because each one answers a different kind of question.&lt;/p&gt;

&lt;div class="table-wrapper-paragraph"&gt;&lt;table&gt;
&lt;thead&gt;
&lt;tr&gt;
&lt;th&gt;Shape&lt;/th&gt;
&lt;th&gt;Answers questions like&lt;/th&gt;
&lt;th&gt;Typical storage&lt;/th&gt;
&lt;th&gt;On this site&lt;/th&gt;
&lt;/tr&gt;
&lt;/thead&gt;
&lt;tbody&gt;
&lt;tr&gt;
&lt;td&gt;Document store with vector search&lt;/td&gt;
&lt;td&gt;"What does our runbook say about rotating the signing key?"&lt;/td&gt;
&lt;td&gt;chunks plus embeddings, for example PostgreSQL with pgvector&lt;/td&gt;
&lt;td&gt;&lt;a href="https://dotnet-talk.com/blog/building-a-retrieval-augmented-generation-rag-system-in-net" rel="noopener noreferrer"&gt;RAG in .NET&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Knowledge graph&lt;/td&gt;
&lt;td&gt;"What breaks if &lt;code&gt;billing-db&lt;/code&gt; is down?", "Who owns everything downstream of this queue?"&lt;/td&gt;
&lt;td&gt;entities and typed edges, for example NebulaGraph or Neo4j&lt;/td&gt;
&lt;td&gt;&lt;a href="https://dotnet-talk.com/blog/hybrid-retrieval-csharp-vector-graph-rerank" rel="noopener noreferrer"&gt;Hybrid Retrieval in C#&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;tr&gt;
&lt;td&gt;Agent memory&lt;/td&gt;
&lt;td&gt;"What did we decide in the last session?", "What does this user prefer?"&lt;/td&gt;
&lt;td&gt;facts the agent itself writes, with timestamps and importance&lt;/td&gt;
&lt;td&gt;&lt;a href="https://dotnet-talk.com/blog/dotnet-agent-durable-memory-postgres-pgvector" rel="noopener noreferrer"&gt;Durable Memory with Postgres and pgvector&lt;/a&gt;&lt;/td&gt;
&lt;/tr&gt;
&lt;/tbody&gt;
&lt;/table&gt;&lt;/div&gt;

&lt;p&gt;The document store is the one most teams build first, and it's very good for questions whose answer is written down somewhere in one place. It is weak at questions whose answer is spread over many places and only appears when you follow relationships, which is where the knowledge graph comes in. A vector index can tell the agent which documents &lt;em&gt;look similar&lt;/em&gt; to "billing database", but it can't tell it that four services depend on that database through two hops, because similarity is not dependency.&lt;/p&gt;

&lt;p&gt;The knowledge graph also helps with a kind of question that plain RAG handles badly, which is the global question about a whole collection. Darren Edge and his colleagues at Microsoft Research described this in the GraphRAG paper: standard RAG struggles with "global questions directed at an entire text corpus, such as 'What are the main themes in the dataset?'", and their approach first uses an LLM to "derive an entity knowledge graph from the source documents" and then pre-generates summaries for groups of closely related entities [6]. You don't need GraphRAG itself to benefit from the idea, but it shows very clearly that the structure of a knowledge base decides which questions it can answer.&lt;/p&gt;

&lt;p&gt;Agent memory is the third shape and the most different one, because here the agent is not only a reader but also a writer. It records what it learned and what was decided so that the next session doesn't start from zero. That makes it very powerful, but it also means it can fill itself with stale or contradicting facts, which is the subject of &lt;a href="https://dotnet-talk.com/blog/agentic-system-dotnet-keeping-memory-true" rel="noopener noreferrer"&gt;Keeping Memory True&lt;/a&gt;.&lt;/p&gt;

&lt;p&gt;In practice a serious agent ends up using more than one of these, and the retrieval step combines them. &lt;a href="https://dotnet-talk.com/blog/hybrid-retrieval-csharp-vector-graph-rerank" rel="noopener noreferrer"&gt;Hybrid Retrieval in C#&lt;/a&gt; shows that pipeline in full: vector search finds the entry points, graph traversal expands the context around them, and a reranker decides what actually reaches the model.&lt;/p&gt;

&lt;h2&gt;
  
  
  Let the agent decide when to look
&lt;/h2&gt;

&lt;p&gt;There are two ways to connect a knowledge base to a model. In classic RAG, retrieval runs before every model call, whether the question needs it or not. In an agentic system it's usually better to expose the knowledge base as a tool, so that the model decides when it needs to look something up, what to search for and whether the first result was enough or it should search again with different words.&lt;/p&gt;

&lt;p&gt;In .NET, &lt;code&gt;Microsoft.Extensions.AI&lt;/code&gt; makes this very convenient. &lt;code&gt;AIFunctionFactory.Create&lt;/code&gt; turns a normal .NET method into a tool the model can call, and if you don't pass a description it takes it from the &lt;code&gt;[Description]&lt;/code&gt; attribute on the method [7]. &lt;code&gt;UseFunctionInvocation()&lt;/code&gt; then adds a &lt;code&gt;FunctionInvokingChatClient&lt;/code&gt; to the pipeline, which runs the tool when the model asks for it and sends the result back [8].&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;System.ComponentModel&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;
&lt;span class="k"&gt;using&lt;/span&gt; &lt;span class="nn"&gt;Microsoft.Extensions.AI&lt;/span&gt;&lt;span class="p"&gt;;&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;record&lt;/span&gt; &lt;span class="nc"&gt;KnowledgeHit&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Text&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;Source&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;          &lt;span class="c1"&gt;// e.g. "adr/0042-at-least-once-delivery.md"&lt;/span&gt;
    &lt;span class="n"&gt;DateTimeOffset&lt;/span&gt; &lt;span class="n"&gt;UpdatedAt&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt;
    &lt;span class="kt"&gt;double&lt;/span&gt; &lt;span class="n"&gt;Score&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="k"&gt;sealed&lt;/span&gt; &lt;span class="k"&gt;class&lt;/span&gt; &lt;span class="nc"&gt;KnowledgeTools&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;IKnowledgeStore&lt;/span&gt; &lt;span class="n"&gt;store&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="nf"&gt;Description&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="s"&gt;"Searches the team's knowledge base: architecture decisions, service "&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt;
                 &lt;span class="s"&gt;"ownership and dependencies, runbooks and incident reports. Use it before "&lt;/span&gt; &lt;span class="p"&gt;+&lt;/span&gt;
                 &lt;span class="s"&gt;"answering anything about our own systems. Each hit has a source and a date."&lt;/span&gt;&lt;span class="p"&gt;)]&lt;/span&gt;
    &lt;span class="k"&gt;public&lt;/span&gt; &lt;span class="n"&gt;Task&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;IReadOnlyList&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;KnowledgeHit&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&amp;gt;&lt;/span&gt; &lt;span class="nf"&gt;SearchKnowledge&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="kt"&gt;string&lt;/span&gt; &lt;span class="n"&gt;question&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="kt"&gt;int&lt;/span&gt; &lt;span class="n"&gt;top&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="m"&gt;5&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt; &lt;span class="p"&gt;=&amp;gt;&lt;/span&gt;
        &lt;span class="n"&gt;store&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;SearchAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;question&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;Math&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Clamp&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;top&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;1&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="m"&gt;8&lt;/span&gt;&lt;span class="p"&gt;));&lt;/span&gt;
&lt;span class="p"&gt;}&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The important design decision is in the return type. Every hit carries its source and the date it was last updated, because without them the agent can't give us the provenance that was the whole point, and it can't tell an old runbook from a current one.&lt;br&gt;
&lt;/p&gt;

&lt;div class="highlight js-code-highlight"&gt;
&lt;pre class="highlight csharp"&gt;&lt;code&gt;&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;knowledge&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="nf"&gt;KnowledgeTools&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;store&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;

&lt;span class="n"&gt;IChatClient&lt;/span&gt; &lt;span class="n"&gt;agent&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="n"&gt;chatClient&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;AsBuilder&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;UseFunctionInvocation&lt;/span&gt;&lt;span class="p"&gt;()&lt;/span&gt;
    &lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Build&lt;/span&gt;&lt;span class="p"&gt;();&lt;/span&gt;

&lt;span class="kt"&gt;var&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;new&lt;/span&gt; &lt;span class="n"&gt;ChatOptions&lt;/span&gt;
&lt;span class="p"&gt;{&lt;/span&gt;
    &lt;span class="n"&gt;Tools&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="p"&gt;[&lt;/span&gt;&lt;span class="n"&gt;AIFunctionFactory&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;Create&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;knowledge&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;SearchKnowledge&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt;&lt;span class="p"&gt;:&lt;/span&gt; &lt;span class="s"&gt;"search_knowledge"&lt;/span&gt;&lt;span class="p"&gt;)]&lt;/span&gt;
&lt;span class="p"&gt;};&lt;/span&gt;

&lt;span class="n"&gt;List&lt;/span&gt;&lt;span class="p"&gt;&amp;lt;&lt;/span&gt;&lt;span class="n"&gt;ChatMessage&lt;/span&gt;&lt;span class="p"&gt;&amp;gt;&lt;/span&gt; &lt;span class="n"&gt;messages&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt;
&lt;span class="p"&gt;[&lt;/span&gt;
    &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ChatRole&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;System&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s"&gt;"""
&lt;/span&gt;        &lt;span class="n"&gt;You&lt;/span&gt; &lt;span class="n"&gt;answer&lt;/span&gt; &lt;span class="n"&gt;questions&lt;/span&gt; &lt;span class="n"&gt;about&lt;/span&gt; &lt;span class="n"&gt;our&lt;/span&gt; &lt;span class="n"&gt;services&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt; &lt;span class="n"&gt;Facts&lt;/span&gt; &lt;span class="n"&gt;about&lt;/span&gt; &lt;span class="n"&gt;our&lt;/span&gt; &lt;span class="n"&gt;own&lt;/span&gt; &lt;span class="n"&gt;systems&lt;/span&gt; &lt;span class="n"&gt;must&lt;/span&gt; &lt;span class="n"&gt;come&lt;/span&gt;
        &lt;span class="k"&gt;from&lt;/span&gt; &lt;span class="n"&gt;search_knowledge&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;you&lt;/span&gt; &lt;span class="n"&gt;must&lt;/span&gt; &lt;span class="n"&gt;name&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;source&lt;/span&gt; &lt;span class="k"&gt;and&lt;/span&gt; &lt;span class="n"&gt;its&lt;/span&gt; &lt;span class="n"&gt;date&lt;/span&gt; &lt;span class="k"&gt;for&lt;/span&gt; &lt;span class="n"&gt;each&lt;/span&gt; &lt;span class="n"&gt;one&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;
        &lt;span class="n"&gt;If&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;knowledge&lt;/span&gt; &lt;span class="k"&gt;base&lt;/span&gt; &lt;span class="n"&gt;has&lt;/span&gt; &lt;span class="n"&gt;nothing&lt;/span&gt; &lt;span class="k"&gt;on&lt;/span&gt; &lt;span class="n"&gt;the&lt;/span&gt; &lt;span class="n"&gt;question&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;say&lt;/span&gt; &lt;span class="n"&gt;so&lt;/span&gt; &lt;span class="n"&gt;instead&lt;/span&gt; &lt;span class="n"&gt;of&lt;/span&gt; &lt;span class="n"&gt;guessing&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;
        &lt;span class="s"&gt;"""),
&lt;/span&gt;    &lt;span class="k"&gt;new&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;ChatRole&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;User&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="s"&gt;"What breaks if we take billing-db offline on Sunday night?"&lt;/span&gt;&lt;span class="p"&gt;)&lt;/span&gt;
&lt;span class="p"&gt;];&lt;/span&gt;

&lt;span class="n"&gt;ChatResponse&lt;/span&gt; &lt;span class="n"&gt;response&lt;/span&gt; &lt;span class="p"&gt;=&lt;/span&gt; &lt;span class="k"&gt;await&lt;/span&gt; &lt;span class="n"&gt;agent&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;GetResponseAsync&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;messages&lt;/span&gt;&lt;span class="p"&gt;,&lt;/span&gt; &lt;span class="n"&gt;options&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;span class="n"&gt;Console&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="nf"&gt;WriteLine&lt;/span&gt;&lt;span class="p"&gt;(&lt;/span&gt;&lt;span class="n"&gt;response&lt;/span&gt;&lt;span class="p"&gt;.&lt;/span&gt;&lt;span class="n"&gt;Text&lt;/span&gt;&lt;span class="p"&gt;);&lt;/span&gt;
&lt;/code&gt;&lt;/pre&gt;

&lt;/div&gt;



&lt;p&gt;The last sentence of the system prompt matters very much. A model that is told to use the knowledge base but is not told what to do when it finds nothing will very often fall back to its parametric memory and produce a plausible answer about a system it has never seen, and that is exactly the failure the knowledge base exists to prevent.&lt;/p&gt;

&lt;p&gt;If more than one agent or tool needs the same knowledge, the next step is to put the search behind an MCP server instead of a method in one application, so that Claude Code, an IDE assistant and your own agents all use the same source. &lt;a href="https://dotnet-talk.com/blog/mcp-server-csharp-dotnet" rel="noopener noreferrer"&gt;Writing an MCP Server in C#&lt;/a&gt; covers that part.&lt;/p&gt;

&lt;h2&gt;
  
  
  The risk of a stale knowledge base
&lt;/h2&gt;

&lt;p&gt;There is one risk that is easy to miss. When an agent answers from its weights and is wrong, people have learned to be suspicious. When it answers from the knowledge base and cites a source, people trust it, so if the source is out of date the agent becomes confidently and convincingly wrong. A service dependency that was removed six months ago but is still an edge in the graph will send an engineer to the wrong place at three in the morning, and the citation will make it look correct.&lt;/p&gt;

&lt;p&gt;This is why maintenance has to be part of the design from the first version. Every fact should have a source and an updated date, facts that are derived from systems (deployment manifests, git history, tracing data) should be re-derived on a schedule rather than written by hand, and conflicts between sources should be visible instead of silently resolved. &lt;a href="https://dotnet-talk.com/blog/knowledge-graph-maintenance-reconciliation-worker" rel="noopener noreferrer"&gt;Keeping Your Knowledge Graph Current Without a Dedicated Team&lt;/a&gt; builds exactly this loop for a knowledge graph.&lt;/p&gt;

&lt;h2&gt;
  
  
  Where to start
&lt;/h2&gt;

&lt;p&gt;If you are building an agent and you are not sure if you need a knowledge base, a simple test is to write down ten real questions the agent should answer and mark for each one whether the answer is general knowledge, recent, specialised, private, or needs a source. If most of them are general, the model alone is probably enough. If most are specialised, private or need a source, which in my view is the case for almost every agent that does real work inside a company, then the knowledge base becomes the main part of the system, and the model becomes the part that reads it and reasons about it.&lt;/p&gt;

&lt;p&gt;From there the order that makes sense is usually:&lt;/p&gt;

&lt;ol&gt;
&lt;li&gt;Start with a document store and vector search over the documents you already have, and return the source and date with every chunk.&lt;/li&gt;
&lt;li&gt;Expose it as a tool and tell the agent explicitly what to do when the search finds nothing.&lt;/li&gt;
&lt;li&gt;When the questions start to be about relationships ("what depends on", "who owns", "what changed together"), add a knowledge graph next to it rather than trying to make embeddings answer them.&lt;/li&gt;
&lt;li&gt;Add agent memory when the agent needs to carry decisions from one session to the next, and give it decay and verification from the beginning.&lt;/li&gt;
&lt;li&gt;Automate the maintenance before you have many users, because a stale knowledge base loses trust very quickly and it is very difficult to win it back.&lt;/li&gt;
&lt;/ol&gt;

&lt;p&gt;The model gives an agent its ability to reason and to write, and that part keeps getting better with every release, but knowledge of your own systems, your decisions and the last few months has to come from somewhere else, and in an agentic system that place is the knowledge base, together with the work of keeping it current.&lt;/p&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Lewis, P. et al. &lt;em&gt;Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks&lt;/em&gt;, 2020. &lt;a href="https://arxiv.org/abs/2005.11401" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2005.11401&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Anthropic. &lt;em&gt;Models overview&lt;/em&gt;, Claude Platform documentation, accessed 16 October 2026. &lt;a href="https://platform.claude.com/docs/en/about-claude/models/overview" rel="noopener noreferrer"&gt;https://platform.claude.com/docs/en/about-claude/models/overview&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Kandpal, N. et al. &lt;em&gt;Large Language Models Struggle to Learn Long-Tail Knowledge&lt;/em&gt;, ICML 2023. &lt;a href="https://arxiv.org/abs/2211.08411" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2211.08411&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Mallen, A. et al. &lt;em&gt;When Not to Trust Language Models: Investigating Effectiveness of Parametric and Non-Parametric Memories&lt;/em&gt;, ACL 2023. &lt;a href="https://arxiv.org/abs/2212.10511" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2212.10511&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Liu, N. F. et al. &lt;em&gt;Lost in the Middle: How Language Models Use Long Contexts&lt;/em&gt;, 2023. &lt;a href="https://arxiv.org/abs/2307.03172" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2307.03172&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Edge, D. et al. &lt;em&gt;From Local to Global: A Graph RAG Approach to Query-Focused Summarization&lt;/em&gt;, 2024. &lt;a href="https://arxiv.org/abs/2404.16130" rel="noopener noreferrer"&gt;https://arxiv.org/abs/2404.16130&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Microsoft. &lt;em&gt;AIFunctionFactory.Create Method&lt;/em&gt;, .NET API reference. &lt;a href="https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.ai.aifunctionfactory.create" rel="noopener noreferrer"&gt;https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.ai.aifunctionfactory.create&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Microsoft. &lt;em&gt;Use the IChatClient interface&lt;/em&gt;, .NET documentation. &lt;a href="https://learn.microsoft.com/en-us/dotnet/ai/ichatclient" rel="noopener noreferrer"&gt;https://learn.microsoft.com/en-us/dotnet/ai/ichatclient&lt;/a&gt;
&lt;/li&gt;
&lt;/ol&gt;

</description>
      <category>rag</category>
      <category>knowledgegraph</category>
      <category>dotnet</category>
      <category>aiagents</category>
    </item>
    <item>
      <title>Why the Agile Coach Is Not a Luxury in a Software Team</title>
      <dc:creator>Mehdi Mohseni</dc:creator>
      <pubDate>Tue, 13 Oct 2026 13:28:32 +0000</pubDate>
      <link>https://dev.to/mehdimohseni82/why-the-agile-coach-is-not-a-luxury-in-a-software-team-4178</link>
      <guid>https://dev.to/mehdimohseni82/why-the-agile-coach-is-not-a-luxury-in-a-software-team-4178</guid>
      <description>&lt;p&gt;When a company has to reduce its costs, the agile coach is very often one of the first positions that is removed, and the reasoning usually sounds sensible: we already have a tech lead, we have a CTO, and the developers know what a sprint is, so why do we pay someone whose job is to run meetings? I have worked as a developer in teams for many years, and in my view this decision is one of the most expensive "savings" a software company can make. In this article I want to explain why the work of an agile coach can't simply be handed to the tech lead, why agile is about results and not about comfort, and why the ceremonies that many developers see as a waste of time are actually part of what keeps a team together.&lt;/p&gt;

&lt;h2&gt;
  
  
  The tech lead can't be the coach of their own team
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fj73q6t4ehwvade4dyxyn.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fj73q6t4ehwvade4dyxyn.webp" alt="A one to one conversation in a small glass meeting room" width="800" height="447"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;The first argument I hear is that a good tech lead or a good CTO can do this job as well, because they know the team, they know the product, and they are already in every meeting. Although this is partly true, but it misses the most important point, which is that the tech lead is part of the system that the coach has to look at.&lt;/p&gt;

&lt;p&gt;I'm not the first person to say that even very capable leaders need someone outside their own role to look at them. Eric Schmidt has told many times that when he was CEO of Google, board member John Doerr told him he needed a coach, and when Schmidt answered that he didn't, Doerr's reply was "No, no, everybody needs a coach." Schmidt's explanation of why it worked is, in my view, the best short description of the coach's job: "The one thing that people are never good at is seeing themselves as others see them." The coach Doerr brought in was Bill Campbell, who also worked with Steve Jobs and Larry Page, and Schmidt, Jonathan Rosenberg and Alan Eagle later wrote a whole book about his way of working, &lt;em&gt;Trillion Dollar Coach&lt;/em&gt; [1][2]. If the CEO of Google needed someone outside himself to see what he couldn't, it's difficult to argue that a tech lead with a full sprint of work doesn't.&lt;/p&gt;

&lt;p&gt;A tech lead is responsible for technical decisions, for the architecture, for code review and very often for delivery dates. That's a lot of responsibility, and it shapes how they see the team. When a sprint goes badly, the tech lead naturally looks for the technical cause: the estimate was wrong, the API was not ready, the tests were missing. Sometimes that is the real cause, but sometimes the real cause is how the team is being led, and it's very difficult for anyone to see that clearly when they are the one who is leading.&lt;/p&gt;

&lt;p&gt;Additionally, there is the question of who people talk to. A developer who feels that every decision is taken above their head, or that the workload is not fair, will usually not say this openly to the same person who reviews their pull requests and has an opinion in their performance review. They will say it to someone who has no technical authority over them and whose job is specifically to listen. That's because honest feedback needs a safe channel, and the tech lead, whatever good intentions they have, is not a neutral channel.&lt;/p&gt;

&lt;p&gt;The Scrum Guide itself is very clear about this. It doesn't describe the Scrum Master as a meeting organiser but says that "the Scrum Master is accountable for the Scrum Team's effectiveness", and it lists coaching the team members, causing the removal of impediments and "leading, training, and coaching the organization in its Scrum adoption" among the responsibilities of that role [3]. That is a full job, and it's a different job from designing the system and reviewing the code.&lt;/p&gt;

&lt;h2&gt;
  
  
  Two views that a technical leader doesn't have by default
&lt;/h2&gt;

&lt;p&gt;In my view the agile coach brings two ways of looking at the team which are very different from the technical view.&lt;/p&gt;

&lt;p&gt;The first one is the &lt;strong&gt;agile view&lt;/strong&gt;: how the work flows through the team, where it gets stuck, whether the team really plans together or only receives a list of tasks, whether the sprint goal means something or is just a label on the board. A coach notices when the process has slowly turned into something that has the names of Scrum but none of its purpose.&lt;/p&gt;

&lt;p&gt;The second one is close to the &lt;strong&gt;human resources view&lt;/strong&gt;: how people feel in the team, who has stopped speaking in meetings, where there is a conflict that nobody wants to touch, and whether the way the team is managed is building trust or slowly destroying it. Google's research on team effectiveness, known as Project Aristotle, found that psychological safety was the most important of the five dynamics they identified in effective teams, ahead of dependability, structure and clarity, meaning and impact [4]. The idea itself comes from Amy Edmondson at Harvard, whose 1999 study of 51 work teams defined psychological safety as a shared belief that the team is safe for interpersonal risk taking, and found that it was connected to how much a team actually learns [5]. Psychological safety is exactly the thing that a busy technical leader has the least time to look after.&lt;/p&gt;

&lt;p&gt;This is where the coach becomes really valuable. When the tech lead starts to manage the team in a wrong direction, for example by taking every decision alone, by overloading the sprint to satisfy a stakeholder, or by solving every problem personally instead of letting the team grow, the coach is the person who can see it early and help the lead to correct it. This matters more than it sounds, because the way a team is led has a very big effect on it. Gallup, analysing engagement data from millions of employees, found that the manager accounts for about 70% of the variance in team engagement [6]. When the leadership of a team goes in a wrong direction, the whole team follows it, and someone should be watching that direction. This is not a fight between the coach and the lead. A good coach works with the tech lead, and in many cases the tech lead is the person who benefits most from having one. Google's own research on managers, Project Oxygen, put "is a good coach" first in its list of behaviours of good managers [7], and I think that is exactly the point: coaching is so important that it needs someone who has time for it, and a tech lead who also owns the architecture and the delivery dates rarely has that time.&lt;/p&gt;

&lt;h2&gt;
  
  
  Agile is about performance, not about less pressure
&lt;/h2&gt;

&lt;p&gt;There is a common idea, also among managers, that agile is mainly about making developers comfortable: less pressure, fewer deadlines, more freedom. With this idea in mind, the agile coach looks like a nice-to-have position, something a company can afford when things are good and remove when things are hard.&lt;/p&gt;

&lt;p&gt;I think this idea is wrong. Agile methodology came from a very practical problem, which was that long plans made at the start of a project were wrong by the time the software was delivered. Short iterations, regular planning and regular inspection exist so that the team finds its mistakes early, while they are still cheap to fix. That is about results. A team that plans honestly, knows its real capacity and fixes its own problems every few weeks delivers more and delivers more predictably than a team that is simply pushed harder.&lt;/p&gt;

&lt;p&gt;It's also worth looking at which companies have treated this role as a standard part of the team and not as a decoration. When Henrik Kniberg and Anders Ivarsson described how Spotify organised its engineering in 2012, every squad, which was the small autonomous team at the centre of that model, had access to an agile coach who helped it to improve the way it worked [8]. That model was later studied and copied by many large organisations, and it came from a company whose main problem was moving fast, not keeping developers comfortable.&lt;/p&gt;

&lt;p&gt;So when we talk about the agile coach, we are talking about someone whose work is directly connected to the performance of the team and the results the team produces. Whether we like it or not, the cost of a team that works badly together is much higher than the salary of the person who helps it to work well, and that cost is mostly invisible because it appears as delays, rework and people leaving, not as a line in the budget.&lt;/p&gt;

&lt;h2&gt;
  
  
  Remote teams need it even more
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F6cwdcdugih3dhbsvrvt4.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2F6cwdcdugih3dhbsvrvt4.webp" alt="A developer working from home on a video call with the team" width="800" height="447"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;All of this becomes more important when the team works remotely. In an office, a lot of the coordination happens without anyone planning it: people hear each other's conversations, they notice when a colleague is frustrated, and small problems are solved at the coffee machine before they become big ones.&lt;/p&gt;

&lt;p&gt;In a remote team almost none of that happens by itself. A developer can be blocked for two days and nobody notices, a disagreement can stay in a private chat and grow, and a new team member can feel completely alone without anyone realising it. The only moments in which the whole team really meets are the ones that are planned, which means the quality of those moments decides a large part of the quality of the collaboration. Someone has to take care of them deliberately, and that is a very big part of what an agile coach does in a distributed team.&lt;/p&gt;

&lt;p&gt;This is not only a feeling. Researchers at Microsoft studied the emails, calendars, chats and calls of 61,182 Microsoft employees in the United States during the first half of 2020, when the whole company moved to remote work. They found that the collaboration network became more static and siloed, that the share of time people spent with colleagues in other groups dropped by about a quarter, and that communication moved from synchronous to asynchronous [9]. In other words, when nobody takes care of the connections inside and around a team, they get weaker.&lt;/p&gt;

&lt;h2&gt;
  
  
  The ceremonies are the glue of the team
&lt;/h2&gt;

&lt;p&gt;&lt;a href="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqyvy3dzf68nmllswtb5r.webp" class="article-body-image-wrapper"&gt;&lt;img src="https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fqyvy3dzf68nmllswtb5r.webp" alt="Hands placing sticky notes on a glass wall during a retrospective" width="800" height="447"&gt;&lt;/a&gt;&lt;/p&gt;

&lt;p&gt;This brings me to the meetings themselves. Sprint planning, the daily stand-up, the review and the retrospective are often described by developers as time that is taken away from "real work", and I understand this feeling, because a badly run meeting really is a waste of time. But the answer to a badly run meeting is to run it better, not to remove it.&lt;/p&gt;

&lt;p&gt;Each of these events has a specific job. Sprint planning is where the team agrees together what it is going to do and why, so that the work belongs to the team and not only to the person who wrote the tickets. The daily stand-up, which the Scrum Guide limits to fifteen minutes, is where blockers become visible while they are still small. The review is where the team and the stakeholders look at real software instead of status reports. And the retrospective is the moment in which the team looks at itself and decides what to change. The Scrum Guide says its purpose is "to plan ways to increase quality and effectiveness" [3], and this idea is older than Scrum's popularity: one of the twelve principles behind the Agile Manifesto is that "at regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly" [10].&lt;/p&gt;

&lt;p&gt;The retrospective is usually the first one to go, because it doesn't produce anything that can be shown on a board and because it's honestly not easy to run well. Removing it feels like a small saving in the first weeks, and nothing seems to break. In my experience, over a longer period it has very negative effects on the environment of the team, on collaboration and on teamwork, because the team loses the one place where problems are allowed to be said out loud. Norm Kerth, who wrote one of the first books about retrospectives, suggested opening every one of them with what he called the Prime Directive: "Regardless of what we discover, we understand and truly believe that everyone did the best job they could, given what they knew at the time, their skills and abilities, the resources available, and the situation at hand." [11] A sentence like that only works when someone is responsible for making it true in the room, and that is a facilitation skill, not a technical one. The problems don't disappear when the meeting disappears; they just move into private conversations, into frustration, and eventually into resignations.&lt;/p&gt;

&lt;p&gt;In short, these ceremonies are part of how a team is built and maintained. They are the glue that holds a group of individual developers together as a team, and keeping that glue in good condition is a real job, which needs time, skill and a person who is responsible for it.&lt;/p&gt;

&lt;h2&gt;
  
  
  What I would suggest to a company that is thinking about this role
&lt;/h2&gt;

&lt;p&gt;If a company has decided that it can't afford a full time agile coach for every team, I understand that, and there are reasonable middle ways: one coach shared between two or three teams, or a coach who works intensively with a new or struggling team for a few months. What I would not suggest is to give the role to the tech lead "on top of" their current job and expect the same result, because, as I explained above, the tech lead is inside the problem that the coach has to see from outside.&lt;/p&gt;

&lt;p&gt;And if your team has already dropped the retrospective because it felt like a waste of time, it may be worth bringing it back for a few sprints, run by someone who is not the tech lead, and seeing what the team says when it finally has a place to say it.&lt;/p&gt;

&lt;h2&gt;
  
  
  References
&lt;/h2&gt;

&lt;ol&gt;
&lt;li&gt;Eric Schmidt on the best advice he received, quoted in "Everybody needs a coach", Daily FT: &lt;a href="https://www.ft.lk/Management/Everybody-needs-a-coach/53-706873" rel="noopener noreferrer"&gt;https://www.ft.lk/Management/Everybody-needs-a-coach/53-706873&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Eric Schmidt, Jonathan Rosenberg and Alan Eagle, &lt;em&gt;Trillion Dollar Coach: The Leadership Playbook of Silicon Valley's Bill Campbell&lt;/em&gt;, Harper Business, 2019.&lt;/li&gt;
&lt;li&gt;Ken Schwaber and Jeff Sutherland, &lt;em&gt;The Scrum Guide&lt;/em&gt;, November 2020: &lt;a href="https://scrumguides.org/scrum-guide.html" rel="noopener noreferrer"&gt;https://scrumguides.org/scrum-guide.html&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Google re:Work, "Guide: Understand team effectiveness" (Project Aristotle): &lt;a href="https://rework.withgoogle.com/intl/en/guides/understand-team-effectiveness" rel="noopener noreferrer"&gt;https://rework.withgoogle.com/intl/en/guides/understand-team-effectiveness&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Amy Edmondson, "Psychological Safety and Learning Behavior in Work Teams", &lt;em&gt;Administrative Science Quarterly&lt;/em&gt; 44(2), 1999, pp. 350 to 383.&lt;/li&gt;
&lt;li&gt;Gallup, "Managers Account for 70% of Variance in Employee Engagement": &lt;a href="https://news.gallup.com/businessjournal/182792/managers-account-variance-engagement.aspx" rel="noopener noreferrer"&gt;https://news.gallup.com/businessjournal/182792/managers-account-variance-engagement.aspx&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Google re:Work, Project Oxygen, the behaviours of great managers.&lt;/li&gt;
&lt;li&gt;Henrik Kniberg and Anders Ivarsson, "Scaling Agile @ Spotify with Tribes, Squads, Chapters and Guilds", 2012.&lt;/li&gt;
&lt;li&gt;Longqi Yang, David Holtz et al., "The effects of remote work on collaboration among information workers", &lt;em&gt;Nature Human Behaviour&lt;/em&gt;, 2021: &lt;a href="https://www.microsoft.com/en-us/research/?p=772330" rel="noopener noreferrer"&gt;https://www.microsoft.com/en-us/research/?p=772330&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;"Principles behind the Agile Manifesto": &lt;a href="https://agilemanifesto.org/principles.html" rel="noopener noreferrer"&gt;https://agilemanifesto.org/principles.html&lt;/a&gt;
&lt;/li&gt;
&lt;li&gt;Norm Kerth, &lt;em&gt;Project Retrospectives: A Handbook for Team Reviews&lt;/em&gt;, Dorset House, 2001.&lt;/li&gt;
&lt;/ol&gt;

</description>
      <category>agile</category>
      <category>scrum</category>
      <category>leadership</category>
      <category>career</category>
    </item>
  </channel>
</rss>
