afv-library/skills/agentforce-grid/references/use-case-patterns.md

# Use Case Patterns Reference

Complete workflow examples for common Agentforce Grid use cases using MCP tool calls.

All tool calls use the MCP server prefix `mcp__grid-connect-mcp__`. For brevity, examples show just the tool name and parameters.

---

## Pattern 1: Agent Testing Pipeline

**Goal:** Test an agent with different utterances and evaluate responses.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Test Utterances | Text | Input test cases |
| 2 | Expected Responses | Text | Ground truth (optional) |
| 3 | Expected Topics | Text | Expected topic routing (optional) |
| 4 | Agent Output | AgentTest | Run agent |
| 5 | Response Match | Evaluation | Compare to expected |
| 6 | Topic Check | Evaluation | Verify topic routing |
| 7 | Quality Score | Evaluation | Assess coherence |

### Quick Path: setup_agent_test

For the most common case, use the all-in-one orchestration tool:

```
setup_agent_test({
  agentId: "0XxRM000000xxxxx",
  agentVersion: "0XyRM000000xxxxx",
  utterances: [
    "I need help resetting my password",
    "What's my account balance?",
    "Transfer me to a human"
  ],
  workbookName: "Agent Test Suite",
  worksheetName: "Sales Agent Tests",
  evaluationTypes: ["COHERENCE", "RESPONSE_MATCH", "TOPIC_ASSERTION"],
  expectedResponses: [
    "I can help you reset your password...",
    "Your account balance is...",
    "Let me transfer you..."
  ]
})
```

This single call creates the workbook, worksheet, Text columns, pastes data, adds the AgentTest column, and wires up evaluations.

### Step-by-Step Implementation (Manual)

Use this approach when you need more control over the pipeline.

**Step 1: Create Workbook and Worksheet**

```
create_workbook_with_worksheet({
  workbookName: "Agent Test Suite",
  worksheetName: "Sales Agent Tests"
})
// Returns: { workbookId, worksheetId, ... }
```

**Step 2: Add Text Column for Utterances**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Test Utterances",
  type: "Text",
  config: '{"name":"Test Utterances","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}'
})
```

**Step 3: Add Text Column for Expected Responses**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Expected Responses",
  type: "Text",
  config: '{"name":"Expected Responses","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}'
})
```

**Step 4: Add Text Column for Expected Topics**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Expected Topics",
  type: "Text",
  config: '{"name":"Expected Topics","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}'
})
```

**Step 5: Paste Test Data**

```
// First, get worksheet data to find row IDs
get_worksheet_data({ worksheetId: "{worksheetId}" })

// Paste utterances into the Text columns
paste_data({
  worksheetId: "{worksheetId}",
  startColumnId: "{utterances-column-id}",
  startRowId: "{first-row-id}",
  matrix: '[[{"displayContent":"I need help resetting my password"}],[{"displayContent":"What is my account balance?"}]]'
})
```

**Step 6: Add AgentTest Column**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Agent Output",
  type: "AgentTest",
  config: '{"name":"Agent Output","type":"AgentTest","config":{"type":"AgentTest","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"agentId":"0XxRM000000xxxxx","agentVersion":"0XyRM000000xxxxx","inputUtterance":{"columnId":"{utterances-column-id}","columnName":"Test Utterances","columnType":"Text"},"contextVariables":[]}}}'
})
```

**Step 7: Add Response Match Evaluation**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Response Match",
  type: "Evaluation",
  config: '{"name":"Response Match","type":"Evaluation","config":{"type":"Evaluation","queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"evaluationType":"RESPONSE_MATCH","inputColumnReference":{"columnId":"{agent-output-column-id}","columnName":"Agent Output","columnType":"AgentTest"},"referenceColumnReference":{"columnId":"{expected-responses-column-id}","columnName":"Expected Responses","columnType":"Text"},"autoEvaluate":true}}}'
})
```

**Step 8: Add Topic Assertion Evaluation**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Topic Check",
  type: "Evaluation",
  config: '{"name":"Topic Check","type":"Evaluation","config":{"type":"Evaluation","queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"evaluationType":"TOPIC_ASSERTION","inputColumnReference":{"columnId":"{agent-output-column-id}","columnName":"Agent Output","columnType":"AgentTest"},"referenceColumnReference":{"columnId":"{expected-topics-column-id}","columnName":"Expected Topics","columnType":"Text"},"autoEvaluate":true}}}'
})
```

**Step 9: Add Coherence Evaluation**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Quality Score",
  type: "Evaluation",
  config: '{"name":"Quality Score","type":"Evaluation","config":{"type":"Evaluation","queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"evaluationType":"COHERENCE","inputColumnReference":{"columnId":"{agent-output-column-id}","columnName":"Agent Output","columnType":"AgentTest"},"autoEvaluate":true}}}'
})
```

**Step 10: Monitor Processing**

```
poll_worksheet_status({
  worksheetId: "{worksheetId}",
  maxAttempts: 30,
  intervalMs: 3000
})
```

Or for a one-time status check:

```
get_worksheet_summary({ worksheetId: "{worksheetId}" })
```

---

## Pattern 2: Data Enrichment with AI

**Goal:** Enrich Salesforce Account records with AI-generated summaries.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Accounts | Object | Query Account records |
| 2 | Company Summary | AI | Generate summaries |

### Step-by-Step Implementation

**Step 1: Create Worksheet**

```
create_workbook_with_worksheet({
  workbookName: "Account Enrichment",
  worksheetName: "Tech Account Enrichment"
})
```

**Step 2: Add Object Column**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Accounts",
  type: "Object",
  config: '{"name":"Accounts","type":"Object","config":{"type":"Object","numberOfRows":50,"queryResponseFormat":{"type":"WHOLE_COLUMN","splitByType":"OBJECT_PER_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"objectApiName":"Account","fields":[{"name":"Id","type":"ID"},{"name":"Name","type":"STRING"},{"name":"Industry","type":"PICKLIST"},{"name":"Description","type":"TEXTAREA"},{"name":"AnnualRevenue","type":"CURRENCY"}],"filters":[{"field":"Industry","operator":"In","values":[{"value":"Technology","type":"STRING"},{"value":"Finance","type":"STRING"}]}]}}}'
})
```

**Step 3: Add AI Column**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Company Summary",
  type: "AI",
  config: '{"name":"Company Summary","type":"AI","config":{"type":"AI","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"mode":"llm","modelConfig":{"modelId":"sfdc_ai__DefaultGPT4Omni","modelName":"sfdc_ai__DefaultGPT4Omni"},"instruction":"Write a brief 2-3 sentence summary of this company based on the following information:\\n\\nCompany Name: {$1}\\nIndustry: {$2}\\nDescription: {$3}\\nAnnual Revenue: {$4}\\n\\nFocus on their market position and key business characteristics.","referenceAttributes":[{"columnId":"{accounts-column-id}","columnName":"Accounts","columnType":"Object","fieldName":"Name"},{"columnId":"{accounts-column-id}","columnName":"Accounts","columnType":"Object","fieldName":"Industry"},{"columnId":"{accounts-column-id}","columnName":"Accounts","columnType":"Object","fieldName":"Description"},{"columnId":"{accounts-column-id}","columnName":"Accounts","columnType":"Object","fieldName":"AnnualRevenue"}],"responseFormat":{"type":"PLAIN_TEXT","options":[]}}}}'
})
```

**Step 4: Monitor**

```
poll_worksheet_status({ worksheetId: "{worksheetId}" })
```

---

## Pattern 3: Prompt Template Batch Processing

**Goal:** Run a prompt template across a dataset and evaluate quality.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Customer Names | Text | Input data |
| 2 | Issues | Text | Input data |
| 3 | Generated Emails | PromptTemplate | Execute template |
| 4 | Coherence | Evaluation | Quality check |
| 5 | Completeness | Evaluation | Coverage check |

### Step-by-Step Implementation

**Step 1: Create Input Columns**

```
create_workbook_with_worksheet({
  workbookName: "Prompt Testing",
  worksheetName: "Email Generator"
})
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Customer Names",
  type: "Text",
  config: '{"name":"Customer Names","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}'
})
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Issues",
  type: "Text",
  config: '{"name":"Issues","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}'
})
```

**Step 2: Add PromptTemplate Column**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Generated Emails",
  type: "PromptTemplate",
  config: '{"name":"Generated Emails","type":"PromptTemplate","config":{"type":"PromptTemplate","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"promptTemplateDevName":"Customer_Support_Email","promptTemplateType":"flex","modelConfig":{"modelId":"sfdc_ai__DefaultGPT4Omni","modelName":"sfdc_ai__DefaultGPT4Omni"},"promptTemplateInputConfigs":[{"referenceName":"CustomerName","definition":"Customer name","referenceAttribute":{"columnId":"{customer-names-column-id}","columnName":"Customer Names","columnType":"Text"}},{"referenceName":"Issue","definition":"Customer issue","referenceAttribute":{"columnId":"{issues-column-id}","columnName":"Issues","columnType":"Text"}}]}}}'
})
```

**Step 3: Add Evaluation Columns**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Coherence",
  type: "Evaluation",
  config: '{"name":"Coherence","type":"Evaluation","config":{"type":"Evaluation","queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"evaluationType":"COHERENCE","inputColumnReference":{"columnId":"{generated-emails-column-id}","columnName":"Generated Emails","columnType":"PromptTemplate"},"autoEvaluate":true}}}'
})
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Completeness",
  type: "Evaluation",
  config: '{"name":"Completeness","type":"Evaluation","config":{"type":"Evaluation","queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"evaluationType":"COMPLETENESS","inputColumnReference":{"columnId":"{generated-emails-column-id}","columnName":"Generated Emails","columnType":"PromptTemplate"},"autoEvaluate":true}}}'
})
```

---

## Pattern 4: Flow/Apex Testing

**Goal:** Test a Flow with different inputs and extract outputs.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Subject | Text | Flow input |
| 2 | Description | Text | Flow input |
| 3 | Priority | Text | Flow input |
| 4 | Flow Result | InvocableAction | Execute Flow |
| 5 | Case Id | Reference | Extract output |
| 6 | Status | Reference | Extract output |

### Step-by-Step Implementation

**Step 1: Discover the Flow**

```
get_invocable_actions()
// Find the Flow you want to test

describe_invocable_action({
  actionName: "Create_Support_Case",
  actionType: "FLOW"
})
// Returns input/output schema
```

**Step 2: Create Input Columns**

```
create_workbook_with_worksheet({
  workbookName: "Flow Testing",
  worksheetName: "Create Case Tests"
})
```

```
add_column({ worksheetId: "{worksheetId}", name: "Subject", type: "Text",
  config: '{"name":"Subject","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}' })

add_column({ worksheetId: "{worksheetId}", name: "Description", type: "Text",
  config: '{"name":"Description","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}' })

add_column({ worksheetId: "{worksheetId}", name: "Priority", type: "Text",
  config: '{"name":"Priority","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}' })
```

**Step 3: Add InvocableAction Column**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Flow Result",
  type: "InvocableAction",
  config: '{"name":"Flow Result","type":"InvocableAction","config":{"type":"InvocableAction","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"actionInfo":{"actionType":"FLOW","actionName":"Create_Support_Case","url":"/services/data/v66.0/actions/custom/flow/Create_Support_Case","label":"Create Support Case"},"inputPayload":"{\\\"Subject\\\": \\\"{$1}\\\", \\\"Description\\\": \\\"{$2}\\\", \\\"Priority\\\": \\\"{$3}\\\"}","referenceAttributes":[{"columnId":"{subject-column-id}","columnName":"Subject","columnType":"Text"},{"columnId":"{description-column-id}","columnName":"Description","columnType":"Text"},{"columnId":"{priority-column-id}","columnName":"Priority","columnType":"Text"}]}}}'
})
```

**Step 4: Add Reference Columns to Extract Outputs**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Case Id",
  type: "Reference",
  config: '{"name":"Case Id","type":"Reference","config":{"type":"Reference","queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"referenceColumnId":"{flow-result-column-id}","referenceField":"outputValues.caseId"}}}'
})
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Status",
  type: "Reference",
  config: '{"name":"Status","type":"Reference","config":{"type":"Reference","queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"referenceColumnId":"{flow-result-column-id}","referenceField":"outputValues.status"}}}'
})
```

---

## Pattern 5: Multi-Turn Agent Conversation Testing

**Goal:** Test multi-turn conversations with conversation history.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Turn 1 Utterance | Text | First user message |
| 2 | Turn 1 Response | Agent | First agent response |
| 3 | Turn 2 Utterance | Text | Follow-up message |
| 4 | Turn 2 Response | Agent | Second response with history |

### Implementation

**Step 1: Create First Turn**

```
add_column({ worksheetId: "{worksheetId}", name: "Turn 1 Utterance", type: "Text",
  config: '{"name":"Turn 1 Utterance","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}' })
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Turn 1 Response",
  type: "Agent",
  config: '{"name":"Turn 1 Response","type":"Agent","config":{"type":"Agent","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"agentId":"0XxRM000000xxxxx","agentVersion":"0XyRM000000xxxxx","utterance":"{$1}","utteranceReferences":[{"columnId":"{turn1-utterance-id}","columnName":"Turn 1 Utterance","columnType":"Text"}]}}}'
})
```

**Step 2: Create Second Turn with History**

```
add_column({ worksheetId: "{worksheetId}", name: "Turn 2 Utterance", type: "Text",
  config: '{"name":"Turn 2 Utterance","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}' })
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Turn 2 Response",
  type: "Agent",
  config: '{"name":"Turn 2 Response","type":"Agent","config":{"type":"Agent","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"agentId":"0XxRM000000xxxxx","agentVersion":"0XyRM000000xxxxx","utterance":"{$1}","utteranceReferences":[{"columnId":"{turn2-utterance-id}","columnName":"Turn 2 Utterance","columnType":"Text"}],"conversationHistory":{"columnId":"{turn1-response-id}","columnName":"Turn 1 Response","columnType":"Agent","fieldName":"conversationHistory"}}}}'
})
```

---

## Pattern 6: AI Classification with Single Select

**Goal:** Classify text into categories using AI.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Customer Feedback | Text | Input text |
| 2 | Sentiment | AI | Classification |
| 3 | Category | AI | Classification |

### Implementation

```
add_column({ worksheetId: "{worksheetId}", name: "Customer Feedback", type: "Text",
  config: '{"name":"Customer Feedback","type":"Text","config":{"type":"Text","autoUpdate":true,"config":{"autoUpdate":true}}}' })
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Sentiment",
  type: "AI",
  config: '{"name":"Sentiment","type":"AI","config":{"type":"AI","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"mode":"llm","modelConfig":{"modelId":"sfdc_ai__DefaultGPT4Omni","modelName":"sfdc_ai__DefaultGPT4Omni"},"instruction":"Classify the sentiment of this customer feedback: {$1}","referenceAttributes":[{"columnId":"{feedback-column-id}","columnName":"Customer Feedback","columnType":"Text"}],"responseFormat":{"type":"SINGLE_SELECT","options":[{"label":"Positive","value":"positive"},{"label":"Negative","value":"negative"},{"label":"Neutral","value":"neutral"}]}}}}'
})
```

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Category",
  type: "AI",
  config: '{"name":"Category","type":"AI","config":{"type":"AI","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"mode":"llm","modelConfig":{"modelId":"sfdc_ai__DefaultGPT4Omni","modelName":"sfdc_ai__DefaultGPT4Omni"},"instruction":"Categorize this customer feedback: {$1}","referenceAttributes":[{"columnId":"{feedback-column-id}","columnName":"Customer Feedback","columnType":"Text"}],"responseFormat":{"type":"SINGLE_SELECT","options":[{"label":"Product Issue","value":"product"},{"label":"Service Issue","value":"service"},{"label":"Billing Issue","value":"billing"},{"label":"Feature Request","value":"feature"},{"label":"General Inquiry","value":"general"}]}}}}'
})
```

---

## Pattern 7: Data Cloud / DMO Enrichment

**Goal:** Query Data Cloud DMOs and enrich with AI-generated insights.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Unified Profiles | DataModelObject | Query DMO records |
| 2 | Profile Summary | AI | Generate insights |

### Step-by-Step Implementation

**Step 1: Discover Data Cloud Schema**

```
get_dataspaces()
// Returns: { dataspaces: [{ name: "default", label: "Default Dataspace" }] }

get_data_model_objects({ dataspace: "default" })
// Returns available DMOs in the dataspace

get_data_model_object_fields({ dataspace: "default", dmoName: "UnifiedIndividual__dlm" })
// Returns field definitions for the DMO
```

**Step 2: Create Workbook and Worksheet**

```
create_workbook_with_worksheet({
  workbookName: "Data Cloud Analysis",
  worksheetName: "Unified Profiles"
})
```

**Step 3: Add DataModelObject Column**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Unified Profiles",
  type: "DataModelObject",
  config: '{"name":"Unified Profiles","type":"DataModelObject","config":{"type":"DataModelObject","numberOfRows":50,"queryResponseFormat":{"type":"WHOLE_COLUMN","splitByType":"OBJECT_PER_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"dataModelObjectApiName":"UnifiedIndividual__dlm","dataspaceName":"default","fields":[{"name":"Id__c","type":"string"},{"name":"FirstName__c","type":"string"},{"name":"LastName__c","type":"string"},{"name":"Email__c","type":"string"}]}}}'
})
```

**Step 4: Add AI Enrichment Column**

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Profile Summary",
  type: "AI",
  config: '{"name":"Profile Summary","type":"AI","config":{"type":"AI","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"mode":"llm","modelConfig":{"modelId":"sfdc_ai__DefaultGPT4Omni","modelName":"sfdc_ai__DefaultGPT4Omni"},"instruction":"Create a brief customer profile summary:\\nName: {$1} {$2}\\nEmail: {$3}","referenceAttributes":[{"columnId":"{profiles-column-id}","columnName":"Unified Profiles","columnType":"DataModelObject","fieldName":"FirstName__c"},{"columnId":"{profiles-column-id}","columnName":"Unified Profiles","columnType":"DataModelObject","fieldName":"LastName__c"},{"columnId":"{profiles-column-id}","columnName":"Unified Profiles","columnType":"DataModelObject","fieldName":"Email__c"}],"responseFormat":{"type":"PLAIN_TEXT","options":[]}}}}'
})
```

---

## Pattern 8: List View Import

**Goal:** Import records from a Salesforce List View and enrich them.

### Column Setup

| Order | Column Name | Type | Purpose |
|-------|-------------|------|---------|
| 1 | Records | Object | Import via List View SOQL |
| 2 | Enrichment | AI | Process the records |

### Step-by-Step Implementation

**Step 1: Discover List Views**

```
get_list_views()
// Returns available list views with IDs

get_list_view_soql({
  listViewId: "{listViewId}",
  sObjectType: "Account"
})
// Returns: { soql: "SELECT Id, Name, ... FROM Account WHERE ..." }
```

**Step 2: Create Object Column with advancedMode**

Use the SOQL from the list view directly in an Object column's advanced mode:

```
add_column({
  worksheetId: "{worksheetId}",
  name: "List View Records",
  type: "Object",
  config: '{"name":"List View Records","type":"Object","config":{"type":"Object","numberOfRows":50,"queryResponseFormat":{"type":"WHOLE_COLUMN","splitByType":"OBJECT_PER_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"objectApiName":"Account","advancedMode":{"type":"SOQL","inputs":{"queryString":"SELECT Id, Name, Industry, Description FROM Account WHERE Industry = \'Technology\' LIMIT 50"}}}}}'
})
```

---

## Pattern 9: Draft Agent Testing

**Goal:** Test an unpublished (draft) agent before deploying it.

### Step-by-Step Implementation

**Step 1: Discover Draft Agents and Their Topics**

```
get_agents({ includeDrafts: true })
// Returns agents including drafts; draft agents have activeVersion but no published version

get_draft_topics({
  config: '{"id": "0XxRM000000xxxxx", "name": "My Draft Agent"}'
})
// Returns topic definitions for the draft agent

get_draft_context_variables({
  config: '{"id": "0XxRM000000xxxxx", "name": "My Draft Agent"}'
})
// Returns context variables the draft agent expects
```

**Step 2: Set Up the Test Using setup_agent_test with isDraft**

```
setup_agent_test({
  agentId: "0XxRM000000xxxxx",
  agentVersion: "0XyRM000000xxxxx",
  utterances: [
    "Test utterance for draft agent",
    "Another test case"
  ],
  workbookName: "Draft Agent Tests",
  worksheetName: "Pre-Deploy Validation",
  evaluationTypes: ["COHERENCE", "TOPIC_ASSERTION"],
  expectedResponses: ["Expected topic 1", "Expected topic 2"],
  isDraft: true
})
```

**Step 3: Or Build Manually with isDraft Flag**

When adding an AgentTest column manually, set `isDraft: true` in the inner config:

```
add_column({
  worksheetId: "{worksheetId}",
  name: "Draft Agent Output",
  type: "AgentTest",
  config: '{"name":"Draft Agent Output","type":"AgentTest","config":{"type":"AgentTest","numberOfRows":50,"queryResponseFormat":{"type":"EACH_ROW"},"autoUpdate":true,"config":{"autoUpdate":true,"agentId":"0XxRM000000xxxxx","agentVersion":"0XyRM000000xxxxx","inputUtterance":{"columnId":"{utterance-col-id}","columnName":"Utterances","columnType":"Text"},"contextVariables":[],"isDraft":true,"enableSimulationMode":false}}}'
})
```

**Step 4: Monitor and Compare**

```
poll_worksheet_status({ worksheetId: "{worksheetId}" })

// Once complete, review results
get_worksheet_summary({ worksheetId: "{worksheetId}" })
```

---

## Best Practices

### Column Ordering

1. **Input columns first** -- Text, Object columns that provide data
2. **Processing columns next** -- Agent, AI, PromptTemplate, InvocableAction
3. **Extraction columns** -- Reference columns to pull specific fields
4. **Evaluation columns last** -- Depend on processing columns

### Reference Management

- Always use the exact column ID returned from the `add_column` response
- Use `fieldName` in ReferenceAttribute to extract specific fields from JSON
- For Object columns, `fieldName` specifies which SObject field to use

### Error Handling

- Check column status via `get_worksheet_summary` after processing
- Use `reprocess_column` to retry failed cells
- Use `get_worksheet_data` and inspect cell `statusMessage` for error details

### State Refresh

- After any mutation (add_column, paste_data, trigger_row_execution), call `get_worksheet_data` to get updated IDs and statuses
- Use `poll_worksheet_status` for long-running operations instead of manual polling