<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Agentspan - Medium]]></title>
        <description><![CDATA[The durable agent orchestration platform - Medium]]></description>
        <link>https://medium.com/agentspan?source=rss----6f29461513d7---4</link>
        <image>
            <url>https://cdn-images-1.medium.com/proxy/1*TGH72Nnw24QL3iV9IOm4VA.png</url>
            <title>Agentspan - Medium</title>
            <link>https://medium.com/agentspan?source=rss----6f29461513d7---4</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 10:51:57 GMT</lastBuildDate>
        <atom:link href="https://medium.com/feed/agentspan" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Your Agent Worked Yesterday. Does It Still Work Today?]]></title>
            <link>https://medium.com/agentspan/your-agent-worked-yesterday-does-it-still-work-today-c63d735746f0?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/c63d735746f0</guid>
            <category><![CDATA[agentic-ai]]></category>
            <dc:creator><![CDATA[Deepti Reddy]]></dc:creator>
            <pubDate>Fri, 05 Jun 2026 18:26:59 GMT</pubDate>
            <atom:updated>2026-06-28T12:38:19.138Z</atom:updated>
            <content:encoded><![CDATA[<p>By Deepti Reddy · May 2026</p><h3>Why testing agents is actually different</h3><p>For thirty years, “testing” has meant you write a function, write an assertion, compare expected to actual. The output remains the same for a given set of inputs. If it passed yesterday and the code didn’t change, it passes today.</p><p>Agents break that contract in three places at once.</p><p><strong>The model is non-deterministic.</strong> Send the same prompt twice and you will get two different answers. Change the model version and you might get a wildly different result. Your provider can roll out a sub-version that subtly changes how your agent reasons and your agent starts to behave a bit differently</p><p><strong>The orchestration is dynamic.</strong> A modern agent isn’t one LLM call. It routes, hands off, retries, calls tools, and loops. A regression often doesn’t show up as “wrong answer”, it shows up as “called the wrong specialist,” “skipped a tool,” “ran the editor before the writer.”</p><p><strong>Correctness is multi-dimensional.</strong> A response can be polite, factually accurate, and still miss the point entirely. A summary can be technically correct but not relevant to the user. “Is this output good?” is traced across accuracy, tone, completeness, length, and the right tradeoff depends on the prompt.</p><p>Stack those three together and every prompt tweak, every model bump, every new tool is a small change but now it fails and you only find out when it breaks in production through a support ticket created by an upset customer.</p><h3>So what is an eval, really?</h3><p>An eval is a test case for a system that does not behave the same way each time the test case is run.</p><p>Instead of “assert output equals X,” you assert properties of the output, the trace, the score and you run a whole dataset of them, not just one.</p><p>Across every serious agent eval framework I’ve used such as Braintrust, LangSmith, and Weave, the same three questions show up:</p><ol><li><strong>Did the agent do the right things?</strong> (Structural)</li><li><strong>Is the output any good?</strong> (Semantic)</li><li><strong>Does my own code around the agent work?</strong> (Deterministic)</li></ol><p>The frameworks differ in syntax but the questions are the same kind. Below is how Agentspan handles each.</p><h3>Question 1 — Did the agent do the right things?</h3><p>It may ask things like did the right tool fire and in the right order? Did the handoff happen and did the output contain the field the downstream code is going to parse?</p><p>These are deterministic questions about the execution trace, even though the LLM that produced the trace isn’t deterministic.</p><p>The base primitive is an EvalCase:</p><pre>from agentspan.agents import AgentRuntime<br>  from agentspan.agents.testing import CorrectnessEval, EvalCase<br><br>  case = EvalCase(<br>      name=&quot;refund_routes_to_billing&quot;,<br>      agent=support_agent,<br>      prompt=&quot;I need a refund for order #123&quot;,<br>      expect_handoff_to=&quot;billing&quot;,<br>      expect_tools=[&quot;lookup_order&quot;],<br>  )<br><br>  with AgentRuntime() as runtime:<br>      results = CorrectnessEval(runtime).run([case])<br>      results.print_summary()</pre><p>Declare what should happen, the runner runs it, the trace gets checked.</p><p>The vocabulary covers the obvious axes: expect_tools, expect_tools_not_used, expect_output_contains, assert_max_turns (catch infinite loops or long loops), assert_output_type (for structured outputs). For anything else, custom_assertions=[fn].</p><p>You may keep my structural cases simple. “This message should route to billing.” “This call should hit get_weather and get_fun_fact, in that order.”</p><h3>The orchestration check that catches the pipeline bugs</h3><p>When you compose agents such as researcher &gt;&gt; writer &gt;&gt; editor, or a router, or a swarm, the strategy itself is testable. A sequential pipeline must run every sub-agent in order, exactly once and a router must pick exactly one specialist. Agentspan knows what a correct trace shape should look like for each strategy, and it can validate that automatically:</p><pre>EvalCase(<br>name=&quot;pipeline_runs_in_order&quot;,<br>agent=pipeline, # researcher &gt;&gt; writer &gt;&gt; editor<br>prompt=&quot;Topic: LLM evals&quot;,<br>)<br># validate_orchestration=True is the default - no opt-in needed</pre><p>When the writer runs before the researcher, or the editor gets skipped, you get a clear failure:</p><pre>Agents skipped (never ran): [‘editor’]. Expected all of: [‘researcher’, ‘writer’, ‘editor’]</pre><p>These are the bugs that slip past output level assertions.</p><h3>Question 2 — Is the output any good?</h3><p>Substring matches won’t tell you if the tone of the agent is right according to the prompt instructions you gave to the agent. They won’t tell you if your summary covers the main point. They will tell you whether the agent put the temperature in the response and not much more.</p><p>For the fuzzy parts, you write a criterion in plain English and let another LLM judge it:</p><pre>from agentspan.agents.testing.semantic import assert_output_satisfies<br>assert_output_satisfies(<br>result,<br>&quot;output should be friendly and conversational, not robotic&quot;,<br>threshold=0.7,<br>)</pre><p>The judge returns a score between 0–1 and a written reason. The failure message tells you why it failed and not just that it did.</p><p>You can wire both structural and semantic evals into one case:</p><pre>EvalCase(<br>name=&quot;sf_weather&quot;,<br>agent=weather_agent,<br>prompt=&quot;Tell me the weather and a fun fact about SF.&quot;,<br>expect_tools=[&quot;get_weather&quot;, &quot;get_fun_fact&quot;], # structural<br>custom_assertions=[lambda r: assert_output_satisfies(<br>r, &quot;covers both weather and a fun fact&quot;, threshold=0.7), # semantic<br>],<br>)</pre><h3>Question 3 — Does your code work?</h3><p>You wrote the tool function and you wrote the validator. You also wrote the post-processor that turns the agent’s output into a Slack message. None of that needs an LLM to test and none of it should be paying a per-token fee on every CI run if you care about token costs.</p><p>mock_run lets you script a trace by hand:</p><pre>from agentspan.agents.testing import mock_run, MockEvent, expect<br>result = mock_run(<br>support_agent,<br>&quot;I need a refund&quot;,<br>events=[<br>MockEvent.tool_call(&quot;lookup_order&quot;, {&quot;order_id&quot;: &quot;123&quot;}),<br>MockEvent.handoff(&quot;billing&quot;),<br>MockEvent.done(&quot;Routed to billing.&quot;),<br>],<br>)<br>expect(result).completed().handoff_to(&quot;billing&quot;)</pre><p>This uses no LLM and runs in milliseconds. The mock auto-executes the real tool functions if the agent has them, so your tool code is still exercised, you just skip the model that decides to call it.</p><p>The thing I want to underline is that <strong>mocks test your code and evals test the model’s behavior.</strong> They catch different bugs but you need both.</p><h3>Comparing models and prompts</h3><p>Once your suite is green, the question shifts: should I switch to a cheaper model? Does the new prompt actually do better? Agentspan can run the same dataset across multiple model/prompt variants concurrently.</p><h3>What a practical setup looks like</h3><p>I run different eval categories at different cadences.</p><ul><li><strong>Deterministic mocks</strong> for everything I wrote myself such as every commit. This will run in milliseconds and no API key required for an LLM</li><li><strong>Structural evals</strong> (20–50 cases) covering tool use, routing, orchestration on every PR. Strategy validation is on by default.</li><li><strong>Semantic evals</strong> (5–15 cases) where quality matters nightly or whenever I change the prompt or model.</li><li><strong>Side-by-side benchmarks</strong> — use this only when deciding between models or prompt variants.</li></ul><p>Five structural cases on the paths you care most about, one mock per piece of custom code and a semantic check the first time someone asks, “but is the tone right?” You can always add more evals as you scale the agent.</p><h3>Try it</h3><p>To get started fresh:</p><pre>pip install agentspan[testing]<br>agentspan server start</pre><p>The agent that worked yesterday should still work today. Evals are how you actually know.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c63d735746f0" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/your-agent-worked-yesterday-does-it-still-work-today-c63d735746f0">Your Agent Worked Yesterday. Does It Still Work Today?</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[From SQL Chatbot to Autonomous Insurance Agent: Building a Multi-Agent System with AgentSpan]]></title>
            <link>https://medium.com/agentspan/from-sql-chatbot-to-autonomous-insurance-agent-building-a-multi-agent-system-with-agentspan-1c973dd1f4b4?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/1c973dd1f4b4</guid>
            <category><![CDATA[multi-agent-systems]]></category>
            <category><![CDATA[llm-guardrails]]></category>
            <category><![CDATA[agentic-engineering]]></category>
            <category><![CDATA[human-in-the-loop]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Adrian Warman]]></dc:creator>
            <pubDate>Thu, 21 May 2026 17:38:19 GMT</pubDate>
            <atom:updated>2026-05-21T17:38:19.038Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*inGdltIemkIw1oSe_x7L0w.png" /></figure><p>I had a simple problem, I’m spending way too much time pulling data from our insurance database. Checking claim statuses, investigating suspicious claims, running portfolio health checks, it’s all SQL queries across multiple tables, cross-referencing results, and copying numbers into spreadsheets. I wanted an AI agent that could do this for me to save time.</p><p>What I ended up building code wise was actually pretty straightforward as Agentspan let me evolve from a basic chatbot into a multi-agent system where specialists autonomously investigate claims, analyze portfolios, and generate reports and graphs. Here’s a walkthrough of how that evolution happened.</p><h3>Chapter 1: The Simple Agent</h3><p>I started with the most basic thing possible, an agent that can query an SQLite database.</p><pre>from agentspan.agents import Agent, AgentRuntime, tool<br>import json, sqlite3</pre><pre>@tool<br>def query_database(sql_query: str) -&gt; str:<br>    &quot;&quot;&quot;Execute a read-only SQL query against the insurance database.&quot;&quot;&quot;<br>    conn = sqlite3.connect(&quot;insurance.db&quot;)<br>    conn.row_factory = sqlite3.Row<br>    cur = conn.cursor()<br>    cur.execute(sql_query)<br>    columns = [desc[0] for desc in cur.description]<br>    rows = [dict(zip(columns, row)) for row in cur.fetchall()]<br>    conn.close()<br>    return json.dumps({&quot;data&quot;: rows, &quot;row_count&quot;: len(rows)})</pre><pre>agent = Agent(<br>    name=&quot;insurance_agent&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;You are an insurance data assistant. Use query_database for SELECT queries.&quot;,<br>    tools=[query_database],<br>)</pre><pre>with AgentRuntime() as runtime:<br>    result = runtime.run(agent, &quot;How many open claims do we have?&quot;)<br>    print(result.output[&quot;result&quot;])</pre><p>This worked fine. I could ask natural language questions and get answers from my database. The agent translated my questions like “how many open claims” into SELECT COUNT(*) FROM claims WHERE status = &#39;OPEN&#39; and returned the result. Great!</p><p>But this was just a chatbot wrapping SQL. I could have built this with any framework, or even a simple API. That’s not really an agent though, it’s just a translator.</p><h3>Chapter 2: The Problems I Hit</h3><p>As I started using it for real work, the limitations became obvious real fast.</p><p><strong>No memory.</strong> I’d ask “show me policyholders by risk tier” and get a nice table of the data. Then I’d say “make a pie chart of that” and the agent had no idea what “that” was referring to. Every request was isolated. Every query started from scratch as in every time I asked it a question it was like I was asking it something for the first time.</p><p><strong>No safety.</strong> I gave the agent a modify_database tool so I could update records. It worked but maybe it worked a little too well. I had asked it to &quot;flag policyholder 42 as high risk&quot; and it would just run the UPDATE statement immediately. No confirmation, no review. For a database with real customer data, that&#39;s terrifying. We don&#39;t want agents to just be freely modifying our data. What if the LLM thought when I ask it about some data that I wanted to change it? Sometimes these LLMs can make some unpredictable assumptions about what you are asking it.</p><p><strong>No guardrails.</strong> The agent would happily include phone numbers, email addresses, and dates of birth in its responses. Even social security numbers! When you’re working with sensitive data, that’s a problem.</p><p><strong>Not actually agentic.</strong> The biggest issue was that I had to direct every step. “Run this query.” “Now run that query.” “Now compare the results, but also here’s those results for you since you don’t know what I’m talking about?!” I was doing the thinking, the agent was just executing. If I wanted to investigate a suspicious claim, I had to manually ask for the claim details, then the policyholder profile, then their claims history, then check for fraud flags. That’s four separate prompts. An actual analyst would just do all of that on their own.</p><h3>Chapter 3: Adding Memory</h3><p>The first fix was the easiest. AgentSpan has ConversationMemory built in. You attach it to the agent and manually add messages after each turn.</p><pre>from agentspan.agents import ConversationMemory</pre><pre>memory = ConversationMemory(max_messages=20)</pre><pre>agent = Agent(<br>    name=&quot;insurance_agent&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;You are an insurance data assistant.&quot;,<br>    tools=[query_database, generate_chart],<br>    memory=memory,<br>)</pre><pre># After each turn, store the exchange in memory<br>memory.add_user_message(&quot;Show me policyholders by risk tier&quot;)<br>handle = runtime.start(agent, &quot;Show me policyholders by risk tier&quot;)<br># ... poll for result ...<br>memory.add_assistant_message(result_text)</pre><pre># Next turn — the agent now knows what &quot;that&quot; means<br>memory.add_user_message(&quot;Make a pie chart of that&quot;)<br>handle = runtime.start(agent, &quot;Make a pie chart of that&quot;)</pre><p>One thing I learned: runtime.run() does NOT auto-populate memory. You have to manually call memory.add_user_message() and memory.add_assistant_message() after each turn. I also found it useful to include tool result data in the assistant message so the agent remembers what data it actually returned:</p><pre># Include tool results in the assistant message for context<br>assistant_msg = result_text<br>for tr in tool_results:<br>    assistant_msg += f&quot;\n[Query: {tr[&#39;sql&#39;]} | Data: {tr[&#39;data&#39;][:500]}]&quot;<br>memory.add_assistant_message(assistant_msg)</pre><p>With this, multi-turn conversations work naturally. “Show me claims by status” → “make a pie chart of that” → “how many of those are urgent?”. The agent is able to maintain full context so I can ask follow-up questions easily.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/699/1*m57LYlCZHwKPazpwigVTRA.png" /></figure><h3>Chapter 4: Adding Safety with Human-in-the-Loop</h3><p>For data modifications, I needed a human approval step. AgentSpan has human_tool, a special tool type that pauses execution and waits for a human to respond. In this case, a simple response of either &#39;Accept&#39; or &#39;Reject&#39;.</p><pre>from agentspan.agents import human_tool</pre><pre>request_approval = human_tool(<br>    name=&quot;request_data_change_approval&quot;,<br>    description=&quot;Pause and wait for human approval before modifying data.&quot;,<br>    input_schema={<br>        &quot;type&quot;: &quot;object&quot;,<br>        &quot;properties&quot;: {<br>            &quot;sql_query&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;description&quot;: &quot;The SQL query to execute if approved.&quot;},<br>            &quot;description&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;description&quot;: &quot;What this change does.&quot;},<br>            &quot;impact&quot;: {&quot;type&quot;: &quot;string&quot;, &quot;description&quot;: &quot;Expected impact.&quot;},<br>        },<br>        &quot;required&quot;: [&quot;sql_query&quot;, &quot;description&quot;, &quot;impact&quot;],<br>    },<br>)</pre><p>The key insight is that the agent’s instructions tell it to call request_data_change_approval BEFORE calling modify_database. The execution pauses server-side, not in the client, not with a timeout, but as a durable workflow that waits indefinitely. The best part is I can handle this human tool response from anywhere! For the sake of this agent, I just handle those responses in the simple chat UI I built, but I could do this using emails or a separate UI or even just a simple curl request.</p><pre>agent = Agent(<br>    name=&quot;insurance_agent&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;&quot;&quot;...<br>    For ANY data modification, you MUST:<br>    1. Call request_data_change_approval with the SQL and description<br>    2. Wait for the human response<br>    3. If approved, call modify_database<br>    4. If rejected, acknowledge and do NOT execute<br>    &quot;&quot;&quot;,<br>    tools=[query_database, modify_database, request_data_change_approval],<br>)</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6FOKVj_39YLTB1egjN376Q.png" /></figure><p>Now when I say “flag policyholder 42 as high risk,” the agent builds the UPDATE statement, presents it for approval with a description of the impact, and waits. I review the SQL, click approve or reject, and the execution resumes. Read operations still flow freely and writes are now gated.</p><h3>Chapter 5: Adding Guardrails</h3><p>PII protection was straightforward with RegexGuardrail:</p><pre>from agentspan.agents import RegexGuardrail</pre><pre>no_pii = RegexGuardrail(<br>    name=&quot;no_pii&quot;,<br>    patterns=[<br>        r&quot;\b\d{3}-\d{2}-\d{4}\b&quot;,      # SSN<br>        r&quot;\b\d{2}/\d{2}/\d{4}\b&quot;,      # DOB<br>        r&quot;\(\d{3}\)\s?\d{3}-\d{4}&quot;,     # Phone numbers<br>    ],<br>    message=&quot;Remove PII from the response. Use names and IDs only.&quot;,<br>    on_fail=&quot;retry&quot;,<br>    max_retries=2,<br>)</pre><pre>no_bulk_data = RegexGuardrail(<br>    name=&quot;no_bulk_data&quot;,<br>    patterns=[r&quot;@\w+\.\w+&quot;],           # Email addresses<br>    message=&quot;Do not include email addresses in responses.&quot;,<br>    on_fail=&quot;retry&quot;,<br>    max_retries=2,<br>)</pre><pre>agent = Agent(<br>    name=&quot;insurance_agent&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;...&quot;,<br>    tools=[...],<br>    guardrails=[no_pii, no_bulk_data],<br>)</pre><p>If the agent’s response contains a pattern matching a SSN, phone number, or email address, Agentspan automatically retries the generation with the guardrail message injected. The agent actually learns to exclude PII on the retry. So no manual filtering, no post-processing, it’s handled at the framework level.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aZ7pZlT63McNXSQZ8Za39w.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YVVSJFWXW5x0RDMwS0cl-w.png" /></figure><h3>Chapter 6: The Leap — Multi-Agent Coordination</h3><p>At this point I had a pretty solid agent. It had memory, safety, guardrails. But it still wasn’t that agentic. I was still having to direct every query.</p><p>What I wanted was the ability to say “investigate claim CLM-5334” and have the agent autonomously pull the claim details, check the policyholder’s history, search for similar claims, analyze fraud indicators, and produce a recommendation. But I don’t want to have to give it five prompts to do so. I also want to be able to talk to the same agent with different kinds of requests, like “Show me the most recent claims made”, “investigate this claim”, “run a full scan and search for any fraud activity”.</p><p>The solution was splitting the work across specialist agents and using a coordinator.</p><pre>from agentspan.agents import agent_tool</pre><pre>claims_investigator = Agent(<br>    name=&quot;claims_investigator&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;&quot;&quot;You are a Claims Investigator. When given a claim to investigate,<br>    AUTONOMOUSLY perform these steps without asking the user:</pre><pre>    1. Fetch the claim details<br>    2. Pull the policyholder&#39;s profile and risk tier<br>    3. Analyze their claims history (frequency, amounts, types)<br>    4. Search for similar claims in the same region/timeframe<br>    5. Check for fraud indicators<br>    6. Produce an investigation report with a recommendation<br>    &quot;&quot;&quot;,<br>    tools=[query_database, generate_chart],<br>    max_turns=15,<br>)</pre><pre>portfolio_analyst = Agent(<br>    name=&quot;portfolio_analyst&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;&quot;&quot;You are a Portfolio Analyst. Autonomously execute:<br>    1. Calculate loss ratio by policy type<br>    2. Identify concentration risks<br>    3. Find upcoming high-risk renewals<br>    4. Check payment health<br>    5. Generate charts for key findings<br>    6. Produce an executive summary with action items<br>    &quot;&quot;&quot;,<br>    tools=[query_database, generate_chart],<br>    max_turns=20,<br>)</pre><pre>data_query_agent = Agent(<br>    name=&quot;data_query_agent&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;Handle simple data queries and visualizations.&quot;,<br>    tools=[query_database, generate_chart],<br>)</pre><p>The coordinator uses agent_tool() to wrap each specialist as a callable tool:</p><pre>coordinator = Agent(<br>    name=&quot;insurance_coordinator&quot;,<br>    model=&quot;openai/gpt-4o&quot;,<br>    instructions=&quot;&quot;&quot;You coordinate a team of specialists:<br>    - investigate_claim: for claim investigations<br>    - analyze_portfolio: for portfolio health checks<br>    - query_data: for simple data lookups<br>    Route each request to the right specialist.<br>    &quot;&quot;&quot;,<br>    tools=[<br>        agent_tool(claims_investigator, name=&quot;investigate_claim&quot;,<br>                   description=&quot;Run a full claim investigation&quot;),<br>        agent_tool(portfolio_analyst, name=&quot;analyze_portfolio&quot;,<br>                   description=&quot;Run a portfolio health check&quot;),<br>        agent_tool(data_query_agent, name=&quot;query_data&quot;,<br>                   description=&quot;Simple data query or chart&quot;),<br>        modify_database,<br>        request_data_change_approval,<br>    ],<br>    guardrails=[no_pii, no_bulk_data],<br>)</pre><p>Now when I say “investigate claim CLM-5334,” the coordinator routes to the Claims Investigator, which autonomously runs 6+ database queries, cross-references the results, and produces a structured investigation report, all from a single prompt. The Portfolio Analyst does the same for portfolio health checks, running 7+ queries and generating charts.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1005/1*zGNf4gIzNDeITGnGJfB3xA.png" /></figure><p>The agents actually have the same tools, but the difference is the instructions. They know HOW to investigate, what to look for, and in what order. The “agentic” behavior comes from giving the agent a methodology, not more tools.</p><h3>What Makes This an Agent, Not a Chatbot</h3><p>Looking back, the difference between the first version and the final version isn’t the number of tools or the size of the codebase. It’s autonomy.</p><p>In version 1, I said things like “Run this query. Now run that query. How about this one?“</p><p>In the final version, I say “Investigate this claim.” The coordinator agent decides what kind of request this is and routes it to the required specialist sub agent. Then that agent decides what data to look at, runs 6 queries in sequence based on what it finds at each step, cross-references fraud patterns, and produces a recommendation. I didn’t actually direct any of it.</p><p>That’s the difference between a tool and an agent. A tool does what you tell it. An agent decides what to do.</p><h3>AgentSpan Features That Made This Possible</h3><ul><li><strong>ConversationMemory</strong> — Multi-turn context across interactions. The agent remembers what data it returned and what you asked about.</li><li><strong>human_tool</strong> — Durable human-in-the-loop. Write operations pause the execution (server-side, crash-proof) until a human approves.</li><li><strong>RegexGuardrail</strong> — PII protection at the framework level. Automatic retry if the agent leaks sensitive data.</li><li><strong>agent_tool</strong> — Wrap specialist agents as callable tools. The coordinator decides who handles what.</li><li><strong>Durable execution</strong> — Every run is a workflow managed by AgentSpan. You can view the full execution tree in the AgentSpan UI and see which sub-agent handled the request, what queries it ran, and how long each step took.</li><li><strong>Server-side orchestration</strong> — The agent definitions, tool dispatch, and execution state all live on the server. Workers can restart without losing state. The frontend is just a thin UI that polls for status.</li></ul><h3>Try It Yourself</h3><p>The full demo is available as a standalone repo that you can clone and run in minutes.</p><p><a href="https://github.com/AdrianWarman-Orkes/agentspan-insurance-agent"><strong>https://github.com/AdrianWarman-Orkes/agentspan-insurance-agent</strong></a></p><p>It includes everything you need, the multi-agent coordinator, a SQLite database pre-seeded with ~18,500 rows of fictional insurance data, and a simple frontend with chat, data tables, charts, and human-in-the-loop approval.</p><h3>Quick start</h3><pre># 1. Start AgentSpan<br>npm install -g @agentspan-ai/agentspan<br>agentspan server start --key OPENAI_API_KEY=sk-...</pre><pre># 2. Run the agent (in a new terminal)<br>cd sekro-insurance-demo<br>python -m venv .venv &amp;&amp; source .venv/bin/activate<br>pip install -r requirements.txt<br>python seed.py          # Creates insurance.db with ~18,500 rows of sample data<br>python server.py        # Deploys the agent + starts HTTP server on port 8080</pre><pre># 3. Start the frontend (in another terminal)<br>cd sekro-insurance-demo/frontend<br>npm install &amp;&amp; npm run dev</pre><p>Open http://localhost:3000 and try:</p><ul><li><strong>“How many open claims do we have?”</strong> — simple data query</li><li><strong>“Investigate claim CLM-5334”</strong> — autonomous 6-step investigation with fraud analysis</li><li><strong>“Run a portfolio health check”</strong> — autonomous 7-step analysis with charts</li><li><strong>“Flag policyholder 42 as high risk”</strong> — triggers human-in-the-loop approval</li><li><strong>“Show me claims by status”</strong> then <strong>“make a pie chart of that”</strong> — multi-turn memory</li></ul><p>You can also open the AgentSpan UI at http://localhost:6767 to see the full execution trace, every tool call, every sub-agent invocation, and every decision the coordinator made.</p><p><em>Built with </em><a href="https://agentspan.ai/"><em>AgentSpan</em></a><em> by Orkes. AgentSpan is an open-source framework for building durable, production-grade AI agents.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=1c973dd1f4b4" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/from-sql-chatbot-to-autonomous-insurance-agent-building-a-multi-agent-system-with-agentspan-1c973dd1f4b4">From SQL Chatbot to Autonomous Insurance Agent: Building a Multi-Agent System with AgentSpan</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[See Inside Your Agent: Real-Time Streaming with Agentspan]]></title>
            <link>https://medium.com/agentspan/see-inside-your-agent-real-time-streaming-with-agentspan-3a2bd110ef61?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/3a2bd110ef61</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <dc:creator><![CDATA[Deepti Reddy]]></dc:creator>
            <pubDate>Fri, 15 May 2026 19:54:45 GMT</pubDate>
            <atom:updated>2026-06-28T12:41:48.046Z</atom:updated>
            <content:encoded><![CDATA[<p><em>By Deepti Reddy | May 2026</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1004/1*kRfg3WLI88j9aXZN6phvzw.png" /></figure><p>When you call run() in Agentspan, it blocks until the agent is done and returns a result. Clean and simple. But you see nothing while the agent is working, no indication of what it is thinking, which tools it called, or why it made the decisions it did.</p><p>That is fine for a batch job. It is not fine when you are debugging a failure, building a UI that shows progress, or running an agent that might take 30 seconds to complete.</p><p>That is what stream() is for. Instead of waiting for the final result, you get events as the agent executes — every reasoning step, every tool call, every tool result, and finally the output. Same agent, same execution. Just visible.</p><h3>What is Agentspan</h3><p>Agentspan is an orchestration layer for building, bringing, and observing AI agents as durable workflows.</p><ul><li><strong>Build</strong>: define agents with the Agentspan SDK using Agent, @tool, and 8 multi-agent strategies. Compiles to server-side workflows that survive crashes.</li><li><strong>Bring</strong>: already using an agent framework such as LangGraph, OpenAI Agents SDK, or Google ADK? Pass your agents directly to run(). Agentspan adds durability and orchestration on top.</li><li><strong>Observe</strong>: every execution is inspectable in the dashboard. See agent flows, inputs/outputs, tool calls, and token usage. Debug failures, replay runs.</li></ul><h3>Setup</h3><p>Two commands:</p><pre>pip install agentspan<br>agentspan server start</pre><p>This gives you a local Agentspan server with a visual dashboard at localhost:6767.</p><h3>What we are building</h3><p>An ops agent that investigates a service incident. It has three tools:</p><ul><li>check_service — checks health and error rate</li><li>get_recent_logs — fetches recent log lines</li><li>restart_service — restarts a service</li></ul><p>We run the same agent twice against the same prompt. First with run(). Then with stream(). The difference is what you see while it runs.</p><h3>The agent</h3><p>from agentspan.agents import Agent, AgentRuntime, EventType, tool</p><pre>@tool<br>def check_service(service_name: str) -&gt; dict:<br>&quot;&quot;&quot;Check the health and recent error rate of a service.&quot;&quot;&quot;<br>…<br>@tool<br>def get_recent_logs(service_name: str, lines: int = 20) -&gt; dict:<br>&quot;&quot;&quot;Fetch the most recent log lines for a service.&quot;&quot;&quot;<br>…<br>@tool<br>def restart_service(service_name: str) -&gt; dict:<br>&quot;&quot;&quot;Restart a service.&quot;&quot;&quot;<br>…<br>agent = Agent(<br>name=&quot;ops_agent&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>tools=[check_service, get_recent_logs, restart_service],<br>instructions=(<br>&quot;You are an operations agent investigating a service incident. &quot;<br>&quot;Check the affected service, look at recent logs, identify the root cause, &quot;<br>&quot;and decide whether to restart. Be methodical - check before you act.&quot;<br>),<br>)</pre><p>Nothing unusual here. A standard agent with tools. The difference is how you run it.</p><h3>run() — the black box</h3><pre>with AgentRuntime() as runtime:result = runtime.run(<br>agent,<br>&quot;The payments service is throwing 503s. Investigate and fix it.&quot;,<br>)<br>result.print_result()<br></pre><p>You send the prompt. You wait. You get a result. The agent checked services, read logs, restarted something — you just do not know what happened in between or why.</p><pre>Agent Output<br>The payments service was unhealthy with a 34% error rate. Logs showed repeated<br>connection timeouts to database:5432. The database was degraded with high disk<br>usage (91%) and a slow query queue. I restarted the payments service to clear<br>the connection pool. Root cause: database pressure causing downstream timeouts.</pre><h3>stream() — see every step</h3><pre>with AgentRuntime() as runtime:if event.type == EventType.THINKING:<br>print(f&quot; [thinking] {event.content[:120]}&quot;)<br>elif event.type == EventType.TOOL_CALL:<br>print(f&quot; [tool_call] {event.tool_name}({event.args})&quot;)<br>elif event.type == EventType.TOOL_RESULT:<br>print(f&quot; [tool_result] {event.tool_name} → {str(event.result)[:120]}&quot;)<br>elif event.type == EventType.DONE:<br>print(f&quot;\n [done]\n{event.output}&quot;)<br></pre><p>Same agent and the same prompt, but now you see everything:</p><pre> [thinking]     The payments service is throwing 503s. I should check its<br>                 health first before taking any action.<br>  [tool_call]    check_service({&#39;service_name&#39;: &#39;payments&#39;})<br>  [tool_result]  check_service → {&#39;status&#39;: &#39;unhealthy&#39;, &#39;error_rate&#39;: &#39;34%&#39;, &#39;uptime&#39;: &#39;2m&#39;}<br>  [thinking]     Payments is unhealthy with a 34% error rate and has only been<br>                 up for 2 minutes. Let me check the recent logs.<br>  [tool_call]    get_recent_logs({&#39;service_name&#39;: &#39;payments&#39;})<br>  [tool_result]  get_recent_logs → {&#39;service&#39;: &#39;payments&#39;, &#39;logs&#39;: [&#39;ERROR: connection<br>                 timeout to database:5432&#39;, ...]}<br>  [thinking]     The logs show repeated connection timeouts to database:5432.<br>                 The problem might be upstream. Let me check the database.<br>  [tool_call]    check_service({&#39;service_name&#39;: &#39;database&#39;})<br>  [tool_result]  check_service → {&#39;status&#39;: &#39;degraded&#39;, &#39;error_rate&#39;: &#39;8%&#39;, &#39;uptime&#39;: &#39;6h&#39;}<br>  [tool_call]    get_recent_logs({&#39;service_name&#39;: &#39;database&#39;})<br>  [tool_result]  get_recent_logs → {&#39;service&#39;: &#39;database&#39;, &#39;logs&#39;: [&#39;WARN: disk usage<br>                 at 91%&#39;, &#39;WARN: query queue depth: 847&#39;, ...]}<br>  [thinking]     Database is degraded — high disk usage and a slow query queue<br>                 are causing connection timeouts upstream. I&#39;ll restart payments<br>                 to clear the connection pool.<br>  [tool_call]    restart_service({&#39;service_name&#39;: &#39;payments&#39;})<br>  [tool_result]  restart_service → {&#39;service&#39;: &#39;payments&#39;, &#39;status&#39;: &#39;restarted&#39;}<br><br>  [done]<br>  Root cause: database pressure (91% disk, slow query queue) caused connection<br>  timeouts in payments. Restarted payments to clear the connection pool.</pre><p>You can see exactly why the agent checked the database — it followed the connection timeout in the logs. You can see the decision point where it chose to restart payments rather than the database. Nothing is hidden.</p><h3>The four event types</h3><pre>EventType.THINKING # LLM reasoning — what the agent is about to do and why<br>EventType.TOOL_CALL # agent decided to call a tool: event.tool_name, event.args<br>EventType.TOOL_RESULT # tool returned: event.tool_name, event.result<br>EventType.DONE # finished: event.output<br></pre><p>There is also EventType.WAITING, covered in the HITL posts, which fires when the agent is paused waiting for human input.</p><h3>run() vs stream() vs start()</h3><pre># run() — blocks, returns result when done<br>result = runtime.run(agent, prompt)<br># stream() - yields events as the agent executes, blocks until done<br>for event in runtime.stream(agent, prompt):<br>…<br># start() - fire and forget, returns a handle immediately<br>handle = runtime.start(agent, prompt)<br># later:<br>for event in handle.stream():<br>…</pre><p>start() + handle.stream() is useful when you want to kick off an agent and attach the stream later, for example, in a web server where the HTTP request starts the agent and a WebSocket streams the events to the browser.</p><h3>When to use streaming</h3><ul><li><strong>Debugging</strong> — see exactly what the agent decided and why</li><li><strong>Long-running agents</strong> — show progress instead of waiting silently</li><li><strong>Chat and terminal UIs</strong> — display thinking indicators and tool activity in real time</li><li><strong>HITL workflows</strong> — detect EventType.WAITING and prompt a human to respond</li><li><strong>Observability</strong> — log every step to your monitoring system</li></ul><p>If you just want the final answer and do not care about the steps, use run(). If you want to see inside the agent or react to what it is doing , use stream().</p><h3>How durability works</h3><p>Streaming does not change how Agentspan handles durability. The execution is still persisted on the server. If your process crashes mid-stream, the execution keeps running on the server. Reconnect and stream from the handle:</p><pre>handle = AgentHandle(workflow_id=”your-execution-id”, runtime=runtime)<br>for event in handle.stream():</pre><p>The events you already received are not replayed — you pick up from where the execution currently is.</p><h3>Try it</h3><pre>pip install agentspan<br>agentspan server start</pre><ul><li><strong>GitHub</strong>: <a href="https://github.com/agentspan-ai/agentspan">github.com/agentspan-ai/agentspan</a></li><li><strong>Docs</strong>: <a href="https://agentspan.ai/docs">agentspan.ai/docs</a></li><li><strong>Discord</strong>: <a href="https://discord.com/invite/ajcA66JcKq">https://discord.com/invite/ajcA66JcKq</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3a2bd110ef61" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/see-inside-your-agent-real-time-streaming-with-agentspan-3a2bd110ef61">See Inside Your Agent: Real-Time Streaming with Agentspan</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Your Workflow Engine Is Durable. Your Agent’s Decisions Aren’t.]]></title>
            <link>https://medium.com/agentspan/your-workflow-engine-is-durable-your-agents-decisions-aren-t-a99fa9a74e3a?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/a99fa9a74e3a</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[netflix-conductor]]></category>
            <category><![CDATA[agentic-workflow]]></category>
            <category><![CDATA[llm]]></category>
            <dc:creator><![CDATA[Viren Baraiya]]></dc:creator>
            <pubDate>Fri, 08 May 2026 07:27:31 GMT</pubDate>
            <atom:updated>2026-05-08T07:27:30.919Z</atom:updated>
            <content:encoded><![CDATA[<p>We built <a href="https://netflixtechblog.com/netflix-conductor-a-microservices-orchestrator-2e8d4771bf40">Conductor at Netflix</a> because microservice workflows would not stay still.</p><p>Teams shipped daily. Workflow shapes changed constantly. A runtime that required the entire graph to be frozen before execution could not keep up. So Conductor took a different path: workflow structure could be influenced by data produced during execution. The engine could materialize new work, persist it as state, schedule it, retry it, and record it in the same execution history as everything authored up front.</p><p>Today, we call this property <strong>dynamic synthesis</strong>.</p><p>At the time, it was just a practical answer to a microservices problem. Now it looks like the missing primitive for agents.</p><p>Nearly ten years later, at Orkes — the company commercializing Conductor — we hear the same question from almost every customer running a serious AI initiative:</p><blockquote><em>Can we run our agents on Conductor?</em></blockquote><blockquote><strong>Yes.</strong></blockquote><p>But the more important question is why so many agent systems start to break when they meet the durability model of traditional workflow-as-code platforms. After watching teams try to run serious agents in production, we have reached one conclusion:</p><h4><strong>Agents do not just call tools. Agents synthesize control flow.</strong></h4><p>The model decides what to do next, which tools to call, which branches to create, which work to fan out, when to ask a human, what to retry, and what compensation should exist if an action has to be unwound later.</p><p>If that control flow is forced into pre-authored workflow code, the agent becomes narrower. If it is generated outside the workflow engine, the audit trail splits. If it is left in application logs, the system is not truly durable.</p><p>The runtime under an agent has to record the agent’s decisions as state — not merely record that a model call happened.</p><p><strong><em>That is the gap.</em></strong></p><h4>What we keep seeing</h4><p>A team picks a durable execution platform — usually a workflow-as-code one, because that is what their platform team operates. They build the agent. It works in development. They demo it. Leadership is happy.</p><p>Then the agent meets a security review, a compliance review, an audit, or a real production incident. The audit story is the one that breaks first.</p><p>When someone asks “what did the agent do, and why?”, the team reconstructs the answer from application logs, model gateway traces, tool logs, and workflow event history. Four systems. Four clocks. Four versions of the truth.</p><p>The workflow engine can tell you that a model call happened and what it returned. It cannot tell you what the agent actually planned — the structure it synthesized, the branches it introduced, the compensations it paired with actions, the validation gates it passed through. That work lives outside the durable state machine.</p><p>That is not an audit trail. That is forensics.</p><p>The teams that hit this wall do one of two things. They build a planning service next to the workflow engine — which doubles the surface area without making the agent’s decisions native to either runtime. Or they make the agent narrower, wrapping the model in an activity and branching on its return value from a pre-coded set of options. The second approach is fine when the branches are known ahead of time. It is not the same as letting the agent compose the execution graph.</p><p>The team ships something. It is not the agent they set out to build.</p><h4>The replay contract is not a detail</h4><p>Workflow-as-code platforms are built on a powerful contract: the workflow function is deterministic, and the runtime achieves durability by replaying that function over a persisted event history.</p><p>Side effects — clock reads, network calls, model calls, database writes — are pushed into activities. The first execution records the result. Later replays reuse the recorded result.</p><p>This model has real strengths. It gives durable recovery from failures, a strong programming model, type-checked workflows, IDE ergonomics, and a clean way to reason about long-running code. For workflows whose shape is known ahead of time, it is excellent.</p><p>But the replay contract is not an implementation detail. It is the foundation of the durability model. And that foundation creates a hard boundary for agents.</p><p>To be clear: replay-based systems can call models from activities. They can persist the returned value. They can branch on that value. They can build useful agentic systems when the possible branches are known ahead of time.</p><p>The limitation appears when the model is not merely selecting among pre-authored branches, but synthesizing new workflow structure during execution.</p><p>New tasks. New dependencies. New fan-outs. New human gates. New compensations. New follow-up steps based on context the developer did not know when the workflow was authored.</p><p>That synthesized structure is the agent’s real control flow.</p><p>If the workflow function must remain deterministic, that control flow cannot simply emerge inside the function as arbitrary new structure. It has to be fenced into pre-authored branches, interpreted by application code, or generated into a separate workflow outside the runtime.</p><p>That is where durability stops.</p><p>The platform may durably record that a model was called. It may durably record the model’s returned value. But unless the runtime can accept the agent’s newly synthesized execution graph as a first-class state transition, the agent’s decisions are not native to the durable record.</p><p>The system is durable around the agent. Not through it.</p><h4>Open-world execution</h4><p>The runtime under an agent has to do one specific thing:</p><p><em>Accept new workflow structure as a legitimate state transition during execution.</em></p><p>Borrowing from the open-world / closed-world distinction in logic and databases, I call this property <strong>open-world execution</strong>.</p><p>Open-world execution means the runtime does not require the full workflow graph to be known before execution begins. New tasks, dependencies, branches, fan-outs, human approvals, and compensations can be introduced during execution, validated by policy, persisted as state, and scheduled by the same engine that runs pre-authored workflows.</p><p>The runtime’s answer to “what can happen next?” is not limited to what was committed in advance. It is defined by what has been safely recorded.</p><p>In a closed-world runtime, the set of possible futures is bounded by the workflow code deployed before the execution started.</p><p>In an open-world runtime, the execution record is allowed to grow. A worker — ordinary code or an LLM-driven worker — can return a payload that says:</p><blockquote><em>“Here are the next tasks under this workflow.”</em></blockquote><p>The runtime validates that payload, persists the tasks into the same execution record, schedules them, records the results, and advances the workflow.</p><p>There is no second code path for dynamically synthesized work. Once the new structure is recorded, it is just another durable state transition.</p><p>Replay does not need to re-derive the agent’s decision from a model. It does not need to ask the model to be deterministic. It does not need to reconstruct intent from logs.</p><p>The decision has already become state.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cnmj8TtXbbShT1DvKsewrA.png" /></figure><h4>Why Conductor fits</h4><p>Conductor was not created for agents. It was created because microservices needed a workflow runtime where execution could evolve without freezing the world every time a team shipped.</p><p>That led to primitives like FORK_JOIN_DYNAMIC, SUB_WORKFLOW, HUMAN, EVENT, WAIT, DECISION, and INLINE tasks.</p><p>The important part is not any one task type. The important part is the state model: Conductor can accept runtime-generated structure, persist it under the execution, schedule it through the same coordinator, and record it in the same ledger as the rest of the workflow.</p><p>Human-authored workflows and runtime-authored agent plans feed the same underlying primitive — a workflow definition with a tasks array, where each task carries a name, type, reference, and inputs, and ordering follows from the array plus task types like FORK_JOIN_DYNAMIC or SUB_WORKFLOW for runtime fan-out:</p><pre>{<br>  &quot;name&quot;: &quot;agent_investigation&quot;,<br>  &quot;version&quot;: 1,<br>  &quot;tasks&quot;: [<br>    {<br>      &quot;name&quot;: &quot;fan_out_lookups&quot;,<br>      &quot;taskReferenceName&quot;: &quot;fan_out_lookups_ref&quot;,<br>      &quot;type&quot;: &quot;FORK_JOIN_DYNAMIC&quot;,<br>      &quot;inputParameters&quot;: {<br>        &quot;dynamicTasks&quot;: &quot;${agent_proposal.output.tasks}&quot;,<br>        &quot;dynamicTasksInput&quot;: &quot;${agent_proposal.output.inputs}&quot;<br>      }<br>    }<br>  ]<br>}</pre><p>Whether that structure was authored by a developer at deploy time or synthesized by an agent at runtime, the engine treats it as workflow state.</p><p>That is what makes Conductor interesting for agents. Not because it has an AI feature bolted onto the side. Because the core execution model already fits the agent workload.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*9S28M5YaY86AOR3g-ZQWJA.png" /><figcaption>Conductor + Agentspan — Durable production agents</figcaption></figure><h4>Agentspan: reasoning plane and execution plane</h4><p>Agentspan is our attempt to package this primitive for agents. It separates the system into two planes.</p><p><strong>Reasoning plane: the model.</strong> The model receives a context projection: session state, available tools, prior results, conversation history, policy hints, and relevant memory. It proposes intent.</p><p>It does not execute tools directly. It does not mutate production systems directly. It does not become the runtime.</p><p>It proposes what should happen next.</p><p><strong>Execution plane: Conductor.</strong> Conductor validates the proposal against the agent’s tool catalog and policy. It materializes the proposal as workflow tasks under the agent’s parent execution. It schedules the work, retries failures, records results, and enforces the same RBAC, traceability, and recovery semantics used for ordinary workflow tasks.</p><p>In that split, the model proposes structure, Conductor executes it under policy, and the durable ledger preserves the proposal, materialization, and results together.</p><p>That is the boundary we want in production AI systems. The LLM should be allowed to propose structure. It should not be allowed to become the invisible place where production control flow lives.</p><h4>On-call: an agent investigating an incident</h4><p>Suppose an on-call agent is investigating latency on the checkout service.</p><p>The agent has tools for metrics, deploy history, alert correlation, incident updates, rollback, roll-forward, and paging a human.</p><p>The model sees the page, reads the current context, and proposes a parallel investigation:</p><pre>{<br>  &quot;intent&quot;: &quot;FORK_JOIN_DYNAMIC&quot;,<br>  &quot;tasks&quot;: [<br>    {<br>      &quot;type&quot;: &quot;metrics_lookup&quot;,<br>      &quot;input&quot;: { &quot;service&quot;: &quot;checkout&quot;, &quot;window&quot;: &quot;30m&quot; }<br>    },<br>    {<br>      &quot;type&quot;: &quot;deploy_history&quot;,<br>      &quot;input&quot;: { &quot;service&quot;: &quot;checkout&quot;, &quot;window&quot;: &quot;2h&quot; }<br>    },<br>    {<br>      &quot;type&quot;: &quot;alert_correlate&quot;,<br>      &quot;input&quot;: { &quot;service&quot;: &quot;checkout&quot;, &quot;window&quot;: &quot;30m&quot; }<br>    }<br>  ]<br>}</pre><p><em>Conductor validates the tools, checks the policy, materializes the fan-out as tasks, schedules them, records each result, and resumes the agent with a new context projection.</em></p><p>The model did not execute anything; the runtime did. The execution ledger now contains the proposal, the materialized tasks, the tool results, and the next decision point in one durable record.</p><p>That is the difference between tool calling and durable agent execution.</p><p>Tool calling says: the model asked for tools.</p><p>Durable agent execution says: the model proposed a state transition, the runtime validated it, the engine materialized it, and the ledger recorded it.</p><p>The agent’s plan is not living in application logs. It is part of the durable execution record, alongside the workflow steps that run beside it. Whatever the agent decides to do next — fan out further, escalate to a human, retry under a different policy, hand off to another agent — flows through the same primitive and lands in the same ledger.</p><p>That is what production requires.</p><h4>Pick the runtime whose durability reaches the work</h4><p>This is not an argument for rip-and-replace. If you operate a workflow-as-code platform today for code-defined workflows, keep it. Those platforms are good at what they were built for.</p><p>When the workflow is a program and the program is known ahead of time, replay-based durability is a strong model. It gives developers a clean abstraction for long-running code.</p><p>But agents are not ordinary long-running code. An agent’s control flow is produced at runtime. The model is not merely computing a value inside a fixed graph. It is proposing the graph.</p><p>That changes the durability requirement.</p><p>The question is no longer:</p><blockquote><em>Can my workflow engine call an LLM?</em></blockquote><p>Every serious platform can call an LLM. The real question is:</p><blockquote><em>Can my workflow engine durably record the control flow the LLM synthesizes?</em></blockquote><p>If the answer is no, the agent’s decisions live somewhere else: in logs, in a planning service, in generated workflow definitions, or inside application code that interprets model output. That may be acceptable for simple systems. It is not enough for agents that need governance, auditability, replay, compensation, human review, and production recovery.</p><p>The question is not whether your workflow engine is durable. The question is where that durability stops.</p><p>For code-defined workflows, closed-world workflow platforms can be excellent. The workflow is the program, and the program is known ahead of time.</p><p>For agents, the workflow is not fully known until the model begins reasoning. The agent’s decisions are the control flow.</p><p>If those decisions live outside the durable state machine, your agent is not durable. It is surrounded by durable infrastructure.</p><p>That distinction will matter more as agents move from demos to production systems that touch money, infrastructure, customer data, and security policy.</p><p>Conductor had open-world execution because microservices needed it first. Agentspan builds on that primitive for agents.</p><blockquote><strong>The model reasons. The runtime governs. The ledger records. The system recovers.</strong></blockquote><p>Pick the runtime whose durability extends to where the work actually happens.</p><p><strong>Conductor</strong> — <a href="https://github.com/conductor-oss/conductor">github.com/conductor-oss/conductor</a></p><p><strong>Agentspan</strong> — <a href="https://github.com/agentspan-ai/agentspan">github.com/agentspan-ai/agentspan</a></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a99fa9a74e3a" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/your-workflow-engine-is-durable-your-agents-decisions-aren-t-a99fa9a74e3a">Your Workflow Engine Is Durable. Your Agent’s Decisions Aren’t.</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[You Decide: Build a Human-Directed Editorial Workflow with the Manual Strategy]]></title>
            <link>https://medium.com/agentspan/you-decide-build-a-human-directed-editorial-workflow-with-the-manual-strategy-f6238350a775?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/f6238350a775</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[agentic-workflow]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[agents]]></category>
            <category><![CDATA[ai]]></category>
            <dc:creator><![CDATA[Deepti Reddy]]></dc:creator>
            <pubDate>Fri, 01 May 2026 11:22:37 GMT</pubDate>
            <atom:updated>2026-05-01T11:22:38.352Z</atom:updated>
            <content:encoded><![CDATA[<p><em>By Deepti Reddy | April 2026</em></p><p><em>This is Part 7 of an 8-part series covering every multi-agent strategy in AgentSpan. Today: the manual strategy — the human picks which agent speaks next. Full control.</em></p><p>In <a href="https://medium.com/agentspan/from-support-ticket-to-resolution-build-a-sequential-ai-agent-pipeline-5d1260f98e80">Part 1</a>, we built a sequential pipeline where each agent’s output feeds the next. In <a href="https://medium.com/agentspan/three-reviewers-one-pr-zero-wait-build-a-parallel-ai-agent-pipeline-dae75402d8f2">Part 2</a>, we built a parallel code review where three reviewers running simultaneously. In <a href="https://medium.com/agentspan/the-llm-decides-build-an-issue-triage-bot-with-the-handoff-strategy-6c4945609ff9">Part 3</a>, the LLM decided which agent runs. In <a href="https://medium.com/agentspan/agents-talk-to-each-other-build-a-support-swarm-with-peer-to-peer-transfers-c0a64c6bdd4b">Part 4</a>, agents transferred between each other peer-to-peer. In <a href="https://medium.com/agentspan/three-reviewers-two-rounds-one-verdict-build-a-code-review-debate-with-round-robin-12d3c78d8d9a">Part 5</a>, agents took turns in a fixed rotation: architect, security, pragmatist, architect, security, pragmatist. Predictable and structured. In <a href="https://medium.com/agentspan/roll-the-dice-build-a-brainstorming-session-with-the-random-strategy-bd0d10eaea7b">Part 6</a>, agents were selected randomly.</p><p>Every strategy so far has one thing in common: something other than the human decided which agent runs next — the pipeline, the LLM, the classifier, the rotation, or randomness.</p><p>That is the <strong>manual strategy</strong>. The human picks. Every turn, the workflow pauses and asks: which agent should go next? The human makes the call.</p><h3>What is AgentSpan</h3><p>AgentSpan is an orchestration layer for building, bringing, and observing AI agents as durable workflows.</p><ul><li><strong>Build</strong>: define agents with the AgentSpan SDK using Agent, @tool, and 8 multi-agent strategies. Compiles to server-side workflows that survive crashes.</li><li><strong>Bring</strong>: already using an agent framework such as LangGraph, OpenAI Agents SDK, or Google ADK? Pass your agents directly to run(). AgentSpan adds durability and orchestration on top.</li><li><strong>Observe</strong>: every execution is inspectable in the dashboard. See agent flows, inputs/outputs, tool calls, and token usage. Debug failures, replay runs.</li></ul><h3>Setup</h3><p>Two commands:</p><pre>pip install agentspan<br>agentspan server start</pre><p>This gives you a local AgentSpan server with a visual dashboard at localhost:6767.</p><h3>What we are building</h3><p>An editorial workflow with three specialists:</p><ol><li><strong>Writer</strong>: drafts and revises content</li><li><strong>Fact Checker</strong>: verifies accuracy, flags unsupported claims</li><li><strong>Copy Editor</strong>: fixes grammar, tightens prose, improves flow</li></ol><p>The human editor directs the workflow. Maybe the writer goes first, then the fact checker, then back to the writer for revisions, then the copy editor for polish. The human decides the sequence based on what the draft needs — not a predetermined pipeline.</p><p>Human picks: writer</p><pre>-&gt; [Writer] drafts content</pre><p>Human picks: fact_checker</p><pre>-&gt; [Fact Checker] flags issues</pre><p>Human picks: writer</p><pre>-&gt; [Writer] revises based on feedback</pre><p>Human picks: copy_editor</p><pre>-&gt; [Copy Editor] polishes final version</pre><h3>How is this different from everything else?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HaIdPBs3w8T_IRHGr23r4Q.png" /></figure><p>Manual is the only strategy where a human is in the orchestration loop — not just approving tool calls (that is HITL), but actively directing which agent runs.</p><h3>Defining the specialists</h3><p>Three agents with editorial roles:</p><pre>from agentspan.agents import Agent, AgentRuntime, Strategy, EventType<br><br>writer = Agent(<br>name=&quot;writer&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>instructions=(<br>&quot;You are a writer. Expand on ideas with clear, engaging prose. &quot;<br>&quot;If you receive feedback from other agents, revise your work &quot;<br>&quot;based on their suggestions. Keep your response focused and concise.&quot;<br>),<br>)<br><br>fact_checker = Agent(<br>name=&quot;fact_checker&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>instructions=(<br>&quot;You are a fact checker. Review the content for accuracy. &quot;<br>&quot;Flag any claims that are unsupported, exaggerated, or wrong. &quot;<br>&quot;Be specific - quote the exact text and explain the issue. &quot;<br>&quot;If everything checks out, say so.&quot;<br>),<br>)<br><br>copy_editor = Agent(<br>name=&quot;copy_editor&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>instructions=(<br>&quot;You are a copy editor. Review the content for grammar, clarity, &quot;<br>&quot;tone, and flow. Suggest specific edits. Tighten prose. Remove &quot;<br>&quot;filler. Make it read well. Return the improved version.&quot;<br>),<br>)</pre><p>Each agent sees the full conversation — including what other agents said before them. The writer can revise based on the fact checker’s feedback. The copy editor polishes after everyone else is done.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*t6PzSv14lA2uDz9CAChS1w.png" /></figure><h3>The manual strategy</h3><pre>team = Agent(name=&quot;editorial_team&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>agents=[writer, fact_checker, copy_editor],<br>strategy=Strategy.MANUAL,<br>max_turns=4,<br>)<br><br>No router. No classifier. No rotation. The workflow pauses at each turn and waits for the human to pick.<br>Compare all eight strategies:<br><br># Sequential: fixed order, each runs once<br>pipeline = a &gt;&gt; b &gt;&gt; c<br><br># Parallel: all run at once<br>team = Agent(agents=[a, b, c], strategy=Strategy.PARALLEL)<br><br># Handoff: parent LLM picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.HANDOFF)<br><br># Router: classifier picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.ROUTER, router=classifier)<br><br># Swarm: agents transfer between each other<br>team = Agent(agents=[a, b, c], strategy=Strategy.SWARM)<br><br># Round robin: fixed rotation<br>debate = Agent(agents=[a, b, c], strategy=Strategy.ROUND_ROBIN, max_turns=6)<br><br># Random: random selection each turn<br>brainstorm = Agent(agents=[a, b, c], strategy=Strategy.RANDOM, max_turns=6)<br><br># Manual: human picks each turn<br>workflow = Agent(agents=[a, b, c], strategy=Strategy.MANUAL, max_turns=4)</pre><p>Same Agent class. Eight strategies. One primitive.</p><h3>Running it</h3><pre>with AgentRuntime() as runtime:handle = runtime.start(<br>team, &quot;Write a short paragraph about the history of artificial intelligence.&quot;<br>)<br><br>for event in handle.stream():<br>if event.type == EventType.WAITING:<br>print(&quot;Pick the next agent:&quot;)<br>choice = input(&quot;&gt; &quot;)<br>handle.respond({&quot;selected&quot;: choice})<br>elif event.type == EventType.DONE:<br>print(event.output)<br></pre><p>The workflow starts. Each turn, EventType.WAITING fires and the human types an agent name. handle.respond() sends the selection back to the server. The chosen agent runs, and the cycle repeats until max_turns.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gm9VHVOKt1PUh7-cPEl2sg.png" /></figure><h3>Example session</h3><p>Pick the next agent: writer, fact_checker, copy_editor</p><pre>&gt; writer<br>[Writer produces a draft about AI history]<br>Pick the next agent: writer, fact_checker, copy_editor<br><br>&gt; fact_checker<br>[Fact checker reviews, flags one claim about the Dartmouth Conference date]<br>Pick the next agent: writer, fact_checker, copy_editor<br><br>&gt; writer<br>[Writer revises the draft, fixes the flagged claim]<br>Pick the next agent: writer, fact_checker, copy_editor<br>&gt; copy_editor<br>[Copy editor polishes grammar, tightens prose, returns final version]</pre><p>The human directed the flow: write, check, revise, polish. A fixed pipeline could not do this — the human decided to send it back to the writer after the fact checker flagged an issue. That loop was a judgment call, not a predetermined step.</p><h3>When to use manual</h3><p>Manual is the right strategy when:</p><ul><li><strong>Editorial workflows</strong> — human editors direct the review process based on what the content needs</li><li><strong>Training and education</strong> — a student directs which tutor agent to consult next</li><li><strong>Debugging</strong> — a developer manually directs diagnostic agents to investigate specific areas</li><li><strong>Quality gates</strong> — a human reviewer decides whether the output needs another pass or is ready</li></ul><p>If the routing logic can be automated with rules, LLM judgment, or fixed order, use one of the other seven strategies. Manual is for when the human’s judgment is the routing logic.</p><h3>How durability works</h3><p>Same as every previous part. The workflow pauses durably on the server while waiting for the human’s selection. Kill the process. Come back an hour later. The workflow is still waiting. Respond via the CLI or reconnect from a new process:</p><pre>agentspan agent respond &lt;execution-id&gt; — data ‘{“selected”: “writer”}’</pre><p>No timeout. No thread blocked. The server holds the state indefinitely.</p><h3>What’s next</h3><p><strong>Part 8: Router</strong> — A dedicated classifier agent decides which specialist runs — not the parent LLM, not a fixed order, but a separate lightweight model whose only job is routing. The final strategy in the series.</p><h3>Try it</h3><pre>pip install agentspan<br>agentspan server start<br>python 07_editorial_manual.py</pre><ul><li><strong>GitHub</strong>: <a href="https://github.com/agentspan-ai/agentspan">github.com/agentspan-ai/agentspan</a></li><li><strong>Blog examples</strong>: <a href="https://github.com/agentspan-ai/agentspan/tree/main/sdk/python/examples/blog_and_videos/manual">github.com/agentspan-ai/agentspan/tree/main/sdk/python/examples/blog_and_videos/manual</a></li><li><strong>Docs</strong>: <a href="https://agentspan.ai/docs">agentspan.ai/docs</a></li><li><strong>Discord</strong>: <a href="https://discord.com/invite/ajcA66JcKq">https://discord.com/invite/ajcA66JcKq</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f6238350a775" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/you-decide-build-a-human-directed-editorial-workflow-with-the-manual-strategy-f6238350a775">You Decide: Build a Human-Directed Editorial Workflow with the Manual Strategy</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Roll the Dice: Build a Brainstorming Session with the Random Strategy]]></title>
            <link>https://medium.com/agentspan/roll-the-dice-build-a-brainstorming-session-with-the-random-strategy-bd0d10eaea7b?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/bd0d10eaea7b</guid>
            <category><![CDATA[ai-orchestration]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[agentic-workflow]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Deepti Reddy]]></dc:creator>
            <pubDate>Fri, 01 May 2026 11:06:32 GMT</pubDate>
            <atom:updated>2026-06-19T04:49:01.741Z</atom:updated>
            <content:encoded><![CDATA[<p><em>By Deepti Reddy | April 2026</em></p><p><em>This is Part 6 of an 8-part series covering every multi-agent strategy in Agentspan. Today, we will cover the random strategy, a random agent is selected each turn. No rotation, no decision — pure randomness.</em></p><p>In <a href="https://medium.com/agentspan/from-support-ticket-to-resolution-build-a-sequential-ai-agent-pipeline-5d1260f98e80">Part 1</a>, we built a sequential pipeline where each agent’s output feeds the next. In <a href="https://medium.com/agentspan/three-reviewers-one-pr-zero-wait-build-a-parallel-ai-agent-pipeline-dae75402d8f2">Part 2</a>, we built a parallel code review where three reviewers running simultaneously. In <a href="https://medium.com/agentspan/the-llm-decides-build-an-issue-triage-bot-with-the-handoff-strategy-6c4945609ff9">Part 3</a>, the LLM decided which agent runs. In <a href="https://medium.com/agentspan/agents-talk-to-each-other-build-a-support-swarm-with-peer-to-peer-transfers-c0a64c6bdd4b">Part 4</a>, agents transferred between each other peer-to-peer. In <a href="https://medium.com/agentspan/three-reviewers-two-rounds-one-verdict-build-a-code-review-debate-with-round-robin-12d3c78d8d9a">Part 5</a>, agents took turns in a fixed rotation: architect, security, pragmatist, architect, security, pragmatist. Predictable and structured.</p><p>But what if predictability is the problem? In brainstorming, you do not want a fixed order. You want surprise. You want the creative thinker to jump in twice in a row, or the critical thinker to challenge an idea the moment it lands. Fixed rotations produce fixed thinking.</p><p>That is the random strategy. Each turn, a random agent is selected. No pattern. No schedule. The same agent might go twice in a row, or not at all for three turns. The randomness creates variety in perspective that a fixed rotation cannot.</p><h3>What is Agentspan</h3><p>Agentspan is an orchestration layer for building, bringing, and observing AI agents as durable workflows.</p><ul><li><strong>Build</strong>: define agents with the Agentspan SDK using Agent, @tool, and 8 multi-agent strategies. Compiles to server-side workflows that survive crashes.</li><li><strong>Bring</strong>: already using an agent framework such as LangGraph, OpenAI Agents SDK, or Google ADK? Pass your agents directly to run(). Agentspan adds durability and orchestration on top.</li><li><strong>Observe</strong>: every execution is inspectable in the dashboard. See agent flows, inputs/outputs, tool calls, and token usage. Debug failures, replay runs.</li></ul><h3>Setup</h3><p>Two commands:</p><pre>pip install agentspan<br>agentspan server start</pre><p>This gives you a local Agentspan server with a visual dashboard at localhost:6767.</p><h3>What we are building</h3><p>A brainstorming session with three thinkers:</p><ol><li><strong>Creative</strong>: bold, unconventional ideas — “what if we did the opposite?”</li><li><strong>Practical</strong>: feasibility, timelines, resources — “what would it actually take?”</li><li><strong>Critical</strong>: risks, holes, blind spots — “what could go wrong?”</li></ol><p>Each turn, one is randomly selected. After 6 turns, a summarizer distills the session into the top ideas and next steps.</p><pre>Turn 1: [Creative] &lt;- random<br>Turn 2: [Critical] &lt;- random<br>Turn 3: [Creative] &lt;- random (again!)<br>Turn 4: [Practical] &lt;- random<br>Turn 5: [Critical] &lt;- random<br>Turn 6: [Practical] &lt;- random<br>[Summarizer] -&gt; top 3 ideas + next step</pre><h3>How is this different from round robin?</h3><p>In <strong>round robin</strong>, the order is fixed: A, B, C, A, B, C. Every agent gets equal time. Every agent knows when their turn is.</p><p>In <strong>random</strong>, there is no order. Agent A might speak three times. Agent C might speak once. The distribution is uneven by design — some perspectives naturally dominate in any real brainstorming session, and that is fine.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QrBkdTY-1gT1EFX3fSskrA.png" /></figure><h3>Defining the thinkers</h3><p>Three agents with deliberately different thinking styles:</p><pre>from agentspan.agents import Agent, AgentRuntime, Strategy<br><br>creative = Agent(<br>name=&quot;creative&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>instructions=(<br>&quot;You are a creative thinker. Generate bold, unconventional ideas. &quot;<br>&quot;Push boundaries. Think &#39;what if we did the opposite of what everyone &quot;<br>&quot;expects?&#39; Read what others said before you and build on their ideas &quot;<br>&quot;or take them in a surprising direction. Keep your response to 2–3 paragraphs.&quot;<br>),<br>)<br><br>practical = Agent(<br>name=&quot;practical&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>instructions=(<br>&quot;You are a practical thinker. Focus on what can actually be built &quot;<br>&quot;and shipped. Consider timelines, resources, and feasibility. Read &quot;<br>&quot;what others said before you and ground their ideas in reality - &quot;<br>&quot;what would it take to actually do this? Keep your response to 2–3 paragraphs.&quot;<br>),<br>)<br><br>critical = Agent(<br>name=&quot;critical&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>instructions=(<br>&quot;You are a critical thinker. Find the holes, the risks, the things &quot;<br>&quot;nobody wants to talk about. Read what others said before you and &quot;<br>&quot;stress-test their ideas - what could go wrong? What are they not &quot;<br>&quot;considering? Keep your response to 2–3 paragraphs.&quot;<br>),<br>)</pre><p>The key instruction in each: “Read what others said before you.” Each agent sees the full conversation. The difference from round robin is that who speaks next is random, not predetermined.</p><h3>The summarizer</h3><p>After the brainstorm, a summarizer produces actionable output:</p><pre>summarizer = Agent(name=&quot;summarizer&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>instructions=(<br>&quot;You observed a brainstorming session between a creative thinker, &quot;<br>&quot;a practical thinker, and a critical thinker. Produce a summary:\n\n&quot;<br>&quot;1. Top 3 ideas (ranked by potential)\n&quot;<br>&quot;2. Biggest risk identified\n&quot;<br>&quot;3. Recommended next step (one sentence)\n\n&quot;<br>&quot;Be concise and actionable.&quot;<br>),<br>)</pre><h3>The random strategy</h3><pre>brainstorm = Agent(name=&quot;brainstorm&quot;,<br>model=&quot;openai/gpt-4o&quot;,<br>agents=[creative, practical, critical],<br>strategy=Strategy.RANDOM,<br>max_turns=6,<br>)<br>pipeline = brainstorm &gt;&gt; summarizer</pre><p>max_turns=6 means 6 randomly selected turns. Some agents might go multiple times, others might be skipped entirely. Then &gt;&gt; pipes the brainstorm transcript to the summarizer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*mG46tFm0qz5aCB7sSoNwnA.png" /></figure><p>Compare the strategies:</p><pre># Sequential: fixed order, each runs once<br>pipeline = a &gt;&gt; b &gt;&gt; c<br><br># Parallel: all run at once<br>team = Agent(agents=[a, b, c], strategy=Strategy.PARALLEL)<br><br># Handoff: parent LLM picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.HANDOFF)<br><br># Router: classifier picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.ROUTER, router=classifier)<br><br># Swarm: agents transfer between each other<br>team = Agent(agents=[a, b, c], strategy=Strategy.SWARM)<br><br># Round robin: fixed rotation<br>debate = Agent(agents=[a, b, c], strategy=Strategy.ROUND_ROBIN, max_turns=6)<br><br># Random: random selection each turn<br>brainstorm = Agent(agents=[a, b, c], strategy=Strategy.RANDOM, max_turns=6)</pre><p>Same Agent class. Different strategy. Different behavior.</p><h3>Running it</h3><pre>with AgentRuntime() as runtime:result = runtime.run(<br>pipeline,<br>&quot;How should a developer tools company get its first 1,000 users?&quot;,<br>)<br>result.print_result()<br></pre><p>Every run produces a different conversation because the agent selection is random. Run it twice and you get two different brainstorming sessions. That is the point.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2-c_w-PQg_yYb9yf_o9NWg.png" /></figure><h3>When to use random</h3><p>Random is not a strategy for everything. It is specifically useful when:</p><ul><li><strong>Brainstorming</strong> — you want diverse, unpredictable perspectives</li><li><strong>Load balancing across models</strong> — distribute prompts across GPT-4o, Claude, Gemini randomly to compare output quality</li><li><strong>Stress testing</strong> — randomly select different scenarios to hit an agent with</li><li><strong>Creative writing</strong> — different voices or styles contribute randomly to a collaborative piece</li></ul><p>If you need every agent to participate equally, use round robin. If you need one specific agent, use handoff or router. Random is for when variety itself is the goal.</p><h3>How durability works</h3><p>The random selection is made server-side and persisted. If your process crashes after turn 4:</p><ol><li>Turns 1–4 and their random selections are persisted on the server.</li><li>You restart your script.</li><li>Turns 5–6 continue with new random selections — the first 4 are not re-run.</li></ol><h3>Composability</h3><p>Random composes with other strategies:</p><pre># Random brainstorm, then structured review<br>brainstorm = Agent(agents=[creative, practical, critical], strategy=Strategy.RANDOM, max_turns=6)<br>review = Agent(agents=[architect, security], strategy=Strategy.ROUND_ROBIN, max_turns=4)<br>pipeline = brainstorm &gt;&gt; review &gt;&gt; summarizer</pre><p>Random generates ideas. Round robin reviews them. The summarizer produces the final output. Three strategies, one pipeline.</p><h3>Try it</h3><pre>pip install agentspan<br>agentspan server start<br><br>python 07_brainstorm_random.py</pre><ul><li><strong>GitHub</strong>: <a href="https://github.com/agentspan-ai/agentspan">github.com/agentspan-ai/agentspan</a></li><li><strong>Blog examples</strong>: <a href="https://github.com/agentspan-ai/agentspan/tree/main/sdk/python/examples/blog_and_videos/random">github.com/agentspan-ai/agentspan/tree/main/sdk/python/examples/blog_and_videos/random</a></li><li><strong>Docs</strong>: <a href="https://agentspan.ai/docs">agentspan.ai/docs</a></li><li><strong>Discord</strong>: <a href="https://discord.com/invite/ajcA66JcKq">https://discord.com/invite/ajcA66JcKq</a></li></ul><h3>What’s next</h3><p><strong>Part 7: Manual</strong> — The human picks which agent speaks next. No LLM deciding, no classifier, no randomness — full human control over the orchestration. The final strategy in the series.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bd0d10eaea7b" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/roll-the-dice-build-a-brainstorming-session-with-the-random-strategy-bd0d10eaea7b">Roll the Dice: Build a Brainstorming Session with the Random Strategy</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The anatomy of an agent runtime]]></title>
            <link>https://medium.com/agentspan/the-anatomy-of-an-agent-runtime-e6eb10bdfcdd?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/e6eb10bdfcdd</guid>
            <category><![CDATA[distributed-systems]]></category>
            <category><![CDATA[llm]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Viren Baraiya]]></dc:creator>
            <pubDate>Wed, 29 Apr 2026 20:38:13 GMT</pubDate>
            <atom:updated>2026-04-29T20:38:13.225Z</atom:updated>
            <content:encoded><![CDATA[<p><em>A companion to </em><a href="https://medium.com/agentspan/late-bound-sagas-why-your-agent-is-not-an-llm-in-a-loop-a8c50731c551"><em>Late-Bound Sagas: Why Your Agent Is Not an LLM in a Loop</em></a><em>. That post answered why your agent is not an LLM in a loop. This one answers what you build instead.</em></p><p>This post dives deeper into the architecture of an agent runtime — one built around a clean separation between planning and execution, not just an LLM in a loop.</p><p>The LLM is the brain. The tools are the hands. The runtime is the nervous system that keeps them from killing you. Most teams build the brain and the hands and then wonder why the thing falls over in production. This post is about the nervous system.</p><h3>Requirements for an agent runtime</h3><p>Before the design, the shape of the problem. Any runtime worth shipping has to meet all of these under adversarial operational conditions — process crashes, cluster reboots, network partitions, API outages, humans who wander off for a weekend:</p><ul><li><strong>R1 — Mid-step crash safety.</strong> An agent that terminates mid-tool-call must not leave the external system in an ambiguous state. On recovery, every side effect has run exactly once or is detectable as a duplicate.</li><li><strong>R2 — Long-suspension survival.</strong> A saga blocked on a human, a webhook, or an external asynchronous event must consume zero compute during the wait and survive any number of infrastructure events while suspended.</li><li><strong>R3 — Out-of-band interruption.</strong> Supervisors, humans, budget caps, and timeouts must be able to interrupt a running or suspended saga by ID, without shared memory, without racing the saga’s own progress.</li><li><strong>R4 — Dynamic graph.</strong> The execution graph is synthesized at runtime by a non-deterministic planner. The runtime cannot require the graph to be known at compile time.</li><li><strong>R5 — Polyglot tools.</strong> Tools written in any language, running on any host, must participate as first-class workers. The planner’s language does not constrain the executor’s language.</li><li><strong>R6 — Production-grade observability.</strong> Every decision the agent made, every tool it called, every result it saw, must be recoverable for post-hoc inspection — for at least 13 months after the fact, across model version changes.</li><li><strong>R7 — Bounded-context projection.</strong> The planner’s context is bounded; the saga’s history is not. The runtime must project one onto the other without losing the information the planner needs to decide.</li></ul><h3>Non-goals</h3><p>Five things this design explicitly does <strong>not</strong> attempt:</p><ul><li><strong>Deterministic replay of the LLM.</strong> Temperature=0 is not bit-exact across infrastructure. Model versions change. We make the <em>ledger</em> replayable, not the model.</li><li><strong>Preventing a poorly-implemented tool from leaking its own credentials.</strong> The runtime scopes credentials to tool subprocesses; a tool that prints its credential to stdout is outside our threat model.</li><li><strong>Guarantees about LLM output quality.</strong> Guardrails exist; correctness of reasoning does not. The runtime makes a wrong agent debuggable, not right.</li><li><strong>Replacement of the model provider’s SDK.</strong> The planner calls models through whatever SDK ships. We wrap the call; we do not reimplement it.</li><li><strong>Unbounded agent execution.</strong> Every saga must have enforceable bounds — on wall-clock time, on recursion depth, on token budget, or on step count. Long-running and always-on agents are supported; <em>un</em>bounded agents are not. The runtime relies on the operator to configure at least one bound; a saga with no configured bounds will be refused at compile time.</li></ul><h3>Four properties (of the runtime) that survive a crash</h3><p>Build an agent runtime wrong and a badly-timed kill -9 charges your customer twice. Build it right and four things are true at the same time, even under a process that dies mid-step. Everything else in the design falls out of keeping all four true simultaneously.</p><p><strong>Proposal before effect.</strong> Every action is written to the ledger before it runs, with enough information to identify the effect on replay.</p><ul><li><em>Failure if absent:</em> a recovering process re-runs an action that already completed. You charge the customer twice.</li><li><em>Enforcement:</em> the runtime refuses to dispatch any task until its proposal row is committed.</li></ul><p><strong>Effectively-once side effects.</strong> A side effect runs exactly once per logical proposal, no matter how many times the process dies between proposing and recording the result.</p><ul><li><em>Failure if absent:</em> duplicate Stripe charges, duplicate emails, duplicate database rows, no way to tell which one is “real.”</li><li><em>Enforcement:</em> idempotency keys derived from the step’s stable ledger address, passed to external systems and deduped on re-dispatch.</li></ul><p><strong>Monotonic, durable graph.</strong> The execution graph is append-only. Committed nodes do not change shape. Recovery reads the graph; it does not reconstruct it.</p><ul><li><em>Failure if absent:</em> recovery produces a different graph than the pre-crash state. Debugging is impossible.</li><li><em>Enforcement:</em> the ledger is append-only; status transitions are monotonic; no node is ever deleted or mutated after commit.</li></ul><p><strong>External signal delivery.</strong> Signals from outside the saga’s process — humans, webhooks, timeouts, budget caps, other agents — are durable and deliverable by saga ID.</p><ul><li><em>Failure if absent:</em> “cancel this saga” has no mechanism. A suspended agent cannot be reached. HITL is impossible for real wall-clock durations.</li><li><em>Enforcement:</em> signals are ledger rows addressed to the saga’s ID; delivery wakes a suspended saga on the next scheduler tick.</li></ul><p>The properties are not independent. Effectively-once depends on proposal-before-effect — you need a written proposal to identify the effect on replay. External signals depend on the durable graph — signals are nodes on the graph, and they have to survive restarts. You can skip any one of the four and build a demo. You cannot skip any one of the four and survive a production Tuesday.</p><p>The rest of this document is how each property is enforced, what fails if it isn’t, and what the cost of enforcement is.</p><h3>The two planes: planner and executor</h3><figure><img alt="Agent Runtime — The Brain and the Hands" src="https://cdn-images-1.medium.com/max/1024/1*_dAHqZmSbex4eirr01jikw.png" /></figure><p>The planner plane is the LLM. The executor plane is everything else. The boundary between them is the runtime.</p><p>The planner has one job: given the trajectory so far, emit the next intent. It is a pure function — f(history) -&gt; intent — in the mathematical sense. It does not touch the network. It does not open files. It does not read the clock. If it needs the current time, the current time is in history, because the runtime put it there on a previous step. The planner is stateless beyond its prompt.</p><p>The executor has one job: make the intent real. It takes the intent off a queue, runs the corresponding code, and reports a result. The executor is where your code lives. It’s allowed to be dirty — open sockets, call Stripe, mutate disk. The executor’s relationship to the planner is mediated entirely by the ledger.</p><p>This boundary is not aesthetic. It is the thing that makes proposal-before-effect possible. If the LLM can both decide and act, there is a moment where it has decided and the runtime doesn’t know yet. That moment is the race in which you charge the customer twice.</p><p>A fair objection: modern models emit tool calls directly in a single generation. Doesn’t that collapse the two planes? No. When Claude or GPT emits call(transfer_funds, 5000), the model has produced a <em>token sequence</em> that describes a tool call. Nothing has been called. The runtime parses the sequence, writes the proposal to the ledger, dispatches the worker, writes the result back, and hands a new history to the model on the next call. The model&#39;s &quot;tool use&quot; is the planner proposing. The runtime&#39;s dispatch is the executor acting. The fact that modern models emit multiple parallel tool calls in a single generation just means one planner step produces N children in the graph — a fan-out node, not a linear one. The runtime commits all N proposals atomically before dispatching any worker.</p><p>The cleanest user-facing shape for the planner is the yield pattern:</p><pre>@agent<br>def hire_for_role(role, recruiter_id):<br>    intent = yield plan(history)<br>    result = yield execute(intent)<br>    ...</pre><p>Generators give you the right semantics for free. The user writes straight-line code; the runtime controls the schedule. Every yield is a durable pause. Between two yields, nothing the user wrote runs on the server — the runtime decides when to resume and with what. Activities in Temporal approximate this; generators in Python make it idiomatic. The decorator compiles the function into a workflow definition; the runtime steps through it, calling the LLM to fill in the plan(...) blanks and dispatching workers to fulfill the execute(...) ones. In Agentspan&#39;s case the decorator becomes a Conductor workflow whose LLM-decided steps live as loop nodes that the planner extends at runtime.</p><figure><img alt="two planes of agent runtime — planner and executor" src="https://cdn-images-1.medium.com/max/1024/1*WNJo9UUUvMEaQwIHAKtozw.png" /></figure><h3>What’s in the ledger</h3><p>The ledger is Conductor’s task model — Netflix’s open-source workflow engine, running at scale since 2016.</p><p>Four properties of the ledger are what the rest of this design rests on.</p><p><strong>Identity.</strong> Every run has a stable ID; every step within it has a stable address that survives retries. That addressability is what turns a flat task list into a graph the runtime can navigate — extending it as the agent runs, resuming into it after a crash, unwinding it for compensation.</p><p><strong>History is append-only.</strong> Status transitions are monotonic. Committed rows do not mutate. Recovery reads the graph; it does not reconstruct it.</p><p><strong>Payload.</strong> Every step carries its input and its output as durable data, including token counts on LLM calls. The runtime rolls those counts into a workflow-level total as tasks complete, which is what makes budget caps a single read rather than a scan.</p><p><strong>Graph.</strong> Parent-child relationships come from the workflow definition the compiler emitted — the fan-out node and its children, the sub-workflow call and its body — not from a parent-pointer column. Compensation walks this structure backward.</p><p>One consequence deserves a closer look. Effectively-once against an external system depends on the worker passing a stable idempotency key on every retry. The ledger’s per-step address is that key: unique across the saga’s history, stable across retries, already available. Workers hash it into the Idempotency-Key header when calling Stripe or anything else that honors one. The ledger guarantees effectively-once inside the runtime. The idempotency key extends it one hop outward — and only one hop, because the external system has to cooperate.</p><figure><img alt="agent runtime ledger for durability" src="https://cdn-images-1.medium.com/max/1024/1*muQ17qlAzKhC4px5vuLNVw.png" /></figure><h3>Tools MUST run somewhere else</h3><p>SDK-embedded workers — where your “tool” is a Python function that the agent library calls directly in-process — collapse the dispatcher into your code. They feel simpler at the hello-world stage. They become a cage the moment one of three things is true: you want to scale the tool independently of the planner (one high-throughput scraper, one high-memory reasoning node); you want to write the tool in a language other than the planner’s (your underwriting model has lived in Java for fifteen years, and nobody is rewriting it); you want to bound the blast radius of a tool crash (the tool segfaulted on a pathological PDF; your planner should not go down with it).</p><p>A workers-as-protocol-clients model — where a worker is any process that speaks the runtime’s task protocol and polls for work — addresses all three. The planner doesn’t know or care where get_weather lives. It proposes get_weather(&quot;NYC&quot;); the runtime writes the proposal and enqueues a task on a queue named get_weather; any worker subscribed to that queue picks it up, runs, and acks. Python, Go, Java, a serverless endpoint, an HTTP API — the runtime doesn&#39;t distinguish. Agentspan ships sugar variants (http_tool, api_tool, mcp_tool) that let the server itself act as the worker for pure-HTTP tools, so you don&#39;t need to run anything separate to call Stripe. The substrate is the same regardless: the planner proposes, the dispatcher queues, a worker — somewhere — handles the queue. Conductor has been shaping this protocol since 2016.</p><h4>Credentials</h4><p>One consequence worth dwelling on: tools run in their own process by default. A @tool with credentials=[&quot;STRIPE_KEY&quot;] gets that key injected into its subprocess environment, scoped to the execution, and the key never enters the planner&#39;s process. The planner can&#39;t leak a credential it was never handed. Agents that reason about Stripe don&#39;t have Stripe&#39;s API key in their prompt context. This is not a security feature bolted on; it&#39;s what falls out of separating the planes and dispatching across a boundary.</p><h3>Compilation: the agent becomes a workflow</h3><p>When you write an agent in one of the Agentspan SDKs — Python, TypeScript, Java, Go, .NET, Ruby, or Rust — you are not writing an agent. You are writing a <em>specification</em>: which model to use, which tools it has, which strategies apply (handoff, sequential, parallel, swarm), which guardrails fire on which events, which memory and context-management policies apply, which credentials bind where, which evals run when. Callables get replaced with _worker_ref markers at serialization. The spec lands on the server as a structured JSON DTO. Two stages run before the agent ever executes.</p><p>The <strong>normalizer</strong> converts framework-specific agent shapes into a canonical AgentConfig. An OpenAI Agents SDK agent, a Vercel AI SDK agent, a LangGraph StateGraph, a LangChain AgentExecutor, a Claude Agent SDK agent, a Google ADK LlmAgent, and a native Agentspan agent all land on the same AgentConfig type. A Spring-based NormalizerRegistry auto-discovers AgentConfigNormalizer beans and dispatches on frameworkId(), so supporting a new framework is a new normalizer — nothing else downstream changes. Everything downstream operates on AgentConfig; nothing downstream knows which framework the user wrote in.</p><p>The depth of that lowering varies by framework. Three strategies exist in the codebase:</p><ul><li><strong>Full extraction</strong> (OpenAI, Vercel AI, LangGraph-with-model). Model config, tools, guardrails, handoffs, and output schemas are fully extracted. The LLM call runs as a server-side Conductor task; each tool becomes an independent worker task. This is the tightest integration and gets the most value out of the runtime.</li><li><strong>Graph-structure preservation</strong> (LangGraph with an emitted _graph). The LangGraph DAG — nodes, edges, conditional edges, reducers, retry policies, recursion limits — carries through into a corresponding Conductor workflow. LLM nodes, human nodes, and subgraph nodes each compile to their matching primitive. Conditional edges become router workers. Recursion limits map to the loop&#39;s iteration cap.</li><li><strong>Passthrough</strong> (LangChain, Claude Agent SDK, LangGraph fallback). The entire framework-specific agent runs inside a single SIMPLE worker task. Agentspan wraps it without introspection. You still get durable execution, crash recovery, HITL, and observability — just not the fine-grained step-level tracing that full extraction provides.</li></ul><p>One canonical IR, multiple lowering depths, the same runtime properties regardless of how deep the lowering went. You can port incrementally — start passthrough, move to graph-structure, move to full extraction — without rewriting the agent.</p><p>The <strong>compiler</strong> takes the AgentConfig and emits a Conductor workflow definition. Stripped of implementation detail, the dispatch looks like this:</p><pre># Given a canonical AgentConfig, emit a Conductor workflow.<br>def compile(agent: AgentConfig) -&gt; WorkflowDef:<br>    match agent.strategy:<br><br>        case SingleAgentWithTools:<br>            return do_while(<br>                body=[<br>                    llm_chat_complete(agent.model, agent.tools),<br>                    switch_on_llm_response({<br>                        &quot;tool_call&quot;: simple_task(&quot;${plan.tool}&quot;),<br>                        &quot;fan_out&quot;:   fork_join(&quot;${plan.fan_out}&quot;),<br>                        &quot;handoff&quot;:   sub_workflow(&quot;${plan.agent}&quot;),<br>                    }),<br>                ],<br>                until=agent_done,<br>            )<br><br>        case Parallel:               return fork_join(agent.children)<br>        case Handoff | AgentAsTool:  return sub_workflow(agent.child)<br>        case HumanInTheLoop:         return human_task(agent.form)<br>        case Guardrail:              return check_task(agent.guardrail,<br>                                                       on_fail=agent.policy)<br>        case InlineGate:             return inline_js(agent.script)</pre><p>Two things worth naming. First, the HumanInTheLoop case emits Conductor&#39;s native HUMAN system task — no worker, no poll loop; the task sits in the ledger until a signal arrives. Second, the InlineGate case compiles simple sentinel logic (a text-contains check between sequential stages, for instance) into an INLINE task that runs server-side via graaljs: no worker round-trip for the things that do not need one.</p><p>Here is what it looks like end-to-end. A three-line agent definition:</p><pre>from agentspan.agents import Agent, tool<br><br>@tool<br>def search_candidates(role: str, limit: int) -&gt; list[str]: ...<br><br>@tool<br>def request_interview(candidate_id: str) -&gt; str: ...<br><br>agent = Agent(<br>    name=&quot;hiring_agent&quot;,<br>    model=&quot;anthropic/claude-sonnet-4-6&quot;,<br>    tools=[search_candidates, request_interview],<br>)</pre><p>Compiles to this Conductor workflow (abbreviated):</p><pre>{<br>  &quot;name&quot;: &quot;hiring_agent&quot;,<br>  &quot;tasks&quot;: [{<br>    &quot;name&quot;: &quot;agent_loop&quot;,<br>    &quot;type&quot;: &quot;DO_WHILE&quot;,<br>    &quot;loopCondition&quot;: &quot;$.iteration.done == false&quot;,<br>    &quot;loopOver&quot;: [<br>      { &quot;name&quot;: &quot;plan&quot;,<br>        &quot;type&quot;: &quot;LLM_CHAT_COMPLETE&quot;,<br>        &quot;inputParameters&quot;: {<br>          &quot;model&quot;: &quot;anthropic/claude-sonnet-4-6&quot;,<br>          &quot;messages&quot;: &quot;${workflow.input.history}&quot;,<br>          &quot;tools&quot;: [&quot;search_candidates&quot;,<br>                    &quot;request_interview&quot;]<br>        }<br>      },<br>      { &quot;name&quot;: &quot;route_on_response&quot;,<br>        &quot;type&quot;: &quot;SWITCH&quot;,<br>        &quot;evaluatorType&quot;: &quot;value-param&quot;,<br>        &quot;expression&quot;: &quot;$.plan.output.action_type&quot;,<br>        &quot;decisionCases&quot;: {<br>          &quot;tool_call&quot;: [<br>            { &quot;type&quot;: &quot;SIMPLE&quot;,<br>              &quot;name&quot;: &quot;${plan.output.tool}&quot; }<br>          ],<br>          &quot;fan_out&quot;: [<br>            { &quot;type&quot;: &quot;FORK_JOIN&quot;,<br>              &quot;forkTasks&quot;: &quot;${plan.output.fan_out}&quot; }<br>          ],<br>          &quot;handoff&quot;: [<br>            { &quot;type&quot;: &quot;SUB_WORKFLOW&quot;,<br>              &quot;name&quot;: &quot;${plan.output.target_agent}&quot; }<br>          ]<br>        },<br>        &quot;defaultCase&quot;: [{ &quot;type&quot;: &quot;TERMINATE&quot; }]<br>      }<br>    ]<br>  }]<br>}</pre><p>Nothing in that JSON is novel. Conductor has been running workflows shaped like this for a decade. What’s new is that the LLM_CHAT_COMPLETE task exists, and that the SWITCH on the LLM’s output is the <em>only</em> dynamic part of the graph. Everything else — retry policies, rate limits, worker dispatch, crash recovery, the visual UI that renders this workflow when it runs — is what Conductor does every day orchestrating video pipelines at Netflix. Temporal would be an equally valid substrate to build this on; Conductor is the one I know, and the one Agentspan uses.</p><p>The workflow that comes out is <strong>deterministic in Conductor’s sense</strong>. Conductor does not know or care that an LLM_CHAT_COMPLETE task calls an LLM, that a SUB_WORKFLOW is another agent, or that a HUMAN task is waiting on a recruiter’s click. It sees a graph of tasks, schedules them, records their results, retries per policy, applies rate limits, emits metrics, persists state. Durable workflow execution, distributed priority task queues, crash recovery, replay from a checkpoint, pause and resume — everything Conductor has done for a decade orchestrating Netflix’s pipelines now runs under the agent.</p><p>What the LLM contributes — the part that is <em>not</em> deterministic — is the <em>values</em> it produces: which tool to call, which handoff to take, which branch of a conditional to follow, when the DO_WHILE exits. The LLM is the <strong>brain</strong>, selecting edges in a graph that Conductor walks. The tools are the <strong>hands</strong>, executing what the brain selected. The workflow is the skeleton. The compiler produces the skeleton from your spec.</p><p>The late-bound saga from earlier sections is what this looks like at runtime: the specific path the agent’s execution takes through that skeleton, recorded in the ledger node by node. The skeleton is structurally bounded; the trajectory through it is decided by the model.</p><figure><img alt="Agent runtime — compiling an agent into deterministic workflow" src="https://cdn-images-1.medium.com/max/1024/1*8gI8wygQdwCGXQN3GQbiZA.png" /></figure><p>Because the agent compiles to a Conductor workflow, it inherits Conductor’s retries, rate limits, replay, observability, restart-from-step-N, and visual UI — rather than reimplementing them. Retry on tool failure is the same retry Conductor does on any task. Rate limits on the model API are the same rate-limit primitives Conductor ships with. The execution UI is Conductor’s execution UI, rendering a graph whose nodes happen to include LLM calls. Replay is Conductor’s replay. Restart is Conductor’s restart. Everything that is production-grade for a workflow engine is now production-grade for an agent, because the agent <em>is</em> a workflow.</p><p>And because the emitted artifact is a Conductor workflow definition, every agent in Agentspan is, in a literal sense, a workflow you can inspect, diff, version, export, and run by hand without the SDK. The compiler’s output is not an implementation detail. It is a first-class artifact.</p><h3>How the graph grows</h3><p>The compiled workflow is the skeleton. The saga’s <em>trajectory</em> through it — which iterations of the main loop fire, which tools get called in which order, which branches of which guardrail trigger — does not exist when the saga starts. Here is how it fills in.</p><p>The runtime begins with a single root node: the task. It asks the planner for the next intent, passing the root’s input as the history. The planner returns an intent — call it plan_0. The runtime writes plan_0 as a plan step. Its output contains a list of N proposed effects — possibly one, possibly many if the model emitted parallel tool calls. The runtime materializes those N effects as scheduled steps, all wired together as children of the plan, in one transactional commit. That commit is the monotonic durable graph doing its job: either all the children are scheduled or none of them are.</p><p>Now the runtime dispatches the N effects. Each effect travels to a worker queue; each worker pulls, executes, and acks with a result. Each result is a ledger write that flips the step’s status to a terminal state. The runtime watches for the fan-in: once all N children have completed, it asks the planner for the next intent, handing it the updated history — which now includes plan_0 and all its children. The planner emits plan_1. The graph extends.</p><p>That is the whole algorithm. <em>Plan, commit, dispatch, join, plan.</em> Every one of those verbs is a durable operation. The loop lives in the runtime, not in your code, which means the loop survives when your code doesn’t.</p><p>Recovery is straightforward. The runtime starts a saga supervisor from the ledger: it reads the saga’s graph, finds the frontier (the set of steps not yet in a terminal state, and the most recent plan without a successor), and resumes. If a step was scheduled but never picked up by a worker, it re-enqueues it. If a step was in flight — dispatched, no result yet — the worker either reports back (it survived) or the step times out and the runtime decides whether to redispatch (it didn’t). If a plan is waiting on its children, the runtime waits. If all children are done, it calls the planner. Recovery doesn’t need a special code path; it’s the same code path as forward progress, started from a different place in the graph.</p><h3>Signals: how the outside reaches a suspended saga</h3><p>A signal is a message addressed to saga_id, written to the ledger as a signal kind step, and delivered to the planner on its next call as part of the history. That&#39;s the whole mechanism. The things that fall out of it:</p><p><strong>A human clicking “approve”</strong> on a tool that requires approval is a signal. The approval-required tool proposed the effect; the runtime suspended the saga waiting for the signal; the UI wrote a signal row when the human clicked; the runtime woke the saga; the planner saw the approval in its history on the next call. Days of wall-clock time, zero process-resident state.</p><figure><img alt="Agent runtime — durability across long running agents surviving crashes" src="https://cdn-images-1.medium.com/max/1024/1*CFXb20hwjh7tK3a1lcJDsQ.png" /><figcaption>Agent runtime — durability across long running agents surviving crashes</figcaption></figure><p><strong>A timeout, a cancellation, or a supervisor telling a sub-saga to abort</strong> are all the same mechanism: a signal written to the target saga’s ledger. Timers are the runtime writing to itself when a deadline passes. Cancellations are the runtime writing on behalf of a user. Agent-to-agent messaging is one planner writing to another saga. If the writer dies mid-signal, the write either committed (and the target sees it) or did not (and the writer’s recovery will retry). There is no RPC, no shared memory, no in-process delivery. The ledger is the inbox.</p><p><strong>A budget cap is a signal</strong> the runtime writes when sum(tokens_in + tokens_out) * price crosses a threshold recorded at saga start. The planner sees budget_exceeded and can compensate, summarize, or escalate. Because cost is a ledger column, this is a SQL trigger, not a framework feature.</p><p>At-least-once is the right semantics for signals; deduplication happens at the saga level by letting the planner see duplicate signals in its history and filter them. Making the runtime dedupe is tempting and wrong: the runtime doesn’t know what “two signals mean the same thing” means.</p><h3>Compensation for a graph the model wrote</h3><p>Traditional sagas have static compensations: every local transaction has a predeclared inverse. An agent’s graph is synthesized at runtime; the inverse has to be synthesized too. Three strategies, composed by the runtime in priority order.</p><p><strong>Tool-declared inverse.</strong> The @tool author declared a compensation — another @tool or inline function — at definition time.</p><ul><li><em>How the runtime executes it:</em> on unwind, the runtime walks the graph backward, finds every effect with a registered compensation, and dispatches the inverses in reverse order, each through its own proposal-before-effect bracket.</li><li><em>Failure mode:</em> the compensation itself can fail (e.g., the refund API is down). The runtime retries per policy; on persistent failure, the saga escalates with partial-unwind state recorded in the ledger.</li></ul><p><strong>Model-authored sequence.</strong> The saga receives a cancel signal and at least one effect has no declared inverse.</p><ul><li><em>How the runtime executes it:</em> the planner sees the cancel signal in its history and emits a propose_compensation_sequence intent. This is a plan node; its children are effect nodes; all go through the same four-property bracket. The compensation is a sub-saga of the main saga.</li><li><em>Failure mode:</em> the model proposes an incorrect compensation. The ledger records the attempt; an operator can intervene. This is not a runtime failure; it is the correct answer to a fundamentally semantic problem.</li></ul><p><strong>Escalation.</strong> An effect is flagged irreversible: true on the tool definition (e.g., wire_transfer, send_email).</p><ul><li><em>How the runtime executes it:</em> the runtime stops unwinding at the irreversible boundary. The planner receives the halt condition in its history and can propose a forward-compensating action (wire money back, send correction email) or emit a human_decision_required signal.</li><li><em>Failure mode:</em> none at the runtime level — the runtime correctly refuses to pretend the irreversible action can be undone. Semantic resolution is the operator’s job.</li></ul><p>Irreversibility is a property of the tool, recorded as a flag on the effect. wire_transfer is irreversible. send_email is irreversible. write_to_db is typically not. The runtime never pretends otherwise. When the compensation planner asks the model to unwind, the history contains the irreversibility flags; the model is instructed to stop at the boundary and escalate, or propose a forward-compensating action. Neither the runtime nor the model can undo an ACH transfer; the runtime&#39;s job is to make sure nobody pretends otherwise.</p><h3>Context is the hard problem</h3><p>The ledger is unbounded. A saga can have tens of thousands of steps. The planner’s context window is bounded, and the bound is not growing fast enough to outrun the growth in trajectory length. Every runtime has to reconcile these two, and no projection strategy does it cleanly — they’re all lossy in different directions.</p><p>The design move is to refuse to pick one. The ledger stays the source of truth; the planner sees a projection of it; and the projection is a first-class, pluggable function the operator chooses per agent:</p><pre># The projection is the contract between ledger and planner.<br># Stable signature; operator-chosen implementation.<br>def project(ledger: Ledger, at_step: int) -&gt; History: ...</pre><p>That signature is load-bearing. The function is pure, deterministic given the ledger, and invoked at every planner step. Agentspan ships three implementations and lets you register your own:</p><ul><li><strong>Full replay.</strong> Feed the entire ledger in. Works for short sagas, breaks on long ones, wastes money on every step because the prefix doesn’t change.</li><li><strong>Windowed.</strong> Feed the root plus the last K steps. Simple, cheap, and catastrophic the moment the model needs context from step 14 of a 2000-step saga. Pair with a recall(step) tool so the planner can pull an old step&#39;s output back into context when it notices the gap.</li><li><strong>Summarized.</strong> Periodically, the runtime inserts a summarize plan step whose output replaces a chunk of the ledger in future views. The summaries themselves live in the ledger, which means they replay, which means a debug session months later sees exactly what the planner saw.</li></ul><p>There is no best projection. Summarization is the least lossy but costs an LLM call to produce and can bury a detail the model needed on step 847. Windowing is cheapest but blind to anything old. Retrieval splits the difference but puts load on the planner to know what to ask for. Which is right depends on the agent, the average saga length, the cost budget, and what the agent is expected to remember. Making the choice explicit — a configured projection per agent, recorded in the workflow definition, visible in the ledger — is what turns “memory” from a black box into a debuggable surface.</p><p>Two properties of this design matter more than which strategy you pick.</p><p><strong>The projection is recorded, not inferred.</strong> Every planner step in the ledger references the projection function and its parameters. When you open a saga in the UI six months later and ask “why did the agent not use the invoice from step 40?”, the answer is visible: the projection at step 312 was windowed(k=50), and step 40 wasn&#39;t in the window. Without that recording, the question has no answer.</p><p><strong>Projections compose.</strong> A real production agent uses more than one. The typical shape is windowed recent history plus summarized older history plus a retrieval escape hatch — three projections stacked into one History. Because the projection is a function, composition is function composition. Because the composition is registered per agent, the operator can change the mix without touching the agent&#39;s code.</p><p>This is also where the illusion of “memory” ends and the mechanics begin. An agent “remembers” a fact from two hours ago if, and only if, the projection at step N includes that fact. The ledger never forgot; the projection did. Being precise about this is the difference between a runtime you can reason about and a system that occasionally surprises you.</p><h3>Replay and the model-version problem</h3><p>Temporal’s promise is deterministic replay: given the same code and the same activity outputs, the workflow produces the same decisions. That property is load-bearing for correctness on top of Temporal.</p><p>You can’t have it for agents. Temperature=0 is not bit-exact across infrastructure changes. Model versions change underneath you. Injecting the current date alone introduces non-determinism in the LLM’s output. Asking for deterministic replay in the Temporal sense is asking the model to be reproducible, and it isn’t.</p><p>So the runtime has to distinguish two kinds of replay.</p><p><strong>Recovery replay</strong> is what happens when a process dies and a saga resumes. This is deterministic in the sense that matters: committed results are treated as final, uncommitted effects are re-dispatched with the same idempotency key, no LLM call is re-issued for a committed plan step, no tool is re-invoked for a committed effect. The saga moves forward from where it was. This is sound because proposal-before-effect plus the durable graph make side effects witnessable; you don’t need the model to be bit-exact, you need the ledger to be.</p><p><strong>Cognitive replay</strong> is what happens when you want to ask “what would this agent have done if I changed prompt X?” at debugging time. This is not deterministic; it’s a new run against a recorded history. You run the planner with the ledger’s input at step K and see what comes out. You compare. The answer is rarely the same tokens, but it’s often the same shape, and the shape is what you want when you’re debugging.</p><p>The cost of getting these confused is high. Teams who expect cognitive replay to be bit-exact build flaky test suites. Teams who expect recovery replay to “just work” without the proposal-before-effect bracket double-charge customers. Separating them — in the design and in the UI — is worth the effort.</p><h3>Testing agents without shipping them to production</h3><p>The ledger doubles as the substrate for every testing strategy an agent runtime actually needs. There are three patterns, each targeting a different failure mode, each built on the same artifact: a recorded ledger.</p><p><strong>Unit-testing the planner.</strong> The planner is a pure function — f(history) -&gt; intent — with no side effects. That makes it unit-testable the way any pure function is: construct a history, call the planner, assert on the intent. In practice, &quot;constructing a history&quot; means either writing ledger rows by hand (tedious but precise) or loading a recorded saga&#39;s ledger and feeding it to the planner at an arbitrary step. The runtime exposes the second pattern as a first-class operation:</p><pre>from agentspan.testing import load_saga, run_planner<br><br>ledger = load_saga(&quot;s_42&quot;)<br>intent = run_planner(agent, ledger, at_step=5)<br>assert intent.tool == &quot;enrich_candidate&quot;<br>assert intent.args[&quot;limit&quot;] == 20</pre><p>This tests the planner’s decision at step 5 of a real saga without running any tools, without hitting any external system, and without spending any tokens beyond the one planner call. A CI run of 100 such tests costs less than one production saga.</p><p><strong>Integration-testing the saga.</strong> The runtime’s end-to-end test is: start a saga with a fixed seed (deterministic tool-mocks, recorded LLM responses), let it run to completion, compare the resulting ledger to a golden ledger. Every row in the golden ledger must match: plans, effects, signals, compensations, terminal status. This is the kind of test that catches “the agent used to call the search tool three times; now it calls it four” — a regression the LLM alone would not surface.</p><pre>from agentspan.testing import replay_saga, assert_ledger_matches<br><br>result = replay_saga(<br>    agent,<br>    task=&quot;hire for senior backend&quot;,<br>    llm_responses=fixture(&quot;recorded_responses.json&quot;),<br>    tool_mocks={&quot;search_candidates&quot;: lambda role, limit: [...], ...},<br>)<br>assert_ledger_matches(result.ledger, fixture(&quot;golden_ledger.json&quot;))</pre><p><strong>Regression-testing against model version changes.</strong> When the model provider ships claude-sonnet-4-7 and you want to know whether it behaves the same as claude-sonnet-4-6 on your production workloads: cognitive replay becomes CI. Point the planner at a corpus of real ledgers, rerun each at a specific step with the new model, diff the trajectories. The question isn&#39;t &quot;does the new model produce the same tokens&quot; — it won&#39;t — but &quot;does the new model make the same <em>decisions</em> at the same branch points.&quot; This is measurable: for each plan step, the old model proposed tool X with args A; the new model proposed tool Y with args B. You score the divergence. Anything over a threshold triggers human review before the model version rolls forward.</p><p>Crucially, none of these patterns require the runtime to support a special “test mode.” They all operate on the ledger — the same artifact the runtime produces in production. A test is just a saga you run against recorded inputs and assert on the result. A regression check is just a saga you replay. An outage debug is just a saga you load in the UI. One substrate, three use cases, one mental model.</p><h3>Observability is not a feature</h3><p>Distributed tracing for agents is often sold as a checkbox. In a ledger-based runtime, it’s what you already have. Every step has timing data, a position in the graph, its input, its output, and a token count where relevant. A trace is a graph query. A waterfall is a topological sort. <em>Why did the agent do this</em> is a scan of the ledger ordered by time.</p><p>What you add on top is cosmetics: a visual UI over the graph, Prometheus metrics aggregated from the running totals, OpenTelemetry spans that correspond one-to-one with steps. The hard work was done when you decided the ledger had stable per-step addressing, durable inputs and outputs, and a workflow-level rollup. Don’t re-do it in a separate tracing layer.</p><h3>The cost of the ledger</h3><p>On a single-node Conductor setup with Redis-backed queues and Postgres-backed indexing (wrk2 sustained load, batched long-poll at 10 tasks/batch, ~80 MB/s sustained workload data), four writes per step is ~20ms of ledger overhead per state transition at p99. An LLM call is 500ms at the aggressive end — short output, warm model — and several seconds in the common case. The ledger is 1–3% of the planner round-trip. You do not feel it on the single-saga path. You feel the LLM.</p><p>What you feel under load is throughput, not latency. The same setup sustains ~1,450 task executions per second and ~210 moderately-complex workflows per second — a rate that projects to roughly 540M workflows per month on one commodity node. Netflix runs Conductor at multiple orders of magnitude beyond that using Cassandra with a Redis-based queuing layer. Servers are stateless; horizontal scale is linear until Redis or Postgres becomes the bottleneck, at which point the knobs are Redis Cluster and provisioned IOPS. Full methodology and numbers are in <a href="https://medium.com/orkes/running-a-billion-workflows-a-month-with-netflix-conductor-5fd358d9b6c1">Running a Billion Workflows a Month with Conductor</a>.</p><p>The real failure mode to watch for is ledger contention under fan-out. A saga that proposes 1,000 parallel effects in one plan step will commit 1,000 rows in one transaction, then drive 1,000 workers through 1,000 result writes. The ledger handles it. The bottleneck is the downstream worker queue, and more often, the external APIs the workers are calling. A runtime that has thought about this — partitioned queues per tool type, backpressure on fan-out width, per-saga write batching — absorbs the spike. A runtime that has not will throttle the wrong thing and the symptom will look like a database problem when it is a queue problem.</p><h3>Failure modes</h3><p>A design is only as good as its worst-case behavior. Five failure modes are what a production operator will actually see; this section is the runtime’s contract for how each is handled.</p><p><strong>Worker crash mid-tool-call.</strong> The worker process dies after the external side effect ran, but before acking the result back to the ledger.</p><ul><li><em>Detection:</em> task heartbeat timeout; the worker does not respond within the configured dispatch window.</li><li><em>Runtime response:</em> redispatch the task to any available worker, carrying the <strong>same idempotency key</strong>. The external system returns the existing result or re-executes idempotently. The ledger records the result exactly once.</li><li><em>Operator sees:</em> brief uptick in the task-retry metric. Saga completes without intervention.</li></ul><p><strong>LLM provider outage.</strong> The planner’s model API returns 5xx or times out on every request.</p><ul><li><em>Detection:</em> LLM_CHAT_COMPLETE task failure rate exceeds threshold over a rolling window.</li><li><em>Runtime response:</em> per-saga exponential backoff up to a bounded ceiling. Sagas remain alive but paused. If the operator has configured a fallback model, the runtime fails over per policy.</li><li><em>Operator sees:</em> saga progress rate drops; no sagas fail. The backoff metric exposes the upstream issue directly.</li></ul><p><strong>Worker pool exhaustion.</strong> Task dispatch rate exceeds worker capacity for a particular tool; queue depth grows unboundedly.</p><ul><li><em>Detection:</em> queue depth metric exceeds threshold; task-wait-time p99 climbs.</li><li><em>Runtime response:</em> backpressure on new fan-outs for that tool type. Sagas that do not use the exhausted tool continue unaffected. Tasks are never silently dropped.</li><li><em>Operator sees:</em> “Workers for tool_x saturated&quot; alert. Sagas depending on tool_x slow; others unaffected.</li></ul><p><strong>Context window overflow.</strong> A saga’s history exceeds the planner’s context bound.</p><ul><li><em>Detection:</em> the projection function detects token count over the configured model limit before dispatching the LLM_CHAT_COMPLETE task.</li><li><em>Runtime response:</em> apply the configured context-management policy — summarization, windowed truncation, or explicit retrieval-on-demand. If no policy is configured and hard overflow is reached, the saga fails with CONTEXT_OVERFLOW and the ledger is preserved for inspection.</li><li><em>Operator sees:</em> either degraded saga quality (summarization was lossy) or explicit saga failure with a full ledger to debug. Never a silent truncation.</li></ul><p><strong>HITL signal delayed indefinitely.</strong> A saga suspends on a HUMAN task; the human takes a weekend, a vacation, or never responds at all.</p><ul><li><em>Detection:</em> the HUMAN task is a durable row in the ledger; its signal is delivered through a queue-backed eventing layer. Signals are not lost — they are received whenever the human eventually acts, or never at all if they don’t. The failure mode here is semantic (did the human respond?), not delivery (did the message arrive?).</li><li><em>Runtime response:</em> the saga stays suspended, consuming zero compute, until a signal arrives. If a per-HUMAN-task timeout is configured, the runtime writes a timeout signal at the deadline and the planner decides how to proceed (retry, compensate, escalate). Without a configured timeout, the saga remains suspended indefinitely, which is sometimes the correct behavior — a pending approval is a pending approval.</li><li><em>Operator sees:</em> the saga surfaces as “awaiting human” in the UI with full ledger context and the age of the wait. Suspended sagas are first-class inventory, not zombie processes.</li></ul><p>The unifying principle: <strong>the runtime’s worst behavior is to stop making progress, never to make incorrect progress.</strong> A stopped saga is debuggable. A saga that silently did the wrong thing is not. Every failure mode above chooses visibility and pause over silent continuation.</p><p>Three classes of issue are explicitly out of scope for the runtime to handle and belong to the operator or the application:</p><ul><li><strong>Logic bugs in tools.</strong> A tool that computes the wrong answer is the tool author’s problem. The runtime records the call and the result; it does not validate correctness.</li><li><strong>Prompt injection via tool outputs.</strong> A malicious tool output that manipulates the planner is a content-layer problem. Guardrails help; the runtime does not detect injection.</li><li><strong>Semantic compensation.</strong> The runtime walks the graph backward on cancel; it does not know that refunding a payment also requires sending an apology email. The compensation planner decides; the runtime executes.</li></ul><h3>Tradeoffs accepted</h3><p>No design is free. Five costs we pay on purpose, each chosen because the alternative was worse.</p><p><strong>No deterministic replay of the planner.</strong> Temperature=0 does not give bit-exact replay across infrastructure; model versions change; even the current date in context produces different outputs.</p><ul><li><em>What we get:</em> recovery replay still works — committed results are final, uncommitted effects re-dispatched with the same idempotency key. Cognitive replay becomes a design-time tool, not a correctness guarantee.</li><li><em>Why it’s the right call here:</em> LLMs are non-deterministic. A runtime that pretends otherwise builds flaky tests and misleads its operators. Separating the two kinds of replay is the honest abstraction; collapsing them to sell “Temporal for agents” is not.</li></ul><p><strong>More operational surface area.</strong> A runtime server, a queue, a database, a worker pool, a UI. Not a single import.</p><ul><li><em>What we get:</em> durable execution, horizontal scaling, operator visibility, the ability to reason about one saga across pods, the ability to kill a saga by ID from outside its process.</li><li><em>Why it’s the right call here:</em> the alternative — an in-process agent library — is a single point of failure that cannot be inspected, interrupted, or scaled independently of the application it’s embedded in. When the process dies, the saga dies with it, and nothing that happened during the run is recoverable. An operator staring at a production incident will take more components over a black box every time.</li></ul><p><strong>The agent definition is not Python — it’s a workflow.</strong> What you write in Python (or TypeScript, or Java) compiles to a Conductor workflow definition. The workflow is the artifact that runs.</p><ul><li><em>What we get:</em> production-grade retries, rate limits, observability, replay, pause/resume, a visual UI, horizontal scale, thirteen months of operational history — all inherited, not built.</li><li><em>Why it’s the right call here:</em> building these from scratch for agents is a decade of work that has already been done for workflows. Pretending that an agent is sufficiently different from a workflow to justify starting over is the mistake most agent frameworks have made. An agent is a workflow whose graph is synthesized at runtime by a non-deterministic planner. That’s the only new thing. Everything else is solved.</li></ul><p><strong>Signals at-least-once, not exactly-once.</strong> The planner may see the same signal twice in its history.</p><ul><li><em>What we get:</em> simpler delivery semantics. No distributed consensus required at the signal boundary. No “did my signal actually arrive” ambiguity because the ledger is the inbox.</li><li><em>Why it’s the right call here:</em> deduplication at the planner level is cheap — the LLM sees “accept” and “accept” in the history and treats them as the same event. Runtime-level exactly-once is distributed-systems folklore and does not exist without coordination overhead that would dominate the ledger’s latency budget. Pay the cheap dedup at the planner; skip the expensive dedup at the runtime.</li></ul><p><strong>No guarantee that the agent’s answer is correct.</strong> Guardrails catch policy violations; they do not validate truth.</p><ul><li><em>What we get:</em> the runtime is a substrate, not a referee. Correctness is a product-layer concern, handled by evals, human review, and domain-specific validators.</li><li><em>Why it’s the right call here:</em> correctness is not decidable in the general case. A runtime that claims to guarantee correct agent output is lying, and a runtime that tries to enforce correctness ends up either refusing valid outputs or waving through invalid ones. The honest move is to make the wrong answer <em>visible and debuggable</em> — through the ledger, the trace, the recorded projection at each step — rather than pretending to prevent it.</li></ul><p>The theme across all five: we prefer <strong>visible, bounded, operator-controllable cost</strong> over hidden, unbounded, operator-invisible cost. Every tradeoff above trades a marginal cost for the ability to reason about the system from outside it. For production software, that is the correct direction.</p><h3>The irreducible core</h3><p>A runtime for agents — the nervous system between the brain and the hands — does six things. Everything else is sugar or consequence.</p><p>It <strong>owns the program counter</strong>, so your code dying does not kill the saga. It <strong>witnesses every intent</strong> before it becomes an effect, so “did this happen?” is always answerable. It <strong>gates every effect</strong> until the ledger can account for it, so you never charge the customer twice. It <strong>delivers every external signal</strong> as a first-class ledger event, so the outside world can interrupt a running agent without racing it. It <strong>projects the growing history</strong> into the bounded context of a non-deterministic planner, so the model sees exactly what the runtime decides it should see. It <strong>refuses to execute any code the user wrote</strong> except as a dispatched task in a worker it does not share a process with, so one bad tool cannot take down the brain.</p><p>That is the core. Drop any one of the six and you have a framework that demos well and fails quietly. Keep all six and you have a runtime.</p><p>The decorator, the UI, the provider integrations, the multi-agent strategies, the guardrails, the compiler — all of it is either sugar over those six properties or a feature built by taking them as given.</p><p>An agent is not an LLM in a loop. It’s a saga the model writes as it runs, and the thing that makes it real is the runtime underneath.</p><h3>Appendix: key types</h3><p>The eight terms that do the most work in this document.</p><ul><li><strong>Saga.</strong> A long-running, durable agent execution. A single agent invocation produces a single saga, identified at the substrate level by a Conductor workflowInstanceId. Survives process death and cluster restarts.</li><li><strong>Step.</strong> A single task in the saga’s Conductor task list. Every plan, every effect, every signal, every compensation is a task. Identified by taskId (unique per attempt) and referenceTaskName (stable across retries).</li><li><strong>Plan.</strong> A task of type LLM_CHAT_COMPLETE in which the planner proposes what to do next. Output lands in outputData.toolCalls as one or more intents.</li><li><strong>Intent.</strong> The planner’s proposed next action: a tool call, a fan-out, a handoff, or a final answer. An intent is <em>data</em>, not an action. It becomes an action only when the runtime materializes it as a scheduled task.</li><li><strong>Effect.</strong> A task the runtime dispatches to execute an intent — typically SIMPLE, SUB_WORKFLOW, FORK_JOIN, or INLINE. Produces a result in outputData.</li><li><strong>Signal.</strong> A message addressed to a saga from outside the saga’s process. Signals from humans (delivered to a waiting HUMAN task), the runtime itself (timeouts, budget caps), or other sagas (supervisor abort). Delivered through Conductor&#39;s eventing layer; observed by the planner on its next call.</li><li><strong>Projection.</strong> The function that maps the full task history into the bounded context the planner sees on each call. Implemented as windowed truncation, summarization, retrieval-on-demand, or a mix.</li><li><strong>Lowering.</strong> The compiler’s job: transforming a canonical AgentConfig into a Conductor workflow definition. Called &quot;compilation&quot; in this document even though no code generation occurs, because the transformation has every property a compiler has except a target ISA.</li></ul><p>Code: <a href="https://github.com/agentspan-ai/agentspan">github.com/agentspan-ai/agentspan</a>. Agentspan is open source and looking for builders. PRs welcome.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=e6eb10bdfcdd" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/the-anatomy-of-an-agent-runtime-e6eb10bdfcdd">The anatomy of an agent runtime</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Three Reviewers, Two Rounds, One Verdict: Build a Code Review Debate with Round Robin]]></title>
            <link>https://medium.com/agentspan/three-reviewers-two-rounds-one-verdict-build-a-code-review-debate-with-round-robin-12d3c78d8d9a?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/12d3c78d8d9a</guid>
            <category><![CDATA[langgraph]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[agentic-workflow]]></category>
            <category><![CDATA[agentic-applications]]></category>
            <category><![CDATA[google-adk]]></category>
            <dc:creator><![CDATA[Deepti Reddy]]></dc:creator>
            <pubDate>Fri, 24 Apr 2026 18:49:43 GMT</pubDate>
            <atom:updated>2026-05-01T09:43:35.335Z</atom:updated>
            <content:encoded><![CDATA[<p>By Deepti Reddy | April 2026</p><p>This is Part 5 of an 8-part series covering every multi-agent strategy in AgentSpan. Today, we will cover the round robin strategy where agents take turns in a fixed rotation, each building on what the others said.</p><p>— -</p><h3>What is AgentSpan</h3><p>AgentSpan is an orchestration layer for building, bringing, and observing AI agents as durable workflows.</p><p>- Build: define agents with the AgentSpan SDK using Agent, @tool, and 8 multi-agent strategies. Compiles to server-side workflows that survive crashes.</p><p>- Bring: already using an agent framework such as LangGraph, OpenAI Agents SDK, or Google ADK? Pass your agents directly to run(). AgentSpan adds durability and orchestration on top.</p><p>- Observe: every execution is inspectable in the dashboard. See agent flows, inputs/outputs, tool calls, and token usage. Debug failures, replay runs.</p><h3>Setup</h3><p>Two commands:</p><pre>pip install agentspan<br>agentspan server start</pre><p>This gives you a local AgentSpan server with a visual dashboard at localhost:6767.</p><p>— -</p><p>In <a href="https://medium.com/agentspan/from-support-ticket-to-resolution-build-a-sequential-ai-agent-pipeline-5d1260f98e80">Part 1</a>, we built a sequential pipeline where each agent’s output feeds the next. In <a href="https://medium.com/agentspan/three-reviewers-one-pr-zero-wait-build-a-parallel-ai-agent-pipeline-dae75402d8f2">Part 2</a>, we built a parallel code review where three reviewers running simultaneously. In <a href="https://medium.com/agentspan/the-llm-decides-build-an-issue-triage-bot-with-the-handoff-strategy-6c4945609ff9">Part 3</a>, the LLM decided which agent runs. In <a href="https://medium.com/agentspan/agents-talk-to-each-other-build-a-support-swarm-with-peer-to-peer-transfers-c0a64c6bdd4b">Part 4</a>, agents transferred between each other peer-to-peer.</p><p>Every strategy so far either runs agents once or lets someone (a parent, a classifier, or the agents themselves) decide who goes next. But what about tasks where you want every agent to weigh in, then weigh in again — a back-and-forth discussion where each round builds on the last?</p><p>That is the round robin strategy. No routing. No decisions about who goes next. Just a fixed rotation: A, B, C, A, B, C. Each agent sees the full conversation history — what every other agent said before them — and builds on it.</p><h3>What we are building</h3><p>A code review debate with three reviewers who take turns:</p><p>1. Architect: focuses on design, structure, scalability</p><p>2. Security Reviewer: focuses on vulnerabilities, data exposure, insecure defaults</p><p>3. Pragmatist: focuses on what actually matters for shipping — minimum fix, what can wait</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qbJ5M6bh5FCXA-cA68r6kg.png" /></figure><p>They review the same code. But unlike parallel (Part 2), where each reviewer works independently, round robin reviewers read each other’s comments and respond to them. The architect raises a design concern. The security reviewer agrees and adds a vulnerability. The pragmatist pushes back — “that is a follow-up PR, not a blocker.” Two rounds of this, then a summarizer produces the verdict.</p><pre>Round 1: [Architect] -&gt; [Security] -&gt; [Pragmatist]<br>Round 2: [Architect] -&gt; [Security] -&gt; [Pragmatist]<br> |<br> [Summarizer] -&gt; APPROVE / REQUEST CHANGES</pre><h3>How is this different from parallel?</h3><p>In parallel (Part 2), all three reviewers run at the same time on the same input. They never see each other’s work. You get three independent opinions.</p><p>In round robin, reviewers take turns. Each one sees the full conversation — including what previous reviewers said. The second-round architect can respond to what the pragmatist said in round one. It is a discussion, not three monologues.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EeE4swILtA_GowrobbK0Mw.png" /></figure><h3>Defining the reviewers</h3><p>Three agents, each with a different perspective:</p><pre>architect = Agent(<br> name=”architect”,<br> model=”openai/gpt-4o”,<br> instructions=(<br> “You are a software architect reviewing code. Focus on:\n”<br> “- Design patterns and structure\n”<br> “- Separation of concerns\n”<br> “- Scalability and maintainability\n\n”<br> “Read what other reviewers said before you. Build on their points, “<br> “don’t repeat them. Keep your response to 2–3 paragraphs.”<br> ),<br>)</pre><pre>security_reviewer = Agent(<br> name=”security_reviewer”,<br> model=”openai/gpt-4o”,<br> instructions=(<br> “You are a security engineer reviewing code. Focus on:\n”<br> “- Injection vulnerabilities (SQL, command, path traversal)\n”<br> “- Authentication and authorization gaps\n”<br> “- Data exposure and insecure defaults\n\n”<br> “Read what other reviewers said before you. Build on their points, “<br> “don’t repeat them. Keep your response to 2–3 paragraphs.”<br> ),<br>)</pre><pre>pragmatist = Agent(<br> name=”pragmatist”,<br> model=”openai/gpt-4o”,<br> instructions=(<br> “You are a senior engineer who values shipping. Focus on:\n”<br> “- Is this good enough to merge today?\n”<br> “- What is the minimum fix needed?\n”<br> “- What can wait for a follow-up PR?\n\n”<br> “Push back on over-engineering. Read what other reviewers said “<br> “and decide what actually matters for this PR. “<br> “Keep your response to 2–3 paragraphs.”<br> ),<br>)</pre><p>The key instruction in each: “Read what other reviewers said before you. Build on their points, don’t repeat them.” This is what makes round robin a discussion, not a repetition. Each agent knows it is part of a conversation.</p><h3>The summarizer</h3><p>After the debate, a summarizer reads the entire transcript and produces a verdict:</p><pre>summarizer = Agent(<br> name=”summarizer”,<br> model=”openai/gpt-4o”,<br> instructions=(<br> “You observed a code review discussion between an architect, “<br> “a security reviewer, and a pragmatist. Produce a final verdict:\n\n”<br> “1. APPROVE, REQUEST CHANGES, or NEEDS DISCUSSION\n”<br> “2. Must-fix items (block merge)\n”<br> “3. Nice-to-have items (follow-up PR)\n”<br> “4. One-sentence summary\n\n”<br> “Be decisive. Don’t hedge.”<br> ),<br>)</pre><h3>The round robin strategy</h3><pre>review = Agent(<br> name=”code_review_round_robin”,<br> model=”openai/gpt-4o”,<br> agents=[architect, security_reviewer, pragmatist],<br> strategy=Strategy.ROUND_ROBIN,<br> max_turns=6,<br>)</pre><pre>pipeline = review &gt;&gt; summarizer</pre><p>max_turns=6 means 6 total turns: architect, security, pragmatist, architect, security, pragmatist. Two full rounds. Then &gt;&gt; pipes the discussion transcript to the summarizer for a verdict.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AgTPDdp4Mq2xO20oQk8y1Q.png" /></figure><p>Compare all six strategies:</p><pre># Sequential — fixed order, each runs once<br>pipeline = a &gt;&gt; b &gt;&gt; c</pre><pre># Parallel — all run at once<br>team = Agent(agents=[a, b, c], strategy=Strategy.PARALLEL)</pre><pre># Handoff — parent LLM picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.HANDOFF)</pre><pre># Router — classifier picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.ROUTER, router=classifier)</pre><pre># Swarm — agents transfer between each other<br>team = Agent(agents=[a, b, c], strategy=Strategy.SWARM)</pre><pre># Round Robin — fixed rotation, agents respond to each other<br>debate = Agent(agents=[a, b, c], strategy=Strategy.ROUND_ROBIN, max_turns=6)</pre><p>Same Agent class. Different strategy. Different behavior.</p><h3>The code to review</h3><p>A short Python snippet with a mix of design, security, and pragmatic issues:</p><pre>import sqlite3<br>import os<br><br>def get_user(db_path, user_id):<br> conn = sqlite3.connect(db_path)<br> query = f&quot;SELECT * FROM users WHERE id = {user_id}&quot;<br> result = conn.execute(query).fetchone()<br> conn.close()<br> return result<br><br>def save_upload(filename, data):<br> path = f&quot;/uploads/{filename}&quot;<br> with open(path, &quot;wb&quot;) as f:<br> f.write(data)<br> os.chmod(path, 0o777)<br> return path<br><br>def process_payment(amount, card_number):<br> print(f&quot;Processing ${amount} on card {card_number}&quot;)<br> return {&quot;status&quot;: &quot;ok&quot;, &quot;amount&quot;: amount}</pre><p>Three functions. SQL injection. Path traversal. Card number in logs. File permissions wide open. No error handling. But also — it is short, it works, and someone wants to merge it. The three reviewers will have very different opinions about what to do.</p><h3>Running it</h3><pre>with AgentRuntime() as runtime:<br> result = runtime.run(pipeline, code)<br> result.print_result()</pre><h3>What happens</h3><p>Round 1:</p><p>The architect goes first. Sees the raw code. Flags the lack of abstraction — no database layer, no upload service, direct file system access. Suggests separating concerns.</p><p>The security reviewer goes second. Sees the architect’s comments AND the code. Agrees on the design issues, then adds the critical security findings: SQL injection in get_user, path traversal in save_upload, card number logged in plaintext by process_payment, 0o777 permissions.</p><p>The pragmatist goes third. Sees both previous reviews. Agrees the SQL injection and card logging are blockers — those must be fixed before merge. But pushes back on the architecture refactoring: “That is a follow-up PR. The code works. Fix the security issues, merge, and refactor next sprint.”</p><p>Round 2:</p><p>The architect responds to the pragmatist: concedes the full refactor can wait, but insists on at minimum extracting the database connection into a context manager.</p><p>The security reviewer doubles down: the path traversal and 0o777 are just as critical as the SQL injection. All three security issues must be fixed, not just the SQL one.</p><p>The pragmatist agrees on all three security fixes, accepts the context manager suggestion, and calls it: “Fix those four things and this is ready to merge.”</p><p>Summarizer reads the whole transcript and produces the verdict.</p><p>This is the value of round robin over parallel. In parallel (Part 2), you get three independent opinions and have to synthesize them yourself. In round robin, the agents synthesize for you — they debate, converge, and the summarizer captures the consensus.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bi7Ew-JqdOIJYNuxMzW4VQ.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*p0K3MYsDj4Wodn5H2-foOA.png" /></figure><h3>Round Robin vs Parallel: when to use which</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DF0nSw-tHPm7xyVQfGTbqA.png" /></figure><p>Use parallel when speed matters and independence is a feature. Use round robin when convergence matters and you want agents to challenge each other.</p><h3>How durability works</h3><p>Same as every previous part. The round robin compiles into a durable DoWhile loop on the server. If your process crashes after turn 4 (second round, security reviewer just finished):</p><p>1. Turns 1–4 are persisted on the server.</p><p>2. You restart your script.</p><p>3. Turn 5 (pragmatist, round 2) resumes — no re-running the first 4 turns.</p><p>Each turn in the rotation is a durable checkpoint.</p><h3>Composability</h3><p>Round robin composes naturally:</p><pre># Debate, then summarize<br>pipeline = review &gt;&gt; summarizer</pre><pre># Parallel fan-out for data, then round robin debate on findings<br>research = Agent(agents=[market, technical, financial], strategy=Strategy.PARALLEL)<br>debate = Agent(agents=[optimist, skeptic], strategy=Strategy.ROUND_ROBIN, max_turns=4)</pre><pre>pipeline = research &gt;&gt; debate &gt;&gt; summarizer</pre><p>Parallel collects independent research. Round robin debates the findings. Summarizer produces the final recommendation. Three strategies, one pipeline.</p><h3>Try it</h3><pre>pip install agentspan<br>agentspan server start<br>python 06_code_review_debate.py</pre><p>- GitHub: <a href="https://github.com/agentspan-ai/agentspan">github.com/agentspan-ai/agentspan</a></p><p>- Blog examples: github.com/agentspan-<a href="https://github.com/agentspan-ai/agentspan/pull/160">ai/agentspan/tree/main/sdk/python/examples/blog_and_videos/round_robin</a></p><p>- Docs: <a href="https://agentspan.ai/docs">agentspan.ai/docs</a></p><p>- Discord: <a href="https://discord.com/invite/ajcA66JcKq">https://discord.com/invite/ajcA66JcKq</a></p><h3>What’s next</h3><p>Part 6: Random — A random agent is selected each turn. Not a rotation, not a decision but pure randomness. Useful for creative brainstorming, load balancing across models, and generating diverse output ensembles. Same Agent class, different strategy.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=12d3c78d8d9a" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/three-reviewers-two-rounds-one-verdict-build-a-code-review-debate-with-round-robin-12d3c78d8d9a">Three Reviewers, Two Rounds, One Verdict: Build a Code Review Debate with Round Robin</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Agents Talk to Each Other: Build a Support Swarm with Peer-to-Peer Transfers]]></title>
            <link>https://medium.com/agentspan/agents-talk-to-each-other-build-a-support-swarm-with-peer-to-peer-transfers-c0a64c6bdd4b?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/c0a64c6bdd4b</guid>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[agentic-workflow]]></category>
            <category><![CDATA[langgraph]]></category>
            <category><![CDATA[ai-agents-in-action]]></category>
            <dc:creator><![CDATA[Deepti Reddy]]></dc:creator>
            <pubDate>Fri, 24 Apr 2026 07:05:51 GMT</pubDate>
            <atom:updated>2026-04-24T08:25:21.311Z</atom:updated>
            <content:encoded><![CDATA[<p>By Deepti Reddy | April 2026</p><p>This is Part 4 of an 8-part series covering every multi-agent strategy in AgentSpan. Today: the swarm strategy agents hand off to each other using transfer tools. No manager and no classifier. Peer-to-peer.</p><p>— -</p><p>In <a href="https://medium.com/agentspan/from-support-ticket-to-resolution-build-a-sequential-ai-agent-pipeline-5d1260f98e80">Part 1</a>, we built a sequential pipeline, agents in a fixed order. In <a href="https://medium.com/agentspan/three-reviewers-one-pr-zero-wait-build-a-parallel-ai-agent-pipeline-dae75402d8f2">Part 2</a>, we built a parallel code review agents running simultaneously. In <a href="https://medium.com/agentspan/the-llm-decides-build-an-issue-triage-bot-with-the-handoff-strategy-6c4945609ff9">Part 3</a>, we built a handoff triage bot where the parent LLM decides the route.</p><p>Every strategy so far has been top-down. A parent agent, a classifier, or a fixed pipeline decides which agent runs. The agents themselves never talk to each other. The bug handler in Part 3 never said “actually, this should go to the docs handler.”</p><p>That is the swarm strategy. There is no parent deciding. Instead, every agent gets auto-generated transfer_to_&lt;peer&gt; tools. The refund specialist can transfer to tech support. Tech support can transfer back to the refund specialist. They decide among themselves — peer-to-peer.</p><h3>What we are building</h3><p>A customer support system with three agents that can transfer between each other:</p><p>1. Front-line Support: triages incoming requests, looks up orders</p><p>2. Refund Specialist: checks eligibility, processes refunds</p><p>3. Tech Support: checks warranty, creates warranty claims</p><p>The front-line agent gets the initial message. When it recognizes the issue, it transfers to the right specialist. But here is the key difference from handoff: the specialists can transfer to each other. If a customer asks for a refund but the issue is actually a product defect, the refund specialist transfers to tech support — no need to go back to the front-line agent first.</p><pre>Customer → [Front-line] → transfer_to_refund_specialist()<br> ↓<br> [Refund Specialist] → “this is a defect, not a return”<br> ↓<br> transfer_to_tech_support()<br> ↓<br> [Tech Support] → warranty claim created</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*EvnTC9aqbchCFDxWMKKNTA.png" /></figure><h3>How is this different from handoff and router?</h3><p>In handoff (Part 3), the parent agent’s LLM decides everything. Sub-agents are tools the parent calls. Once the bug handler runs, it cannot say “actually, send this to the docs handler”, it finishes and control returns to the parent.</p><p>In router, a dedicated classifier picks one specialist. Same limitation: once the specialist runs, it cannot redirect.</p><p>In swarm, every agent has transfer tools for every other agent. The LLM inside each agent can decide to transfer at any point during its own execution. There is no parent in the loop.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xQUTsTYKwrAuVYImNr_peQ.png" /></figure><h3>Setup</h3><p>Same as Parts 1 through 3:</p><pre>pip install agentspan<br>agentspan server start</pre><h3>Defining the specialists</h3><p>Each specialist has tools for its domain:</p><p>from agentspan.agents import Agent, AgentRuntime, Strategy, tool<br>from agentspan.agents.handoff import OnTextMention</p><pre>@tool<br>def lookup_order(order_id: str) -&gt; dict:<br> “””Look up order details and status.”””<br> return {<br> “order_id”: order_id,<br> “status”: “delivered”,<br> “item”: “Wireless Headphones (Model WH-1000)”,<br> “amount”: 249.99,<br> }<br></pre><pre>@tool<br>def check_refund_eligibility(order_id: str) -&gt; dict:<br> “””Check if an order is eligible for a refund.”””<br> return {<br> “order_id”: order_id,<br> “eligible”: True,<br> “refund_amount”: 249.99,<br> “processing_time”: “3–5 business days”,<br> }<br></pre><pre>@tool<br>def process_refund(order_id: str, amount: float, reason: str) -&gt; dict:<br> “””Process a refund for an order.”””<br> return {<br> “refund_id”: “RF-88431”,<br> “amount”: amount,<br> “status”: “processed”,<br> }<br></pre><pre>@tool<br>def check_warranty(order_id: str) -&gt; dict:<br> “””Check warranty status for a product.”””<br> return {<br> “order_id”: order_id,<br> “warranty_status”: “active”,<br> “warranty_expiry”: “2027–04–10”,<br> “claim_options”: [“replacement”, “repair”],<br> }<br></pre><pre>@tool<br>def create_warranty_claim(order_id: str, issue: str) -&gt; dict:<br> “””Create a warranty claim.”””<br> return {<br> “claim_id”: “WC-55102”,<br> “next_step”: “Prepaid shipping label via email within 24 hours”,<br> }</pre><p>Now the agents. Notice the instructions — each specialist knows when to transfer to the other:</p><pre>refund_specialist = Agent(<br> name=”refund_specialist”,<br> model=”openai/gpt-4o”,<br> instructions=(<br> “You are a refund specialist. Handle refund requests.\n\n”<br> “1. Use check_refund_eligibility to verify the order qualifies.\n”<br> “2. If eligible, use process_refund to issue the refund.\n”<br> “3. Confirm the refund amount, method, and timeline.\n\n”<br> “If the customer’s issue is actually a product defect (not a return), “<br> “transfer to tech_support — they handle warranty claims.”<br> ),<br> tools=[check_refund_eligibility, process_refund],<br>)</pre><pre>tech_support = Agent(<br> name=”tech_support”,<br> model=”openai/gpt-4o”,<br> instructions=(<br> “You are technical support. Handle product issues and warranty claims.\n\n”<br> “1. Use check_warranty to verify warranty status.\n”<br> “2. If under warranty, use create_warranty_claim.\n”<br> “3. Explain next steps to the customer.\n\n”<br> “If the customer just wants their money back (not a replacement/repair), “<br> “transfer to refund_specialist.”<br> ),<br> tools=[check_warranty, create_warranty_claim],<br>)</pre><p>The refund specialist knows: “if this is a defect, transfer to tech_support.” Tech support knows: “if they just want money back, transfer to refund_specialist.” They can bounce the customer between themselves — no parent agent involved.</p><h3>The swarm strategy</h3><pre>support = Agent(<br> name=”support”,<br> model=”openai/gpt-4o”,<br> instructions=(<br> “You are front-line customer support. Triage the request.\n”<br> “- Refund or return → transfer to refund_specialist\n”<br> “- Product issue or defect → transfer to tech_support\n”<br> “Do NOT handle refunds or technical issues yourself.”<br> ),<br> agents=[refund_specialist, tech_support],<br> strategy=Strategy.SWARM,<br> tools=[lookup_order],<br> handoffs=[<br> OnTextMention(text=”refund”, target=”refund_specialist”),<br> OnTextMention(text=”defect”, target=”tech_support”),<br> ],<br> max_turns=5,<br>)</pre><p>Two things are happening here:</p><p>1. Auto-generated transfer tools (primary mechanism). When you set strategy=Strategy.SWARM, AgentSpan automatically creates transfer_to_refund_specialist() and transfer_to_tech_support() as callable tools on the front-line agent. The LLM sees these tools and decides when to call them. Each specialist also gets transfer tools for every other agent, so refund_specialist gets transfer_to_tech_support() and vice versa.</p><p>2. OnTextMention fallback conditions (optional safety net). The handoffs= list provides fallback rules: if the agent’s response mentions “refund” but it did not call a transfer tool, the condition triggers and forces the handoff. These are optional — you can omit handoffs= entirely and rely purely on the auto-generated transfer tools.</p><p>The transfer tools are the core mechanism. The OnTextMention conditions are belt-and-suspenders.</p><p>Compare all five strategies:</p><pre># Sequential — fixed order, all run<br>pipeline = a &gt;&gt; b &gt;&gt; c</pre><pre># Parallel — all run at once<br>team = Agent(agents=[a, b, c], strategy=Strategy.PARALLEL)</pre><pre># Handoff — parent LLM picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.HANDOFF)</pre><pre># Router — separate classifier picks one<br>triage = Agent(agents=[a, b, c], strategy=Strategy.ROUTER, router=classifier)</pre><pre># Swarm — agents transfer between each other<br>team = Agent(agents=[a, b, c], strategy=Strategy.SWARM)</pre><p>Same Agent class. Different strategy. Different behavior.</p><h3>Running it</h3><pre>with AgentRuntime() as runtime:<br> result = runtime.run(<br> support,<br> “I bought wireless headphones (order ORD-7821) last week and “<br> “the left ear cup stopped working after 3 days. I want my money back.”,<br> )<br> result.print_result()</pre><p>This message is interesting because it has two intents: a product defect (left ear cup stopped working) AND a refund request (I want my money back). Watch what happens.</p><h3>The flow</h3><p>1. Front-line reads the message, sees “money back” → calls transfer_to_refund_specialist()</p><p>2. Refund specialist reads the full context, sees “stopped working after 3 days” → recognizes this is a defect, not a simple return → calls transfer_to_tech_support()</p><p>3. Tech support checks warranty (active until 2027), creates a warranty claim, offers replacement or repair options</p><p>That re-routing refund specialist deciding “actually, this is a tech issue” and transferring — is the thing that handoff and router cannot do. In those strategies, once a specialist runs, it finishes. In a swarm, agents redirect mid-conversation.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QicElOrsMj5Br9CqS-WqaQ.png" /></figure><h3>The transfer tool mechanism</h3><p>When you set strategy=Strategy.SWARM, AgentSpan auto-generates transfer tools. You do not define them. They appear as regular tools that the LLM can call.</p><p>For the front-line agent:</p><p>Available tools:<br> — lookup_order(order_id)<br> — transfer_to_refund_specialist() ← auto-generated<br> — transfer_to_tech_support() ← auto-generated</p><p>For the refund specialist:</p><p>Available tools:<br> — check_refund_eligibility(order_id)<br> — process_refund(order_id, amount, reason)<br> — transfer_to_tech_support() ← auto-generated<br> — transfer_to_support() ← auto-generated (back to front-line)</p><p>Every agent can reach every other agent. The LLM decides when — based on its instructions and the conversation context.</p><h3>OnTextMention: the fallback</h3><p>The handoffs= conditions are optional. They exist as a safety net:</p><pre>handoffs=[<br> OnTextMention(text=”refund”, target=”refund_specialist”),<br> OnTextMention(text=”defect”, target=”tech_support”),<br>]</pre><p>The evaluation order is:</p><p>1. Did the LLM call a transfer tool? → Yes → use that transfer. Done.</p><p>2. No transfer tool called? → Check OnTextMention conditions against the agent’s response text.</p><p>3. Condition matches? → Force the handoff.</p><p>4. Nothing matches? → No transfer. Agent’s turn ends.</p><p>The transfer tools are priority 1. The text conditions are priority 2. You can omit handoffs= entirely and the swarm still works — the LLM-driven transfers are the primary mechanism.</p><h3>When to use swarm vs handoff vs router</h3><p>Handoff<br> Use when: You want a parent agent to delegate.<br> Pattern: Top-down. Parent picks a child, child runs, control returns.<br> Example: Issue triage — read once, route once.</p><p>Router<br> Use when: Classification is straightforward and you want cost control.<br> Pattern: Top-down. Classifier picks, specialist runs.<br> Example: Ticket categorization at scale — cheap model classifies.</p><p>Swarm<br> Use when: Conversations evolve and agents need to redirect.<br> Pattern: Peer-to-peer. Any agent can transfer to any other.<br> Example: Support conversations where the initial classification is wrong.</p><p>The mental model: handoff and router are dispatchers, they pick once. Swarm is a team conversation as agents pass the baton as the situation evolves.</p><h3>How durability works</h3><p>Same as every previous part. The swarm compiles into a durable server-side workflow. If your process crashes after the refund specialist transfers to tech support but before tech support finishes:</p><p>1. The transfer decision is persisted on the server.</p><p>2. You restart your script.</p><p>3. Tech support resumes from where it was, no re-triage, no re-transfer.</p><p>Every transfer is a durable state transition on the server.</p><h3>Composability</h3><p>Swarm composes with other strategies:</p><pre># Swarm handles the conversation, then a summarizer wraps up<br>team = Agent(<br> agents=[support, refund_specialist, tech_support],<br> strategy=Strategy.SWARM,<br>)</pre><pre>pipeline = team &gt;&gt; summarizer</pre><p>Or use a swarm inside a larger handoff:</p><pre># Handoff decides: simple question → single agent, complex issue → swarm team<br>support_swarm = Agent(<br> agents=[refund_specialist, tech_support],<br> strategy=Strategy.SWARM,<br>)</pre><pre>router = Agent(<br> agents=[faq_agent, support_swarm],<br> strategy=Strategy.HANDOFF,<br>)</pre><p>Same Agent class. Strategies nest naturally.</p><h3>Try it</h3><pre>pip install agentspan<br>agentspan server start<br>python 05_support_swarm.py</pre><p>- GitHub: <a href="https://github.com/agentspan-ai/agentspan">github.com/agentspan-ai/agentspan</a></p><p>- Blog examples: <a href="http://github.com/agentspan-ai/agentspan/tree/main/sdk/python/examples/blog_and_videos/swarm">github.com/agentspan-ai/agentspan/tree/main/sdk/python/examples/blog_and_videos/swarm</a></p><p>- Docs: <a href="https://agentspan.ai/docs">agentspan.ai/docs</a></p><p>- Discord: <a href="https://discord.com/invite/ajcA66JcKq">https://discord.com/invite/ajcA66JcKq</a></p><h3>What’s next</h3><p>Part 5: Round Robin — Agents take turns in a fixed rotation. No routing decision at all, just A, B, C, A, B, C. Useful for debates, iterative refinement, and multi-perspective review. Same Agent class, different strategy.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c0a64c6bdd4b" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/agents-talk-to-each-other-build-a-support-swarm-with-peer-to-peer-transfers-c0a64c6bdd4b">Agents Talk to Each Other: Build a Support Swarm with Peer-to-Peer Transfers</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[How to Build Agents on Top of Your APIs with Agentspan]]></title>
            <link>https://medium.com/agentspan/how-to-build-agents-on-top-of-your-apis-with-agentspan-c691913df8ac?source=rss----6f29461513d7---4</link>
            <guid isPermaLink="false">https://medium.com/p/c691913df8ac</guid>
            <dc:creator><![CDATA[Nick]]></dc:creator>
            <pubDate>Sun, 19 Apr 2026 23:38:55 GMT</pubDate>
            <atom:updated>2026-04-24T17:32:44.363Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Z6XyoDzROo6lF79riA5obw.png" /></figure><p>Many teams already have the hard part of API integration in place. They have a documented service with a usable OpenAPI or Swagger spec. The friction starts when an AI agent needs to use that API. Writing a wrapper for each endpoint is repetitive, easy to drift from the spec, and not especially interesting work.</p><p>This walkthrough focuses how to cleanly expose your API surface to an agent so the agent can use it. The demo uses a small service catalog API, turns the published spec into runtime tools, narrows the operations visible to the agent, and then inspects the resulting run in the Agentspan UI.</p><h3>What is Agentspan?</h3><p><a href="https://agentspan.ai/">Agentspan</a> is an execution layer for AI agents. You define agents in Python, but execution state lives on the server, not inside the local process that happened to start the run. That gives you durable workflow state, tool history, execution IDs, and a UI that shows what happened step by step.</p><p>To get started with Agentspan, download and install the Python library.</p><pre>pip install agentspan</pre><p>This walkthrough was developed and tested against agentspan==0.1.5. You can work through all the steps in the accompanying <a href="https://github.com/agentspan-ai/agentspan-demos/tree/main/notebooks/api-tool-openapi-service">Jupyter notebook and support files</a>.</p><h3>What are Agentspan tools?</h3><p>Agentspan currently exposes four main tool patterns:</p><ul><li>@tool for custom Python functions</li><li>http_tool() for a single HTTP endpoint</li><li>api_tool() for a full OpenAPI, Swagger, or Postman-described API</li><li>mcp_tool() for tools exposed by an MCP server</li></ul><p>If you need one fixed endpoint, http_tool() is usually the smallest option. If you need local Python code or dependencies, use @tool. If the API already publishes a machine-readable spec and you want the runtime to discover multiple operations from that spec, api_tool() is the better fit.</p><p>api_tool() currently supports an explicit spec URL, request headers, injected credentials, max_tools, and tool_names. In practice, tool_names matters quickly. Real APIs often expose more operations than one agent should see at once, so narrowing the visible surface is part of using api_tool() well rather than an optional cleanup step.</p><h3>What this demo builds</h3><p>The demo service acts like a small internal operations API. It exposes service ownership, latest production deployment data, and runbook URLs for a few services. The agent’s job is to answer an on-call style question: who owns checkout-api, what changed in the latest production deploy, and which runbook should the engineer open first?</p><p>If you want to follow along from a clean environment, the minimal setup is:</p><pre>pip install agentspan==0.1.5<br>export OPENAI_API_KEY=your-own-key<br>agentspan server start --port 6770</pre><p>For the full soup-to-nuts execution, refer to the <a href="https://github.com/agentspan-ai/agentspan-demos/tree/main/notebooks/api-tool-openapi-service">demo directory</a>. It includes the Jupyter notebook and the supporting files the notebook runs against. The rest of this article keeps the code snippets short and focuses on the reasoning behind the setup.</p><h3>Turn an OpenAPI Document into Agent Tools with api_tool()</h3><p>The service in this demo publishes an OpenAPI document. In the Agentspan Python library, api_tool() is the tool type that turns a published API description into agent-callable runtime tools. In this snippet, the code does two things: it defines a scoped API-backed tool set from the published spec, and it defines an agent that will use only those operations when it answers service questions.</p><pre>from agentspan.agents import Agent, AgentRuntime, api_tool<br># Build a runtime tool set from the published OpenAPI document.<br>service_api = api_tool(<br>    url=&quot;http://127.0.0.1:8010/openapi.json&quot;,<br>    name=&quot;service_catalog_api&quot;,<br>    # Expose only the three operations this assistant actually needs.<br>    tool_names=[&quot;get_service_details&quot;, &quot;get_latest_deployment&quot;, &quot;get_service_runbook&quot;],<br>    max_tools=3,<br>)<br># Define the agent that will call those discovered API operations.<br>assistant = Agent(<br>    name=&quot;service_ops_assistant&quot;,<br>    model=&quot;openai/gpt-4o-mini&quot;,<br>    instructions=(<br>        &quot;You help on-call engineers answer questions about service ownership, &quot;<br>        &quot;production deployments, incidents, and runbooks. Use the API tools for facts.&quot;<br>    ),<br>    tools=[service_api],<br>)</pre><p>The important shift is that the code points to the published API description instead of duplicating endpoint definitions in Python. The runtime fetches the spec, resolves the selected operations, and turns them into tool calls the agent can use in a normal execution.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JS_Fqa3rBVfmdCNrIkcZvA.gif" /><figcaption><em>The notebook starts by inspecting the published operations, then runs the same focused </em><em>api_tool() configuration used in the final agent.</em></figcaption></figure><h3>Scope the API surface with tool_names</h3><p>Once an API is connected, the next question is which operations the agent actually needs. The service publishes more operations than the assistant needs, but this agent only has to answer ownership, deployment, and runbook questions. The first step is to expose only that three-operation slice of the API surface:</p><pre># Keep the API surface aligned with the questions this assistant is allowed to answer.<br>service_api = api_tool(<br>    url=&quot;http://127.0.0.1:8010/openapi.json&quot;,<br>    name=&quot;service_catalog_api&quot;,<br>    tool_names=[&quot;get_service_details&quot;, &quot;get_latest_deployment&quot;, &quot;get_service_runbook&quot;],<br>    max_tools=3,<br>)<br>copy</pre><p>That does two things:</p><ul><li>it reduces the number of tools the model has to choose from</li><li>it makes the execution graph and task history easier to interpret later</li></ul><p>If the prompt only needs owner and deployment status, narrow the same API surface again and drop the runbook operation entirely:</p><pre># Build a smaller tool set for prompts that do not need runbook lookup.<br>service_api = api_tool(<br>    url=&quot;http://127.0.0.1:8010/openapi.json&quot;,<br>    name=&quot;service_catalog_api&quot;,<br>    tool_names=[&quot;get_service_details&quot;, &quot;get_latest_deployment&quot;],<br>    max_tools=2,<br>)</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_E3-TjZLCJLxVdNHBuu38w.gif" /><figcaption><em>This terminal walkthrough uses a smaller </em><em>tool_names set when the prompt only needs two facts from the API.</em></figcaption></figure><h3>Inspect the run in the UI</h3><p>Once the agent runs, the value of server-side execution becomes visible. The UI shows the same execution ID the notebook returned, along with the LLM step, the discovered HTTP operations, and the final answer.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lfoefFOHgKoHCifhiG5T5Q.gif" /><figcaption><em>The execution graph shows one LLM step followed by the HTTP operations discovered from the OpenAPI spec.</em></figcaption></figure><p>The <a href="http://127.0.0.1:4322/docs/concepts/tools">Task List</a> view is useful when you want to see how the runtime prepared and filtered the API surface before the actual HTTP calls:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bPkHV_8pz9__HgNYHw05eA.gif" /><figcaption><em>The task list makes the discovery pipeline visible: fetch, prepare, filter, resolve, and then execute the selected operations.</em></figcaption></figure><p>And the output panel gives you the final answer under the same execution ID:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*rmU8Xof7pJ0SgNn5s1DdOA.gif" /><figcaption><em>The final output stays attached to the same server-side execution, so you can move from the answer back to the underlying tool activity.</em></figcaption></figure><p>The practical takeaway is that you can keep the API spec as the source of truth, expose only the operations an agent actually needs, and still get a complete execution trail in the runtime UI.</p><h3>Next steps</h3><ul><li><a href="https://github.com/agentspan-ai/agentspan-demos/tree/main/notebooks/api-tool-openapi-service">Jupyter notebook and support files</a></li><li><a href="https://agentspan.ai/docs/concepts/tools">Agentspan tools docs</a></li><li><a href="https://agentspan.ai/docs/quickstart">Agentspan Quickstart</a></li><li><a href="https://github.com/agentspan-ai/agentspan">Agentspan on GitHub</a></li><li><a href="https://discord.com/invite/ajcA66JcKq">Discord community</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c691913df8ac" width="1" height="1" alt=""><hr><p><a href="https://medium.com/agentspan/how-to-build-agents-on-top-of-your-apis-with-agentspan-c691913df8ac">How to Build Agents on Top of Your APIs with Agentspan</a> was originally published in <a href="https://medium.com/agentspan">Agentspan</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>