Module ast 

Abstract Syntax Tree types for AgentScript.

This module defines all types representing a parsed AgentScript file. Every node in the AST is wrapped in Spanned to track its source location, enabling precise error reporting and IDE features like go-to-definition.

For a comprehensive guide to the AST structure, node relationships, and UX development patterns, see the AST Reference.

AST Structure

The root type is AgentFile, which contains optional blocks:

AgentFile
├── config: ConfigBlock (agent metadata)
├── system: SystemBlock (global instructions/messages)
├── variables: VariablesBlock (state management)
├── connections: ConnectionsBlock (escalation routing)
├── language: LanguageBlock (locale settings)
├── start_agent: StartAgentBlock (entry point)
└── topics: Vec<TopicBlock> (conversation topics)

Span Tracking

All nodes use Spanned<T> to preserve source locations:

use busbar_sf_agentscript::Spanned;

// A spanned string with byte offsets 10..20
let name = Spanned::new("MyAgent".to_string(), 10..20);
assert_eq!(name.node, "MyAgent");
assert_eq!(name.span, 10..20);

Serialization

All types implement Serialize and Deserialize for JSON interop:

let source = "config:\n   agent_name: \"Test\"\n";
let agent = parse(source).unwrap();
let json = serde_json::to_string(&agent).unwrap();

Structs

ActionDef

An action definition.

ActionsBlock

A block of action definitions.

AgentFile

A complete parsed AgentScript file.

Comment

A comment in the source.

ConfigBlock

Agent configuration block containing metadata.

ConnectionBlock

A connection block defines escalation routing for a specific channel.

ConnectionEntry

A key-value entry in a connection block.

DirectiveBlock

A directive block contains imperative statements.

IfClause

A conditional clause in reasoning actions.

KnowledgeBlock

The knowledge block configures knowledge base access.

KnowledgeEntry

LanguageBlock

The language block configures locale settings.

LanguageEntry

OutputRef

Reference to an action output.

ParamDef

A parameter definition (for action inputs/outputs).

ReasoningAction

An action available during reasoning.

ReasoningBlock

The reasoning block configures LLM reasoning.

Reference

A reference to a namespaced resource.

RunClause

A chained run clause in reasoning actions.

SetClause

A set clause assigns a value to a variable.

Spanned

A value with an associated source span.

StartAgentBlock

The start_agent block is the entry point for the agent.

SystemBlock

The system block defines global agent settings.

SystemMessages

System messages (welcome, error).

TopicBlock

A topic block defines a conversation topic.

TopicSystemOverride

System instruction override for a topic.

VariableDecl

A single variable declaration.

VariablesBlock

Variables block containing state variable declarations.

WithClause

A with clause binds an action input.

Enums

BinOp

Binary operators.

Expr

An expression in AgentScript.

InstructionPart

A part of dynamic instructions.

Instructions

Instructions can be static or dynamic.

ReasoningActionTarget

Target of a reasoning action.

Stmt

A statement in a directive block.

Type

Data type for variables and action parameters.

UnaryOp

Unary operators.

VariableKind

Variable mutability kind.

WithValue

The value of a with clause.

Type Aliases

ConnectionsBlock

@deprecated Use ConnectionBlock instead - this type exists only for backwards compatibility

Span

A span in the source code represented as byte offsets.