通过 ACP 集成 IaC Code

更新时间:
复制 MD 格式

智能体客户端协议(Agent Client Protocol,ACP)适合 IDE、编辑器和自定义智能体客户端。它提供结构化会话、流式文本和工具事件,并允许客户端响应 IaC Code 发起的权限请求。本文介绍传输选择、最小客户端和会话生命周期。

前提条件

  • 已完成安装和配置 IaC Code。

  • 已确定客户端允许 IaC Code 操作的项目绝对路径。

  • 使用 HTTP+SSE 时,已准备服务认证和网络访问控制。

选择传输方式

传输方式

启动命令

适用场景

Stdio,默认

iac-code acp

客户端在本机启动并管理 IaC Code 子进程。

HTTP+SSE

iac-code acp --transport http --host 127.0.0.1 --port 8765

独立部署、多客户端或网络连接。

本地 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 请求头。

相关文档