dataverse-python-agentic-workflows — правило для GitHub Copilot

# Dataverse SDK for Python - Agentic Workflows Guide

## ⚠️ PREVIEW FEATURE NOTICE

**Status**: This feature is in **Public Preview** as of December 2025  
**Availability**: General Availability (GA) date TBD  
**Documentation**: Complete implementation details forthcoming  

This guide covers the conceptual framework and planned capabilities for building agentic workflows with the Dataverse SDK for Python. Specific APIs and implementations may change before general availability.

---

## 1. Overview: Agentic Workflows with Dataverse

### What are Agentic Workflows?

Agentic workflows are autonomous, intelligent processes where:
- **Agents** make decisions and take actions based on data and rules
- **Workflows** orchestrate complex, multi-step operations
- **Dataverse** serves as the central source of truth for enterprise data

The Dataverse SDK for Python is designed to enable data scientists and developers to build these intelligent systems without .NET expertise.

### Key Capabilities (Planned)

The SDK is strategically positioned to support:

1. **Autonomous Data Agents** - Query, update, and evaluate data quality independently
2. **Form Prediction & Autofill** - Pre-fill forms based on data patterns and context
3. **Model Context Protocol (MCP)** Support - Enable standardized agent-to-tool communication
4. **Agent-to-Agent (A2A)** Collaboration - Multiple agents working together on complex tasks
5. **Semantic Modeling** - Natural language understanding of data relationships
6. **Secure Impersonation** - Run operations on behalf of specific users with audit trails
7. **Compliance Built-in** - Data governance and retention policies enforced

---

## 2. Architecture Patterns for Agentic Systems

### Multi-Agent Pattern
```python
# Conceptual pattern - specific APIs pending GA
class DataQualityAgent:
    """Autonomous agent that monitors and improves data quality."""
    
    def __init__(self, client):
        self.client = client
    
    async def evaluate_data_quality(self, table_name):
        """Evaluate data quality metrics for a table."""
        records = await self.client.get(table_name)
        
        metrics = {
            'total_records': len(records),
            'null_values': sum(1 for r in records if None in r.values()),
            'duplicate_records': await self._find_duplicates(table_name)
        }
        return metrics
    
    async def auto_remediate(self, issues):
        """Automatically fix identified data quality issues."""
        # Agent autonomously decides on remediation actions
        pass

class DataEnrichmentAgent:
    """Autonomous agent that enriches data from external sources."""
    
    async def enrich_accounts(self):
        """Enrich account data with market information."""
        accounts = await self.client.get("account")
        
        for account in accounts:
            enrichment = await self._lookup_market_data(account['name'])
            await self.client.update("account", account['id'], enrichment)
```

### Agent Orchestration Pattern
```python
# Conceptual pattern - specific APIs pending GA
class DataPipeline:
    """Orchestrates multiple agents working together."""
    
    def __init__(self, client):
        self.quality_agent = DataQualityAgent(client)
        self.enrichment_agent = DataEnrichmentAgent(client)
        self.sync_agent = SyncAgent(client)
    
    async def run(self, table_name):
        """Execute multi-agent workflow."""
        # Step 1: Quality check
        print("Running quality checks...")
        issues = await self.quality_agent.evaluate_data_quality(table_name)
        
        # Step 2: Enrich data
        print("Enriching data...")
        await self.enrichment_agent.enrich_accounts()
        
        # Step 3: Sync to external systems
        print("Syncing to external systems...")
        await self.sync_agent.sync_to_external_db(table_name)
```

---

## 3. Model Context Protocol (MCP) Support (Planned)

### What is MCP?

The Model Context Protocol (MCP) is an open standard for:
- **Tool Definition** - Describe what tools/capabilities are available
- **Tool Invocation** - Allow LLMs to call tools with parameters
- **Context Management** - Manage context between agent and tools
- **Error Handling** - Standardized error responses

### MCP Integration Pattern (Conceptual)

```python
# Conceptual pattern - specific APIs pending GA
from dataverse_mcp import DataverseMCPServer

# Define available tools
tools = [
    {
        "name": "query_accounts",
        "description": "Query accounts with filters",
        "parameters": {
            "filter": "OData filter expression",
            "select": "Columns to retrieve",
            "top": "Maximum records"
        }
    },
    {
        "name": "create_account",
        "description": "Create a new account",
        "parameters": {
            "name": "Account name",
            "credit_limit": "Credit limit amount"
        }
    },
    {
        "name": "update_account",
        "description": "Update account fields",
        "parameters": {
            "account_id": "Account GUID",
            "updates": "Dictionary of field updates"
        }
    }
]

# Create MCP server
server = DataverseMCPServer(client, tools=tools)

# LLMs can now use Dataverse tools
await server.handle_tool_call("query_accounts", {
    "filter": "creditlimit gt 100000",
    "select": ["name", "creditlimit"]
})
```

---

## 4. Agent-to-Agent (A2A) Collaboration (Planned)

### A2A Communication Pattern

```python
# Conceptual pattern - specific APIs pending GA
class DataValidationAgent:
    """Validates data before downstream agents process it."""
    
    async def validate_and_notify(self, data):
        """Validate data and notify other agents."""
        if await self._is_valid(data):
            # Publish event that other agents can subscribe to
            await self.publish_event("data_validated", data)
        else:
            await self.publish_event("validation_failed", data)

class DataProcessingAgent:
    """Waits for valid data from validation agent."""
    
    async def __init__(self):
        self.subscribe("data_validated", self.process_data)
    
    async def process_data(self, data):
        """Process already-validated data."""
        # Agent can safely assume data is valid
        result = await self._transform(data)
        await self.publish_event("processing_complete", result)
```

---

## 5. Building Autonomous Data Agents

### Data Quality Agent Example
```python
# Working example with current SDK features
from PowerPlatform.Dataverse.client import DataverseClient
from azure.identity import InteractiveBrowserCredential
import json

class DataQualityAgent:
    """Monitor and report on data quality."""
    
    def __init__(self, org_url, credential):
        self.client = DataverseClient(org_url, credential)
    
    def analyze_completeness(self, table_name, required_fields):
        """Analyze field completeness."""
        records = self.client.get(
            table_name,
            select=required_fields
        )
        
        missing_by_field = {field: 0 for field in required_fields}
        total = 0
        
        for page in records:
            for record in page:
                total += 1
                for field in required_fields:
                    if field not in record or record[field] is None:
                        missing_by_field[field] += 1
        
        # Calculate completeness percentage
        completeness = {
            field: ((total - count) / total * 100) 
            for field, count in missing_by_field.items()
        }
        
        return {
            'table': table_name,
            'total_records': total,
            'completeness': completeness,
            'missing_counts': missing_by_field
        }
    
    def detect_duplicates(self, table_name, key_fields):
        """Detect potential duplicate records."""
        records = self.client.get(table_name, select=key_fields)
        
        all_records = []
        for page in records:
            all_records.extend(page)
        
        seen = {}
        duplicates = []
        
        for record in all_records:
            key = tuple(record.get(f) for f in key_fields)
            if key in seen:
                duplicates.append({
                    'original_id': seen[key],
                    'duplicate_id': record.get('id'),
                    'key': key
                })
            else:
                seen[key] = record.get('id')
        
        return {
            'table': table_name,
            'duplicate_count': len(duplicates),
            'duplicates': duplicates
        }
    
    def generate_quality_report(self, table_name):
        """Generate comprehensive quality report."""
        completeness = self.analyze_completeness(
            table_name,
            ['name', 'telephone1', 'emailaddress1']
        )
        
        duplicates = self.detect_duplicates(
            table_name,
            ['name', 'emailaddress1']
        )
        
        return {
            'timestamp': pd.Timestamp.now().isoformat(),
            'table': table_name,
            'completeness': completeness,
            'duplicates': duplicates
        }

# Usage
client = DataverseClient("https://<org>.crm.dynamics.com", InteractiveBrowserCredential())
agent = DataQualityAgent("https://<org>.crm.dynamics.com", InteractiveBrowserCredential())

report = agent.generate_quality_report("account")
print(json.dumps(report, indent=2))
```

### Form Prediction Agent Example
```python
# Conceptual pattern using current SDK capabilities
from sklearn.ensemble import RandomForestRegressor
import pandas as pd

class FormPredictionAgent:
    """Predict and autofill form values."""
    
    def __init__(self, org_url, credential):
        self.client = DataverseClient(org_url, credential)
        self.model = None
    
    def train_on_historical_data(self, table_name, features, target):
        """Train prediction model on historical data."""
        # Collect training data
        records = []
        for page in self.client.get(table_name, select=features + [target]):
            records.extend(page)
        
        df = pd.DataFrame(records)
        
        # Train model
        X = df[features].fillna(0)
        y = df[target]
        
        self.model = RandomForestRegressor()
        self.model.fit(X, y)
        
        return self.model.score(X, y)
    
    def predict_field_values(self, table_name, record_id, features_data):
        """Predict missing field values."""
        if self.model is None:
            raise ValueError("Model not trained. Call train_on_historical_data first.")
        
        # Predict
        prediction = self.model.predict([features_data])[0]
        
        # Return prediction with confidence
        return {
            'record_id': record_id,
            'predicted_value': prediction,
            'confidence': self.model.score([features_data], [prediction])
        }
```

---

## 6. Integration with AI/ML Services

### LLM Integration Pattern
```python
# Using LLM to interpret Dataverse data
from openai import OpenAI

class DataInsightAgent:
    """Use LLM to generate insights from Dataverse data."""
    
    def __init__(self, org_url, credential, openai_key):
        self.client = DataverseClient(org_url, credential)
        self.llm = OpenAI(api_key=openai_key)
    
    def analyze_with_llm(self, table_name, sample_size=100):
        """Analyze data using LLM."""
        # Get sample data
        records = []
        count = 0
        for page in self.client.get(table_name):
            records.extend(page)
            count += len(page)
            if count >= sample_size:
                break
        
        # Create summary for LLM
        summary = f"""
        Table: {table_name}
        Total records sampled: {len(records)}
        
        Sample data:
        {json.dumps(records[:5], indent=2, default=str)}
        
        Provide insights about this data.
        """
        
        # Ask LLM
        response = self.llm.chat.completions.create(
            model="gpt-4",
            messages=[{"role": "user", "content": summary}]
        )
        
        return response.choices[0].message.content
```

---

## 7. Secure Impersonation & Audit Trails

### Planned Capabilities

The SDK will support running operations on behalf of specific users:

```python
# Conceptual pattern - specific APIs pending GA
from dataverse_security import ImpersonationContext

# Run as different user
with ImpersonationContext(client, user_id="user-guid"):
    # All operations run as this user
    client.create("account", {"name": "New Account"})
    # Audit trail: Created by [user-guid] at [timestamp]

# Retrieve audit trail
audit_log = client.get_audit_trail(
    table="account",
    record_id="record-guid",
    action="create"
)
```

---

## 8. Compliance and Data Governance

### Planned Governance Features

```python
# Conceptual pattern - specific APIs pending GA
from dataverse_governance import DataGovernance

# Define retention policy
governance = DataGovernance(client)
governance.set_retention_policy(
    table="account",
    retention_days=365
)

# Define data classification
governance.classify_columns(
    table="account",
    classifications={
        "name": "Public",
        "telephone1": "Internal",
        "creditlimit": "Confidential"
    }
)

# Enforce policies
governance.enforce_all_policies()
```

---

## 9. Current SDK Capabilities Supporting Agentic Workflows

While full agentic features are in preview, current SDK capabilities already support agent building:

### ✅ Available Now
- **CRUD Operations** - Create, retrieve, update, delete data
- **Bulk Operations** - Process large datasets efficiently
- **Query Capabilities** - OData and SQL for flexible data retrieval
- **Metadata Operations** - Work with table and column definitions
- **Error Handling** - Structured exception hierarchy
- **Pagination** - Handle large result sets
- **File Upload** - Manage document attachments

### 🔜 Coming in GA
- Full MCP integration
- A2A collaboration primitives
- Enhanced authentication/impersonation
- Governance policy enforcement
- Native async/await support
- Advanced caching strategies

---

## 10. Getting Started: Build Your First Agent Today

```python
from PowerPlatform.Dataverse.client import DataverseClient
from azure.identity import InteractiveBrowserCredential
import json

class SimpleDataAgent:
    """Your first Dataverse agent."""
    
    def __init__(self, org_url):
        credential = InteractiveBrowserCredential()
        self.client = DataverseClient(org_url, credential)
    
    def check_health(self, table_name):
        """Agent function: Check table health."""
        try:
            tables = self.client.list_tables()
            matching = [t for t in tables if t['LogicalName'] == table_name]
            
            if not matching:
                return {"status": "error", "message": f"Table {table_name} not found"}
            
            # Get record count
            records = []
            for page in self.client.get(table_name):
                records.extend(page)
                if len(records) > 1000:
                    break
            
            return {
                "status": "healthy",
                "table": table_name,
                "record_count": len(records),
                "timestamp": pd.Timestamp.now().isoformat()
            }
        
        except Exception as e:
            return {"status": "error", "message": str(e)}

# Usage
agent = SimpleDataAgent("https://<org>.crm.dynamics.com")
health = agent.check_health("account")
print(json.dumps(health, indent=2))
```

---

## 11. Resources & Documentation

### Official Documentation
- [Dataverse SDK for Python Overview](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/sdk-python/overview)
- [Working with Data](https://learn.microsoft.com/en-us/power-apps/developer/data-platform/sdk-python/work-data)
- [Release Plan: Agentic Workflows](https://learn.microsoft.com/en-us/power-platform/release-plan/2025wave2/data-platform/build-agentic-flows-dataverse-sdk-python)

### External Resources
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Azure AI Services](https://learn.microsoft.com/en-us/azure/ai-services/)
- [Python async/await](https://docs.python.org/3/library/asyncio.html)

### Repository
- [SDK Source Code](https://github.com/microsoft/PowerPlatform-DataverseClient-Python)
- [Issues & Feature Requests](https://github.com/microsoft/PowerPlatform-DataverseClient-Python/issues)

---

## 12. FAQ: Agentic Workflows

**Q: Can I use agents today with the current SDK?**  
A: Yes! Use the current capabilities to build agent-like systems. Full MCP/A2A support coming in GA.

**Q: What's the difference between current SDK and agentic features?**  
A: Current: Synchronous CRUD; Agentic: Async, autonomous decision-making, agent collaboration.

**Q: Will there be breaking changes from preview to GA?**  
A: Possibly. This is a preview feature; expect API refinements before general availability.

**Q: How do I prepare for agentic workflows today?**  
A: Build agents using current CRUD operations, design with async patterns in mind, use MCP specs for future compatibility.

**Q: Is there a cost difference for agentic features?**  
A: Unknown at this time. Check release notes closer to GA.

---

## 13. Next Steps

1. **Build a prototype** using current SDK capabilities
2. **Join preview** when MCP integration becomes available
3. **Provide feedback** via GitHub issues
4. **Watch for GA announcement** with full API documentation
5. **Migrate to full agentic** features when ready

The Dataverse SDK for Python is positioning itself as the go-to platform for building intelligent, autonomous data systems on the Microsoft Power Platform.