You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
<p>Welcome to the Python SDK for the Agent Client Protocol (ACP). The package ships ready-to-use transports, typed protocol models, and examples that stream messages to ACP-aware clients such as Zed.</p>
465
486
<h2id="what-you-get">What you get<aclass="headerlink" href="#what-you-get" title="Permanent link">¶</a></h2>
466
487
<ul>
467
-
<li>Fully typed dataclasses generated from the upstream ACP schema (<code>acp.schema</code>)</li>
468
-
<li>Async agent base class and stdio helpers to spin up an agent in a few lines</li>
469
-
<li>Examples that demonstrate streaming updates and tool execution over ACP</li>
488
+
<li>Pydantic models generated from the upstream ACP schema (<code>acp.schema</code>)</li>
489
+
<li>Async agent/client wrappers with JSON-RPC task supervision built in</li>
<li>Helper APIs in <code>acp.helpers</code> that mirror the Go/TS SDK builders for content blocks, tool calls, and session updates. They instantiate the generated Pydantic types for you, so call sites stay concise without sacrificing validation.</li>
492
+
<li>Examples that showcase streaming updates, file operations, permission flows, and even a Gemini CLI bridge (<code>examples/gemini.py</code>)</li>
<li>Point your ACP-capable client at the running process (for Zed, configure an Agent Server entry). The SDK takes care of JSON-RPC framing and lifecycle transitions.</li>
480
503
</ol>
481
-
<p>Prefer a guided tour? Head to the <ahref="quickstart/">Quickstart</a> for step-by-step instructions, including how to run the agent from an editor or terminal.</p>
504
+
<p>Prefer a guided tour? Head to the <ahref="quickstart/">Quickstart</a> for terminal, editor, and programmatic launch walkthroughs.</p>
<li><code>--yolo</code> auto-approves permission prompts with sensible defaults</li>
514
+
</ul>
515
+
<p>An opt-in smoke test lives at <code>tests/test_gemini_example.py</code>. Enable it with <code>ACP_ENABLE_GEMINI_TESTS=1</code> (and optionally <code>ACP_GEMINI_TEST_ARGS</code>) when the CLI is authenticated; otherwise the test stays skipped.</p>
<li><ahref="quickstart/">Quickstart</a>: install, run, and extend the echo agent</li>
485
-
<li><ahref="mini-swe-agent/">Mini SWE Agent guide</a>: bridge mini-swe-agent over ACP, including duet launcher and Textual client</li>
518
+
<li><ahref="quickstart/">Quickstart</a>: install, run, and embed the echo agent, plus next steps for extending it</li>
519
+
<li><ahref="releasing/">Releasing</a>: schema upgrade workflow, version bumps, and publishing checklist</li>
486
520
</ul>
487
521
<p>Source code lives under <code>src/acp/</code>, while tests and additional examples are available in <code>tests/</code> and <code>examples/</code>. If you plan to contribute, see the repository README for the development workflow.</p>
<p>Keep it running while you connect your client.</p>
584
-
<h2id="3-connect-from-your-client">3. Connect from your client<aclass="headerlink" href="#3-connect-from-your-client" title="Permanent link">¶</a></h2>
601
+
<p>Leave this process running while you connect from an editor or another program.</p>
602
+
<h2id="3-connect-from-an-editor">3. Connect from an editor<aclass="headerlink" href="#3-connect-from-an-editor" title="Permanent link">¶</a></h2>
<p>Open the Agents panel and start the session. Each message you send should be echoed back via streamed <code>session/update</code> notifications.</p>
prompt=[text_block("Hello from spawn!")],
646
+
)
647
+
)
648
+
649
+
asyncio.run(main())
650
+
</code></pre>
651
+
<p><code>spawn_agent_process</code> manages the child process, wires its stdio into ACP framing, and closes everything when the block exits. The mirror helper <code>spawn_client_process</code> lets you drive an ACP client from Python as well.</p>
601
652
<h2id="4-extend-the-agent">4. Extend the agent<aclass="headerlink" href="#4-extend-the-agent" title="Permanent link">¶</a></h2>
602
653
<p>Create your own agent by subclassing <code>acp.Agent</code>. The pattern mirrors the echo example:</p>
<p>Hook it up with <code>AgentSideConnection</code> inside an async entrypoint and wire it to your client. Refer to <ahref="https://github.com/psiace/agent-client-protocol-python/blob/main/examples/echo_agent.py">examples/echo_agent.py</a> for the complete structure, including lifetime hooks (<code>initialize</code>, <code>newSession</code>) and streaming responses.</p>
612
-
<h2id="optional-mini-swe-agent-bridge">Optional: Mini SWE Agent bridge<aclass="headerlink" href="#optional-mini-swe-agent-bridge" title="Permanent link">¶</a></h2>
613
-
<p>The repository also ships a bridge for <ahref="https://github.com/groundx-ai/mini-swe-agent">mini-swe-agent</a>. To try it:</p>
614
-
<ol>
615
-
<li>Install the dependency:
616
-
<code>bash
617
-
pip install mini-swe-agent</code></li>
618
-
<li>Configure Zed to run <code>examples/mini_swe_agent/agent.py</code> and supply environment variables such as <code>MINI_SWE_MODEL</code> and <code>OPENROUTER_API_KEY</code>.</li>
619
-
<li>Review the <ahref="../mini-swe-agent/">Mini SWE Agent guide</a> for environment options, tool-call mapping, and a duet launcher that starts both the bridge and a Textual client (<code>python examples/mini_swe_agent/duet.py</code>).</li>
620
-
</ol>
662
+
<p>Hook it up with <code>AgentSideConnection</code> inside an async entrypoint and wire it to your client. Refer to:</p>
663
+
<ul>
664
+
<li><ahref="https://github.com/psiace/agent-client-protocol-python/blob/main/examples/echo_agent.py"><code>examples/echo_agent.py</code></a> for the smallest streaming agent</li>
665
+
<li><ahref="https://github.com/psiace/agent-client-protocol-python/blob/main/examples/agent.py"><code>examples/agent.py</code></a> for an implementation that negotiates capabilities and streams richer updates</li>
666
+
<li><ahref="https://github.com/psiace/agent-client-protocol-python/blob/main/examples/duet.py"><code>examples/duet.py</code></a> to see <code>spawn_agent_process</code> in action alongside the interactive client</li>
667
+
<li><ahref="https://github.com/psiace/agent-client-protocol-python/blob/main/examples/gemini.py"><code>examples/gemini.py</code></a> to drive the Gemini CLI (<code>--experimental-acp</code>) directly from Python</li>
668
+
</ul>
669
+
<p>Need builders for common payloads? <code>acp.helpers</code> mirrors the Go/TS helper APIs:</p>
<p>Each helper wraps the generated Pydantic models in <code>acp.schema</code>, so the right discriminator fields (<code>type</code>, <code>sessionUpdate</code>, and friends) are always populated. That keeps examples readable while maintaining the same validation guarantees as constructing the models directly. Golden fixtures in <code>tests/test_golden.py</code> ensure the helpers stay in sync with future schema revisions.</p>
680
+
<h2id="5-optional-talk-to-the-gemini-cli">5. Optional: Talk to the Gemini CLI<aclass="headerlink" href="#5-optional-talk-to-the-gemini-cli" title="Permanent link">¶</a></h2>
681
+
<p>If you have the Gemini CLI installed and authenticated:</p>
<li><code>ACP_GEMINI_BIN</code> — override the CLI path (defaults to <code>PATH</code> lookup)</li>
688
+
<li><code>ACP_GEMINI_TEST_ARGS</code> — extra flags forwarded during the smoke test</li>
689
+
<li><code>ACP_ENABLE_GEMINI_TESTS=1</code> — opt-in toggle for <code>tests/test_gemini_example.py</code></li>
690
+
</ul>
691
+
<p>Authentication hiccups (e.g. missing <code>GOOGLE_CLOUD_PROJECT</code>) are surfaced but treated as skips during testing so the suite stays green on machines without credentials.</p>
0 commit comments