當你的 AI Agent 有 500 個工具：從 GPT-5.4 的 Tool Search 看工具管理的正確姿勢

import numpy as np
from openai import OpenAI

client = OpenAI()

# 事先建好工具的 embedding 索引
tool_embeddings = {}
for tool in all_tools:
    response = client.embeddings.create(
        model="text-embedding-3-small",
        input=f"{tool['name']}: {tool['description']}"
    )
    tool_embeddings[tool["name"]] = {
        "embedding": response.data[0].embedding,
        "definition": tool
    }

def search_tools(user_message: str, top_k: int = 8) -> list:
    """根據使用者輸入，找出最相關的工具"""
    query_embedding = client.embeddings.create(
        model="text-embedding-3-small",
        input=user_message
    ).data[0].embedding

    scores = []
    for name, data in tool_embeddings.items():
        # cosine similarity
        score = np.dot(query_embedding, data["embedding"])
        scores.append((name, score, data["definition"]))

    scores.sort(key=lambda x: x[1], reverse=True)
    return [item[2] for item in scores[:top_k]]

# 使用
relevant_tools = search_tools("幫我建一張 Jira ticket 追蹤這個 bug")
response = client.chat.completions.create(
    model="claude-opus-4-6",  # 任何模型都能用
    messages=[{"role": "user", "content": "幫我建一張 Jira ticket 追蹤這個 bug"}],
    tools=relevant_tools  # 只傳 8 個工具，不是 200 個
)

TOOL_CATEGORIES = {
    "project_management": ["create_jira_ticket", "update_ticket", "list_sprints", ...],
    "database": ["query_database", "create_table", "run_migration", ...],
    "communication": ["send_slack_message", "create_channel", "send_email", ...],
    "monitoring": ["get_metrics", "create_alert", "query_logs", ...],
}

def route_to_category(user_message: str) -> str:
    """用小模型快速分類意圖"""
    response = client.chat.completions.create(
        model="gpt-5.4-mini",  # 用最便宜的模型做路由
        messages=[{
            "role": "system",
            "content": f"分類使用者意圖。只回覆分類名稱：{list(TOOL_CATEGORIES.keys())}"
        }, {
            "role": "user",
            "content": user_message
        }],
        max_tokens=20
    )
    return response.choices[0].message.content.strip()

def two_stage_tool_call(user_message: str) -> dict:
    # 階段一：選工具
    tool_index = [
        {"name": t["name"], "description": t["description"][:80]}
        for t in all_tools
    ]

    selection = client.chat.completions.create(
        model="claude-opus-4-6",
        messages=[{
            "role": "system",
            "content": (
                "根據使用者需求，從工具清單中選出需要的工具名稱。"
                "回覆 JSON 陣列，例如：[\"tool_a\", \"tool_b\"]"
            )
        }, {
            "role": "user",
            "content": f"需求：{user_message}\n\n可用工具：{tool_index}"
        }]
    )

    selected_names = json.loads(selection.choices[0].message.content)

    # 階段二：用完整定義執行
    selected_tools = [t for t in all_tools if t["name"] in selected_names]

    return client.chat.completions.create(
        model="claude-opus-4-6",
        messages=[{"role": "user", "content": user_message}],
        tools=selected_tools
    )

# ❌ 爛描述
{"name": "process_data", "description": "處理資料"}

# ✅ 好描述
{"name": "process_data", "description": "從 PostgreSQL 查詢銷售資料，按月份彙總，回傳 CSV 格式。用於產生月報表。"}