From 10e45c3592249be9a5c62a4f1cb959c258e56f01 Mon Sep 17 00:00:00 2001 From: Sri Kolagani Date: Sat, 5 Sep 2026 23:13:46 +0000 Subject: [PATCH] docs(agentforce): clarify pre_tool_call and post_tool_call authoring Document that post_tool_call is compiler-emitted from chained reasoning actions, and that pre_tool_call is not supported for Agent Script authoring. Refs #42. --- .../ascript-patterns-action-chaining.md | 19 +++++++++++++++++++ .../agentforce/reference/ascript-ref-tools.md | 7 +++++++ 2 files changed, 26 insertions(+) diff --git a/apps/docs/docs/dialects/agentforce/patterns/ascript-patterns-action-chaining.md b/apps/docs/docs/dialects/agentforce/patterns/ascript-patterns-action-chaining.md index e19736bb..a0f56c53 100644 --- a/apps/docs/docs/dialects/agentforce/patterns/ascript-patterns-action-chaining.md +++ b/apps/docs/docs/dialects/agentforce/patterns/ascript-patterns-action-chaining.md @@ -100,6 +100,24 @@ reasoning: | Explain that the user is not eligible for this offer. ``` +## pre_tool_call and post_tool_call + +You may see `pre_tool_call` and `post_tool_call` in the generated Agent DSL schema or in compiled IR. Those names are **compiler/runtime concepts**, not Agent Script authoring keywords you write by hand in Agentforce. + +**What to write instead** + +- To run follow-up work after the LLM calls a reasoning action, use **chained actions** in `reasoning.actions` — nested `run`, `set`, `if` / `elif` / `else`, or `transition` under the tool (see examples above). The compiler emits that follow-up logic as `post_tool_call` for you. +- Prefer the documented patterns on this page and in [Tools (Reasoning Actions)](../reference/ascript-ref-tools.md) over raw DSL hook fields. + +**Support status** + +| Hook | Authoring support | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `post_tool_call` | Supported **indirectly**: produced by the compiler from chained reasoning-action bodies (nested `run` / conditionals / transitions). | +| `pre_tool_call` | **Not supported** for Agent Script authoring today. It appears in generated schema types only; there is no documented authoring surface or compiler path that emits it. Do not rely on it. | + +If you need work to run before the LLM reasons, use `before_reasoning` / instructions at the start of the subagent — see [After Reasoning](../reference/ascript-ref-before-after-reasoning.md). + ## Tips - **Use sequential instructions for deterministic flows**: When you always want actions to run in a specific order. @@ -110,3 +128,4 @@ reasoning: - Reference: [Actions](../reference/ascript-ref-actions.md) - Reference: [Reasoning Instructions](../reference/ascript-ref-instructions.md) - Reference: [Tools (Reasoning Actions)](../reference/ascript-ref-tools.md) +- Reference: [After Reasoning](../reference/ascript-ref-before-after-reasoning.md) diff --git a/apps/docs/docs/dialects/agentforce/reference/ascript-ref-tools.md b/apps/docs/docs/dialects/agentforce/reference/ascript-ref-tools.md index e5248256..0a29841b 100644 --- a/apps/docs/docs/dialects/agentforce/reference/ascript-ref-tools.md +++ b/apps/docs/docs/dialects/agentforce/reference/ascript-ref-tools.md @@ -116,9 +116,16 @@ reasoning: available when @variables.needs_expert_help == True ``` +## Chaining Follow-up Work After a Tool Call + +To run deterministic follow-up logic after the LLM calls a tool, nest `run`, `set`, conditionals, or `transition` under that tool in `reasoning.actions`. The compiler turns that nested body into `post_tool_call` behavior in the generated IR — you do not author `post_tool_call` (or `pre_tool_call`) directly. + +See [Action Chaining](../patterns/ascript-patterns-action-chaining.md#pre_tool_call-and-post_tool_call) for examples and support status. + ## Related Topics - [Flow of Control](../ascript-flow.md) - [Actions](ascript-ref-actions.md) - [Utils](ascript-ref-utils.md) - [Variables](ascript-ref-variables.md) +- Pattern: [Action Chaining](../patterns/ascript-patterns-action-chaining.md)