Deployed 4d4e9de with MkDocs version: 1.6.1

Author: Chojan Shang

404.html

@@ -294,6 +294,28 @@
 
 
 
+    <li class="md-nav__item">
+      <a href="/python-sdk/use-cases/" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    Use Cases
+    
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+    
+      
+      
+  
+  
+  
+  
     <li class="md-nav__item">
       <a href="/python-sdk/contrib/" class="md-nav__link">
 

contrib/index.html

@@ -15,7 +15,7 @@
         <link rel="canonical" href="https://agentclientprotocol.github.io/python-sdk/contrib/">
 
 
-        <link rel="prev" href="../quickstart/">
+        <link rel="prev" href="../use-cases/">
 
 
         <link rel="next" href="../releasing/">
@@ -303,6 +303,28 @@
 
 
 
+  
+  
+    <li class="md-nav__item">
+      <a href="../use-cases/" class="md-nav__link">
+        
+  
+  
+  <span class="md-ellipsis">
+    Use Cases
+    
+  </span>
+  
+
+      </a>
+    </li>
+  
+
+    
+      
+      
+  
+  
 
 
 
@@ -356,18 +378,18 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#sessionaccumulator" class="md-nav__link">
+  <a href="#sessionaccumulator-acpcontribsession_state" class="md-nav__link">
     <span class="md-ellipsis">
-      SessionAccumulator
+      SessionAccumulator (acp.contrib.session_state)
     </span>
   </a>
 
 </li>
 
         <li class="md-nav__item">
-  <a href="#toolcalltracker-permissionbroker" class="md-nav__link">
+  <a href="#toolcalltracker-permissionbroker-acpcontribtool_calls-acpcontribpermissions" class="md-nav__link">
     <span class="md-ellipsis">
-      ToolCallTracker &amp; PermissionBroker
+      ToolCallTracker &amp; PermissionBroker (acp.contrib.tool_calls, acp.contrib.permissions)
     </span>
   </a>
 
@@ -439,18 +461,18 @@
     <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
 
         <li class="md-nav__item">
-  <a href="#sessionaccumulator" class="md-nav__link">
+  <a href="#sessionaccumulator-acpcontribsession_state" class="md-nav__link">
     <span class="md-ellipsis">
-      SessionAccumulator
+      SessionAccumulator (acp.contrib.session_state)
     </span>
   </a>
 
 </li>
 
         <li class="md-nav__item">
-  <a href="#toolcalltracker-permissionbroker" class="md-nav__link">
+  <a href="#toolcalltracker-permissionbroker-acpcontribtool_calls-acpcontribpermissions" class="md-nav__link">
     <span class="md-ellipsis">
-      ToolCallTracker &amp; PermissionBroker
+      ToolCallTracker &amp; PermissionBroker (acp.contrib.tool_calls, acp.contrib.permissions)
     </span>
   </a>
 
@@ -485,41 +507,41 @@
 
 
 <h1 id="experimental-contrib-modules">Experimental Contrib Modules<a class="headerlink" href="#experimental-contrib-modules" title="Permanent link">&para;</a></h1>
-<blockquote>
-<p>The helpers under <code>acp.contrib</code> capture patterns we observed in reference integrations such as Toad and kimi-cli. Every API here is experimental and may change without notice.</p>
-</blockquote>
-<h2 id="sessionaccumulator">SessionAccumulator<a class="headerlink" href="#sessionaccumulator" title="Permanent link">&para;</a></h2>
-<p>Module: <code>acp.contrib.session_state</code></p>
-<p>UI surfaces like Toad need a live, merged view of the latest tool calls, plan entries, and message stream. The core SDK only emits raw <code>SessionNotification</code> payloads, so applications usually end up writing their own state layer. <code>SessionAccumulator</code> offers that cache out of the box.</p>
-<p>Capabilities:</p>
+<p>The helpers under <code>acp.contrib</code> package recurring patterns we saw in integrations such as Toad, kimi-cli, and Gemini. Keep in mind they are experimental—APIs can still shift as we learn. Use this page as a menu:</p>
+<ul>
+<li><strong><code>session_state.SessionAccumulator</code></strong> — build a canonical, immutable snapshot of every session update so UIs can render tool calls and plans without re-implementing state machines.</li>
+<li><strong><code>tool_calls.ToolCallTracker</code> + <code>permissions.PermissionBroker</code></strong> — coordinate streamed tool call updates and permission prompts from one place.</li>
+</ul>
+<h2 id="sessionaccumulator-acpcontribsession_state">SessionAccumulator (<code>acp.contrib.session_state</code>)<a class="headerlink" href="#sessionaccumulator-acpcontribsession_state" title="Permanent link">&para;</a></h2>
+<p><strong>Use it when:</strong> you need a live, merged view of <code>SessionNotification</code> events (e.g. tool calls, plan entries, user/agent messages) to drive UI widgets.</p>
+<p><strong>Key capabilities</strong></p>
 <ul>
-<li><code>SessionAccumulator.apply(notification)</code> merges <code>tool_call</code> and <code>tool_call_update</code> events, backfilling a missing start message when necessary.</li>
-<li>Each call to <code>snapshot()</code> returns an immutable <code>SessionSnapshot</code> (Pydantic model) containing the active plan, current mode ID, available commands, and historical user/agent/thought chunks.</li>
-<li><code>subscribe(callback)</code> wires a lightweight observer that receives every new snapshot, making it easy to refresh UI widgets.</li>
-<li>Automatic reset when a different session ID arrives (configurable via <code>auto_reset_on_session_change</code>).</li>
+<li><code>SessionAccumulator.apply(notification)</code> reconciles <code>tool_call</code> and <code>tool_call_update</code> payloads, even if the start event arrives late.</li>
+<li><code>snapshot()</code> returns an immutable <code>SessionSnapshot</code> Pydantic model containing the plan, current mode, commands, and ordered message history.</li>
+<li><code>subscribe(callback)</code> lets you push snapshots into stores or UI components whenever state changes.</li>
+<li>Automatic reset on session-change (toggle with <code>auto_reset_on_session_change</code>).</li>
 </ul>
 <blockquote>
-<p>Integration tip: create one accumulator per UI controller. Feed every <code>SessionNotification</code> through it, then render from <code>snapshot.tool_calls</code> or <code>snapshot.user_messages</code> instead of mutating state manually.</p>
+<p>Tip: Create one accumulator per UI controller. Feed every raw <code>SessionNotification</code> into it and render from <code>snapshot.tool_calls</code> / <code>snapshot.user_messages</code> instead of mutating state manually.</p>
 </blockquote>
-<h2 id="toolcalltracker-permissionbroker">ToolCallTracker &amp; PermissionBroker<a class="headerlink" href="#toolcalltracker-permissionbroker" title="Permanent link">&para;</a></h2>
-<p>Modules: <code>acp.contrib.tool_calls</code> and <code>acp.contrib.permissions</code></p>
-<p>Agent-side runtimes (for example kimi-cli) are responsible for synthesising tool call IDs, streaming argument fragments, and formatting permission prompts. Managing bare Pydantic models quickly devolves into boilerplate; these helpers centralise the bookkeeping.</p>
+<h2 id="toolcalltracker-permissionbroker-acpcontribtool_calls-acpcontribpermissions">ToolCallTracker &amp; PermissionBroker (<code>acp.contrib.tool_calls</code>, <code>acp.contrib.permissions</code>)<a class="headerlink" href="#toolcalltracker-permissionbroker-acpcontribtool_calls-acpcontribpermissions" title="Permanent link">&para;</a></h2>
+<p><strong>Use them when:</strong> your agent runtime synthesises tool call IDs, streams arguments, and prompts the user for approval. The helpers centralise the bookkeeping so you don’t juggle raw Pydantic models.</p>
 <ul>
-<li><code>ToolCallTracker.start()/progress()/append_stream_text()</code> manages tool call state and emits canonical <code>ToolCallStart</code> / <code>ToolCallProgress</code> messages. The tracker also exposes <code>view()</code> (immutable <code>TrackedToolCallView</code>) and <code>tool_call_model()</code> for logging or permission prompts.</li>
-<li><code>PermissionBroker.request_for()</code> wraps <code>requestPermission</code> RPCs. It reuses the tracker’s state (or an explicit <code>ToolCall</code>), applies optional extra content, and defaults to a standard Approve / Approve for session / Reject option set.</li>
-<li><code>default_permission_options()</code> exposes that canonical option triple so applications can customise or extend it.</li>
+<li><code>ToolCallTracker.start()/progress()/append_stream_text()</code> emits canonical <code>ToolCallStart</code> / <code>ToolCallProgress</code> updates and keeps an in-memory view via <code>view()</code> or <code>tool_call_model()</code>.</li>
+<li><code>PermissionBroker.request_for()</code> wraps <code>requestPermission</code> RPCs. It reuses tracker state (or a provided <code>ToolCall</code>), lets you append extra content, and defaults to Approve / Approve for session / Reject options.</li>
+<li><code>default_permission_options()</code> exposes that canonical option triple if you need to customise it.</li>
 </ul>
 <blockquote>
-<p>Integration tip: keep a single tracker alongside your agent loop. Emit tool call notifications through it, and hand the tracker to <code>PermissionBroker</code> so permission prompts stay in sync with the latest call state.</p>
+<p>Tip: Keep one tracker near the agent event loop. Emit notifications through it and share the tracker with <code>PermissionBroker</code> so permission prompts always match the latest tool call state.</p>
 </blockquote>
 <h2 id="design-guardrails">Design Guardrails<a class="headerlink" href="#design-guardrails" title="Permanent link">&para;</a></h2>
 <p>To stay aligned with the ACP schema, the contrib layer follows a few rules:</p>
 <ul>
-<li>Protocol types continue to live in <code>acp.schema</code>. Contrib code always copies them via <code>.model_copy(deep=True)</code> to avoid mutating shared instances.</li>
-<li>Helpers are opt-in; the core package never imports them implicitly and imposes no UI or agent framework assumptions.</li>
-<li>Implementations focus on the common pain points (tool call aggregation, permission requests) while leaving business-specific policy to the application.</li>
+<li>Schema data classes continue to live in <code>acp.schema</code>. Contrib helpers clone them with <code>.model_copy(deep=True)</code> before mutation.</li>
+<li>The core runtime never imports contrib modules implicitly—you opt in when they help.</li>
+<li>Helpers focus on painful bookkeeping (tool call aggregation, permission UX) and leave product-specific policy to your application.</li>
 </ul>
-<p>Try the contrib modules in your agent or client, and open an issue/PR with feedback so we can decide which pieces should graduate into the stable surface.</p>
+<p>Try the contrib modules, then open an issue or PR with feedback so we know which APIs should graduate into the stable surface.</p>