ACP (Giao thức khách hàng agent)

Biên tập viên như Zed nói ACP: giao thức JSON-RPC stdio cho phép TUI hoặc trình soạn thảo điều khiển coding agent bên ngoài -- truyền trực tuyến văn bản của nó, hiển thị các chỉnh sửa tệp của nó dưới dạng khác biệt và nhắc người dùng phê duyệt các lệnh gọi công cụ nhạy cảm. Đạt được khả năng này khi bạn muốn có AI Pydantic Agent xuất hiện với tư cách là agent hạng nhất bên trong một trong những trình soạn thảo đó mà không cần tự mình triển khai phía máy chủ ACP.

!!! cảnh báo "Thử nghiệm" Không giống như các khả năng tăng dần trong các tài liệu này, bản thân ACP vẫn có thể bị xóa chứ không chỉ thay đổi -- nó vẫn tồn tại dưới pydantic_ai_harness.experimental và có thể thay đổi hoặc bị xóa trong bất kỳ bản phát hành nào mà không có thời gian ngừng sử dụng. Nhập nó từ đường dẫn thử nghiệm -- không có xuất cấp cao nhất:

```python
from pydantic_ai_harness.experimental.acp import run_acp_stdio_sync
```

Việc nhập bất kỳ khả năng thử nghiệm nào sẽ phát ra một `HarnessExperimentalWarning`. Im lặng **tất cả** khai thác các cảnh báo thử nghiệm bằng một bộ lọc duy nhất (không cần dòng theo khả năng):

```python
import warnings
from pydantic_ai_harness.experimental import HarnessExperimentalWarning

warnings.filterwarnings('ignore', category=HarnessExperimentalWarning)
```

vấn đề

Để cắm AI agent Pydantic vào trình soạn thảo ACP, nếu không, bạn sẽ phải triển khai thủ công máy chủ ACP -- phân đoạn văn bản được truyền trực tuyến dưới giới hạn dây, hiển thị các lệnh gọi công cụ dưới dạng khác biệt, ánh xạ các yêu cầu cấp phép của giao thức lên các công cụ của agent và quản lý các phiên trên mỗi không gian làm việc.

Giải pháp

run_acp_stdio phục vụ bất kỳ AI Pydantic nào Agent với tư cách là agent ACP trên stdin/stdout. Trình chỉnh sửa khởi chạy tập lệnh của bạn dưới dạng một quy trình con và nói chuyện với nó; bộ chuyển đổi dịch giữa ACP và vòng lặp chạy của agent:

Cài đặt

uv add "pydantic-ai-harness[acp]"

Điều này kéo theo agent-client-protocol SDK. Phần còn lại của harness không phụ thuộc vào nó - chỉ pydantic_ai_harness.experimental.acp có.

Bắt đầu nhanh

Viết một tập lệnh xây dựng agent của bạn và phục vụ nó:

# my_acp_agent.py
from pydantic_ai import Agent
from pydantic_ai_harness.experimental.acp import run_acp_stdio_sync


def build_agent() -> Agent[None, str]:
    return Agent('anthropic:claude-sonnet-4-6', instructions='You are a coding assistant.')


if __name__ == '__main__':
    run_acp_stdio_sync(build_agent())

run_acp_stdio_sync chặn trong suốt thời gian tồn tại của kết nối -- đó là main() của một agent biên tập viên ra mắt. Bên trong vòng lặp sự kiện hiện có, hãy sử dụng async run_acp_stdio thay vào đó.

Kết nối từ trình chỉnh sửa

Các máy khách ACP khởi chạy agent dưới dạng một quy trình con. Trong Zed, đăng ký nó làm agent bên ngoài trong settings.json:

{
  "agent_servers": {
    "My Pydantic AI Agent": {
      "type": "custom",
      "command": "python",
      "args": ["/absolute/path/to/my_acp_agent.py"],
      "env": { "ANTHROPIC_API_KEY": "..." }
    }
  }
}

Mọi máy khách tương thích với ACP đều hoạt động theo cách tương tự -- hãy trỏ nó vào python my_acp_agent.py.

Môi trường nhà cung cấp phải có sẵn cho quy trình con được khởi chạy. Trình chỉnh sửa GUI và trình bao bọc thử nghiệm dựa trên SDK có thể không lấy được các tệp khởi động shell tương tác của bạn. Nếu một agent mô hình thực thoát ra trước khi khởi tạo hoặc không xác thực được nhà cung cấp, trước tiên hãy xác minh rằng quy trình của lệnh có thể thấy các biến như ANTHROPIC_API_KEY.

Công cụ root tại không gian làm việc

coding agent phải đọc và ghi tệp trong không gian làm việc mà trình soạn thảo đã mở, chứ không phải ở bất kỳ nơi nào quy trình con bắt đầu. ACP cung cấp cho mỗi phiên một thư mục làm việc (cwd); a session_config nhà máy biến nó thành công cụ cho mỗi phiên:

from pydantic_ai import Agent
from pydantic_ai_harness import FileSystem, Shell
from pydantic_ai_harness.experimental.acp import AcpSession, AcpSessionConfig, run_acp_stdio_sync

agent = Agent('anthropic:claude-sonnet-4-6')


def session_config(session: AcpSession) -> AcpSessionConfig[None]:
    # Root file and shell tools at the workspace the client opened.
    return AcpSessionConfig(
        deps=None,
        toolsets=[
            FileSystem[None](root_dir=session.cwd).get_toolset(),
            Shell[None](cwd=session.cwd).get_toolset(),
        ],
    )


if __name__ == '__main__':
    run_acp_stdio_sync(agent, session_config=session_config)

Nhà máy chạy một lần mỗi phiên với khách hàng AcpSession thiết lập (nó cwd, mcp_serversvà khả năng) và trả về một AcpSessionConfig của ai deps và toolsets áp dụng cho mọi lần chạy trong phiên đó. Điều này đúng trên nhiều phiên đồng thời trong một quy trình, trong đó một phiên tĩnh duy nhất FileSystem không thể được.

Hệ thống tập tin gốc và shell (tùy chọn)

Địa phương FileSystem và Shell ở trên hoạt động trên đĩa và các quy trình con của chính tiến trình agent. Nguồn thông tin chính xác của trình soạn thảo thì khác: vùng đệm chưa được lưu, ý tưởng riêng về bố cục không gian làm việc và -- đối với trình soạn thảo từ xa hoặc được đóng gói -- máy thực sự tồn tại mã. Khi khách hàng quảng cáo hỗ trợ, acp_filesystem và acp_terminal đưa agent read_file/write_file/run_command các công cụ định tuyến qua máy khách, do đó, nó hoạt động ở nơi người dùng:

from pydantic_ai_harness import FileSystem, Shell
from pydantic_ai_harness.experimental.acp import AcpSession, AcpSessionConfig, acp_filesystem, acp_terminal


def session_config(session: AcpSession) -> AcpSessionConfig[None]:
    # Use the editor's filesystem/terminal when offered; otherwise fall back to local.
    fs = acp_filesystem(session) or FileSystem[None](root_dir=session.cwd).get_toolset()
    shell = acp_terminal(session) or Shell[None](cwd=session.cwd).get_toolset()
    return AcpSessionConfig(deps=None, toolsets=[fs, shell])

Mỗi người trợ giúp trở về None khi khách hàng không quảng cáo khả năng, vì vậy or quay trở lại địa phương và agent hoạt động theo một trong hai cách. Tên công cụ khớp với tên địa phương FileSystem/Shell, do đó kết xuất phong phú vẫn giống hệt nhau.

Phê duyệt công cụ

Đánh dấu một công cụ để yêu cầu phê duyệt và ACP chuyển tiếp quyết định cho khách hàng, hiển thị cho người dùng lời nhắc phê duyệt/từ chối:

@agent.tool_plain(requires_approval=True)
def delete_file(path: str) -> str:
    ...

Vòng đời mà khách hàng nhìn thấy là pending (đang chờ phê duyệt) -> in_progress (được cấp, đang chạy) -> completed/failed, do đó, một hành động không được phê duyệt sẽ không bao giờ được hiển thị là đã chạy. Các quyết định "Luôn cho phép"/"luôn từ chối" được ghi nhớ cho phiên, theo mặc định nằm trong phạm vi lệnh gọi chính xác (tên công cụ cộng với đối số) nên việc phê duyệt một lệnh gọi không bao giờ âm thầm phê duyệt một lệnh gọi khác. Vượt qua permission_policy để mở rộng hoặc thu hẹp phạm vi đó.

Kết xuất công cụ phong phú

Theo mặc định, bộ chuyển đổi nhận dạng harness FileSystem và Shell công cụ gọi theo tên và chú thích chúng bằng ACP kind (read/edit/search/execute), tập tin locations họ chạm vào và một khác biệt nội tuyến cho các chỉnh sửa -- vì vậy trình chỉnh sửa hiển thị các liên kết nhấp vào tệp và chế độ xem khác biệt thay vì JSON mờ. Vượt qua tool_presenter để thêm kết xuất cho các công cụ của riêng bạn (tùy chọn với chain_presenters trước mặc định default_coding_presenter), hoặc lambda _call: None để vô hiệu hóa nó.

máy chủ MCP

Máy khách ACP có thể cung cấp máy chủ MCP trong quá trình thiết lập phiên. Bộ điều hợp này không tự kết nối chúng; một session_config là nơi để rẽ session.mcp_servers vào bộ công cụ Pydantic AI (ví dụ với pydantic_ai.mcp.MCPServerStdio). Nếu một khách hàng gửi máy chủ MCP và không session_config được cài đặt để sử dụng chúng, yêu cầu phiên sẽ bị từ chối thay vì âm thầm bỏ qua chúng. Máy khách theo thông số kỹ thuật chỉ gửi máy chủ HTTP/SSE MCP khi agent quảng cáo hỗ trợ trong thời gian initialize; khi bạn session_config kết nối chúng, nói như vậy:

from acp import schema
from pydantic_ai_harness.experimental.acp import PydanticAIACPAgent

PydanticAIACPAgent(
    agent,
    session_config=connect_mcp_servers,
    mcp_capabilities=schema.McpCapabilities(http=True, sse=True),
)

Các loại nội dung nhắc nhở

agent quảng cáo nội dung nhắc nhở mà nó chấp nhận. Mặc định là chỉ văn bản, vì vậy khách hàng không được mời gửi các khối mà mô hình văn bản không thể xử lý. Kích hoạt các loại mô hình của bạn hỗ trợ:

from acp import schema

run_acp_stdio_sync(agent, prompt_capabilities=schema.PromptCapabilities(image=True, embedded_context=True))

Sự kiên trì của phiên

Vượt qua một session_store để cho phép khách hàng mở lại cuộc trò chuyện trước đây với session/load. Mỗi lượt cam kết được duy trì thành hai phần -- lịch sử tin nhắn của mô hình và bản ghi hiển thị cho khách hàng -- và việc mở lại sẽ khôi phục lịch sử trong agent và phát lại bản ghi cho máy khách, do đó giao diện người dùng của nó được xây dựng lại khi người dùng nhìn thấy lần cuối. Không có cửa hàng, session/load được quảng cáo là không được hỗ trợ.

from pydantic_ai_harness.experimental.acp import InMemorySessionStore

run_acp_stdio_sync(agent, session_store=InMemorySessionStore())

InMemorySessionStore giữ các phiên trong suốt thời gian tồn tại của quá trình. Thực hiện các SessionStore giao thức (save/load a StoredSession) trên một tệp hoặc cơ sở dữ liệu để giúp chúng tồn tại khi khởi động lại -- các giá trị được lưu trữ là các mô hình Pydantic, vì vậy chúng tuần tự hóa với Pydantic. Sự kiên trì của phiên là để mở lại cuộc trò chuyện; nó trực giao với độ bền mỗi lần chạy. Để giúp từng ngã rẽ có khả năng chống va chạm, hãy thêm khả năng độ bền từng bước -- mỗi lượt ACP là một lần chạy agent, vì vậy hai lớp kết hợp không có keo.

Lựa chọn mô hình

Vượt qua models để quảng cáo tùy chọn cấu hình phiên ACP ổn định có tên model (sử dụng Pydantic AI tên mẫu). Đầu tiên là mặc định của mỗi phiên. Một lựa chọn được áp dụng dưới dạng ghi đè mỗi lần chạy -- agent dùng chung không bao giờ bị thay đổi -- và được duy trì trong phiên khi một session_store được thiết lập.

run_acp_stdio_sync(agent, models=['anthropic:claude-sonnet-4-6', 'anthropic:claude-opus-4-8', 'openai:gpt-4o'])

Id mô hình là bất kỳ chuỗi nào mà mô hình AI Pydantic chấp nhận, vì vậy các mô hình mới hơn chưa có trong KnownModelName làm việc quá. Vượt qua models='all' để cung cấp mọi mô hình Pydantic AI biết. Để quảng cáo id infer_model không hiểu (OAuth hoặc mô hình đăng ký), hãy chuyển model_resolver để ánh xạ id đã chọn vào một id dựng sẵn Model.

Hủy bỏ và giới hạn

• Hủy. session/cancel và session/close hủy lượt trên chuyến bay; close chờ cho nó thư giãn trước khi quay trở lại. Các công cụ không đồng bộ hợp tác dừng ngay lập tức. Không thể dừng cưỡng bức một công cụ đồng bộ đang chạy trong một luồng công việc, vì vậy hãy ưu tiên các công cụ không đồng bộ cho công việc nhạy cảm với việc hủy.
• Phát hiện phê duyệt. Các công cụ yêu cầu phê duyệt được nhận dạng khi chúng hoạt động trong một môi trường FunctionToolset (mà harness FileSystem/Shell và @agent.tool đều sử dụng được). Một công cụ có yêu cầu phê duyệt được quyết định linh hoạt cho mỗi lệnh gọi (bằng cách nâng cao ApprovalRequired từ cơ thể của nó) bắt đầu như in_progress, và bất kỳ tác dụng phụ nào nó xảy ra trước khi tăng đều đã xảy ra -- hãy sử dụng ApprovalRequiredToolset đối với các hành động không được thực hiện một phần trước khi được phê duyệt.
• Ghi đè những khác biệt. write_file hiển thị ghi đè như thể đang tạo một tệp mới, do đó, phần khác biệt sẽ đánh giá thấp những gì nó thay thế.
• Bảng terminal trực tiếp. acp_terminal trả về đầu ra đã bắt của lệnh; nó không nhúng khung terminal trực tiếp vào lệnh gọi công cụ.
• Hình ảnh. Khối hình ảnh nhắc nhở bị tắt theo mặc định và phải được bật thông qua prompt_capabilities với một mô hình chấp nhận chúng.
• Lệnh gạch chéo. Bộ điều hợp chưa quảng cáo bất kỳ lệnh nào, do đó không có lệnh gạch chéo nào xuất hiện trong máy khách. Đã lên kế hoạch.

API

run_acp_stdio(            # async; serve until the client disconnects
    agent,
    *,
    deps=None,
    name=None,            # advertised name; defaults to the agent's name
    version='0.1.0',
    session_config=None,  # per-session deps/toolsets from the client's setup
    permission_policy=None,   # scope of remembered "always" approval decisions
    prompt_capabilities=None, # defaults to text-only
    mcp_capabilities=None,    # MCP transports to advertise; needs a session_config to connect them
    tool_presenter=None,      # defaults to the FileSystem/Shell presenter
    session_store=None,       # enables session/load by persisting each session
    models=None,              # models offered as the `model` config option ('all' for every known model)
    model_resolver=None,      # maps an advertised model id to the Model used for the run
    usage_limits=None,        # per-run request/token ceilings
)

run_acp_stdio_sync(...)   # synchronous wrapper, same arguments

PydanticAIACPAgent(agent, *, ...)  # the ACP agent object, to embed in a custom server

Mô-đun này cũng xuất các loại phiên (AcpSession, AcpSessionConfig, McpServer), các loại cửa hàng (SessionStore, StoredSession, InMemorySessionStore), bộ công cụ máy khách (AcpFileSystemToolset, AcpTerminalToolset, acp_filesystem, acp_terminal), các loại quyền (ToolCallPermission, default_permission_scope) và những người trợ giúp trình bày (ToolCallPresentation, chain_presenters, default_coding_presenter).

Nguồn: pydantic_ai_harness/experimental/acp/.

Đọc thêm

• Giao thức khách hàng agent -- đặc tả giao thức
• Zed agent bên ngoài - cấu hình phía biên tập viên
• Phê duyệt công cụ con người trong vòng lặp (Pydantic AI)
• Khả năng AI của Pydantic