Repository navigation
feat: Refactor the API to expose less types users need to import #30
Description
Problem statement
Taking from the quick start example:
import asyncio
import sys
from pathlib import Path
from acp import spawn_agent_process, text_block
from acp.interfaces import Client
from acp.schema import InitializeRequest, NewSessionRequest, PromptRequest, SessionNotification
class SimpleClient(Client):
async def requestPermission(self, params): # pragma: no cover - minimal stub
return {"outcome": {"outcome": "cancelled"}}
async def sessionUpdate(self, params: SessionNotification) -> None:
print("update:", params.sessionId, params.update)
async def main() -> None:
script = Path("examples/echo_agent.py")
async with spawn_agent_process(lambda _agent: SimpleClient(), sys.executable, str(script)) as (conn, _proc):
await conn.initialize(InitializeRequest(protocolVersion=1))
session = await conn.newSession(NewSessionRequest(cwd=str(script.parent), mcpServers=[]))
await conn.prompt(
PromptRequest(
sessionId=session.sessionId,
prompt=[text_block("Hello from spawn!")],
)
)
asyncio.run(main())connection.initialize takes a single parameter with a set fields defined, and users have to import that InitializeRequest to construct it. Same as connection.newSession() method.
It can be easily changed to the following API style:
connection.initialize(protocol_version=1)(snake_case is also preferred)
Proposed solution
While this is a breaking change, we can add a compatibility layer on such methods, something like below:
@compat_params(InitializeRequest)
async def initialize(self, protocol_version: int) -> InitializeResponse:
return await request_model(
self._conn,
AGENT_METHODS["initialize"],
InitializeRequest(protocolVersion=protocol_version),
InitializeResponse,
)Alternatives considered
If it's not easy to do over the codebase, in the worst case, we can add a acp._next package with the new APIs, and export all members in acp/__init__.py with proper deprecation warnings.
Additional context
No response
Can you help build it?
- I can contribute code or docs for this request.
Reacted by Chojan Shang and yihong
Activity
PsiACE commentedon Nov 19, 2025
I believe we are about to embark on a truly Pythonic beginning. 🤗
frostming commentedon Nov 19, 2025
Here are some to-do items I’ve broken down.
phil65 commentedon Nov 19, 2025
Feel free to steal code from my fork:
https://github.com/phil65/llmling-agent/tree/main/src/acp
I already added quite a lot of "pythonicness" (session.notification + session.requests helper classes for example), and also switched to a handcrafted schema definition (its not worth it to auto-generate the schema classes, you spend more time adjusting the generation code than just adjusting the schema manually)
frostming commentedon Nov 19, 2025
Thanks for the code; it’s good to read. I think your point makes sense—we can remove the auto-generated code anytime we feel overwhelmed maintaining it and switch to a handcrafted schema.
phil65 commentedon Nov 19, 2025
oh, and for @frostming , I see that you dabble a lot with OpenDAL, I also added a quick shot for an FSSpec ACP filesystem to operate client-side. perhaps its interesting for you. (only did some basic testing yet though)
https://github.com/phil65/llmling-agent/blob/main/src/acp/filesystem.py
PsiACE commentedon Nov 20, 2025
Most of the points in #30 are already addressed in the
0.7.xbranch — huge thanks to @frostming for the exceptional work and for keeping everything compatible. I suggest we close this issue, and I’ll open a [DNM] PR for0.7.xso we can start reviewing the upcoming changes.