agentkit创建智能体失败87%源于配置环节：环境变量缺失、工具定义格式不合规或状态管理模块未初始化，需严格隔离python环境、校验openai function calling规范、注入state_handler并核对蓝图id与租户配置。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
AgentKit创建智能体失败时，87%的案例根源在配置环节——不是代码写错，而是环境变量缺失、工具定义格式不合规或状态管理模块未初始化。直接运行agentkit run却报错“Tool not found”或“State handler unavailable”，说明配置链路在启动前就已断裂。
检查环境与依赖配置
打开终端，进入项目根目录，执行：
python -m venv agent_env → source agent_env/bin/activate（Linux/Mac）或 agent_env\Scripts\activate（Windows）
这一步必须做，【AgentKit 严格要求隔离Python环境】。全局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(), state_handler=RedisStateHandler(host="localhost", port=6379))
第二步：若使用默认内存状态，请确认未同时启用多进程模式——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，导致你本地设置的预设文本被静默丢弃。
