Tool Use Mathematics and Implementation: From JSON Schema to Pydantic AI — Production Agent Engineering

# OpenAI Function Calling — Türkçe Tool Örnek
from openai import OpenAI
from typing import Literal
import json
import re
 
client = OpenAI()
 
# 1. Tool fonksiyonu — gerçek iş
def tc_kimlik_dogrula(tc_no: str) -> dict:
    '''Türkiye TC kimlik numarası algoritmik doğrulama.'''
    if len(tc_no) != 11 or not tc_no.isdigit():
        return {'gecerli': False, 'hata': 'TC kimlik 11 rakam olmalı'}
    if tc_no[0] == '0':
        return {'gecerli': False, 'hata': 'İlk rakam 0 olamaz'}
    
    digits = [int(d) for d in tc_no]
    sum_odd = sum(digits[i] for i in [0, 2, 4, 6, 8])
    sum_even = sum(digits[i] for i in [1, 3, 5, 7])
    check_10 = (sum_odd * 7 - sum_even) % 10
    check_11 = sum(digits[:10]) % 10
    
    if digits[9] == check_10 and digits[10] == check_11:
        return {'gecerli': True, 'tc_no': tc_no}
    return {'gecerli': False, 'hata': 'Kontrol algoritması başarısız'}
 
def e_fatura_sorgula(fatura_uuid: str) -> dict:
    '''Türk e-fatura UUID'siyle sorgulama (mock).'''
    return {
        'uuid': fatura_uuid,
        'durum': 'onaylandı',
        'toplam': 1250.50,
        'tarih': '2025-03-15',
        'satici': 'XYZ Ltd. Şti.',
        'alici': 'ABC A.Ş.',
    }
 
# 2. JSON Schema tanımı
tools = [
    {
        'type': 'function',
        'function': {
            'name': 'tc_kimlik_dogrula',
            'description': 'Türkiye Cumhuriyeti kimlik numarasını algoritmik olarak doğrular',
            'parameters': {
                'type': 'object',
                'properties': {
                    'tc_no': {
                        'type': 'string',
                        'description': '11 haneli TC kimlik numarası',
                    },
                },
                'required': ['tc_no'],
            },
        },
    },
    {
        'type': 'function',
        'function': {
            'name': 'e_fatura_sorgula',
            'description': 'Türk e-fatura UUID\'siyle fatura detaylarını sorgular',
            'parameters': {
                'type': 'object',
                'properties': {
                    'fatura_uuid': {
                        'type': 'string',
                        'description': 'E-fatura UUID (36 karakter, dash\'lerle)',
                    },
                },
                'required': ['fatura_uuid'],
            },
        },
    },
]
 
# 3. Ajan döngüsü
messages = [
    {'role': 'system', 'content': 'Sen Türkçe muhasebe asistanısın. TC kimlik doğrulama ve e-fatura sorgulama tool\'larına erişimin var.'},
    {'role': 'user', 'content': 'Müşterimin TC\'sini doğrula: 12345678901. Sonra e-fatura uuid 6f1b9c2a-3e4d-5f6a-7b8c-9d0e1f2a3b4c hakkında bilgi ver.'},
]
 
while True:
    response = client.chat.completions.create(
        model='gpt-4o',
        messages=messages,
        tools=tools,
        tool_choice='auto',
    )
    
    msg = response.choices[0].message
    messages.append(msg)
    
    if not msg.tool_calls:
        # Final answer
        print(msg.content)
        break
    
    # Tool çağrılarını işle
    for tool_call in msg.tool_calls:
        func_name = tool_call.function.name
        func_args = json.loads(tool_call.function.arguments)
        
        if func_name == 'tc_kimlik_dogrula':
            result = tc_kimlik_dogrula(**func_args)
        elif func_name == 'e_fatura_sorgula':
            result = e_fatura_sorgula(**func_args)
        else:
            result = {'hata': f'Bilinmeyen tool: {func_name}'}
        
        messages.append({
            'role': 'tool',
            'tool_call_id': tool_call.id,
            'content': json.dumps(result, ensure_ascii=False),
        })
 
# Beklenen output:
# 'TC numarası 12345678901 geçersiz (kontrol algoritması başarısız). E-fatura ... onaylanmış, 1250.50 TL toplam...'