Skip to content

forcedotcom/sf-skills / plugins/builder/agentforce-adlc/skills/agentforce-generate

agentforce-generate

Flagged

Build, modify, audit, repair, optimize, debug, and deploy agents with Agentforce Agent Script. TRIGGER when: user creates, reviews, or changes .agent files or aiAuthoringBundle metadata; asks to fix AgentScript, audit an existing agent, run an AgentScript health check, common-pitfall review, or baseline-versus-candidate repair loop; changes a response, action, subagent, route, state flow, or Agent Spec; migrates or upgrades a legacy GenAiPlannerBundle Agentforce agent (NOT an Einstein Bot) to an aiAuthoringBundle (Agent Script) agent; previews, debugs, deploys, publishes, or tests agents; uses sf agent generate/preview/publish/test; or manages Agentforce MCP servers, tools, assets, or authentication. DO NOT TRIGGER when: Apex, Flow, Prompt Template, Experience Cloud, or general Salesforce CLI work is unrelated to Agent Script; the source is an Einstein Bot (BotDefinition/BotVersion) — use agentforce-bot-upgrade; or the primary input is a production session or trace ID rather than an agent artifact.

FileKindSize
README.mdmarkdown5.4 KB
SKILL.mdskill md31.7 KB
assets/agent-spec-template.mdmarkdown6.4 KB
assets/agents/README.mdmarkdown2.6 KB
assets/agents/hello-world.agentother1.9 KB
assets/agents/knowledge-grounded.agentother5.6 KB
assets/agents/local-info-agent-annotated.agentother17.0 KB
assets/agents/order-service.agentother11.7 KB
assets/agents/production-faq.agentother3.9 KB
assets/agents/production-faq.bundle-meta.xmlconfig161 B
assets/agents/router-first.agentother5.6 KB
assets/agents/simple-qa.agentother1.9 KB
assets/agents/template-multi-subagent.agentother5.4 KB
assets/agents/template-single-subagent.agentother2.6 KB
assets/agents/verification-gate.agentother10.7 KB
assets/agents/voice-knowledge-grounded.agentother8.2 KB
assets/agents/voice-service-agent.agentother4.6 KB
assets/bundle-meta.xmlconfig808 B
assets/invocable-apex-template.clsother6.9 KB
assets/patterns/README.mdmarkdown10.8 KB
assets/patterns/action-callbacks.agentother4.7 KB
assets/patterns/advanced-input-bindings.agentother6.9 KB
assets/patterns/bidirectional-routing.agentother5.6 KB
assets/patterns/critical-input-collection.agentother12.2 KB
assets/patterns/delegation-routing.agentother6.4 KB
assets/patterns/lifecycle-events.agentother4.7 KB
assets/patterns/llm-controlled-actions.agentother5.1 KB
assets/patterns/multi-step-workflow.agentother10.1 KB
assets/patterns/open-gate-routing.agentother11.6 KB
assets/patterns/procedural-instructions.agentother4.8 KB
assets/patterns/prompt-template-action.agentother6.6 KB
assets/patterns/system-instruction-overrides.agentother10.6 KB
references/action-prompt-templates.mdmarkdown5.7 KB
references/actions-reference.mdmarkdown30.2 KB
references/agent-access-guide.mdmarkdown2.9 KB
references/agent-audit-and-repair.mdmarkdown7.9 KB
references/agent-audit-candidate-verification.mdmarkdown5.2 KB
references/agent-audit-diagnostic-catalog.mdmarkdown7.6 KB
references/agent-audit-diagnostics-actions-state.mdmarkdown6.9 KB
references/agent-audit-diagnostics-architecture-evaluation.mdmarkdown2.5 KB
references/agent-audit-diagnostics-instructions-routing.mdmarkdown11.8 KB
references/agent-audit-evaluation-loop.mdmarkdown6.0 KB
references/agent-audit-repair-report.mdmarkdown6.9 KB
references/agent-audit-scope-path-review.mdmarkdown8.5 KB
references/agent-design-and-spec-creation.mdmarkdown54.5 KB
references/agent-metadata-and-lifecycle.mdmarkdown30.2 KB
references/agent-script-core-language.mdmarkdown49.3 KB
references/agent-subagent-map-diagrams.mdmarkdown10.8 KB
references/agent-user-setup.mdmarkdown27.8 KB
references/agent-validation-and-debugging.mdmarkdown44.6 KB
references/agentscript-toolchain.mdmarkdown4.6 KB
references/architecture-patterns.mdmarkdown13.5 KB
references/common-control-flow-pitfalls.mdmarkdown9.4 KB
references/complex-data-types.mdmarkdown3.9 KB
references/control-flow-actions-sequencing.mdmarkdown6.9 KB
references/control-flow-lifecycle-side-effects.mdmarkdown3.3 KB
references/data-library-reference.mdmarkdown40.8 KB
references/deploy-reference.mdmarkdown6.7 KB
references/discover-reference.mdmarkdown4.3 KB
references/examples.mdmarkdown12.6 KB
references/feature-validity.mdmarkdown2.1 KB
references/instruction-resolution.mdmarkdown23.4 KB
references/known-issues.mdmarkdown27.6 KB
references/legacy-nga-regression-eval.mdmarkdown30.2 KB
references/mcp-management-reference.mdmarkdown37.6 KB
references/optimization-pattern-1-data-flow.mdmarkdown4.6 KB
references/optimization-pattern-2-deterministic-logic.mdmarkdown5.4 KB
references/optimization-pattern-3-reference-syntax.mdmarkdown4.1 KB
references/optimization-pattern-4-escalation.mdmarkdown2.2 KB
references/org-setup-for-adl.mdmarkdown23.7 KB
references/patterns-by-requirement.mdmarkdown5.4 KB
references/posture-and-determinism.mdmarkdown9.3 KB
references/production-gotchas.mdmarkdown12.6 KB
references/reference-map.mdmarkdown5.3 KB
references/safety-review-reference.mdmarkdown6.3 KB
references/salesforce-cli-for-agents.mdmarkdown16.7 KB
references/scaffold-reference.mdmarkdown6.7 KB
references/scoring-rubric.mdmarkdown3.3 KB
references/upgrade-legacy-agent-to-agentscript.mdmarkdown26.2 KB
references/version-history.mdmarkdown4.4 KB
references/voice-latency-heuristics.mdmarkdown9.7 KB
references/voice-modality-reference.mdmarkdown19.0 KB
references/voice-telephony-cli.mdmarkdown10.3 KB
references/zen-of-agentscript.mdmarkdown13.1 KB
scripts/__init__.pyscript0 B
scripts/agentscript-sdk-loader.mjsscript4.0 KB
scripts/discover.pyexecutablescript20.2 KB
scripts/generators/__init__.pyscript0 B
scripts/generators/apex_stub.pyscript13.4 KB
scripts/generators/apex_test_stub.pyscript3.8 KB
scripts/generators/flow_xml.pyscript7.6 KB
scripts/generators/permission_set_xml.pyscript1014 B
scripts/generators/remote_site_xml.pyscript1.4 KB
scripts/index-agent.mjsexecutablescript3.8 KB
scripts/org_describe.pyexecutablescript5.8 KB
scripts/scaffold.pyexecutablescript15.1 KB
scripts/setup-agentscript-sdk.mjsexecutablescript9.7 KB
scripts/upgrade-legacy-nga-analyze.pyexecutablescript20.0 KB
scripts/upgrade-legacy-nga-run-trials.shexecutablescript3.4 KB

references/control-flow-actions-sequencing.md

View on GitHub
# AgentScript Action and Sequencing Pitfalls

Use this reference when action availability, ordered tool use, state timing, or
result handling may explain a behavior defect.

## Contents

- [Actions that escape their intended branch](#actions-that-escape-their-intended-branch)
- [Impossible same-turn sequences](#impossible-same-turn-sequences)
- [State written too early](#state-written-too-early)
- [Stale, raw, or missing action results](#stale-raw-or-missing-action-results)

## Actions that escape their intended branch

### Pitfall: mentioning an action under one branch is assumed to scope it

Actions are defined for the reasoning scope, not nested under the visual prompt
paragraph that mentions them. Unless gated, an action remains available while
other branches are active.

```agentscript
reasoning:
    instructions: ->
        if @variables.validation_succeeded == True:
            | Use the {!@actions.submit} action.
    actions:
        submit: @actions.submit_request
```

The `submit` action is still available when `validation_succeeded` is false.

Fix:

```agentscript
submit: @actions.submit_request
    available when @variables.validation_succeeded == True
```

### Pitfall: an action remains available after it succeeds

If repeating an action would duplicate a write, charge, message, or external
commitment, gate it on a result or idempotency value.

```agentscript
submit: @actions.submit_request
    available when @variables.validation_succeeded == True
    available when @variables.submission_id == ""
    set @variables.submission_id = @outputs.submission_id
```

Do not depend only on prose such as “do not call this again.”

## Impossible same-turn sequences

### Pitfall: model-selected actions are written as imperative steps

`@utils.setVariables` is a normal model-selected state-update tool. If the
model calls it successfully, the runtime stores the values. The action does
not itself define a turn boundary or guarantee another reasoning iteration.
Prompt text does not execute the tool:

```text
Call the state-setting action.
Then call the submission action.
```

The model may call either action, call both in one batch, or return text without
calling either. The second action does not automatically follow merely because
the prompt lists it second.

Fix with the smallest suitable option:

- bind current-turn values directly to the real action with `...`;
- set trusted values deterministically before reasoning;
- pass fixed values through a purpose-built transition or action;
- return the required values from the first real action; or
- combine inseparable writes into one implementation that owns the complete
  update.

### Pitfall: ask now and capture the future answer now

```text
Ask for the issue description.
Call the capture action with the issue description.
```

The answer does not exist when the question is asked. Give that branch one
outcome: ask. On the later turn, capture or use the answer.

### Pitfall: one branch requires several model-selected tools in order

The model may choose one tool, choose them in a different order, or produce a
response before the expected sequence is complete. If the order protects
authorization, correctness, or an external side effect, do not encode it only
as a tool list in prompt text.

Use deterministic post-action logic, gated actions with explicit intermediate
results, or one purpose-built action that owns the sequence.

## State written too early

### Pitfall: “complete” means “started”

Do not set:

```agentscript
set @variables.operation_completed = True
```

before the consequential action has returned a successful result.

Prefer state names that match the evidence:

```text
validation_completed
operation_requested
operation_succeeded
```

If the runtime cannot observe the final external side effect, use a weaker name
such as `operation_initiated` instead of claiming completion.

### Pitfall: workflow state advances on failure

Do not advance a stage, close a gate, or hide retry behavior merely because an
action was attempted. Branch on the trusted action result and preserve a safe
retry or failure path.

### Pitfall: state exists only to imitate dialogue stages

Avoid `current_step`, `question_asked`, or `has_greeted` when the available
conversation history already supplies the required continuity. Add state for a
named runtime consumer or when a value must outlive the usable history window;
give it the reset, correction, and failure behavior relevant to its use cases.

### Pitfall: one phase is represented several ways

Pairs such as `q1_asking`/`q1_answered`, plus `current_step` and completion
flags, can describe contradictory workflow positions. When deterministic
sequencing is truly required, prefer one explicit phase value and keep separate
state only for durable facts or trusted action inputs.

Before adding state, list its producer, consumer, reset, failure behavior, and
valid combinations with neighboring variables.

## Stale, raw, or missing action results

### Pitfall: “checked” is set before the result is usable

Do not mark validation complete while its result still needs model-driven
parsing:

```agentscript
set @variables.validation_output = @outputs.raw_json
set @variables.validation_checked = True
```

Later conditions can read old or default structured values and choose the wrong
branch. The raw output has resolved, but its derived fields have not.

Fix:

- Prefer typed action outputs.
- Otherwise normalize the raw result deterministically.
- Mark the check complete only after all branch inputs are stored.
- If normalization must be model-driven, use an explicit reasoning boundary so
  producing the raw result and consuming its parsed fields cannot occur in one
  half-populated state.

### Pitfall: raw JSON controls important branches

Do not ask the model to extract authorization, eligibility, confirmation, or
success flags from display-oriented text when those flags determine tool
availability or a consequential transition. Return typed, machine-checkable
outputs.

### Pitfall: the script branches on a value no producer returns

For every condition and `available when`, trace the value backward:

```text
consumer -> stored variable -> action output or deterministic assignment
```

If no reachable producer exists, the branch is dead or depends on an accidental
default.

### Pitfall: independent conditions overlap

Sequential top-level condition blocks are evaluated independently. This is a
pitfall only when predicates can overlap, leave an unintended gap, or require
first-match priority. Complementary predicates such as `X == value` and
`X != value` are mutually exclusive and do not overlap. When authoring new
first-match alternatives, prefer `if / else if / else`; use independent blocks
when multiple branches may run or mutual exclusion is explicit. Do not rewrite
equivalent control flow in a bounded repair solely for style. Spell the clause
`else if`; Python-style `elif` is invalid. Verify the effective prompt for each
reachable state.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall