Documentation

Learn how to define, build, and ship AI agents with AgentLang.

Quick Start

# Install
curl -fsSL https://agentlang.dev/install.sh | sh

# Create a new agent
mkdir my-agent && cd my-agent

# Define the agent
cat > agent.yaml << 'EOF'
name: my-agent
version: 1.0.0
title: My First Agent
subtitle: Hello world

models:
  claude-sonnet-4:
    provider: anthropic

tools:
  - name: web_search
  - name: artifacts
EOF

# Define the prompt
cat > prompt.yaml << 'EOF'
version: 2
role: user
sections:
  - name: identity
    content: |
      You are a helpful research assistant.
  - name: workflow
    content: |
      1. Search for relevant information
      2. Synthesize findings into a report
      3. Save to artifacts
EOF

# Build
agentlang build .

# Run (requires compatible runtime)
agentlang run . --prompt "Research AI agents"

Agent Structure

my-agent/
  agent.yaml       # Main definition (required)
  prompt.yaml      # System prompt (required)
  ux.yaml          # UX hints (optional)
  agent.lock       # Generated lockfile

  # For multi-agent:
  specialists/
    researcher.yaml
    researcher-prompt.yaml
    analyst.yaml
    analyst-prompt.yaml

  # Bundled resources:
  context/
    templates/
    data/

agent.yaml Reference

prompt.yaml Reference

Prompts use PromptLang - a sectioned YAML format that compiles to markdown or XML tags.

version: 2
role: user           # or system
sections:
  - name: mindset
    content: |
      Core beliefs and motivations.

  - name: who_you_are
    content: |
      Character traits and approach.

  - name: your_tools
    content: |
      Brief tool descriptions.

  - name: workflow
    content: |
      Step-by-step process.

  - name: constraints
    content: |
      What NOT to do.

Recommended sections: mindset, who_you_are, your_tools, workflow, constraints. The build validates for missing common sections.

Tool Categories

AgentLang defines tool interfaces. Runtimes provide implementations.

Tools are versioned and locked. The lockfile ensures reproducibility.

Best Practices

Mindset over rules

Focus on WHO the agent IS, not WHAT it must DO. An agent with the right mindset will naturally exhibit the behaviors you want.

# Bad: Rules
sections:
  - name: workflow
    content: |
      1. Before EACH step, call journal
      2. Execute ONE step only
      3. After EACH step, call journal again

# Good: Mindset
sections:
  - name: mindset
    content: |
      You are genuinely trying to discover something.
      You journal your thinking not for documentation,
      but because externalizing helps you catch mistakes.

Memory first

Always check what you know before asking the user.

sections:
  - name: session_start
    content: |
      ALWAYS start by checking what you know:
      1. user_memory(action: "list")
      2. journal(action: "read")
      3. Only AFTER checking, ask about missing info

Proactive, not passive

Use available tools to solve problems. Only ask users after exhausting reasonable alternatives.

# Bad: Passive
1. Ask: "What would you like to analyze?"
2. Ask: "Which time period?"
3. Ask: "What format for results?"

# Good: Proactive
1. Load all available data
2. Analyze last 30 days (sensible default)
3. Show top findings
4. Offer: "Want different time period?"