智能体客户端协议(Agent Client Protocol,ACP)适合 IDE、编辑器和自定义智能体客户端。它提供结构化会话、流式文本和工具事件,并允许客户端响应 IaC Code 发起的权限请求。本文介绍传输选择、最小客户端和会话生命周期。
前提条件
已完成安装和配置 IaC Code。
已确定客户端允许 IaC Code 操作的项目绝对路径。
使用 HTTP+SSE 时,已准备服务认证和网络访问控制。
选择传输方式
传输方式 |
启动命令 |
适用场景 |
Stdio,默认 |
|
客户端在本机启动并管理 IaC Code 子进程。 |
HTTP+SSE |
|
独立部署、多客户端或网络连接。 |
本地 IDE 集成优先使用 Stdio,避免额外开放端口。ACP 兼容客户端可以使用以下进程配置:
{
"agent_servers": {
"iac-code": {
"type": "custom",
"command": "iac-code",
"args": ["acp"]
}
}
}
Stdio 最小客户端
基础包已经包含 ACP 运行依赖。下面的 Python 示例完成协议初始化、创建会话、发送提示词、接收流式文本和关闭会话:
import asyncio
from pathlib import Path
from typing import Any
import acp
import acp.schema
class IaCCodeClient(acp.Client):
async def session_update(
self, session_id: str, update: Any, **kwargs: Any
) -> None:
if isinstance(update, acp.schema.AgentMessageChunk):
print(update.content.text, end="", flush=True)
async def request_permission(
self, options: Any, session_id: str, tool_call: Any, **kwargs: Any
) -> acp.RequestPermissionResponse:
# 最小示例默认拒绝;生产客户端应展示操作并让用户决定。
return acp.RequestPermissionResponse(
outcome=acp.schema.DeniedOutcome(outcome="cancelled")
)
async def main() -> None:
async with acp.spawn_agent_process(
IaCCodeClient(), "iac-code", "acp"
) as (connection, _):
initialized = await connection.initialize(
protocol_version=1,
client_info=acp.schema.Implementation(
name="iac-code-demo", version="1.0"
),
)
print(f"ACP version: {initialized.protocol_version}")
session = await connection.new_session(cwd=str(Path.cwd()))
result = await connection.prompt(
session_id=session.session_id,
prompt=[
acp.schema.TextContentBlock(
type="text",
text="检查当前目录中的 ROS 模板,只输出建议,不要修改文件。",
)
],
)
print(f"\nstop_reason={result.stop_reason}")
await connection.close_session(session_id=session.session_id)
asyncio.run(main())
预期结果:客户端先输出协议版本,再增量输出回复,最后输出停止原因。文本之外,
session_update 还可以处理思考、工具调用和工具进度等事件。
处理权限和会话
new_session(cwd=...)将会话绑定到项目目录。使用绝对路径,并限制客户端可选择的根目录。客户端应向用户展示权限请求中的工具、参数和影响,再返回一次允许、持续允许或拒绝。
不要在示例或生产客户端中默认批准所有文件、命令和云上写操作。
一个提示词完成后,
prompt()返回停止原因;流式内容通过session_update接收。会话不再使用时主动调用
close_session,客户端退出时关闭 Stdio 子进程或 HTTP 连接。
使用 HTTP+SSE
启动服务:
iac-code acp --transport http --host 127.0.0.1 --port 8765
检查健康状态:
curl http://127.0.0.1:8765/health
跨主机访问时,通过部署环境的 Secret 设置 IACCODE_ACP_HTTP_TOKEN。客户端为每个请求发送匹配的 Authorization: Bearer <token> 请求头。连接 ID、JSON-RPC 请求和 SSE 事件的完整流程请参见 ACP HTTP+SSE 传输文档。
常见问题
Stdio 连接后立即断开
直接运行 iac-code acp 检查启动错误,再确认客户端命令、环境变量和工作目录。Stdio 的标准输出用于协议帧,客户端和启动脚本不能向其中写入普通日志。
工具操作没有执行
确认客户端实现了 request_permission,并返回协议支持的允许或拒绝结果。IaC Code 不会因为使用 ACP 就绕过工具权限。
HTTP 请求返回 401
确认服务端设置了预期的 IACCODE_ACP_HTTP_TOKEN,客户端使用相同 Secret,并且代理没有移除 Authorization 请求头。