kris/afv-library
1
0
Fork 0
mirror of https://github.com/forcedotcom/afv-library.git synced 2026-07-30 03:09:50 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat: add agentforce-grid skill

Browse Source 
Adds the Agentforce Grid (AI Workbench) skill for spreadsheet-like AI
operations in Salesforce — agent testing with utterances, batch prompt
processing, AI-driven data enrichment, and evaluation columns.

Covers the /services/data/v66.0/public/grid/ Connect API and 12 column
types (AI, Agent, AgentTest, Evaluation, Formula, Object,
DataModelObject, PromptTemplate, InvocableAction, Action, Reference,
Text).

Skill previously lived at git.soma.salesforce.com/tmcgrath/agentforce-grid-ai-skills
and github.com/Agentforce-emu/agentforce-grid-skills.
This commit is contained in:
Marzi Golbaz 2026-07-01 16:21:30 -07:00
parent a9a77002cb
commit 31d36f5210
6 changed files with 4727 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

298
skills/agentforce-grid/SKILL.md Normal file
View File

@ -0,0 +1,298 @@
---
name: agentforce-grid
description: "Use for Agentforce Grid (AI Workbench) — the spreadsheet-like interface for AI operations in Salesforce. ALWAYS use this skill when the user wants to: test or evaluate an Agentforce agent with utterances; create workbooks, worksheets, or columns; enrich Salesforce records with AI-generated content; add AI columns (SINGLE_SELECT, PLAIN_TEXT), Formula columns, Object columns, Evaluation columns, or Reference columns; import CSV data; compare agent versions; debug column config errors; query SObjects or Data Cloud in a grid; run evaluations (coherence, topic assertion, response match); or use any mcp__grid-connect__ tools. Covers the Grid Connect API for all column CRUD, cell operations, agent testing pipelines, and batch processing. Skip for standalone Apex, Flows, dashboards, reports, validation rules, or Einstein Bots that don't involve Grid."
---
# Agentforce Grid Skill
Agentforce Grid (AI Workbench) is a spreadsheet-like interface for AI operations in Salesforce. Worksheets contain typed columns that query data, run agents, generate AI content, and evaluate outputs.
**Hierarchy:** Workbook > Worksheet > Columns > Rows > Cells
> **Note:** The MCP tool surface is being consolidated from ~65 tools to ~15. Tool names below reflect the current state. If a tool is not found, check `get_supported_types` or `get_column_types` for alternatives.
## Before You Act (Mandatory Checklist)
Run this checklist before creating or suggesting any column:
1. **Read current grid state** -- call `get_worksheet_data` to see all existing columns, their IDs, and cell data
2. **Check for duplicates** -- does a column with the same name or purpose already exist? If so, suggest editing it (`edit_ai_prompt`, `edit_column`) instead of creating a new one
3. **Verify all referenced column IDs exist** -- every `columnId` in `referenceAttributes`, `inputColumnReference`, or `referenceColumnReference` MUST come from the current grid state. NEVER hallucinate column IDs or reference columns that do not exist yet
4. **Confirm column type matches the task** -- use the decision table below
5. **Confirm response format matches the use case** -- SINGLE_SELECT for filtering/sorting, PLAIN_TEXT for free-form content
6. **Check dependency order** -- source columns must exist before processing columns that reference them
7. **Check available resources** -- call `get_prompt_templates` or `get_invocable_actions` before creating an AI column that could be handled by existing platform capabilities
## Column Types
| Type | `type` value | Use Case |
|------|-------------|----------|
| AI | `"AI"` | LLM text generation with custom prompts |
| Agent | `"Agent"` | Run agent conversations |
| AgentTest | `"AgentTest"` | Batch-test agent with utterances |
| Evaluation | `"Evaluation"` | Evaluate agent/prompt outputs (13 types) |
| Formula | `"Formula"` | Deterministic computed values |
| Object | `"Object"` | Query Salesforce SObjects |
| DataModelObject | `"DataModelObject"` | Query Data Cloud DMOs |
| PromptTemplate | `"PromptTemplate"` | Execute GenAI prompt templates |
| InvocableAction | `"InvocableAction"` | Execute Flows or Apex |
| Action | `"Action"` | Execute platform actions |
| Reference | `"Reference"` | Extract fields via JSON path |
| Text | `"Text"` | Static/editable text or CSV import |
**Casing:** Server is case-insensitive. PascalCase and UPPER_CASE both work. API returns vary by context.
For complete JSON configs: [Column Configs Reference](references/column-configs.md)
## Choosing the Right Column Type
| Need | Type | Format | Why |
|------|------|--------|-----|
| Categorize/filter/sort | AI | SINGLE_SELECT | Limited options enable filtering and scanning |
| Generate free-text (email, summary) | AI | PLAIN_TEXT | Open-ended content needs free-form output |
| Deterministic computation | Formula | N/A | No LLM needed, exact and reproducible |
| Extract field from JSON/Object | Reference | N/A | Zero LLM cost, exact extraction |
| Score/rate on a scale | AI | SINGLE_SELECT | e.g., High/Medium/Low for scannable output |
| Task already handled by a prompt template | PromptTemplate | N/A | Pre-built, tested, maintained by the org |
| Task already handled by a Flow | InvocableAction | N/A | Deterministic logic, no LLM cost |
**Key principle:** If output is used for filtering, sorting, or downstream comparison, use SINGLE_SELECT. Free-text defeats scanability. If a platform capability (prompt template, Flow, list view) already does the job, prefer it over AI.
## Role-Aware Suggestions
Before suggesting columns, understand the user's role and intent. Ask if unclear.
| Role | Common Needs | Pipeline Pattern |
|------|-------------|------------------|
| Sales Rep | Deal risk, competitive intel, account priority | Object(Opps) -> AI(risk, SINGLE_SELECT) |
| CSM | Customer health, check-in emails | Object(Accounts/Cases) -> AI(analysis) -> AI(email, PLAIN_TEXT) |
| RevOps | Pipeline quality, data hygiene flags | Object(Opps) -> AI(quality flag, SINGLE_SELECT: Clean/Minor Issues/Needs Fix) |
| Dev/QA | Agent testing, flow testing | Text(utterances) -> AgentTest -> Evaluation |
| Admin | Data enrichment, bulk updates | Object/ListView -> AI -> Action(RecordUpdate) |
A RevOps user needs data quality flags (SINGLE_SELECT), not outreach emails. A CSM needs customer-facing outputs, not pipeline metrics.
## Evaluation Types
| Type | Needs Reference Column | Supported Inputs |
|------|----------------------|------------------|
| COHERENCE | No | Agent, AgentTest, PromptTemplate |
| CONCISENESS | No | Agent, AgentTest, PromptTemplate |
| FACTUALITY | No | Agent, AgentTest, PromptTemplate |
| INSTRUCTION_FOLLOWING | No | Agent, AgentTest, PromptTemplate |
| COMPLETENESS | No | Agent, AgentTest, PromptTemplate |
| RESPONSE_MATCH | **Yes** | Agent, AgentTest |
| TOPIC_ASSERTION | **Yes** | Agent, AgentTest |
| ACTION_ASSERTION | **Yes** | Agent, AgentTest |
| LATENCY_ASSERTION | No | Agent, AgentTest |
| BOT_RESPONSE_RATING | **Yes** | Agent, AgentTest |
| EXPRESSION_EVAL | No | Agent, AgentTest |
| CUSTOM_LLM_EVALUATION | **Yes** | Agent, AgentTest |
| TASK_RESOLUTION | No | Agent, AgentTest (conversation-level) |
For complete evaluation guidance: [Evaluation Types Reference](references/evaluation-types.md)
## Dependency Rules
Column creation must follow the dependency DAG. A column CANNOT reference a column that does not yet exist or that depends on it.
1. **Source data** (Text, Object, DataModelObject) -- no dependencies
2. **Processing** (AI, Agent, AgentTest, PromptTemplate, InvocableAction) -- depend on source
3. **Extraction** (Reference) -- depends on processing columns
4. **Assessment** (Evaluation) -- depends on Agent/AgentTest/PromptTemplate
5. **Formula** -- any level, but must only reference existing columns
**Always create columns sequentially.** Each `add_column` returns the new column ID needed by subsequent columns. Parallel creation leads to missing IDs and unpredictable ordering.
## Leverage Existing Resources
Before creating an AI column, check if platform capabilities handle the task:
1. `get_prompt_templates` -- use PromptTemplate column for pre-built prompts
2. `get_invocable_actions` -- use InvocableAction column for deterministic logic
3. `get_list_views` -- use list view SOQL in Object column's advancedMode
4. Existing columns -- use Reference column to extract data already present
AI columns should be reserved for tasks requiring LLM reasoning.
## Critical Config Rules
**Nested config structure (REQUIRED for ALL column types):**
```json
{
"name": "Column Name",
"type": "AI",
"config": {
"type": "AI",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true
}
}
}
```
Even Text columns need `type` inside config. An empty `config: {}` will fail.
**queryResponseFormat:** Use `EACH_ROW` when adding a column to a worksheet that already has data. Use `WHOLE_COLUMN` with `splitByType: "OBJECT_PER_ROW"` only when importing new records (Object/DataModelObject).
**modelConfig:** Use the model `name` for both `modelId` and `modelName`. Call `get_llm_models` to list available models. Default: `sfdc_ai__DefaultGPT4Omni`.
**AI columns:** Require `mode: "llm"`, `responseFormat` with `options` array (empty `[]` for PLAIN_TEXT).
**Evaluation columns:** Types requiring reference columns (RESPONSE_MATCH, TOPIC_ASSERTION, ACTION_ASSERTION, BOT_RESPONSE_RATING, CUSTOM_LLM_EVALUATION) must include `referenceColumnReference`.
For complete JSON configs for all 12 types: [Column Configs Reference](references/column-configs.md)
## Common Patterns
### Agent Testing Pipeline
```
Text(utterances) -> Text(expected) -> AgentTest -> Evaluation(RESPONSE_MATCH) -> Evaluation(COHERENCE)
```
**Quick path:** Use `setup_agent_test` for one-call creation of the full pipeline.
### Data Enrichment
```
Object(Accounts) -> AI(summary, PLAIN_TEXT) -> AI(sentiment, SINGLE_SELECT)
```
### Flow/Apex Testing
```
Text(inputs) -> InvocableAction(Flow) -> Reference(extract output field)
```
For complete step-by-step MCP tool call examples: [Use Case Patterns Reference](references/use-case-patterns.md)
## SF CLI Setup & Authentication
Before using the Grid API, authenticate to a Salesforce org using the SF CLI.
```bash
sf --version # Check if installed
sf org login web --alias my-org # Authenticate (add --instance-url for specific org)
sf org display --target-org my-org --json # Get access token + instance URL
```
**Instance URL formats:** `https://sdbX.testX.pc-rnd.pc-aws.salesforce.com/` (internal), `https://mycompany.my.salesforce.com` (production), `https://mycompany--sandbox.sandbox.my.salesforce.com` (sandbox).
**SF CLI does NOT accept lightning domains.** If a user provides one (e.g., `orgfarm-xxx.test1.lightning.pc-rnd.force.com`), ask for the instance URL instead.
For full auth instructions: `sf org login web --help`
## MCP Tool Reference
All tools use prefix `mcp__grid-connect__`. Grouped by operation type.
### Orchestration (Start Here)
| Tool | What It Does |
|------|-------------|
| `apply_grid` | Create/update a full grid from YAML DSL -- most powerful orchestration tool |
| `setup_agent_test` | One-call agent test pipeline: workbook + worksheet + columns + evaluations |
| `create_workbook_with_worksheet` | Create workbook + worksheet in one call |
| `poll_worksheet_status` | Poll until processing completes |
| `get_worksheet_summary` | Compact status overview |
| `run_worksheet` | Execute worksheet with optional `runStrategy: "ColumnByColumn"` for sequential |
### Read State
| Tool | What It Does |
|------|-------------|
| `get_workbooks` | List all workbooks |
| `get_workbook` | Get workbook details |
| `get_worksheet` | Get worksheet metadata |
| `get_worksheet_data` | **Primary read tool** -- full data with all columns, rows, cells |
| `get_worksheet_data_generic` | Generic format variant |
| `get_column_data` | Get cell data for one column |
### Create & Modify
| Tool | What It Does |
|------|-------------|
| `create_workbook` / `create_worksheet` | Create resources |
| `add_column` | Add column (returns new column ID) |
| `edit_column` | Update config AND reprocess all cells |
| `save_column` | Update config WITHOUT reprocessing |
| `reprocess_column` / `reprocess` | Reprocess cells (column or worksheet) |
| `delete_column` / `delete_workbook` / `delete_worksheet` | Delete resources |
| `add_rows` / `delete_rows` | Manage rows |
| `update_cells` | Update specific cells (use `fullContent`, not `displayContent`) |
| `paste_data` | Paste data matrix into grid |
| `trigger_row_execution` | Run processing for specific rows or cells |
| `import_csv` | Import CSV to worksheet |
### Typed Mutations (Prefer Over Raw edit_column)
These auto-fetch current config, merge changes, and handle references correctly.
| Tool | What It Does |
|------|-------------|
| `edit_ai_prompt` | Edit AI column prompt, model, or response format |
| `edit_agent_config` | Edit Agent/AgentTest config |
| `edit_prompt_template` | Edit PromptTemplate column |
| `change_model` | Switch LLM model on AI or PromptTemplate column |
| `add_evaluation` | Add evaluation with auto-wired references |
| `update_filters` | Update Object/DMO query filters |
### Discovery
| Tool | What It Does |
|------|-------------|
| `get_agents` | List agents (use `includeDrafts` for unpublished) |
| `get_agent_variables` | Get agent context variables |
| `get_sobjects` / `get_sobject_fields_display` / `get_sobject_fields_filter` | SObject discovery |
| `get_dataspaces` / `get_data_model_objects` / `get_data_model_object_fields` | Data Cloud discovery |
| `get_llm_models` | List available LLM models |
| `get_evaluation_types` | List evaluation types available in the org |
| `get_column_types` / `get_supported_types` | List column types |
| `get_formula_functions` / `get_formula_operators` | Formula building helpers |
| `get_invocable_actions` / `describe_invocable_action` | Discover Flows/Apex |
| `get_prompt_templates` / `get_prompt_template` | Discover prompt templates |
| `get_list_views` / `get_list_view_soql` | List view SOQL |
### AI Generation
| Tool | What It Does |
|------|-------------|
| `create_column_from_utterance` | Create column from natural language description |
| `generate_soql` | Natural language to SOQL |
| `generate_json_path` | AI-assisted JSON path generation |
| `generate_test_columns` | Generate test column configs |
| `generate_ia_input` | Generate invocable action input payload |
| `get_url` | Generate Lightning Experience URLs |
## Tool Operation Distinctions
| Tool | Behavior | When to Use |
|------|----------|-------------|
| `edit_column` | Updates config AND reprocesses | Changing prompt, model, references |
| `save_column` | Updates config, NO reprocess | Renaming, display-only changes |
| `reprocess_column` | Reprocesses with current config | Source data changed, retrying failures |
## State Refresh
Call `get_worksheet_data` after any mutation (add_column, paste_data, trigger_row_execution) to get updated IDs and statuses. Use `poll_worksheet_status` for long-running operations.
## Error Patterns
| Situation | What to Do |
|-----------|-----------|
| Column creation returns error but column exists | Verify with `get_worksheet_data` -- column may have been created despite the error |
| Cell processing failures | Use `reprocess_column` or `trigger_row_execution` with failed row IDs |
| Duplicate column name | API rejects with `DuplicateColumnName` -- check existing columns first |
| Config validation error | Fix config per error message and retry |
## Known Limits
- 100 test suites per org, 20 runs per suite, 10 concurrent runs per org
- AI column batches: 25 rows/batch, 4 parallel threads for evaluations
## Reference Documentation
- **[Column Configs](references/column-configs.md)** -- Complete JSON for all 12 column types
- **[Evaluation Types](references/evaluation-types.md)** -- All 13 evaluation types with guidance
- **[API Endpoints](references/api-endpoints.md)** -- Complete endpoint docs with examples
- **[Use Case Patterns](references/use-case-patterns.md)** -- Common workflows with MCP tool call examples
- **[Workflow Patterns](references/workflow-patterns.md)** -- User interaction models, conversation examples, CI/CD patterns

1001
skills/agentforce-grid/references/api-endpoints.md Normal file
View File

File diff suppressed because it is too large Load Diff

1009
skills/agentforce-grid/references/column-configs.md Normal file
View File

File diff suppressed because it is too large Load Diff

595
skills/agentforce-grid/references/evaluation-types.md Normal file
View File

@ -0,0 +1,595 @@
# Evaluation Types Reference
Complete guide to all 13 evaluation types in Agentforce Grid.
## Overview
Evaluation columns assess the quality or correctness of agent/prompt outputs. Some evaluations compare against expected values (requiring a reference column), while others assess quality independently.
## Evaluation Types Summary
| Type | Requires Reference | Supported Inputs | Use Case |
|------|-------------------|------------------|----------|
| `COHERENCE` | No | Agent, AgentTest, PromptTemplate | Assess logical flow |
| `CONCISENESS` | No | Agent, AgentTest, PromptTemplate | Assess brevity |
| `FACTUALITY` | No | Agent, AgentTest, PromptTemplate | Assess factual accuracy |
| `INSTRUCTION_FOLLOWING` | No | Agent, AgentTest, PromptTemplate | Assess instruction adherence |
| `COMPLETENESS` | No | Agent, AgentTest, PromptTemplate | Assess coverage |
| `RESPONSE_MATCH` | **Yes** | Agent, AgentTest | Compare to expected |
| `TOPIC_ASSERTION` (UI: "Subagent") | **Yes** | Agent, AgentTest | Verify topic routing |
| `ACTION_ASSERTION` | **Yes** | Agent, AgentTest | Verify actions |
| `LATENCY_ASSERTION` | No | Agent, AgentTest | Check response time |
| `BOT_RESPONSE_RATING` | **Yes** | Agent, AgentTest | Overall quality rating |
| `EXPRESSION_EVAL` | No | Agent, AgentTest | Custom formula |
| `CUSTOM_LLM_EVALUATION` | **Yes** | Agent, AgentTest | Custom LLM judge |
| `TASK_RESOLUTION` | No | Agent, AgentTest (conversation-level only) | Assess task completion |
---
## Quality Assessment Evaluations (No Reference Required)
These evaluations assess intrinsic quality without comparing to expected output.
### COHERENCE
Measures logical flow and consistency of the response.
**Assesses:**
- Logical flow of ideas
- Consistency in reasoning
- Clear connection between statements
**Example:**
```json
{
"name": "Coherence Score",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "COHERENCE",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"autoEvaluate": true
}
}
}
```
### CONCISENESS
Measures brevity without losing important information.
**Assesses:**
- Brevity without losing important information
- Elimination of redundancy
- Efficient communication
**Example:**
```json
{
"name": "Conciseness Score",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "CONCISENESS",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"autoEvaluate": true
}
}
}
```
### FACTUALITY
Measures factual accuracy of the response.
**Assesses:**
- Correctness of stated facts
- Absence of misinformation
- Verifiable claims
**Example:**
```json
{
"name": "Factuality Score",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "FACTUALITY",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"autoEvaluate": true
}
}
}
```
### INSTRUCTION_FOLLOWING
Measures how well the response follows given instructions.
**Assesses:**
- Adherence to specific requirements
- Compliance with format guidelines
- Following of step-by-step instructions
**Example:**
```json
{
"name": "Instruction Following",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "INSTRUCTION_FOLLOWING",
"inputColumnReference": {
"columnId": "prompt-output-col-id",
"columnName": "Prompt Output",
"columnType": "PromptTemplate"
},
"autoEvaluate": true
}
}
}
```
### COMPLETENESS
Measures if the response fully addresses the query.
**Assesses:**
- Coverage of all required information
- Depth of explanation
- Inclusion of necessary context
**Example:**
```json
{
"name": "Completeness Score",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "COMPLETENESS",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "Agent"
},
"autoEvaluate": true
}
}
}
```
---
## Comparison Evaluations (Reference Required)
These evaluations compare output against expected values.
### RESPONSE_MATCH
Compares agent's response to an expected response.
**Assesses:**
- Content similarity and accuracy
- Tone and style consistency
- Completeness of information
**Required:** `referenceColumnReference` pointing to expected response column
**Example:**
```json
{
"name": "Response Match",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "RESPONSE_MATCH",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"referenceColumnReference": {
"columnId": "expected-response-col-id",
"columnName": "Expected Response",
"columnType": "Text"
},
"autoEvaluate": true
}
}
}
```
### TOPIC_ASSERTION
**Note:** This evaluation type appears as "Subagent" in the Grid UI. The API name remains `topic_sequence_match`.
Validates that the agent correctly identified and used the expected topic.
**Assesses:**
- Topic selection accuracy
- Matches expected topic from reference column
**Required:** `referenceColumnReference` pointing to expected topic column
**Example:**
```json
{
"name": "Topic Assertion",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "TOPIC_ASSERTION",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"referenceColumnReference": {
"columnId": "expected-topic-col-id",
"columnName": "Expected Topic",
"columnType": "Text"
},
"autoEvaluate": true
}
}
}
```
### ACTION_ASSERTION
Validates that the agent executed the expected actions.
**Assesses:**
- Action execution accuracy
- All expected actions were performed
**Required:** `referenceColumnReference` pointing to expected actions column
**Example:**
```json
{
"name": "Action Assertion",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "ACTION_ASSERTION",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"referenceColumnReference": {
"columnId": "expected-actions-col-id",
"columnName": "Expected Actions",
"columnType": "Text"
},
"autoEvaluate": true
}
}
}
```
### BOT_RESPONSE_RATING
Provides overall quality rating comparing to expected response.
**Assesses:**
- Overall response quality
- Comparison against expected baseline
**Required:** `referenceColumnReference` pointing to expected response column
**Example:**
```json
{
"name": "Response Rating",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "BOT_RESPONSE_RATING",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"referenceColumnReference": {
"columnId": "expected-response-col-id",
"columnName": "Expected Response",
"columnType": "Text"
},
"autoEvaluate": true
}
}
}
```
---
## Performance Evaluation
### LATENCY_ASSERTION
Validates that response time meets performance requirements.
**Assesses:**
- Response time is within acceptable limits
**Example:**
```json
{
"name": "Latency Check",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "LATENCY_ASSERTION",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"autoEvaluate": true
}
}
}
```
---
## Custom Evaluations
### EXPRESSION_EVAL
Evaluate using a custom formula expression over the agent response JSON.
**Fields:**
- `expressionFormula` (String, required) - Formula with JSON path references
- `expressionReturnType` (String, optional) - Expected return type
**Example - Check Topic Name:**
```json
{
"name": "Topic Check",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "EXPRESSION_EVAL",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"expressionFormula": "{response.topicName} == 'Service'",
"expressionReturnType": "boolean",
"autoEvaluate": true
}
}
}
```
**Example - Check Message Count:**
```json
{
"name": "Message Count Check",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "EXPRESSION_EVAL",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"expressionFormula": "LEN({response.botMessages}) > 0",
"expressionReturnType": "boolean",
"autoEvaluate": true
}
}
}
```
### CUSTOM_LLM_EVALUATION
Use a custom prompt template for LLM-as-a-Judge evaluation.
**Fields:**
- `customEvaluation` (object, required)
- `type`: "llm"
- `apiName`: Prompt template API name
- `customInput`: Optional custom input
**Required:** `referenceColumnReference` for comparison baseline
**Example:**
```json
{
"name": "Custom Quality Check",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "CUSTOM_LLM_EVALUATION",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"referenceColumnReference": {
"columnId": "criteria-col-id",
"columnName": "Evaluation Criteria",
"columnType": "Text"
},
"customEvaluation": {
"type": "llm",
"apiName": "Custom_Evaluation_Template"
},
"autoEvaluate": true
}
}
}
```
---
### TASK_RESOLUTION
Assesses whether the agent successfully resolved the user's task across the full conversation.
**IMPORTANT:** Only works with conversation-level agent tests (`testType: "CONVERSATION_LEVEL"`). Does not apply to turn-level tests.
**Assesses:**
- Whether the agent achieved the user's stated goal
- End-to-end task completion across multiple turns
**Example:**
```json
{
"name": "Task Resolution",
"type": "Evaluation",
"config": {
"type": "Evaluation",
"queryResponseFormat": {"type": "EACH_ROW"},
"autoUpdate": true,
"config": {
"autoUpdate": true,
"evaluationType": "TASK_RESOLUTION",
"inputColumnReference": {
"columnId": "agent-output-col-id",
"columnName": "Agent Output",
"columnType": "AgentTest"
},
"autoEvaluate": true
}
}
}
```
---
## Selection Guide
### For Quality Assessment (No Expected Output)
When you want to assess intrinsic quality without a reference:
- **COHERENCE** - Is the response logically structured?
- **CONCISENESS** - Is the response appropriately brief?
- **FACTUALITY** - Are the facts accurate?
- **INSTRUCTION_FOLLOWING** - Did it follow instructions?
- **COMPLETENESS** - Did it cover everything needed?
### For Comparing Against Expected Output
When you have expected/golden responses:
- **RESPONSE_MATCH** - Does the response match expected?
- **BOT_RESPONSE_RATING** - Overall quality vs expected
### For Agent Routing Validation
When testing agent topic/action routing:
- **TOPIC_ASSERTION** - Did it route to correct topic?
- **ACTION_ASSERTION** - Did it execute correct actions?
### For Performance Testing
- **LATENCY_ASSERTION** - Is response time acceptable?
### For Conversation-Level Testing
- **TASK_RESOLUTION** - Did the agent resolve the task? (conversation-level only)
### For Custom Logic
- **EXPRESSION_EVAL** - Custom formula over response JSON
- **CUSTOM_LLM_EVALUATION** - Custom LLM judge with your criteria
---
## Common Patterns
### Agent Testing Suite
```
Text: "Utterances"
Text: "Expected Responses"
Text: "Expected Topics"
AgentTest: "Agent Output"
Evaluation: "Response Match" (RESPONSE_MATCH)
Evaluation: "Topic Check" (TOPIC_ASSERTION)
Evaluation: "Coherence" (COHERENCE)
Evaluation: "Latency" (LATENCY_ASSERTION)
```
### Prompt Quality Evaluation
```
Text: "Inputs"
PromptTemplate: "Output"
Evaluation: "Coherence" (COHERENCE)
Evaluation: "Completeness" (COMPLETENESS)
Evaluation: "Instruction Following" (INSTRUCTION_FOLLOWING)
```

663
skills/agentforce-grid/references/use-case-patterns.md Normal file
View File

@ -0,0 +1,663 @@
# 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

1161
skills/agentforce-grid/references/workflow-patterns.md Normal file
View File

File diff suppressed because it is too large Load Diff