Tool Use & Function Calling — Trang bị công cụ cho AI Agent

{
  "type": "function",
  "function": {
    "name": "get_order_status",
    "description": "Tra cứu trạng thái đơn hàng theo mã đơn. Dùng khi khách hỏi về tình trạng, tiến độ hoặc thời gian giao hàng. KHÔNG dùng để sửa hay hủy đơn.",
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "Mã đơn hàng, định dạng ORD-XXXXXX hoặc số nguyên"
        },
        "include_history": {
          "type": "boolean",
          "description": "Có trả về lịch sử trạng thái hay không. Mặc định false.",
          "default": false
        }
      },
      "required": ["order_id"]
    }
  }
}

{
  "type": "function",
  "function": {
    "name": "create_support_ticket",
    "description": "Tạo ticket hỗ trợ khi vấn đề không thể giải quyết tự động, hoặc khi khách hàng yêu cầu được hỗ trợ bởi nhân viên. KHÔNG tạo ticket nếu vấn đề đã được giải quyết.",
    "parameters": {
      "type": "object",
      "properties": {
        "customer_id": {
          "type": "string",
          "description": "ID khách hàng trong hệ thống CRM"
        },
        "subject": {
          "type": "string",
          "description": "Tiêu đề ngắn gọn mô tả vấn đề, tối đa 100 ký tự"
        },
        "description": {
          "type": "string",
          "description": "Mô tả chi tiết vấn đề, bao gồm context từ hội thoại"
        },
        "priority": {
          "type": "string",
          "enum": ["low", "medium", "high", "urgent"],
          "description": "Mức độ ưu tiên. Chọn 'urgent' chỉ khi ảnh hưởng đến giao dịch tài chính hoặc sức khỏe."
        },
        "category": {
          "type": "string",
          "enum": ["billing", "shipping", "technical", "product", "other"],
          "description": "Danh mục của ticket"
        }
      },
      "required": ["customer_id", "subject", "description", "priority", "category"]
    }
  }
}

{
  "type": "function",
  "function": {
    "name": "send_notification",
    "description": "Gửi thông báo tới khách hàng qua kênh ưu tiên của họ (email hoặc SMS). Chỉ dùng sau khi đã hoàn thành một hành động cụ thể cần xác nhận. KHÔNG spam — không gửi quá 1 thông báo cho cùng một sự kiện.",
    "parameters": {
      "type": "object",
      "properties": {
        "customer_id": {
          "type": "string",
          "description": "ID khách hàng"
        },
        "channel": {
          "type": "string",
          "enum": ["email", "sms", "zalo", "push"],
          "description": "Kênh gửi thông báo"
        },
        "template_id": {
          "type": "string",
          "description": "ID mẫu thông báo đã được phê duyệt trong hệ thống"
        },
        "variables": {
          "type": "object",
          "description": "Các biến điền vào template, ví dụ: { order_id, status, eta }"
        }
      },
      "required": ["customer_id", "channel", "template_id"]
    }
  }
}

// LLM trả về nhiều tool_call cùng lúc
{
  "tool_calls": [
    {
      "id": "call_abc",
      "function": { "name": "get_order_status", "arguments": "{\"order_id\": \"ORD-001\"}" }
    },
    {
      "id": "call_def",
      "function": { "name": "get_customer_profile", "arguments": "{\"customer_id\": \"CUS-123\"}" }
    }
  ]
}

using Microsoft.SemanticKernel;
using System.ComponentModel;

// ============================================================
// Bước 1: Định nghĩa Plugin với KernelFunction attributes
// ============================================================
public class OrderPlugin
{
    private readonly IOrderService _orderService;
    private readonly ITicketService _ticketService;

    public OrderPlugin(IOrderService orderService, ITicketService ticketService)
    {
        _orderService = orderService;
        _ticketService = ticketService;
    }

    [KernelFunction("get_order_status")]
    [Description("Tra cứu trạng thái đơn hàng theo mã đơn. Dùng khi khách hỏi về tình trạng, tiến độ hoặc ETA giao hàng. KHÔNG dùng để sửa hay hủy đơn.")]
    public async Task<string> GetOrderStatusAsync(
        [Description("Mã đơn hàng, định dạng ORD-XXXXXX")] string orderId,
        [Description("Có trả về lịch sử trạng thái không, mặc định false")] bool includeHistory = false)
    {
        var order = await _orderService.GetOrderAsync(orderId);
        if (order == null)
            return $"Không tìm thấy đơn hàng với mã {orderId}.";

        var result = $"Đơn {orderId}: {order.Status} | ETA: {order.EstimatedDelivery:dd/MM/yyyy}";
        if (includeHistory && order.StatusHistory?.Any() == true)
        {
            var history = string.Join("\n", order.StatusHistory.Select(h => $"  - {h.Date:dd/MM} {h.Status}"));
            result += $"\nLịch sử:\n{history}";
        }
        return result;
    }

    [KernelFunction("create_support_ticket")]
    [Description("Tạo ticket hỗ trợ khi vấn đề cần nhân viên xử lý hoặc không thể tự động giải quyết. KHÔNG tạo ticket nếu đã giải quyết xong.")]
    public async Task<string> CreateSupportTicketAsync(
        [Description("ID khách hàng trong CRM")] string customerId,
        [Description("Tiêu đề ngắn gọn, tối đa 100 ký tự")] string subject,
        [Description("Mô tả chi tiết vấn đề")] string description,
        [Description("Mức ưu tiên: low, medium, high, urgent")] string priority = "medium")
    {
        // Human-in-the-loop: log để audit trước khi write
        Console.WriteLine($"[AUDIT] Creating ticket for customer {customerId}: {subject}");

        var ticket = await _ticketService.CreateAsync(new CreateTicketRequest
        {
            CustomerId = customerId,
            Subject = subject,
            Description = description,
            Priority = Enum.Parse<TicketPriority>(priority, ignoreCase: true)
        });

        return $"Đã tạo ticket #{ticket.Id}. Nhân viên sẽ liên hệ trong {ticket.SlaHours} giờ.";
    }
}

// ============================================================
// Bước 2: Đăng ký Plugin và chạy Agent loop
// ============================================================
public class AgentService
{
    public async Task<string> HandleUserMessageAsync(string userMessage, string customerId)
    {
        // Khởi tạo Kernel
        var builder = Kernel.CreateBuilder();
        builder.AddOpenAIChatCompletion(
            modelId: "gpt-4o-mini",
            apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY")!);

        var kernel = builder.Build();

        // Đăng ký plugin
        kernel.Plugins.AddFromObject(
            new OrderPlugin(orderService, ticketService),
            pluginName: "OrderPlugin");

        // Cấu hình auto tool invocation
        var executionSettings = new OpenAIPromptExecutionSettings
        {
            ToolCallBehavior = ToolCallBehavior.AutoInvokeKernelFunctions
        };

        // System prompt
        var systemPrompt = $"""
            Bạn là trợ lý hỗ trợ khách hàng của Công ty ABC.
            ID khách hàng hiện tại: {customerId}
            Nguyên tắc:
            - Chỉ sử dụng tool khi thực sự cần thiết
            - Không tạo ticket nếu đã giải quyết được bằng thông tin có sẵn
            - Luôn xác nhận lại với khách trước khi tạo ticket hoặc gửi thông báo
            """;

        var history = new ChatHistory(systemPrompt);
        history.AddUserMessage(userMessage);

        // Gọi LLM với auto tool invocation
        var chatService = kernel.GetRequiredService<IChatCompletionService>();
        var result = await chatService.GetChatMessageContentAsync(
            history,
            executionSettings,
            kernel);

        return result.Content ?? "Xin lỗi, tôi không thể xử lý yêu cầu này lúc này.";
    }
}

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from typing import Optional
import logging

logger = logging.getLogger(__name__)

# ============================================================
# Bước 1: Định nghĩa Tools bằng decorator
# ============================================================

@tool
def get_order_status(order_id: str, include_history: bool = False) -> str:
    """Tra cứu trạng thái đơn hàng theo mã đơn.
    Dùng khi khách hỏi về tình trạng, tiến độ hoặc ETA giao hàng.
    KHÔNG dùng để sửa hay hủy đơn.
    
    Args:
        order_id: Mã đơn hàng, định dạng ORD-XXXXXX
        include_history: Có trả về lịch sử trạng thái không, mặc định False
    """
    # Gọi service thực tế (minh hoạ)
    order = order_service.get(order_id)
    if not order:
        return f"Không tìm thấy đơn hàng với mã {order_id}."
    
    result = f"Đơn {order_id}: {order['status']} | ETA: {order['eta']}"
    if include_history and order.get("history"):
        history_str = "\n".join(f"  - {h['date']} {h['status']}" for h in order["history"])
        result += f"\nLịch sử:\n{history_str}"
    return result


@tool
def create_support_ticket(
    customer_id: str,
    subject: str,
    description: str,
    priority: str = "medium",
    category: str = "other"
) -> str:
    """Tạo ticket hỗ trợ khi vấn đề cần nhân viên xử lý.
    KHÔNG tạo ticket nếu đã giải quyết được bằng thông tin có sẵn.
    
    Args:
        customer_id: ID khách hàng trong CRM
        subject: Tiêu đề ngắn gọn (tối đa 100 ký tự)
        description: Mô tả chi tiết vấn đề
        priority: Mức ưu tiên (low/medium/high/urgent)
        category: Danh mục (billing/shipping/technical/product/other)
    """
    # Audit log trước khi write
    logger.info(f"[AUDIT] Creating ticket | customer={customer_id} | priority={priority}")
    
    # Validate priority
    valid_priorities = {"low", "medium", "high", "urgent"}
    if priority not in valid_priorities:
        return f"Priority không hợp lệ. Chọn một trong: {', '.join(valid_priorities)}"
    
    ticket = ticket_service.create({
        "customer_id": customer_id,
        "subject": subject[:100],  # enforce max length
        "description": description,
        "priority": priority,
        "category": category
    })
    
    sla_map = {"urgent": 1, "high": 4, "medium": 8, "low": 24}
    return f"Đã tạo ticket #{ticket['id']}. Nhân viên sẽ phản hồi trong {sla_map[priority]} giờ."


@tool
def search_faq(query: str) -> str:
    """Tìm kiếm trong cơ sở tri thức FAQ.
    Dùng trước khi tạo ticket để xem có thể tự giải quyết không.
    
    Args:
        query: Câu hỏi hoặc từ khoá cần tìm kiếm
    """
    results = rag_service.search(query, top_k=3)
    if not results:
        return "Không tìm thấy thông tin liên quan trong FAQ."
    
    return "\n\n".join(
        f"[{i+1}] {r['title']}\n{r['content'][:300]}..."
        for i, r in enumerate(results)
    )


# ============================================================
# Bước 2: Khởi tạo Agent với tool list
# ============================================================

def create_customer_support_agent(customer_id: str) -> AgentExecutor:
    llm = ChatOpenAI(model="gpt-4o-mini", temperature=0)
    
    tools = [get_order_status, create_support_ticket, search_faq]
    
    prompt = ChatPromptTemplate.from_messages([
        ("system", f"""Bạn là trợ lý hỗ trợ khách hàng của Công ty ABC.
ID khách hàng: {customer_id}

Nguyên tắc:
1. Luôn tìm kiếm FAQ trước khi tạo ticket
2. Không tạo ticket nếu đã có câu trả lời
3. Xác nhận với khách trước khi thực hiện write action
4. Ưu tiên giải quyết nhanh, chỉ escalate khi thực sự cần"""),
        MessagesPlaceholder(variable_name="chat_history", optional=True),
        ("human", "{input}"),
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])
    
    agent = create_openai_tools_agent(llm, tools, prompt)
    
    return AgentExecutor(
        agent=agent,
        tools=tools,
        verbose=True,           # Log tool calls để debug
        max_iterations=5,       # Giới hạn vòng lặp, tránh loop vô hạn
        handle_parsing_errors=True
    )


# ============================================================
# Bước 3: Sử dụng
# ============================================================

async def handle_message(customer_id: str, message: str) -> str:
    agent = create_customer_support_agent(customer_id)
    result = await agent.ainvoke({
        "input": message,
        "chat_history": []
    })
    return result["output"]

def get_tools_for_context(user_role: str, conversation_stage: str) -> list:
    """Chỉ cấp tool phù hợp với role và giai đoạn hội thoại."""
    
    # Mọi người dùng: chỉ read + search
    base_tools = [get_order_status, search_faq]
    
    # Khách hàng đã xác thực: thêm notify
    if user_role in ("authenticated_customer", "agent"):
        base_tools.append(send_notification)
    
    # Nhân viên CS: thêm write tools
    if user_role == "agent":
        base_tools.extend([create_support_ticket, update_ticket_status])
    
    # Chỉ mở write tools sau khi đã thu thập đủ thông tin
    if conversation_stage == "resolution" and user_role == "agent":
        base_tools.append(schedule_callback)
    
    return base_tools

def execute_tool_safely(tool_name: str, args: dict, user_context: dict) -> dict:
    """Wrapper bảo mật cho mọi tool execution."""
    
    # 1. Kiểm tra tool có trong allow-list không
    allowed = get_tools_for_context(user_context["role"], user_context["stage"])
    if tool_name not in [t.name for t in allowed]:
        return {"error": f"Tool '{tool_name}' không được phép trong context này"}
    
    # 2. Validate schema bằng JSON Schema
    schema = TOOL_SCHEMAS[tool_name]
    errors = jsonschema.validate(args, schema["parameters"])
    if errors:
        return {"error": f"Invalid arguments: {errors}"}
    
    # 3. Business rule validation
    if tool_name == "create_support_ticket":
        if args.get("priority") == "urgent" and user_context["role"] != "agent":
            args["priority"] = "high"  # Downgrade nếu không có quyền
    
    # 4. Audit log trước khi execute write
    if TOOL_WRITE_FLAG.get(tool_name):
        audit_log.write({
            "timestamp": datetime.utcnow().isoformat(),
            "user_id": user_context["user_id"],
            "tool": tool_name,
            "args": sanitize_pii(args),  # Mask PII trước khi log
            "session_id": user_context["session_id"]
        })
    
    # 5. Execute
    return TOOL_REGISTRY[tool_name](**args)

# Pseudo workflow: human_approval_gate
name: write_tool_approval_flow
trigger: tool_call_detected

steps:
  - name: classify_tool_impact
    check:
      - tool_name in HIGH_IMPACT_TOOLS  # cancel_order, process_refund, update_contract
    on_match: require_approval
    on_no_match: auto_execute

  - name: request_human_approval
    action: send_approval_request
    channels:
      - slack_manager_channel
      - email_supervisor
    timeout: 30_minutes
    payload:
      tool: "{{ tool_name }}"
      args: "{{ tool_args_sanitized }}"
      context: "{{ conversation_summary }}"
      requested_by: "{{ agent_id }}"

  - name: wait_for_decision
    action: pause_workflow
    resume_on:
      - approved: execute_tool_with_audit_log
      - rejected: notify_agent_and_user
      - timeout: escalate_to_level2

on_error:
  - default_action: reject_and_notify
  - audit_log: always