.agent DSL — VS Code Extension

Full IDE support for the .agent DSL (.description, .type, .behavior) used to define autonomous agents and their behavioral state machines.

Architecture

This extension is a thin LSP client. Most IDE features (hover, completions, diagnostics, go-to-definition, references, rename, symbols, formatting) are provided by the Agent DSL Language Server — a standalone Node.js process started automatically when the extension activates. The server is bundled with the extension and speaks the Language Server Protocol over stdio.

Two features are implemented directly in the extension (VS Code-specific):

• Flow Graph — Mermaid state diagram rendered in a WebView panel
• Status bar — shows the current state the cursor is inside

Features

Syntax Highlighting

TextMate grammars for both .agent and .flow files — keywords, strings, operators, memory domains, and identifiers each get distinct colors.

Hover Documentation

Hover over any keyword to see inline documentation explaining its purpose and syntax.

Code Completion

Context-aware suggestions as you type:

Go-to-Definition

• .behavior — Ctrl/Cmd+Click on a state name to jump to its state declaration.
• .agent — Ctrl/Cmd+Click on a type name to jump to its type declaration.

Find All References

Right-click → "Find All References" on a state or type name to list every occurrence across the file.

Rename Symbol (F2)

• .behavior — Rename a state and all transition references update automatically.
• .agent — Rename a type and all references in input/output/requires/capabilities update automatically.

Document Links

File references become clickable links — Ctrl/Cmd+Click to open the target file:

• .behavior — run script "file.js", run behavior "file.behavior", guide "file", teach "file", apply css "file", etc.
• .agent — behavior file.behavior, schema file.json

Linting / Diagnostics

.behavior files:

• Dangling transition — transition to pointing to an undeclared state → error (or warning if it looks like an external reference with a dot).
• Dead-end interact — interact with no transition or on intent/offtopic → warning ("will trap the agent").

.agent files:

• Deprecated keywords — flags obsolete keywords (do, server, author, version, etc.) as errors.
• Strict lint — validates input/output/requires/capabilities blocks in both compact mode (Type1, Type2) and documented mode (Type "Description").
• Undeclared types — warns when a type used in a block is not declared in the file (could be native or external).

Code Actions (Quick Fixes)

Lightbulb on a diagnostic:

• "Create state 'X'" — inserts a new state scaffold at the end of the file.
• "Remove this line" — removes a deprecated keyword line.
• "Add 'on intent' handler" — inserts an on intent block after a dead-end interact.

Outline (Document Symbols)

The Outline panel shows:

• .behavior — states (class icon) and global event observers (on event: name).
• .agent — agent declarations and type declarations.

Workspace Symbols

Ctrl/Cmd+T searches states and events across all .flow files and agents/types across all .agent files in the workspace.

Document Formatting

Format Document normalizes indentation for both languages:

• .flow — 0 / 2 / 4 spaces for top-level, state body, and nested blocks respectively.
• .agent — 0 / 2 spaces for top-level keywords and their block content.

Folding

Explicit fold regions at state and on event boundaries in .flow; at top-level keyword boundaries in .agent.

Status Bar

When editing a .flow file, the status bar shows the name of the state the cursor is currently inside.

Flow Graph

Open the visual state diagram for any .flow file:

• Click the graph icon in the editor title bar, or
• Run "Flow: Open Graph" from the Command Palette.

A Mermaid stateDiagram-v2 diagram opens in a side panel and automatically refreshes on save.

Language Reference

.agent — Agent Manifest

agent My Agent

domain https://example.com
license MIT
description
  A brief description of what this agent does.

behavior main.behavior

input
  UserMessage "The user's message"

output
  Response

capabilities
  SendEmail
  ReadCalendar

type UserMessage
  concept https://schema.org/Message
  schema schemas/user-message.json

.behavior — Behavioral Flow

on event "start"
  transition to greeting

state greeting
  guide "Welcome! How can I help you today?"
  interact
  on intent "book meeting"
    transition to booking
  on offtopic
    guide "Are you sure you want to exit?"
    interact

state booking
  run subagent "BookingAgent"
  on complete
    transition to confirmation
  on failed
    transition to greeting

state confirmation
  guide "Your meeting has been booked."

Snippets

Installation

Install from the .vsix file:

code --install-extension vscode-dot-agent-0.2.0.vsix

Or build from source:

npm run package
npm run install-ext

License

Copyright (c) 2026 Danilo Borges (https://github.com/daniloborges)

Licensed under the Apache License, Version 2.0 — see LICENSE.