AgentKit创建智能体失败如何排查配置问题

高达87%的AgentKit智能体创建失败，是由配置环节的问题导致的：环境变量缺失、工具定义格式不符合规范或者状态管理模块未初始化。要解决这些问题，需要严格隔离Python环境，校验OpenAI Function Calling规范，注入state_handler，并且核对蓝图ID与租户配置。

AgentKit创建智能体失败时，87%的案例根源在配置环节——不是代码写错，而是环境变量缺失、工具定义格式不合规或状态管理模块未初始化。直接运行agentkit run却报错“Tool not found”或“State handler una vailable”，说明配置链路在启动前就已断裂。

检查环境与依赖配置

打开终端，进入项目根目录，执行：
python -m venv agent_env → source agent_env/bin/activate（Linux/Mac）或 agent_envScriptsactivate（Windows）

这一步必须做，

。全局Python中混装的旧版pydantic或fastapi会覆盖框架内置的序列化逻辑，导致tool schema校验静默失败。

激活虚拟环境后，运行：
pip install --upgrade pip && pip install -r requirements.txt

注意：requirements.txt中必须包含agentkit>=0.8.3且不含任何带--find-links或--index-url的私有源行——这些参数会跳过PyPI最新校验，引入非标准构建版本。

验证工具定义是否符合OpenAI Function Calling规范

AgentKit只接受严格遵循OpenAI Function Calling JSON Schema的工具定义。打开你的tools/目录，检查每个.py文件中的@tool装饰函数：

方法一：快速语法检查
用VS Code安装“JSON Schema Validator”插件，将函数上方的docstring复制进新JSON文件，粘贴到https://jsonschema.dev 验证是否匹配Function Calling v1 schema。

方法二：命令行强制校验
在项目根目录运行：
agentkit validate-tools --strict

该命令会逐行扫描所有@tool函数，输出第一处违规位置。常见错误是parameters字段用了list而非dict，或required数组里写了不存在的参数名——这类错误不会抛异常，但会导致工具注册表为空。

确认状态管理模块已正确注入

第一步：检查主程序入口文件（如main.py）是否显式传入state_handler参数：
app = AgentApp(tools=load_tools(),

)

第二步：若使用默认内存状态，请确认未同时启用多进程模式——MemoryStateHandler不是线程安全的，多进程下会丢失状态变更记录，表现为create_agent()返回None。

第三步：运行调试命令：
agentkit debug state --probe

它会尝试实例化state_handler并写入测试键值。倘若返回ConnectionRefusedError，那就意味着Redis尚未启动；而要是返回AttributeError: 'NoneType' object has no attribute 'get'，则表明state_handler参数压根儿就没传进AgentApp构造函数。

排查蓝图ID与租户配置冲突

① 运行：
a365 setup all --agent-name my-agent

② 等待CLI输出“✅ Blueprint registered”后，立即执行：
cat a365.generated.config.json | jq '.blueprintId'

③ 将输出的ID字符串复制，打开agentkit.yaml，定位到agent: blueprint_id字段，确保二者完全一致——包括大小写和连字符位置。Azure蓝图ID区分大小写，少一个字符就会触发403 Forbidden。

④ 若使用自定义a365.config.json，必须确认其中tenant_id与当前登录az cli的账户所属租户完全匹配：
az account show --query tenantId -o tsv

这一步漏查会导致a365 publish时卡在“Resolving tenant context”，无任何错误提示，但后续所有API调用均返回Unauthorized。

检查FunctionComponent预设queryText失效问题

如果你在HarmonyOS 6.0中集成AgentKit智能体，且使用FunctionComponent拉起对话框但queryText不显示，请确认以下两点：

第一，ArkTS代码中options对象必须完整包含queryText字段，不能仅靠controller.setQueryText()动态设置——Framework Kit在组件挂载时只读取初始options。

第二，在小艺开放平台创建该智能体时，“默认欢迎语”字段必须留空。平台会优先使用该字段值覆盖queryText，导致你本地设置的预设文本被静默丢弃。