Getting Started

This is the shortest path from an empty folder to a working Norn agent. You will create three small files: one for credentials, one for the agent, and one for the workflow that runs it.

The Three-File Mental Model

• .nornenv holds environment-specific values and secrets.
• .nornai declares models, agents, knowledge sources, databases, and the tools each agent may use.
• .norn is the executable flow. It imports your agents, passes work to them, and combines them with deterministic steps.

That is enough for your first agent. As a project grows, you may also meet:

• norn.config.json for project-wide settings and shared MCP server declarations.
• .nornapi for reusable API endpoints and headers.
• .nornsql for named database queries and commands.
• Markdown files and folders containing the domain knowledge an agent is allowed to use.

1. Install Norn

Install Norn from the VS Code Marketplace, or run:

code --install-extension Norn-PeterKrustanov.norn

2. Add Your Model Credential

Create .nornenv in your project root. This example creates a local environment and marks the key as a secret so Norn masks it in output and recordings.

[env:local]
secret OPENAI_API_KEY = paste-your-key-here

Do not commit a plaintext key. Once the file exists, run Norn: Select Environment from the Command Palette and choose local.

3. Declare Your First Agent

Create agents.nornai. The model block describes the provider connection; the agent block describes the role you want that model to perform.

model Workbench
    provider openai
    name gpt-4o-mini
    apiKey {{$env.OPENAI_API_KEY}}
end model

agent BacklogAnalyst
    model Workbench
    system "Turn a backlog item into a concise plan with a clear first action."
end agent

Agent sidecars can use either .nornai or .nornagent. They are the same language, parser, and runtime, in VS Code and in the CLI, so an existing .nornagent file keeps working unchanged. .nornai is what new files and the starters use. A plain .ai extension is not a Norn sidecar and is rejected with a message telling you to rename the file.

4. Put the Agent in a Flow

Create first-agent.norn. The import makes the sidecar available, and the sequence gives the agent a task.

import "./agents.nornai"

test sequence FirstAgentRun
    var result = run BacklogAnalyst "Customers cannot tell when an order will arrive."

    assert result.text exists
end sequence

5. Run It

1. Open first-agent.norn.
2. Confirm local is the selected environment.
3. Click Run Sequence above FirstAgentRun.
4. Read the agent output and invocation details in the Norn response panel.

If the sequence passes, the full path is working: environment → model → agent → workflow. Recording is enabled by default, so you can inspect or replay what happened.

Turn the Example into Real Work

• Shape the agent with contracts, specialist sub-agents, knowledge boundaries, judging, and replay.
• Give it tools by declaring an MCP server and granting only the capabilities it needs.
• Build the flow around agents with APIs, scripts, SQL, conditions, and deterministic checks.
• Learn HTTP basics if your workflow needs to call an API directly.