LlamaDeploy项目中API调用忽略service参数的问题分析

问题背景

在LlamaDeploy项目使用过程中，开发者发现通过API调用特定部署服务时存在一个参数传递问题。当尝试通过API运行特定部署服务时，传入的"service"参数会被系统忽略，导致总是使用默认服务(default-service)执行任务。

问题现象

开发者通过以下Python代码调用API端点：

url = f"{server}/deployments/{deployment}/tasks/run"
payload = {"input": json.dumps(args), "service": service}

async with httpx.AsyncClient() as client:
    response = await client.post(url, json=payload)

预期行为应与CLI命令llamactl --server SOME_URL run --deployment SOME_DEPLOYMENT --service SOME_SERVICE --arg SOME_KEY SOME_VALUE一致，但实际上API调用忽略了service参数，始终返回default-service。

根本原因

经过项目维护者确认，问题的根源在于API接口设计时的字段命名不一致。在内部实现中，服务标识参数的实际字段名是agent_id而非service。这是一个历史遗留问题，源于项目早期实现时的命名选择。

解决方案

要正确指定运行的服务，应该修改请求payload，使用agent_id字段替代service字段：

payload = {"input": json.dumps(args), "agent_id": service}

项目维护说明

项目维护者已确认这是一个需要改进的设计问题，建议在未来版本中统一参数命名，提高API的易用性和一致性。对于开发者而言，在当前版本中需要注意这一特殊设计，正确使用agent_id参数来指定目标服务。

最佳实践建议

1. 在使用LlamaDeploy API时，查阅最新的接口文档确认参数命名
2. 对于关键业务逻辑，建议先进行小规模测试验证参数传递效果
3. 关注项目更新，未来版本可能会统一参数命名，届时需要相应调整代码

这个问题提醒我们在使用开源项目API时，需要特别注意其内部实现细节可能与直觉预期存在差异，通过社区反馈和文档查阅可以避免类似问题。