BizFirstAI Data Model Roadmap

Code Walkthrough

Overview

About This Documentation

This document provides a comprehensive walkthrough of all data models in the BizFirstAI conversation system. The models are designed to handle multi-agent conversations, tool calls, file management, and governance across distributed AI systems.

BizFirstAI 1.0 has a legacy data model. We are moving away from the previous structure to a more modular and flexible design. The conversion will take place in multiple phases

BizFirstAI 2.x design is aimed at multi-agent swarm intelligence, enabling seamless collaboration and communication between agents. Also autonomous agents will be able to manage their own state and interactions more effectively. Micro-payments, agent-rewards and payment modules, request and sender authentication and agent level accountability, metering, rate limiting and DID etc are target usescases of the new design.

Files covered: conversation.cs, ContentBlock.cs, Demo.cs

25+ Classes

Comprehensive data models covering the entire conversation lifecycle

5 Enums

Type-safe enumeration for roles, statuses, and visibility

Multi-Agent

Built for distributed AI agent interactions

Enums & Primitive Types

conversation.cs:6-33
MessageRole Enum

Purpose: Defines the role of message participants in conversations

Values:

System User Assistant Tool
Location: conversation.cs:8
RunStatus Enum

Purpose: Tracks the lifecycle status of AI run executions

Values:

Queued InProgress RequiresAction Interrupted Completed Failed Cancelled
Location: conversation.cs:10
ToolCallStatus Enum

Purpose: Status tracking for individual tool executions

Values:

Pending Running Succeeded Failed
Location: conversation.cs:11
Visibility & SchemaType Enums

Visibility: Access control levels

Public Private Internal

SchemaType: Tool schema formats

None OpenApi JsonSchema
Location: conversation.cs:9, 12
Usage Class - Token & Cost Tracking
conversation.cs:15-21

Purpose: Tracks usage and cost accounting for token-based AI providers

Properties:
  • int PromptTokens - Input tokens consumed
  • int CompletionTokens - Output tokens generated
  • int TotalTokens - Calculated total (read-only)
  • decimal? CostUsd - Optional cost in USD
Computed Property:
int TotalTokens => PromptTokens + CompletionTokens
ModelConfig Class - AI Model Configuration
conversation.cs:24-31

Purpose: Configures AI model selection and runtime parameters for execution runs

Properties:
  • string Provider - AI provider (openai, anthropic, google, azure, local) [default: "unknown"]
  • string Model - Specific model name [default: ""]
  • double? Temperature - Creativity/randomness setting (0.0-1.0)
  • int? MaxTokens - Maximum response length
  • Dictionary<string, object> SafetySettings - Provider-specific safety configs

Content Blocks - Typed Message Components

ContentBlock.cs:4-40
Inheritance Hierarchy:
ContentBlock (abstract base)
├── TextBlock (sealed)
├── FileBlock (sealed)
├── ToolCallBlock (sealed)
├── ToolResultBlock (sealed)
└── CitationBlock (sealed)
abstract ContentBlock - Base Content Component
ContentBlock.cs:4-8

Purpose: Abstract base class for all content types in messages

  • string ContentId - Unique identifier [auto-generated GUID]
  • DateTimeOffset Timestamp - Creation timestamp [auto: UtcNow]
sealed TextBlock
ContentBlock.cs:10-13

Purpose: Contains plain text content

Inherits: ContentId, Timestamp

  • string Text - The actual text content [default: ""]
sealed FileBlock
ContentBlock.cs:15-19

Purpose: References attached files with context

Inherits: ContentId, Timestamp

  • FileRef File - File reference object
  • string Purpose - Usage context: "input", "output", "context" [default: "context"]
sealed ToolCallBlock
ContentBlock.cs:21-26

Purpose: Represents a tool/function call request

Inherits: ContentId, Timestamp

  • string ToolCallId - Unique call identifier [auto-generated GUID]
  • string ToolName - Name of tool to invoke [default: ""]
  • Dictionary<string, object> Arguments - Tool parameters
sealed ToolResultBlock
ContentBlock.cs:28-33

Purpose: Contains the result of a tool execution

Inherits: ContentId, Timestamp

  • string ToolCallId - Links to original ToolCallBlock
  • object Result - Tool execution result (any type)
  • bool IsError - Error flag [default: false]
sealed CitationBlock
ContentBlock.cs:35-38

Purpose: Contains citations and references to source materials

Inherits: ContentId, Timestamp

  • List<Citation> Citations - List of citation objects with excerpts and locations

Files & Citations

conversation.cs:37-55
sealed FileRef - File Reference & Metadata
conversation.cs:37-47

Purpose: Comprehensive file metadata and storage reference

Identity & Metadata:
  • string FileId - Unique identifier [auto-generated GUID]
  • string Name - Original filename
  • string MimeType - Content type
  • long SizeBytes - File size in bytes
Storage & Security:
  • string Hash - Content hash (e.g. SHA256)
  • string StorageUri - Storage location (s3://, gs://, https://)
  • string OwnerAgentId - Uploading agent ID
  • DateTimeOffset UploadedAt - Upload timestamp [auto: UtcNow]
sealed Citation
conversation.cs:49-54

Purpose: Links content to source material

  • string FileId - References FileRef
  • string Excerpt - Quoted text snippet
  • string Location - Position reference (e.g. "page:4;offset:120")

Agent & Payment Models

conversation.cs:61-105
sealed Payment - Payment Tracking
conversation.cs:61-68

Purpose: Tracks payment methods and spending limits for agent services

  • string PaymentType - Type: "prepaid", "invoice", "card", "crypto" [default: ""]
  • decimal Amount - Payment amount [default: 0m]
  • string Currency - Currency code [default: "USD"]
  • decimal? MaxSpendLimit - Optional spending cap
  • string Hash - Payment token/hash for security
sealed Tool - Tool/Function Definition
conversation.cs:70-79

Purpose: Defines available tools/functions for agent execution

  • string ToolId - Unique identifier [auto-generated GUID]
  • string Name - Tool name [default: ""]
  • string Provider - Provider: "function", "http", "bedrock", "custom"
  • SchemaType SchemaType - Schema format type
  • string Schema - OpenAPI/JSON schema definition
  • bool RequiresApproval - Human-in-the-loop gate [default: false]
  • Dictionary<string, object> Metadata - Additional tool metadata
sealed AgentCapabilities
conversation.cs:81-86

Purpose: Defines what an agent can do and access

  • List<Tool> Tools - Available tools/functions
  • List<string> Scopes - ACL tags or data access permissions
  • Dictionary<string, object> Quotas - Rate limits (e.g. "rpm": 10, "tpm": 1000, "$": 100.0)
sealed AgentIdentity - Agent Profile
conversation.cs:88-96

Purpose: Complete agent identity and capabilities profile

  • string Id - Agent identifier [auto-generated GUID]
  • bool IdVerified - Identity verification status [default: false]
  • string IdType - ID system: "did", "user", "service", "operateID.com" [default: "did"]
  • List<Payment> Payments - Associated payment methods
  • string Summary - Agent description
  • AgentCapabilities Capabilities - Tools, scopes, and quotas
sealed AgentMetadata - Communication Metadata
conversation.cs:98-104

Purpose: Tracks communication protocol and routing information

  • string Sender - Sending agent ID
  • string Receiver - Receiving agent ID
  • string Protocol - Communication protocol: "http", "agent-proto", "websocket"
  • string Performative - Message intent: "request", "inform", "confirm"

Messages, Conversations & Events

conversation.cs:110-194
sealed ConversationEvent - Event Tracking
conversation.cs:110-117

Purpose: Records significant events in conversation lifecycle

  • string EventId - Unique event identifier [auto-generated GUID]
  • string Type - Event type: "Created", "Ended", "Archived", "Redacted", "CheckpointSaved"
  • DateTimeOffset Timestamp - Event time [auto: UtcNow]
  • string Actor - Who triggered the event: user/agent/system
  • Dictionary<string, object> Data - Additional event data
sealed Message - Core Message Object
conversation.cs:119-151

Purpose: Individual message with content, metadata, and event tracking

Core Properties:
  • string MessageId - Unique identifier [auto-generated GUID]
  • DateTimeOffset Timestamp - Creation time [auto: UtcNow]
  • MessageRole Role - Sender role [default: User]
  • string Language - Message language [default: "en"]
Threading:
  • string ReplyWith - Reply handling token
  • string InReplyTo - Reply target message
  • string ParentMessageId - Parent in thread
  • string ThreadId - Thread identifier
Content & Classification:
  • List<ContentBlock> Content - Message content blocks
  • List<string> BusinessClassificationIds - Business category tags
  • string Ontology - Content ontology/schema
Metadata & Tracking:
  • List<AgentMetadata> Agents - Agent communication info
  • List<ConversationEvent> Events - Message-level events
  • Usage Usage - Token and cost tracking
  • Dictionary<string, object> Metadata - Additional metadata
Methods:
void AddContentBlock(ContentBlock block)
Adds content and creates "ContentBlockAdded" event
void AddEvent(string type, Dictionary<string, object> data = null, string actor = "system")
Adds custom event to message
sealed Conversation - Conversation Container
conversation.cs:153-194

Purpose: Top-level container for multi-message conversations with governance

Identity & Timing:
  • string ConversationId - Unique identifier [auto-generated GUID]
  • DateTimeOffset StartedAt - Start time [auto: UtcNow]
  • DateTimeOffset? EndedAt - Optional end time
  • string Language - Primary language [default: "en"]
Classification:
  • string ThreadId - Thread grouping
  • List<string> BusinessClassificationIds - Business categories
  • string Ontology - Content schema
  • string Intent - Conversation purpose
  • string ActionType - Action classification
Access Control:
  • Visibility Visibility - Access level [default: Public]
  • List<string> AccessRoles - Allowed roles
System Configuration:
  • Dictionary<string, object> Limits - Operational limits
  • Dictionary<string, object> Auth - Auth status [default: "not-loggedin"]
  • Dictionary<string, object> Storage - Storage config [default: "persisted"]
Tenancy & Governance:
  • string TenantId - Multi-tenant identifier
  • string ProjectId - Project scope
  • string DataRegion - Data locality: "us", "eu", "ap"
Content:
  • List<ConversationEvent> Events - Conversation events
  • List<Message> Messages - All messages
Methods:
void AddEvent(string type, string actor = "system", Dictionary<string, object> data = null)
Adds event to conversation
void AddMessage(Message message)
Adds message and creates "MessageAdded" event
void EndConversation(string actor = "system")
Sets EndedAt and creates "ConversationEnded" event

Runs, ToolCalls, Checkpoints & Interrupts

conversation.cs:200-266
sealed ToolCall - Individual Tool Execution
conversation.cs:200-210

Purpose: Tracks execution of individual tools/functions

  • string ToolCallId - Unique call identifier [auto-generated GUID]
  • string Name - Tool name [default: ""]
  • Dictionary<string, object> Arguments - Input parameters
  • ToolCallStatus Status - Execution status [default: Pending]
  • object Result - Execution result (any type)
  • DateTimeOffset CreatedAt - Creation time [auto: UtcNow]
  • DateTimeOffset? CompletedAt - Completion time
  • string ErrorMessage - Error details if failed
sealed Run - AI Execution Session
conversation.cs:212-246

Purpose: Manages AI model execution with tool calls and state tracking

Identity & Status:
  • string RunId - Unique identifier [auto-generated GUID]
  • string ConversationId - Parent conversation
  • string TriggerMessageId - Message that started this run
  • RunStatus Status - Execution status [default: Queued]
Timing:
  • DateTimeOffset CreatedAt - Creation time [auto: UtcNow]
  • DateTimeOffset? StartedAt - Execution start
  • DateTimeOffset? EndedAt - Execution end
Execution Context:
  • ModelConfig Model - AI model configuration
  • List<ToolCall> ToolCalls - Executed tool calls
  • Usage Usage - Resource consumption
  • string Error - Error details if failed
Metadata & Control:
  • Dictionary<string, object> Metadata - Additional run data
  • bool RequiresAction - Human intervention needed [default: false]
Methods:
void Start()
Sets Status to InProgress and StartedAt to UtcNow
void End(RunStatus finalStatus = RunStatus.Completed)
Sets final status and EndedAt timestamp
ToolCall CreateToolCall(string name, Dictionary<string, object> args = null)
Creates and adds new ToolCall to this run
sealed Checkpoint
conversation.cs:248-256

Purpose: Saves execution state for resumption

  • string CheckpointId - Unique identifier [auto-generated GUID]
  • string ConversationId - Parent conversation
  • string RunId - Associated run
  • DateTimeOffset CreatedAt - Checkpoint time [auto: UtcNow]
  • string StateJson - Serialized state [default: ""]
  • string Node - Execution graph node [default: ""]
sealed Interrupt
conversation.cs:258-265

Purpose: Handles execution interrupts requiring human intervention

  • string InterruptId - Unique identifier [auto-generated GUID]
  • string RunId - Interrupted run
  • string Reason - Interrupt cause: "await_approval", "missing_param" [default: ""]
  • DateTimeOffset At - Interrupt time [auto: UtcNow]
  • string ResumeToken - Resumption token [auto-generated GUID]

Governance & Auditing

conversation.cs:271-290
sealed PolicyContext - Policy Configuration
conversation.cs:271-277

Purpose: Defines governance policies and compliance rules

  • bool PiiRedactionEnabled - Enable PII masking [default: false]
  • TimeSpan Retention - Data retention period [default: 30 days]
  • List<string> AllowedRegions - Permitted data regions
  • List<string> DisallowedTools - Blocked tool names
sealed AuditEntry - Audit Trail Record
conversation.cs:279-288

Purpose: Records all significant system actions for compliance

  • string AuditId - Unique identifier [auto-generated GUID]
  • DateTimeOffset Timestamp - Action time [auto: UtcNow]
  • string Actor - Who performed action: user/agent/system [default: ""]
  • string Action - Action type: "tool_call", "message_redacted", "policy_violation" [default: ""]
  • string ConversationId - Related conversation
  • string RunId - Related run
  • Dictionary<string, object> Data - Additional audit data

Demo Implementation Walkthrough

Demo.cs:6-91
Complete Usage Example

The Demo.cs file shows a complete example of how all these data models work together in a real conversation flow.

static class Program - Demo Implementation
Demo.cs:6-91

Purpose: Demonstrates complete conversation lifecycle with tool calls

Demo Flow Breakdown:
1. Agent & Tool Setup (Lines 12-25)
  • Creates search tool with JSON schema
  • Sets up agent identity with capabilities
3. User Message (Lines 33-40)
  • Creates user message with TextBlock
  • Adds message to conversation
5. Tool Execution (Lines 52-58)
  • Creates tool call with search parameters
  • Simulates execution and result
7. Cleanup & Audit (Lines 72-84)
  • Ends run and conversation
  • Creates audit entry
2. Conversation Setup (Lines 28-31)
  • Creates conversation with intent
  • Sets tenant and project IDs
4. Run Initialization (Lines 43-49)
  • Creates run linked to trigger message
  • Configures GPT-4.1 model
6. Assistant Response (Lines 61-69)
  • Creates assistant message
  • Adds ToolResultBlock with results
8. Console Output (Lines 86-89)
  • Prints conversation summary
  • Shows run status and results
Key Insights from Demo:
  • Model Integration: Shows how all models work together in practice
  • Event Tracking: Automatic event creation for content blocks and messages
  • Tool Lifecycle: Complete tool call lifecycle from creation to result
  • Multi-Agent: Demonstrates agent identity and capabilities
  • Governance: Audit trail creation for compliance