Step 4 of 16

Function Tools and Structured Output

text

Create typed function tools, write useful descriptions, validate inputs, and return structured data.

ต่อ agent เข้ากับ application code ผ่าน contract ขนาดเล็ก พร้อม validation และ typed output ครับ

Function Tools and Structured Output

Level: Intermediate

Agent ตอบจาก model ได้ แต่ยังอ่านข้อมูลของระบบเราไม่ได้ครับ Function tool คือ contract ที่เปิด application capability ให้ model เลือกเรียก โดย Description มีผลต่อการเลือก tool และการสร้าง arguments

Outcome

เพิ่ม read-only tool หนึ่งตัวที่เรียก application service ผ่าน typed input/output และมี contract tests ครับ

Create a Read-only Tool

using System.ComponentModel;
using Microsoft.Extensions.AI;

[Description("Find one handbook section by its stable section ID.")]
static HandbookSection? FindSection(
    [Description("Stable ID such as deploy-health-checks")] string sectionId)
{
    var sections = new Dictionary<string, HandbookSection>
    {
        ["deploy-health-checks"] = new(
            "deploy-health-checks",
            "Expose readiness and liveness endpoints.")
    };

    return sections.GetValueOrDefault(sectionId);
}

record HandbookSection(string Id, string Text);

ลงทะเบียน tool ตอนสร้าง agent:

AIAgent agent = projectClient.AsAIAgent(
    model: model,
    instructions: "Use handbook tools when a section ID is available.",
    tools: [AIFunctionFactory.Create(FindSection)]);

เริ่มจาก read-only tool ที่ deterministic ก่อนครับ Tool ควร validate input, รองรับ cancellation สำหรับ I/O, คืนข้อมูลขนาดเล็ก และโยน typed exception ที่ middleware แปลงเป็น safe error ได้ อย่าส่ง database entity ทั้งก้อนกลับไปหา model

Use Structured Output at Boundaries

ถ้าคำตอบต้องถูกใช้ต่อใน code ให้กำหนด record แทนการ parse prose:

record DeploymentAdvice(
    string Summary,
    IReadOnlyList<string> Checks,
    string RiskLevel);

Structured output ช่วยลด parsing error แต่ยังต้อง validate ค่าทาง business เช่น RiskLevel และจำนวนรายการครับ Schema validation ไม่ได้แทน authorization หรือ domain rule

Tool Contract Checklist

ชื่อบอก action ชัด
description ระบุขอบเขตและข้อจำกัด
arguments มี type และ validation
output เล็กและไม่มี secret
retry เฉพาะ operation ที่ idempotent
มี timeout, metric และ audit event

Tool handler ต้องรับ identity จาก trusted runtime context ไม่ใช่ parameter ที่ model สร้างครับ เช่น tenantId ควรมาจาก authenticated request และถูกส่งผ่าน AgentRunOptions.AdditionalProperties หรือ middleware

Verify

สร้าง contract tests สำหรับ valid input, unknown ID, forbidden tenant, timeout และ cancellation จากนั้น run prompt matrix ที่ควรเรียก tool, ไม่ควรเรียก tool และส่ง arguments ผิดรูปแบบครับ บันทึก tool name กับ sanitized outcome โดยไม่เก็บ sensitive payload

Production Gate

ใช้ allow-list ต่อ agent role
จำกัด payload และ execution time
ใช้ idempotency key สำหรับ write tool
แยก domain validation ออกจาก model instructions
ไม่ expose infrastructure exception ให้ model หรือ client

Deliverable

ส่ง tool contract, handler, registration, automated tests และ metric สำหรับ call count, latency กับ failures

บทถัดไปจะวาง approval gate หน้า tool ที่สร้าง side effect ครับ

References

View on GitHub

Sessions and Persistence

Human Approval and Middleware

Function Tools and Structured Output

Level: Intermediate

Create a Read-only Tool

using System.ComponentModel; using Microsoft.Extensions.AI; [Description("Find one handbook section by its stable section ID.")] static HandbookSection? FindSection( [Description("Stable ID such as deploy-health-checks")] string sectionId) { var sections = new Dictionary<string, HandbookSection> { ["deploy-health-checks"] = new( "deploy-health-checks", "Expose readiness and liveness endpoints.") }; return sections.GetValueOrDefault(sectionId); } record HandbookSection(string Id, string Text);

ลงทะเบียน tool ตอนสร้าง agent:

AIAgent agent = projectClient.AsAIAgent( model: model, instructions: "Use handbook tools when a section ID is available.", tools: [AIFunctionFactory.Create(FindSection)]);

Use Structured Output at Boundaries

ถ้าคำตอบต้องถูกใช้ต่อใน code ให้กำหนด record แทนการ parse prose:

record DeploymentAdvice( string Summary, IReadOnlyList<string> Checks, string RiskLevel);

Tool Contract Checklist

ชื่อบอก action ชัด

description ระบุขอบเขตและข้อจำกัด

arguments มี type และ validation

output เล็กและไม่มี secret

retry เฉพาะ operation ที่ idempotent

มี timeout, metric และ audit event

Verify