Hello Turn

This walkthrough traces your first Turn program step by step. It demonstrates the core primitives like variable binding, memory, context, tool calls, and suspension in a single turn of execution.

CLI Quickstart

If you have Turn installed, you can run this example right now. If not, see Installation first.

# Configure your inference provider
export TURN_LLM_PROVIDER=openai
export OPENAI_API_KEY=sk-...

# Save the program
cat > hello.tn << 'EOF'
let name = "Turn";
remember("user", name);
context.append("Hello, " + name);
let out = call("echo", "Hello");
return out;
EOF

# Run it
turn run hello.tn
# Hello

The result is "Hello", which is the return value of the program. Let's trace exactly how execution got there.

The Program

The program below defines a single turn in which the agent binds a variable, persists a value to memory, appends a message to its context window, calls an external tool, and returns the result.

let name = "Turn";
remember("user", name);
context.append("Hello, " + name);
let out = call("echo", "Hello");
return out;

This is a complete, runnable Turn program. It compiles to bytecode and executes on the Turn VM. Every line exercises a distinct language primitive.

Step-by-Step Execution

The table below traces the state of the three mutable components (the environment (env), the context window, and persistent memory) at each step of execution.

Turn result: "Hello"

At step 4, the VM does not block a thread. It serializes the continuation (the remaining program plus the current state) and suspends. The runtime executes the tool asynchronously, and when the result arrives, the VM resumes from the saved continuation at step 5. This is the core of Turn's durable execution model.

Variant: Using Recall

To demonstrate memory retrieval, this variant writes a value to memory and then reads it back within the same program:

turn {
let name = "Turn";
remember("user", name);
context.append("Hello");
call("echo", "Hello");
let who = recall("user");
return who;
}

Here the turn result is "Turn", which is the value that was stored with remember and retrieved with recall. Memory persists across suspensions and even across process restarts, because it is written to durable storage as part of the process state.

Next Steps

• Grammar
• Types & Errors