[I-01] Function Calling / Tool Use — IToolProvider + AIFunction integration via Microsoft.Extensions.AI

[techbuzzz]

Overview

Version: v10.4.0 Intelligence & DX
Effort: L · 5–8 days
Branch: feature/i01-function-calling

Enable council members to call external tools (functions) during their debate turns, using the AIFunction abstraction from Microsoft.Extensions.AI.

---

Background

Currently council members only reason and respond with text. In many real-world scenarios (code review, requirements analysis, risk assessment) members need to query external systems — check a database, call an API, run a linter, search documentation. Tool use closes this gap.

---

Design

Core Interface

public interface IToolProvider
{
    IReadOnlyList<AIFunction> GetTools();
}

CouncilBuilder Integration

// Global tools available to all members
councilBuilder.WithTools(IToolProvider toolProvider);
councilBuilder.WithTools(params AIFunction[] functions);

// Per-member tools
councilBuilder.AddMember("Reviewer", provider, systemPrompt,
    tools: new[] { searchCodeTool, lintTool });

Execution Flow

1. Member generates response with tool call request (via AIFunctionCallContent)
2. CouncilExecutor detects tool call in response
3. Executor invokes AIFunction with provided arguments
4. Tool result appended to member's context as AIFunctionResultContent
5. Member generates final response incorporating tool result
6. DebateRound includes ToolCallLog entries

Result Additions

public record ToolCallLog
{
    public string MemberRole { get; init; }
    public string FunctionName { get; init; }
    public string Arguments { get; init; }   // JSON
    public string Result { get; init; }       // JSON
    public TimeSpan Duration { get; init; }
    public bool Success { get; init; }
}

// DebateRound gains:
public IReadOnlyList<ToolCallLog> ToolCalls { get; init; }

Built-in Tool Providers

Provider	Description
FileSystemToolProvider	Read files, list directories (sandboxed to a root path)
HttpToolProvider	HTTP GET/POST to configured endpoints
McpToolProvider	Wrap any MCP (Model Context Protocol) server as tools

---

Tasks

• Define IToolProvider in Delibera.Core.Interfaces
• Implement tool call detection loop in CouncilExecutor.ExecuteMemberTurnAsync
• Add WithTools() to ICouncilBuilder and CouncilBuilder
• Add per-member tool support to CouncilMember
• Add ToolCallLog to DebateRound
• Implement FileSystemToolProvider
• Implement HttpToolProvider
• Implement McpToolProvider (delegates to existing IOperator bridge)
• Handle tool call errors gracefully (log + continue, don't abort debate)
• Respect WithTimeout — tool calls count against overall debate timeout
• OpenTelemetry: add ToolCallExecute span
• Add ToolCallExample.cs in Delibera.Examples
• Update Delibera.Server — DebateRequest gains Tools collection
• Docs: docs/tool-use.md with architecture diagram and examples

---

Acceptance Criteria

• CouncilBuilder.WithTools(...) compiles and works end-to-end
• Tool call logs appear in DebateRound.ToolCalls
• Tool errors do not abort the debate (graceful degradation)
• FileSystemToolProvider and HttpToolProvider work in examples
• McpToolProvider bridges correctly to existing IOperator implementations
• OpenTelemetry span ToolCallExecute emitted for each call
• Example ToolCallExample.cs runs successfully
• Unit tests for tool call loop, error handling, timeout propagation

Labels

enhancement, v10.4.0, AI