Skip to content

AgentScript Base Examples

This document provides sample AgentScript code snippets along with their transpiled TypeScript to illustrate key features.


Example 1. Natural Language Context

AgentScript

function fetchUser(userId: UserID): User
goal: "Fetches user data for profile display"
backstory: "Interacts with the User Service API"
requires:
userId >= 1: "User ID must be at least 1"
return:
// Call to an external service
callUserService(userId)
errors:
UserNotFound: "No user found for the given ID" when callUserService(userId) is null
APIError: "Failed to fetch user data" when callUserService(userId) throws
tests:
success:
// Expect a valid user object when userId is valid
1 -> { id: 1, name: "Alice" }
performance:
// Should respond within 10ms under normal conditions
input: 10 -> expect < 10ms

Transpiled TypeScript

export function fetchUser(userId: number): User {
// Contract check: userId >= 1
if (userId < 1) {
throw new Error("User ID must be at least 1");
}
let user: User;
try {
// Implementation
user = callUserService(userId);
} catch (error) {
throw new Error("Failed to fetch user data"); // APIError
}
if (!user) {
throw new Error("No user found with the given ID"); // UserNotFound
}
return user;
}

Explanation:
• Demonstrates meta-sections (intent, context) in AgentScript for clarity and includes error logic inline.
• Embedded tests define expected behavior across success, performance, and load categories.
• The generated TypeScript includes contract checks, a try/catch for API errors, and a condition for missing users.


Example 2. Embedded Tests

AgentScript

function calculateDiscount(price: number, discount: number): number
goal: "Apply a discount to a price in e-commerce."
backstory: "Used during checkout."
requires:
price >= 0: "Price must be non-negative"
discount >= 0 && discount <= 100: "Discount must be between 0 and 100"
return:
price * (1 - discount / 100)
errors:
InvalidPrice: "Price must be non-negative"
InvalidDiscount: "Discount must be between 0 and 100"
tests:
success:
100, 20 -> 80
200, 50 -> 100
errors:
-100, 20 -> InvalidPrice
100, -10 -> InvalidDiscount
100, 150 -> InvalidDiscount
performance:
input: [1000, 10] -> expect < 1ms
input: [9999999, 99] -> expect < 10ms

Transpiled TypeScript

export function calculateDiscount(price: number, discount: number): number {
if (price < 0) {
throw new Error("Price must be non-negative"); // InvalidPrice
}
if (discount < 0 || discount > 100) {
throw new Error("Discount must be between 0 and 100"); // InvalidDiscount
}
return price * (1 - discount / 100);
}

Explanation:
• Multiple embedded test types specify success and smoke scenarios.
• The performance tests hint at maximum acceptable execution times.
• Transpiled TypeScript includes straightforward contract checks before performing the calculation.


Example 3. State Machines

AgentScript

function orderStateMachine(order: Order): State
machine:
state: pending -> confirmed on confirmOrder
state: confirmed -> shipped on shipOrder
state: shipped -> delivered on deliverOrder
errors:
InvalidTransition: "Attempted an invalid state transition"
tests:
success:
{ status: "pending" } -> "confirmed" after confirmOrder
{ status: "confirmed" } -> "shipped" after shipOrder
smoke:
{ status: "delivered" } -> error: InvalidTransition

Transpiled TypeScript

export function orderStateMachine(order: Order): State {
// A naive representation of transitioning states
function confirmOrder(current: Order) {
if (current.status !== "pending") {
throw new Error("Attempted an invalid state transition"); // InvalidTransition
}
return { ...current, status: "confirmed" };
}
function shipOrder(current: Order) {
if (current.status !== "confirmed") {
throw new Error("Attempted an invalid state transition"); // InvalidTransition
}
return { ...current, status: "shipped" };
}
function deliverOrder(current: Order) {
if (current.status !== "shipped") {
throw new Error("Attempted an invalid state transition"); // InvalidTransition
}
return { ...current, status: "delivered" };
}
// In a real app, you'd call one of the above transitions
// based on external events. For demo purposes, return the new order state.
switch (order.status) {
case "pending":
return confirmOrder(order).status;
case "confirmed":
return shipOrder(order).status;
case "shipped":
return deliverOrder(order).status;
default:
throw new Error("Attempted an invalid state transition");
}
}

Explanation:
• Machine-style definition outlines valid transitions between states (pending → confirmed → shipped → delivered).
• The TypeScript output includes functions to validate and apply transitions, highlighting the same error type on invalid transitions.


Example 4. Tagged Errors and Pipe Operator

AgentScript

function processData(data: string): number
goal: "Parses, validates, then calculates a numeric result from string data."
backstory: "Used in data ingestion pipeline."
requires:
CannotBeEmpty: "Input data cannot be empty" -> data != ""
return:
data
|> parseJSON
|> validateFormat
|> computeResult
errors:
ParseError: "Invalid JSON structure"
ValidationError: "Data format is invalid"
computationError: "Unable to compute result"
tests:
success:
"{ \"value\": 10 }" -> 20
smoke:
"" -> CannotBeEmpty
performance:
input: "{ \"value\": 9999 }" -> expect < 5ms

Transpiled TypeScript

export function processData(data: string): number {
if (!data) {
throw new Error("Input data cannot be empty");
}
const parsed = parseJSON(data); // could throw "Invalid JSON structure"
const validated = validateFormat(parsed); // could throw "Data format is invalid"
const result = computeResult(validated); // could throw "Unable to compute result"
return result;
}

Explanation:
• Demonstrates the pipe operator (|>) for chaining transformations and computations.
• Tagged errors let you differentiate failure points in your pipeline.
• The TypeScript output chains calls in a more verbose manner, matching each pipeline step.


Example 5. Pattern Matching

AgentScript

function handleUserRole(user: { role: string }): string
goal: "Assigns privileges based on user role."
return:
match (user) {
case { role: "admin" } -> "Admin privileges"
case { role: "guest" } -> "Guest access"
default -> "Basic access"
}
tests:
success:
{ role: "admin" } -> "Admin privileges"
{ role: "guest" } -> "Guest access"
{ role: "other" } -> "Basic access"

Transpiled TypeScript

export function handleUserRole(user: { role: string }): string {
if (user.role === "admin") {
return "Admin privileges";
} else if (user.role === "guest") {
return "Guest access";
} else {
return "Basic access";
}
}
if (import.meta.vitest) {
const { it, expect } = import.meta.vitest
it('handleUserRole', () => {
expect(handleUserRole({ role: "admin" })).toBe("Admin privileges")
expect(handleUserRole({ role: "guest" })).toBe("Guest access")
expect(handleUserRole({ role: "other" })).toBe("Basic access")
})
}

Explanation:
• Uses a match block to branch logic based on pattern matching.
• Transpiled TypeScript falls back to standard conditional checks.


Summary

These examples showcase how AgentScript’s concise syntax, contract programming, built-in testing, and concurrency features map to more verbose but widely deployable TypeScript. By embedding best practices directly into the language, AgentScript ensures that AI- or human-generated code is robust, easy to maintain, and aligned with business requirements.