# 基本用法

DataHub SDK 提供了三种使用方式，从简单到复杂逐步满足不同需求。

## 1. 快捷方法 `make_call()`

最简单的使用方式，一行代码完成工具调用。

### 基本调用

```python
async with DatahubSDK() as sdk:
    result = await sdk.make_call("get_brands_categories")
    print(result.data)
```

### 带上下文的调用

提供更多上下文信息帮助 AI 构建正确的参数：

```python
async with DatahubSDK() as sdk:
    result = await sdk.make_call(
        query="query_daily_avg_received_amount",
        context="去年 10 月日均实收，门店 code 填写 1"
    )
    print(result.data)
```

### 自定义重试次数

```python
async with DatahubSDK() as sdk:
    result = await sdk.make_call(
        query="查询天气",
        context="查询北京今天的天气",
        max_retries=5  # 失败时最多重试 5 次
    )
```

### 工作流程

`make_call()` 内部执行以下步骤：

1. **搜索工具** - 根据 `query` 自动搜索最匹配的工具
2. **构建参数** - 使用 AI 根据 `context` 构建工具参数
3. **执行工具** - 调用工具并返回结果
4. **失败重试** - 如果失败，自动重试（最多 `max_retries` 次）

## 2. 批量调用 `make_call_multi()`

同时调用多个相关工具。

### 基本用法

```python
async with DatahubSDK() as sdk:
    results = await sdk.make_call_multi(
        query="查询品牌",
        context="获取所有品牌和品类信息",
        top_k=3  # 返回最匹配的 3 个工具
    )
    
    # 遍历所有工具的结果
    for tool_name, result in results.items():
        print(f"工具: {tool_name}")
        print(f"结果: {result.data}")
        print()
```

### 返回值

`make_call_multi()` 返回一个字典：
```python
{
    "tool_name_1": ExecuteResponse(...),
    "tool_name_2": ExecuteResponse(...),
    ...
}
```

### 使用场景

- 需要对比多个相似工具的结果
- 需要从多个数据源获取信息
- 不确定哪个工具最合适，想看多个选项

## 3. 分步调用

更细粒度的控制，适合复杂场景。

### 完整流程

```python
async with DatahubSDK() as sdk:
    # 步骤 1: 搜索工具
    search_resp = await sdk.search_tools("查询天气", top_k=3)
    
    # 查看搜索到的工具
    for tool in search_resp.tools:
        print(f"工具名: {tool.name}")
        print(f"描述: {tool.desc}")
    
    # 步骤 2: 构建参数
    args = await sdk.build_args(
        search_response=search_resp,
        args_fill_tips="查询北京今天的天气",
        tool_index=0  # 使用第一个工具
    )
    
    print(f"构建的参数: {args}")
    
    # 步骤 3: 执行工具
    result = await sdk.execute_tool(
        tool_name=search_resp.tools[0].name,
        args=args
    )
    
    print(f"执行结果: {result.data}")
```

### 各步骤详解

#### `search_tools()` - 搜索工具

```python
search_resp = await sdk.search_tools(
    query="查询天气",
    top_k=5  # 返回前 5 个匹配的工具
)

# 返回 SearchResponse
# - tools: list[ToolSchema] - 工具列表
```

#### `build_args()` - 构建参数

```python
args = await sdk.build_args(
    search_response=search_resp,
    args_fill_tips="查询北京今天的天气",
    max_retries=3,  # 参数构建失败时的重试次数
    tool_index=0  # 使用哪个工具（默认第一个）
)

# 返回 dict[str, Any] - 工具参数
```

#### `execute_tool()` - 执行工具

```python
result = await sdk.execute_tool(
    tool_name="get_weather",
    args={"city": "Beijing", "date": "2024-01-25"}
)

# 返回 ExecuteResponse
# - data: dict[str, Any] | list[Any] - 执行结果
```

### 使用场景

- 需要检查搜索到的工具列表
- 需要自定义参数构建逻辑
- 需要在执行前验证参数
- 需要记录详细的执行日志

## 响应数据处理

### ExecuteResponse

```python
result = await sdk.make_call("query")

# data 可能是 dict 或 list
if isinstance(result.data, dict):
    print(result.data["key"])
elif isinstance(result.data, list):
    for item in result.data:
        print(item)
```

### 使用 Pydantic 模型

```python
result = await sdk.make_call("query")

# 转换为 JSON
json_str = result.model_dump_json(indent=2, ensure_ascii=False)
print(json_str)

# 转换为字典
data_dict = result.model_dump()
```

## 错误处理

```python
async with DatahubSDK() as sdk:
    try:
        result = await sdk.make_call("query")
    except ValueError as e:
        # 未找到匹配的工具
        print(f"工具搜索失败: {e}")
    except Exception as e:
        # 其他错误（网络、参数构建、执行失败等）
        print(f"执行失败: {e}")
```

## 下一步

- 🔐 [认证方式](authentication.md) - 配置 API Key 和 JWT 认证
- 🚀 [高级功能](advanced.md) - 自定义 LLM、调试模式
- 📚 [API 参考](api_reference.md) - 完整的方法文档
