mirror of
https://github.com/forcedotcom/afv-library.git
synced 2026-07-30 19:50:42 +08:00
261abd679a
* @W-21955450@ Rename topic to subagent for Agent Script v2
Aligns with Agent Script v2 naming standards where `topic` is renamed
to `subagent` across all skill documentation and templates.
Changes:
- Agent Script templates: topic keyword → subagent keyword
- References: @topic.* → @subagent.*
- Documentation: Updated all skill references and guides
- Natural language references preserved in comments/descriptions
* Rename start_agent topic_selector to agent_router
Completes the topic → subagent terminology alignment by:
1. Renaming start_agent from topic_selector to agent_router (15 agent files)
2. Updating template topic declarations: topic {{placeholder}} → subagent {{placeholder}} (5 files)
3. Updating all @subagent.topic_selector references to @subagent.agent_router (35 occurrences)
4. Updating documentation: prose, examples, and diagrams (10 markdown files)
5. Updating comments to use agent_router terminology
Files affected:
- 22 agent template files
- 10 documentation/reference markdown files
- Template component files
The agent_router name is more descriptive of its actual function
(routing to different subagents) and completes the Agent Script v2
terminology standardization.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Rename files with "topic" to use "subagent" terminology
Completes the topic → subagent terminology alignment by renaming
files and updating all references:
**Files renamed (5):**
- multi-topic.agent → multi-subagent.agent
- template-single-topic.agent → template-single-subagent.agent
- template-multi-topic.agent → template-multi-subagent.agent
- topic-with-actions.agent → subagent-with-actions.agent
- agent-topic-map-diagrams.md → agent-subagent-map-diagrams.md
**References updated (6 docs):**
- Updated all filename references to point to new filenames
- Updated "Topic Map" → "Subagent Map" throughout documentation
- Updated "multi-topic"/"single-topic" → "multi-subagent"/"single-subagent"
Files modified:
- README.md, SKILL.md, agent-spec-template.md
- assets/agents/README.md, assets/README-legacy.md
- references/agent-design-and-spec-creation.md
This ensures consistent "subagent" terminology across filenames,
file content, and all documentation references.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Complete topic-to-subagent terminology update across skills
Comprehensive update replacing "topic" with "subagent" terminology throughout
the developing-agentforce and testing-agentforce skills to align with Agent
Script's `subagent` block naming.
Key changes:
- "Topic Selector" → "Subagent Router" in all agent templates and docs
- "Topic/action" → "Subagent/action" in documentation
- "Topic map" → "Subagent map" in diagram references
- Updated all architecture documentation to use "subagent" terminology
- Updated 19 .agent template files with new labels and comments
- Updated 8 reference documentation files with consistent terminology
API contract preservation:
- Test spec YAML files preserve "topic" terminology to match Testing Center API
- Added clarifying comments explaining topic/subagent equivalence in YAML files
- Field names like `expectedTopic` unchanged (Salesforce API requirement)
Preserved terms:
- "off-topic" (standard phrase for out-of-scope)
- "expectedTopic" field (Testing Center API)
- "platform topics" (Salesforce guardrail features)
32 files changed, 379 insertions(+), 366 deletions(-)
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* Complete comprehensive topic-to-subagent terminology update
Thorough update replacing all remaining "topic" references with "subagent"
terminology across developing-agentforce, testing-agentforce, and
observing-agentforce skills to fully align with Agent Script's `subagent`
block naming.
Key changes:
- Agent Script syntax: @topic.<name> → @subagent.<name>
- Agent Script syntax: topic.actions → subagent.actions
- Shell script patterns: ^topic → ^subagent
- Documentation: "topic instructions" → "subagent instructions"
- observing-agentforce skill: Updated all agent architecture references
- Template files: Updated all inline comments and descriptions
- Variable names in scripts: TOPIC → SUBAGENT
Specific updates:
- 45 files changed, 294 insertions, 294 deletions
- Updated all Agent Script code examples to use @subagent syntax
- Updated observing-agentforce issue classification guide
- Updated shell script patterns in diagnostic tools
- Updated Apex comments to clarify topic field maps to subagents
Preserved (as required):
- "off-topic" and "off_topic" (standard out-of-scope phrase)
- Testing Center API fields: expectedTopic, topic: in YAML
- API response fields: .topic, generatedData.topic, topic_assertion
- STDM field names: ssot__TopicApiName__c (with clarifying docs)
- Template placeholders in test specs (API values)
- "Topic hash drift" (API field behavior)
- "Email topic/purpose" (means email subject)
- Explanatory comments about API field mapping
All Agent Script syntax and documentation now consistently uses "subagent"
while preserving backward compatibility with platform API field names.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
* a few more topic -> subagent replacements
---------
Co-authored-by: Steve Hetzel <shetzel@salesforce.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
103 lines
4.2 KiB
Markdown
103 lines
4.2 KiB
Markdown
# Discover -- Target Discovery Reference
|
|
|
|
> Extracted from SKILL.md Section 16. This file is loaded on demand when target discovery details are needed.
|
|
|
|
## Overview
|
|
|
|
Validates that Agent Script `.agent` file targets actually exist in a Salesforce org, providing fuzzy suggestions for missing targets.
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# List all active autolaunched flows (candidate action targets)
|
|
sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+DeveloperName,ProcessType+FROM+Flow+WHERE+IsActive=true+AND+ProcessType='AutoLaunchedFlow'" -o <org-alias>
|
|
|
|
# List all @InvocableMethod Apex classes
|
|
sf api request rest --json "/services/data/v63.0/tooling/query?q=SELECT+Name+FROM+ApexClass+WHERE+Body+LIKE+'%25InvocableMethod%25'" -o <org-alias>
|
|
```
|
|
|
|
## What it does
|
|
|
|
### 1. Target Extraction
|
|
- Finds all `.agent` files in the project
|
|
- Parses each file to extract action `target:` values
|
|
- Identifies target types: `flow://`, `apex://`, `retriever://`, `externalService://`, `generatePromptResponse://`
|
|
|
|
### 2. Org Validation
|
|
|
|
| Target Type | SOQL Query | Object Checked |
|
|
|-------------|------------|----------------|
|
|
| `flow://FlowName` | `SELECT ApiName FROM FlowDefinitionView WHERE ApiName = 'FlowName' AND IsActive = true` | Active flows only |
|
|
| `apex://ClassName` | `SELECT Name FROM ApexClass WHERE Name = 'ClassName'` | Apex classes |
|
|
| `retriever://RetrieverName` | `SELECT DeveloperName FROM DataKnowledgeSpace WHERE DeveloperName = 'RetrieverName'` | Data Cloud retrievers |
|
|
| `externalService://ServiceName` | `SELECT DeveloperName FROM ExternalServiceRegistration WHERE DeveloperName = 'ServiceName'` | External services |
|
|
| `generatePromptResponse://TemplateName` | `SELECT DeveloperName FROM PromptTemplate WHERE DeveloperName = 'TemplateName' AND Status = 'Active'` | Active prompt templates |
|
|
|
|
### 3. Fuzzy Matching
|
|
When a target is missing:
|
|
- Queries for similar names using SOQL `LIKE` patterns
|
|
- Calculates Levenshtein distance for close matches
|
|
- Suggests up to 3 alternatives sorted by similarity
|
|
|
|
### 4. I/O Parameter Validation (--validate-io)
|
|
- **Flows:** Queries `/services/data/v63.0/actions/custom/flow/{FlowApiName}` for actual I/O schema
|
|
- **Apex:** Checks `@InvocableVariable` field names match expected inputs/outputs
|
|
- Results appear as non-blocking warnings
|
|
|
|
### 5. Classification for Scaffold Pipeline
|
|
|
|
| Signal in Description | Classification | Scaffold Output |
|
|
|----------------------|---------------|-----------------|
|
|
| "API", "HTTP", "REST", "external", URL | `callout` | Apex with Http + Remote Site + Custom Metadata |
|
|
| SObject names, "query", "record", "SOQL" | `soql` | Apex with SOQL query logic |
|
|
| No special signals | `basic` | Standard placeholder Apex |
|
|
|
|
## Output Format
|
|
|
|
```
|
|
Agentforce ADLC Discovery Report
|
|
|
|
Agent: OrderManagement
|
|
Subagent: order_inquiry
|
|
Action: get_order_status
|
|
Target: flow://Get_Order_Status Found
|
|
Action: track_shipment
|
|
Target: flow://Track_Shipment_Flow MISSING
|
|
Suggestions:
|
|
- Track_Shipping_Flow (distance: 2)
|
|
|
|
Summary: 2/3 targets found (66.7%)
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
- Missing targets: Run scaffold to generate stubs (see `scaffold-reference.md`)
|
|
- All found: Deploy (`sf agent publish authoring-bundle --json --api-name <AgentName> -o <org-alias>`)
|
|
|
|
## Error Handling
|
|
|
|
| Error | Cause | Resolution |
|
|
|-------|-------|------------|
|
|
| `No .agent files found` | Wrong directory | Check `--agent-file` path |
|
|
| `Invalid org alias` | Org not authenticated | Run `sf org login web --alias <org-alias>` |
|
|
| `SOQL query failed` | Missing permissions | Ensure read access to Flow, ApexClass, etc. |
|
|
|
|
## Exit Codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | All targets found |
|
|
| 1 | Some targets missing |
|
|
| 2 | Critical failure |
|
|
|
|
## Advanced (requires ADLC repo clone)
|
|
|
|
The `discover.py` script provides automated discovery with fuzzy matching and I/O validation. It is NOT bundled with the skill — requires cloning the ADLC repo.
|
|
|
|
```bash
|
|
# From ADLC repo root:
|
|
python3 scripts/discover.py -o <org-alias> --agent-file <path-to-agent-file>
|
|
python3 scripts/discover.py -o <org-alias> --agent-dir force-app/main/default/aiAuthoringBundles
|
|
python3 scripts/discover.py -o <org-alias> --agent-file MyAgent.agent --validate-io
|
|
```
|