Agent Space API调用超时需先区分connect timeout（连接未建立）与read timeout（已连接但响应慢），再通过日志、curl指标、健康检查及下游依赖分析逐层定位。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space API调用超时会导致任务卡死、流式响应中断、工具调用失败甚至整个Agent会话崩溃，必须立即定位是连接建立失败还是响应等待过久。
先确认超时类型
打开 AgentSpace 运行日志（默认路径 ./logs/runtime.log），搜索关键词 “timeout” 或 “Connection refused”，重点看报错前缀：
如果出现 connect timeout：说明 DNS 解析失败、目标端口未开放、安全组拦截或代理配置错误，此时请求根本没发出去；
如果出现 read timeout 或 socket timeout：说明 TCP 连接已建立，但 AgentSpace 后端服务处理太慢，或上游依赖（如模型 API、数据库、缓存）拖慢了整体链路；
如果返回 HTTP 状态码 504 Gateway Timeout：说明 Nginx 或 API Gateway 层设置了比后端更短的超时阈值，它先放弃了等待；
如果日志里反复出现 429 Too Many Requests：不是超时，是被限流，需检查请求频率与 Retry-After 头。
检查客户端超时配置
AgentSpace SDK 默认使用 requests 库发起调用，其超时由两个参数控制：
方法一：显式传参设置（推荐用于调试）
在调用 agent.run() 或 tool.invoke() 时，传入 timeout=(3.0, 30.0)，其中第一个值是 connect timeout，第二个是 read timeout；
方法二：全局环境变量覆盖
启动前设置 export AGENTSPACE_REQUEST_TIMEOUT="3,60"，格式为 “connect,read”，单位秒；
【注意】不要只调大 read timeout 而忽略 connect timeout —— 若连不上，再等 60 秒也无意义，反而掩盖网络层问题。
验证网关与后端服务耗时
第一步：用 curl 直接绕过 SDK 测试网关响应
curl -v -X POST https://your-agentspace-domain/v1/agents/xxx/run -H "Authorization: Bearer xxx" -d '{"input": "hello"}'
第二步：观察 time_namelookup、time_connect、time_starttransfer 三个指标：
若 time_connect > 2s：DNS 或网络路由异常，检查 /etc/resolv.conf 或更换 DNS（如 8.8.8.8）；
若 time_starttransfer – time_connect > 5s：说明网关已收到请求但迟迟不转发，检查 Nginx 的 proxy_read_timeout 和 proxy_connect_timeout 是否小于后端实际处理时间；
第三步：登录 AgentSpace 服务节点，执行 curl -s http://localhost:8000/health，确认内部服务存活；再查 journalctl -u agentspace -n 50 --no-pager，看是否有 “slow query”、“thread pool exhausted” 或 “model call stuck” 日志。
排查下游依赖瓶颈
① 查看 ./logs/model_calls.jsonl，过滤出耗时 >5s 的记录，重点关注字段："model_name"、"duration_ms"、"status"；
② 若大量调用 DashScope 或 OpenAI 接口超时，检查是否启用了流式（stream=True）但未正确 consume SSE event —— 未及时读取会导致连接挂起，触发 read timeout；
③ 若工具调用（如数据库查询、HTTP 工具）频繁超时，进入对应工具代码，在入口处加 logging.debug(f"[tool] start at {time.time()}")，确认是工具自身慢，还是被线程池阻塞；
④ 检查 agentscope[full] 安装版本是否匹配当前 Python（≥3.10），低版本可能因 asyncio 兼容问题导致协程调度延迟，表现为随机 read timeout。
