# busbar-sf-agentscript
[](https://crates.io/crates/busbar-sf-agentscript)
[](https://docs.rs/busbar-sf-agentscript)
[](https://github.com/composable-delivery/busbar-sf-agentscript/actions/workflows/ci.yml)
[](https://codecov.io/gh/composable-delivery/busbar-sf-agentscript)
[](#license)
AgentScript parser, graph analysis, and LSP for [Salesforce Agentforce](https://www.salesforce.com/agentforce/).
AgentScript (`.agent`) is Salesforce's indentation-sensitive language for defining AI agent behavior in Agentforce. This project provides tooling for authoring, validating, and analyzing `.agent` files.
## Getting Started
Choose the option that fits your workflow:
| [SF CLI Plugin](#sf-cli-plugin) | Salesforce developers | `sf agency` commands for validation, graph export, and CI integration |
| [VS Code Extension](#vs-code-extension) | VS Code users | Syntax highlighting, real-time diagnostics, and topic graph visualization |
| [LSP Server](#lsp-server) | Neovim, Helix, and other editors | Full language server for any LSP-capable editor |
| [Rust Crates](#rust-crates) | Rust developers | Parser, graph analysis library, and WASM support |
---
## SF CLI Plugin
Install with the [Salesforce CLI](https://developer.salesforce.com/tools/salesforcecli):
```sh
sf plugins install @muselab/sf-plugin-busbar-agency
```
Validate an AgentScript file:
```sh
sf agency validate --file my-agent.agent
```
Export the topic reference graph:
```sh
sf agency graph --file my-agent.agent --format graphml --output graph.xml
sf agency graph --file my-agent.agent --format html --output report.html
```
Extract action interface definitions:
```sh
sf agency actions --file my-agent.agent
```
The plugin exits non-zero on errors, making it suitable for CI pipelines.
---
## VS Code Extension
Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=composable-delivery.vscode-agentscript):
```sh
code --install-extension composable-delivery.vscode-agentscript
```
Or download the `.vsix` from [GitHub Releases](https://github.com/composable-delivery/busbar-sf-agentscript/releases) and install manually:
```sh
code --install-extension vscode-agentscript-<version>.vsix
```
**Features:**
- Syntax highlighting for `.agent` files
- Real-time diagnostics — undefined references, cycle detection, unreachable topics
- Hover documentation
- Semantic token highlighting
- Topic graph visualization (`AgentScript: Show Topic Graph`)
- AgentScript Dependencies panel in the Explorer sidebar
**Settings:**
| `agentscript.lsp.serverPath` | auto | Path to a custom `busbar-sf-agentscript-lsp` binary |
| `agentscript.maxNumberOfProblems` | `100` | Maximum diagnostics shown per file |
| `agentscript.trace.server` | `off` | LSP communication tracing (`off`, `messages`, `verbose`) |
---
## LSP Server
The `busbar-sf-agentscript-lsp` binary powers the VS Code extension and works with any LSP-capable editor.
### Install
Download the pre-built binary for your platform from [GitHub Releases](https://github.com/composable-delivery/busbar-sf-agentscript/releases):
| macOS (Apple Silicon) | `busbar-sf-agentscript-lsp-aarch64-apple-darwin` |
| Linux x86\_64 | `busbar-sf-agentscript-lsp-x86_64-unknown-linux-gnu` |
| Windows x86\_64 | `busbar-sf-agentscript-lsp-x86_64-pc-windows-msvc.exe` |
Or install from source:
```sh
cargo install --git https://github.com/composable-delivery/busbar-sf-agentscript busbar-sf-agentscript-lsp
```
### Neovim
Using [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig):
```lua
local lspconfig = require('lspconfig')
local configs = require('lspconfig.configs')
if not configs.agentscript then
configs.agentscript = {
default_config = {
cmd = { 'busbar-sf-agentscript-lsp' },
filetypes = { 'agentscript' },
root_dir = lspconfig.util.root_pattern('sfdx-project.json', '.git'),
},
}
end
lspconfig.agentscript.setup {}
```
Add to `~/.config/nvim/init.lua` (or your config's `ftdetect`):
```lua
vim.filetype.add({ extension = { agent = 'agentscript' } })
```
### Helix
Add to `~/.config/helix/languages.toml`:
```toml
[[language]]
name = "agentscript"
scope = "source.agentscript"
file-types = ["agent"]
roots = ["sfdx-project.json", ".git"]
language-servers = ["agentscript-lsp"]
[language-server.agentscript-lsp]
command = "busbar-sf-agentscript-lsp"
```
### Other Editors
Any editor supporting LSP can be configured to launch `busbar-sf-agentscript-lsp` as a stdio language server for files with the `.agent` extension.
---
## Rust Crates
Add to `Cargo.toml`:
```toml
[dependencies]
# Parser only (default)
busbar-sf-agentscript = "0.1"
# Parser + graph analysis
busbar-sf-agentscript = { version = "0.1", features = ["graph"] }
# Parser + WASM bindings
busbar-sf-agentscript = { version = "0.1", features = ["wasm"] }
```
### Parser
```rust
use busbar_sf_agentscript::parse;
let source = std::fs::read_to_string("my-agent.agent").unwrap();
let ast = parse(&source).unwrap();
println!("{} topics defined", ast.topics.len());
```
### Graph Analysis
```rust
use busbar_sf_agentscript::{parse, graph::RefGraph};
let source = std::fs::read_to_string("my-agent.agent").unwrap();
let ast = parse(&source).unwrap();
let graph = RefGraph::from_ast(&ast).unwrap();
println!("Topics: {}", graph.topic_count());
println!("Unreachable: {:?}", graph.unreachable_topics());
println!("Unused actions: {:?}", graph.dead_actions());
```
### Individual Crates
The umbrella crate re-exports everything, but you can depend on individual crates directly:
| `busbar-sf-agentscript` | [](https://docs.rs/busbar-sf-agentscript) | Lexer, parser, AST, serializer, semantic validator, and graph analysis |
| `busbar-sf-agentscript-lsp` | [](https://docs.rs/busbar-sf-agentscript-lsp) | LSP server binary |
---
## AgentScript Language
AgentScript (`.agent`) is an indentation-sensitive (3-space) YAML-like language for defining Agentforce agent behavior. Example:
```
config:
agent_name: MyAgent
variables:
customerName: ""
start_agent:
message: Hello! How can I help you today?
topics:
- topic: SupportTopic
instructions: Handle customer support requests.
actions:
- action: LookupCase
type: FlowAction
api_name: Look_Up_Case
```
See [`agent-script-recipes`](https://github.com/trailheadapps/agent-script-recipes) for real-world examples.
---
## Workspace
```
src/ — parser, graph analysis, WASM bindings
crates/
lsp/ busbar-sf-agentscript-lsp — LSP server binary
packages/ — VS Code extension
plugin-agency/ — SF CLI plugin (sf agency *)
tree-sitter-agentscript/ — Tree-sitter grammar
zed-extension/ — Zed editor extension
agent-script-recipes/ — test fixtures (git submodule)
```
---
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). All contributions are welcome.
### Local Setup
```bash
git clone https://github.com/composable-delivery/busbar-sf-agentscript
cd busbar-sf-agentscript
git submodule update --init # recipe test fixtures
git config core.hooksPath .githooks # enable pre-commit checks
```
The pre-commit hook runs `cargo fmt --check` and `cargo clippy -- -D warnings` before every commit, matching CI exactly.
---
## License
Licensed under either of
- [MIT License](LICENSE-MIT)
- [Apache License, Version 2.0](LICENSE-APACHE)
at your option.