sf-ai-agentscript

What this skill does

# SF-AI-AgentScript Skill

Agent Script is the **code-first** path for deterministic Agentforce agents. Use this skill when the user is authoring `.agent` files, building finite-state topic flows, or needs repeatable control over routing, variables, actions, and publish behavior.

> Start with the shortest guide first: [references/activation-checklist.md](references/activation-checklist.md)
>
> Migrating from the Builder UI? Use [references/migration-guide.md](references/migration-guide.md)

## When This Skill Owns the Task

Use `sf-ai-agentscript` when the work involves:
- creating or editing `.agent` files
- deterministic topic routing, guards, and transitions
- Agent Script CLI workflows (`sf agent generate authoring-bundle`, `sf agent validate authoring-bundle`, `sf agent preview`, `sf agent publish authoring-bundle`, `sf agent activate`)
- slot filling, instruction resolution, post-action loops, or FSM design

Delegate elsewhere when the user is:
- maintaining Builder metadata agents (`GenAiFunction`, `GenAiPlugin`, `GenAiPromptTemplate`, Models API, custom Lightning types) → [sf-ai-agentforce](../sf-ai-agentforce/SKILL.md)
- designing persona / tone / voice → [sf-ai-agentforce-persona](../sf-ai-agentforce-persona/SKILL.md)
- building formal test plans or coverage loops → [sf-ai-agentforce-testing](../sf-ai-agentforce-testing/SKILL.md)

If the user is in Builder Script / Canvas view but the outcome is a `.agent` authoring bundle, keep the work in `sf-ai-agentscript`.

---

## Right-Size Determinism

- Determinism is a dial, not a destination.
- Use Agent Script when “mostly right” is not acceptable: gates, mandatory sequencing, explicit state transitions, compliance, or drift control.
- If a workflow is fully static and linear, use Flow or Apex instead of scripting the conversation.
- Prefer a deterministic envelope: deterministic entry/gate → flexible middle → deterministic closeout.
- More determinism is not automatically better. Start minimal, then harden only the parts that show routing drift, sequencing failures, or compliance risk.

---

## Required Context to Gather First

Ask for or infer:
- agent purpose and whether Agent Script is truly the right fit
- Service Agent vs Employee Agent
- target org and publish intent
- expected actions / targets (Flow, Apex, PromptTemplate, etc.)
- whether the request is authoring, validation, preview, or publish troubleshooting

---

## Activation Checklist

Before you author or fix any `.agent` file, verify these first:

1. **Exactly one `start_agent` block**
2. **No mixed tabs and spaces**
3. **Booleans are `True` / `False`**
4. **No `else if` and no nested `if`**
5. **No top-level `actions:` block**
6. **No `@inputs` in `set` expressions**
7. **`linked` variables have no defaults**
8. **`linked` variables do not use `object` / `list` types**
9. **Use explicit `agent_type`**
10. **Use `@actions.` prefixes consistently**
11. **Use `run @actions.X` only when `X` is a topic-level action definition with `target:`**
12. **Do not branch directly on raw `@system_variables.user_input contains/startswith/endswith` for intent routing**
13. **On prompt-template outputs, prefer `is_displayable: False` + `is_used_by_planner: True`**
14. **Do not assume `@outputs.X` is scalar — inspect the output schema before branching or assignment**

For the expanded version, use [references/activation-checklist.md](references/activation-checklist.md).

---

## Non-Negotiable Rules

### 1) Service Agent vs Employee Agent

| Agent type | Required | Forbidden / caution |
|---|---|---|
| `AgentforceServiceAgent` | Valid `default_agent_user`, correct permissions, target-org checks, prefer `sf org create agent-user` | Publishing without a real Einstein Agent User |
| `AgentforceEmployeeAgent` | Explicit `agent_type` | Supplying `default_agent_user` |

Full details: [references/agent-user-setup.md](references/agent-user-setup.md)

### 2) Recommended top-level block convention

Use this order for consistency in this skill's examples and reviews:

```yaml
config:
variables:
system:
connection:
knowledge:
language:
start_agent:
topic:
```

Official Salesforce materials present top-level blocks in differing sequences, and local validation evidence indicates multiple orderings compile. Treat this as a style convention, not a standalone correctness or publish blocker.

### 3) Critical config fields

| Field | Rule |
|---|---|
| `developer_name` | Must match folder / bundle name |
| `description` | Public docs/examples should use this config field |
| `agent_type` | Set explicitly every time |
| `default_agent_user` | Service Agents only |

Local tooling also accepts `agent_description:` for compatibility, but this skill's public docs and examples should prefer `description:`.

### 4) Syntax blockers you should treat as immediate failures

- `else if`
- nested `if`
- comment-only `if` bodies
- top-level `actions:`
- invocation-level `inputs:` / `outputs:` blocks
- reserved variable / field names like `description` and `label`

Canonical rule set: [references/syntax-reference.md](references/syntax-reference.md) and [references/validator-rule-catalog.md](references/validator-rule-catalog.md)

---

## Recommended Workflow

## Recommended Authoring Workflow

### Phase 1 — design the agent
- decide whether the problem is actually deterministic enough for Agent Script
- model topics as states and transitions as edges
- define only the variables you truly need

### Phase 2 — author the `.agent`
- create `config`, `system`, `start_agent`, and topics first
- add target-backed actions with full `inputs:` and `outputs:`
- use `available when` for deterministic tool visibility
- normalize raw intent/validation signals into booleans or enums before branching; avoid direct substring checks on raw user utterances for critical control flow
- keep post-action checks at the **top** of `instructions: ->`

### Default authoring stance

- Default to direct `.agent` authoring and edits in source control.
- Use `sf agent generate authoring-bundle --no-spec` only when the user wants local bundle scaffolding.
- Treat `sf agent generate agent-spec` as optional ideation / topic bootstrap, not the default workflow.
- Do not route Agent Script users toward `sf agent create` or `sf agent generate template`.

### Phase 3 — validate continuously
Validation already runs automatically on write/edit. Use the CLI before publish:

```bash
sf agent validate authoring-bundle --api-name MyAgent -o TARGET_ORG --json
```

The validator covers structure, runtime gotchas, target readiness, and org-aware Service Agent checks. Rule IDs live in [references/validator-rule-catalog.md](references/validator-rule-catalog.md).

### Phase 4 — preview smoke test
Use the preview loop before publish:
- derive 3–5 smoke utterances
- start preview with the `start` / `send` / `end` subcommands, not bare `sf agent preview`
- if you use `--authoring-bundle`, always choose a mode explicitly: `--simulate-actions` or `--use-live-actions`
- inspect topic routing / action invocation / safety / grounding
- fix and rerun up to 3 times

Full loop: [references/preview-test-loop.md](references/preview-test-loop.md)

### Phase 5 — publish and activate
```bash
sf agent publish authoring-bundle --api-name MyAgent -o TARGET_ORG --json

# Manual activation
sf agent activate --api-name MyAgent -o TARGET_ORG

# CI / deterministic activation of a known BotVersion
sf agent activate --api-name MyAgent --version <n> -o TARGET_ORG --json
```

Publishing does **not** activate the agent.
For automation, prefer `--version <n> --json` so activation is deterministic and machine-readable.

---

## Deterministic Building Blocks

These execute as code, not suggestions:
- conditionals
- `available when` guards
- variable checks
- direct `set` / `transition to`
- `run @actions.X` **only when `X` is a topic-level action definition with `target:`**
- variable injection into LLM-facing text

Important distinction:
- **Deterministic**