AgentScope Runtime 生产部署EngineSandbox 双核架构深度拆解导读AgentScope Runtime 提供了完整的生产级运行时框架,支持从本地到云端的多种部署形态。本文深入拆解 Engine 和 Sandbox 双核架构,详解 Docker/K8s/Serverless 部署方案,以及 Agent-as-a-Service 的服务化输出能力。一、Runtime 架构总览1.1 双核架构设计AgentScope Runtime 采用Engine Sandbox双核架构,各司其职:┌─────────────────────────────────────────────────────────┐ │ AgentScope Runtime │ ├─────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Engine │ │ Sandbox │ │ │ │ ┌────────────┐ │ │ ┌────────────┐ │ │ │ │ │ FastAPI │ │ │ │ Docker │ │ │ │ │ │ Server │ ├─────────▶│ │ Container │ │ │ │ │ └────────────┘ │ RPC │ │ Isolation │ │ │ │ │ ┌────────────┐ │ │ └────────────┘ │ │ │ │ │ Life │ │ │ │ │ │ │ │ Cycle │ │ │ ┌────────────┐ │ │ │ │ │ Manager │ │ │ │ K8s Pods │ │ │ │ │ └────────────┘ │ │ │ Scaling │ │ │ │ │ ┌────────────┐ │ │ └────────────┘ │ │ │ │ │ Health │ │ │ │ │ │ │ │ Monitor │ │ │ ┌────────────┐ │ │ │ │ └────────────┘ │ │ │ FC/ACK │ │ │ │ │ │ │ │ Serverless │ │ │ │ └──────────────────┘ │ └────────────┘ │ │ │ │ │ │ │ └──────────────────┘ │ │ │ └─────────────────────────────────────────────────────────┘1.2 核心职责Engine 模块:FastAPI 服务:提供 REST API 和 SSE 流式接口生命周期管理:Agent 应用的启动、停止、重启健康监控:实时监控 Agent 和 Sandbox 状态负载均衡:多实例部署下的请求分发服务发现:集成 Nacos 等注册中心Sandbox 模块:进程隔离:Docker 容器级别的资源隔离镜像管理:拉取、构建、缓存 Docker 镜像工具执行:安全执行工具和代码资源控制:CPU、内存、网络限制VNC 可视化:GUI 自动化的远程桌面访问二、Runner 对象模型2.1 AgentApp 三阶段模式AgentScope Runtime 通过Runner对象模型管理 Agent 应用的完整生命周期:fromagentscope_runtimeimportRunner,AgentApp# 创建 AgentAppappAgentApp(namecustomer_service,agent_config{name:客服助手,model:qwen-max,tools:[search_knowledge,transfer_to_human]})# 初始化阶段runnerRunner(app)runner.init()# 初始化资源、加载配置# 查询阶段responserunner.query(message用户提问,session_idsession_123)# 关闭阶段runner.shutdown()# 释放资源、保存状态2.2 上下文管理器fromagentscope_runtimeimportRunner# 使用上下文管理器自动管理生命周期withRunner(app)asrunner:# 自动调用 init()responserunner.query(message测试消息)# 自动调用 shutdown()2.3 会话状态管理fromagentscope_runtimeimportSessionManager# 创建会话管理器session_mgrSessionManager(storage_backendmysql,connection_config{host:localhost,port:3306,database:agentscope})# 创建带会话的 RunnerwithRunner(app,session_managersession_mgr)asrunner:# 第一轮对话response1runner.query(message我叫张三,session_iduser_001)# 第二轮对话(会话状态自动加载)response2runner.query(message我的名字是什么?,session_iduser_001)# Agent 记住了用户的名字三、部署形态详解3.1 Local:本地进程部署适用场景:开发、调试、原型验证特点:最简单的部署方式无需额外基础设施快速迭代开发部署代码:fromagentscope_runtimeimportRunner# 创建本地 RunnerrunnerRunner(app,modelocal)# 启动服务runner.start()# API 端点# - http://localhost:8000/query# - http://localhost:8000/health配置文件(runtime.local.yaml):engine:host:0.0.0.0port:8000workers:4sandbox:type:localbackend:boxlite# 轻量级沙箱logging:level:INFOfile:/var/log/agentscope/runtime.log3.2 Docker:容器化部署适用场景:测试环境、中小规模生产特点:环境一致性易于扩展支持 VNC 可视化Dockerfile:FROM agentscope/runtime:latest # 复制 Agent 应用代码 COPY ./app /app # 复制配置文件 COPY ./runtime.docker.yaml /etc/agentscope/runtime.yaml # 暴露端口 EXPOSE 8000 5900 # 8000: API, 5900: VNC # 启动命令 CMD [agentscope-runtime, start, --config, /etc/agentscope/runtime.yaml]docker-compose.yml:version:3.8services:engine:image:agentscope-runtime:latestports:-8000:8000-5900:5900# VNC 端口volumes:-./app:/app-./config:/etc/agentscopeenvironment:-SANDBOX_TYPEdocker-ENABLE_VNCtruedeploy:resources:limits:cpus:2memory:4Grestart:unless-stoppedmysql:image:mysql:8.0environment:MYSQL_ROOT_PASSWORD:passwordMYSQL_DATABASE:agentscopevolumes:-mysql-data:/var/lib/mysqlvolumes:mysql-data:启动命令:# 构建镜像dockerbuild-tagentscope-runtime:latest.# 启动服务docker-composeup-d# 查看 VNCvncviewer localhost:59003.3 K8s:Kubernetes 编排部署适用场景:大规模生产环境、高可用、弹性扩缩容特点:集群级别资源管理自动故障恢复弹性伸缩服务网格集成Deployment 配置:apiVersion:apps/v1kind:Deploymentmetadata:name:agentscope-enginespec:replicas:3selector:matchLabels:app:agentscope-enginetemplate:metadata:labels:app:agentscope-enginespec:containers:-name:engineimage:agentscope/runtime:v1.0.0ports:-containerPort:8000env:-name:SANDBOX_TYPEvalue:k8s-name:NACOS_SERVER_ADDRvalue:nacos-service:8848resources:requests:memory:2Gicpu:1limits:memory:4Gicpu:2livenessProbe:httpGet:path:/healthport:8000initialDelaySeconds:30periodSeconds:10readinessProbe:httpGet:path:/readyport:8000initialDelaySeconds:5periodSeconds:5---apiVersion:v1kind:Servicemetadata:name:agentscope-engine-servicespec:selector:app:agentscope-engineports:-protocol:TCPport:80targetPort:8000type:LoadBalancerHorizontalPodAutoscaler (HPA):apiVersion:autoscaling/v2kind:HorizontalPodAutoscalermetadata:name:agentscope-hpaspec:scaleTargetRef:apiVersion:apps/v1kind:Deploymentname:agentscope-engineminReplicas:3maxReplicas:10metrics:-type:Resourceresource:name:cputarget:type:UtilizationaverageUtilization:70-type:Resourceresource:name:memorytarget:type:UtilizationaverageUtilization:80部署命令:# 部署kubectl apply-fdeployment.yaml# 查看 Pod 状态kubectl get pods-lappagentscope-engine# 扩缩容kubectl scale deployment agentscope-engine--replicas5# 查看 HPA 状态kubectl get hpa3.4 Serverless:无服务器部署适用场景:突发流量、按需计费、轻量级应用特点:按需启动自动伸缩按实际使用计费冷启动优化阿里云函数计算 (FC):# handler.pyimportjsonfromagentscope_runtimeimportRunner# 初始化 Runner (全局)runnerNonedefhandler(event,context):globalrunner# 初始化ifrunnerisNone:appAgentApp.from_json(context.function_config)runnerRunner(app,modeserverless)runner.init()# 解析请求bodyjson.loads(event.body)messagebody.get(message)session_idbody.get(session_id,context.request_id)# 查询responserunner.query(message,session_id)# 返回return{statusCode:200,headers:{Content-Type:application/json},body:json.dumps({response:response.content,session_id:session_id})}template.yml:ROSTemplateFormatVersion:2015-09-01Transform:Aliyun::Serverless-2018-04-03Resources:agentscope-service:Type:Aliyun::Serverless::ServiceProperties:Description:AgentScope Serverless ServiceInternetAccess:trueagentscope-function:Type:Aliyun::Serverless::FunctionProperties:Handler:handler.handlerRuntime:python3.9CodeUri:./MemorySize:2048Timeout:300EnvironmentVariables:SANDBOX_TYPE:fcEvents:http-trigger:Type:HTTPProperties:AuthType:ANONYMOUSMethods:[GET,POST]部署命令:# 使用 Fun CLIfun deploy--templatetemplate.yml# 或使用 Serverless Devss deploy四、服务化输出4.1 自动生成 FastAPI 端点fromagentscope_runtimeimportcreate_server# 自动生成 FastAPI 应用appcreate_server(agent_appmy_agent,routes{/query:query,/stream:stream,/health:health_check})# 启动服务if__name____main__:importuvicorn uvicorn.run(app,host0.0.0.0,port8000)4.2 SSE 流式响应fromfastapiimportFastAPIfromfastapi.responsesimportStreamingResponsefromagentscope_runtimeimportRunner appFastAPI()runnerRunner(my_agent)app.post(/stream)asyncdefstream_response(request:dict):messagerequest[message]session_idrequest.get(session_id,default)asyncdefgenerate():asyncforchunkinrunner.stream_query(message,session_id):yieldfdata:{chunk}\n\nreturnStreamingResponse(generate(),media_typetext/event-stream)4.3 OpenAI SDK 兼容模式fromagentscope_runtimeimportOpenAICompatibleServer# 创建 OpenAI 兼容服务serverOpenAICompatibleServer(agentmy_agent)# 启动服务server.start(host0.0.0.0,port8000)# 使用 OpenAI SDK 调用fromopenaiimportOpenAI clientOpenAI(base_urlhttp://localhost:8000/v1,api_keydummy)responseclient.chat.completions.create(modelagentscope-agent,messages[{role:user,content:你好}])五、高级配置与优化5.1 多租户隔离# runtime.multi-tenant.yamlengine:multi_tenant:enabled:trueisolation_level:strict# strict/medium/loosetenants:-id:tenant_anamespace:tenant-aresource_quota:cpu:2memory:4Gsandbox_instances:5-id:tenant_bnamespace:tenant-bresource_quota:cpu:4memory:8Gsandbox_instances:105.2 缓存优化fromagentscope_runtimeimportCachedRunner# 启用缓存runnerCachedRunner(appmy_agent,cache_config{backend:redis,host:localhost,port:6379,ttl:3600,# 1小时max_size:10000})# 查询(自动缓存)responserunner.query(常见问题)# 第二次查询(从缓存返回)responserunner.query(常见问题)5.3 熔断限流# runtime.resilience.yamlresilience:circuit_breaker:enabled:truefailure_threshold:5recovery_timeout:30rate_limiting:enabled:truerequests_per_second:100burst_size:200retry:enabled:truemax_attempts:3backoff_factor:2六、监控与运维6.1 健康检查fromagentscope_runtimeimportHealthCheck# 创建健康检查healthHealthCheck(runner)# 检查项health.add_check(engine_status,runner.is_healthy)health.add_check(sandbox_status,runner.sandbox.is_healthy)health.add_check(database_connection,check_db_connection)health.add_check(memory_usage,check_memory_threshold)# 运行健康检查statushealth.check()ifnotstatus.healthy:# 触发告警send_alert(status)6.2 日志聚合# runtime.logging.yamllogging:level:INFOformat:json# json/textoutputs:-type:filepath:/var/log/agentscope/runtime.log-type:lokiurl:http://loki-service:3100/loki/api/v1/push-type:elasticsearchhosts:[elasticsearch-service:9200]index:agentscope-logs七、生产部署最佳实践7.1 分层部署策略┌─────────────────────────────────────┐ │ 负载均衡层 (ALB/Nginx) │ └──────────────┬──────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ API 网关层 (Kong/APISIX) │ │ - 认证授权 │ │ - 限流熔断 │ │ - 路由转发 │ └──────────────┬──────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Engine 层 (K8s Deployment) │ │ - 3 副本 │ │ - HPA 自动扩缩容 │ └──────────────┬──────────────────────┘ ↓ ┌─────────────────────────────────────┐ │ Sandbox 层 (K8s Deployment) │ │ - 独立命名空间隔离 │ │ - 资源配额限制 │ └─────────────────────────────────────┘7.2 滚动更新# 更新镜像kubectlsetimage deployment/agentscope-engine\engineagentscope/runtime:v1.1.0# 查看更新状态kubectl rollout status deployment/agentscope-engine# 回滚kubectl rollout undo deployment/agentscope-engine八、总结AgentScope Runtime 通过Engine Sandbox双核架构,提供了从本地到云端、从单体到分布式的完整部署方案:Engine 模块:FastAPI 服务、生命周期管理、健康监控Sandbox 模块:进程隔离、镜像管理、工具执行安全部署形态:Local、Docker、K8s、Serverless,灵活适配服务化输出:自动生成 API 端点、SSE 流式响应、OpenAI 兼容这套架构让 Agent 应用既能快速原型验证,又能平滑扩展到生产环境,真正实现开箱即用到生产就绪的完整路径。延伸阅读:AgentScope Runtime 文档Kubernetes 部署指南Serverless 最佳实践