Agent setup and usage guide

This guide describes how to set up and use agents in dist_agent_lang: project setup, CLI commands, the agent HTTP server, DAL APIs, molds, and evolve context. It reflects what users and developers can do today.

Table of contents

  1. Overview
  2. Quick start: agent project
  3. Project layout and config
  4. CLI: agent commands
  5. Agent HTTP server
  6. DAL: agent and evolve APIs
  7. Molds
  8. Shell trust and evolve context
  9. Persistent memory
  10. Skills and registry
  11. Capabilities and types
  12. RAG (retrieval)
  13. MCP (IDE bridge)
  14. References

1. Overview

Agents in dist_agent_lang are in-process entities with:

You can:

2. Quick start: agent project

Create an agent project

mkdir my-agent && cd my-agent
dal init agent

This creates (only if missing):

Run the agent script

dal run agent.dal

This runs agent.dal: it spawns one agent and calls agent::set_serve_agent(agent_id). The process then exits; the “serve” designation is used when you start the HTTP server with a behavior script.

Run the agent HTTP server

dal agent serve

If agent.dal exists in the current directory, it is run first; the script must spawn an agent and call agent::set_serve_agent(agent_id). That agent is then served at http://localhost:4040 (default port). See Agent HTTP server.

Optional: environment

Copy .env.example to .env, set any keys (e.g. OPENAI_API_KEY, ANTHROPIC_API_KEY for AI), and load them (e.g. export $(cat .env | xargs) or use a .env loader). See Shell trust and evolve context.

Host protocol API note

For DAL apps, prefer the typed request shape:

let ai_result = ai::agent_run({"message": "Run pwd once and summarize", "policy": "tool_loop"});

ai::respond_with_tools_result(...) remains available for compatibility, but new first-party examples and templates use ai::agent_run(...).

For dal init agent, the generated .env includes a minimal host-protocol profile intended for task completion with safety guardrails:

DAL_AGENT_SHELL_TRUST=sandboxed
DAL_AGENT_CONTEXT_PATH=./evolve.md
DAL_AGENT_POLICY_DEFAULT=auto
DAL_AGENT_NATIVE_TOOL_CALLS_ENABLED=1
DAL_AGENT_ENABLE_LEGACY_TEXT_JSON=0
DAL_AGENT_GUARDS_STRICT_MODE=1

3. Project layout and config

Files created by dal init agent

File Purpose
agent.dal Agent behavior: spawn agent, call agent::set_serve_agent(agent_id). Used by dal run agent.dal and by dal agent serve when no --behavior is given.
agent.toml Agent config: [agent.sh] (shell trust), [agent] (e.g. context_path for evolve).
evolve.md Evolve context file: conversation history and action log. Path set by [agent] context_path or DAL_AGENT_CONTEXT_PATH.
playground.dal Minimal DAL language sandbox for quick experimentation (dal run playground.dal).
dal.toml Minimal DAL package (created only if missing).
.env.example Documented env vars (safe to commit).
.env Local overrides (do not commit; in .gitignore).

agent.toml

# Agent project config

[agent.sh]
trust = "sandboxed"
# forbidden_patterns = ["rm -rf", "sudo"]
# allowed_prefixes = ["npm", "cargo", "git"]

[agent]
context_path = "./evolve.md"

Context path can be overridden with DAL_AGENT_CONTEXT_PATH.

Evolve wired at init: When you run dal init agent, evolve is wired by default: agent.toml gets context_path = "./evolve.md" and evolve.md is created. The serve path loads evolve into the prompt each turn; lifecycle hooks (e.g. in molds) can use evolve::append_log, evolve::append_summary, evolve::append_conversation. To disable evolve, comment out or remove the context_path line in agent.toml (and optionally remove evolve.md). To opt in again, uncomment context_path and ensure the evolve file exists.

4. CLI: agent commands

All agent subcommands: dal agent <subcommand> [args...].

dal agent serve

Run the agent HTTP server (one agent per process).

dal agent serve [name] [--port PORT] [--mold path] [--behavior path] [--prompt-only]

Examples:

dal agent serve
dal agent serve my-bot --port 5000
dal agent serve --behavior ./scripts/agent.dal
dal agent serve --prompt-only

dal agent create

Create an agent in the current process (in-memory; process exit clears it).

By type and name:

dal agent create <type> <name> [--role "role"]

Types: ai, system, worker, custom:<name>.

From a mold:

dal agent create --mold <path|ipfs://cid> <name>

With web3: --mold <numeric_mold_id> uses on-chain registry (pay fee, then load from IPFS).

dal agent send

Send a message between two agent IDs (same process).

dal agent send <sender_id> <receiver_id> "<message>"

dal agent messages

Print messages received by an agent (consumes the queue).

dal agent messages <agent_id>

dal agent task assign / list

Assign a task or list pending tasks:

dal agent task assign <agent_id> "<description>" [--priority low|medium|high|critical]
dal agent task list <agent_id>

dal agent chat

Interactive chat with an AI agent (same process): messages go to the agent; replies come from the LLM (OpenAI/Anthropic/local). Requires API keys or DAL_AI_ENDPOINT.

dal agent chat [name]

dal agent list

Prints how to run chat, serve, and multi-agent DAL patterns (agent state is process-local).

dal agent fleet

Off-chain fleet: named set of agents, optionally created from a mold. See FLEET_DEPLOYMENT.md for full deployment flow.

Fleet state is stored in base/.dal/fleets.json when using the CLI (current working directory as base).

dal agent mold

5. Agent HTTP server

When you run dal agent serve, the server listens (default port 4040) and exposes one agent.

Endpoints

Method Path Description
GET /status Agent id, name, type, status
POST /message Send message (body: sender_id, content; optional message_type, wait)
GET /messages Receive (and consume) messages for this agent
POST /task Assign task (body: description; optional task_id, priority, requester_id, wait)
GET /tasks Receive (and consume) pending tasks
GET /health Liveness

Example: send message and get messages

curl -X POST http://localhost:4040/message \
  -H "Content-Type: application/json" \
  -d '{"sender_id": "user1", "content": "Hello"}'

curl http://localhost:4040/messages
curl http://localhost:4040/status

Prompt-only mode

With --prompt-only (or DAL_AGENT_PROMPT_ONLY=1), no behavior script is run. The server spawns a default worker agent and, for each incoming message, calls the LLM and posts the reply back to the sender. Use when you want a simple chat-style API without custom DAL logic.

Structured responses: wait and Idempotency-Key (prompt-only)

For POST /message and POST /task, set "wait": true in the JSON body to block until the multi-step tool loop finishes. The HTTP response includes a result object:

Without wait, the handler returns { "ok": true } immediately and delivers the assistant output via GET /messages (unchanged).

Send HTTP header Idempotency-Key: <opaque> on wait: true requests to cache the JSON response for about 10 minutes. Retries with the same key return the cached body without re-invoking the model (useful for safe cron retries). See CONFIG.md.

Outbound HTTP and overlapping requests

Outbound HTTP tools (search, fetch_url, and other code paths that use reqwest) require the Cargo feature http-interface. The default dal binary enables it. If you build with cargo build --no-default-features, re-enable http-interface for production agent servers that need web access. See root Cargo.toml [features] and CONFIG.md.

Web search defaults to DuckDuckGo Instant Answer (no API key). For fuller results, set DAL_WEB_SEARCH_PROVIDER=brave or serpapi and supply the matching API key env vars listed in CONFIG.md.

URL fetch limits and SSRF-related toggles: DAL_HTTP_FETCH_* in CONFIG.md.

Overlapping long requests: handlers that run an LLM plus a tool loop can hold a blocking worker for a long time. Many concurrent cron-triggered HTTP calls may queue or time out. Mitigate by staggering schedules, limiting parallelism, or using a dedicated worker process. See AUTONOMOUS_JOBS_LANGUAGE_GAPS.md §2.3.

6. DAL: agent and evolve APIs

agent:: — lifecycle and coordination

From DAL you call the agent module as follows.

Spawn an agent

Example:

use agent;

let agent_id = agent::spawn({
    "name": "my-agent",
    "type": "worker",
    "role": "Agent serve"
});
agent::set_serve_agent(agent_id);

Set the serve agent (required when using dal agent serve with a behavior script):

Coordination

Communication

Other

Note: Messages and tasks are consumed when received (e.g. receive_messages / receive_pending_tasks); the HTTP server uses the same in-memory bus and queues.

evolve:: — context file

Evolve uses a single markdown file (path from [agent] context_path or DAL_AGENT_CONTEXT_PATH; default ./evolve.md).

Use these from DAL to keep the context file in sync with agent behavior (e.g. after answering a user or running a command). For evolution that actually helps the next turn, prefer append_working_memory for durable facts and load_recent_for_prompt (or COO’s built-in prompt path) instead of stuffing only raw action-log noise into context.

sh::run — shell execution

Use evolve::append_log after sh::run to record the action in the evolve file.

7. Molds

Molds are reusable agent configs (type, role, capabilities, trust, memory, lifecycle hooks). They can be local files or IPFS/on-chain.

Mold format (canonical)

Mold structure (.mold.dal)

CLI

Principal vs mold: trust and evolve path

When you create or serve an agent from a mold, trust (shell execution) and evolve path (context file) always come from the process (agent.toml, dal.toml, or env), not from the mold. The mold can set role, capabilities, lifecycle, etc., but the operator controls trust and where evolution is stored. See COMPREHENSIVE_AGENT_AND_MOLD_PLANS.md §3–4.

From DAL

8. Shell trust and evolve context

Shell trust

sh::run(cmd) respects:

  1. DAL_AGENT_SHELL_TRUST — off | sandboxed | confirmed | trusted
  2. [agent.sh] in agent.toml or dal.toml: trust, optional forbidden_patterns, allowed_prefixes

If key-based gating is used and the check denies, config falls back to [agent.sh].

Evolve context path

  1. DAL_AGENT_CONTEXT_PATH — explicit path
  2. [agent] context_path in agent.toml or dal.toml
  3. Default: ./evolve.md

Multi-step tool loop (agent serve)

9. Persistent memory

Agent runtime state persists across restarts by default. No configuration is required — when you run dal agent serve, the runtime automatically saves and restores agent memory, tasks, messages, evolution data, and registered skills.

What persists

Backends

Backend Default? Config Notes
File (JSON) Yes DAL_AGENT_RUNTIME_PATH=./agent_runtime.json Atomic writes, human-readable
SQLite No DAL_AGENT_RUNTIME_BACKEND=sqlite WAL mode, higher throughput, requires sqlite-storage feature
Disabled No DAL_AGENT_RUNTIME_PERSIST=0 In-memory only, state lost on exit

Configuration

Set via environment variables or agent.toml / dal.toml:

# Environment variables
DAL_AGENT_RUNTIME_PERSIST=1          # 1 (default) or 0
DAL_AGENT_RUNTIME_BACKEND=file       # file (default) or sqlite
DAL_AGENT_RUNTIME_PATH=./my_state.json  # Custom path
# agent.toml
[agent.persistence]
enabled = true
backend = "file"
path = "./agent_runtime.json"

Behavior

For full details, see Persistent Agent Memory.

10. Skills and registry

Skills define what an agent can do. Each skill is a named bundle of tools and a description that gets included in the agent prompt at serve time.

Built-in skills

Four categories ship with every DAL install:

Category Skill name Tools
Development development read, write, search, run, lint, test, debug
Creative creative read, write, search, generate, transform
Office office read, write, search, run, schedule, email
Home home read, search, run, control, monitor

User-defined skills

Create .skill.dal files in your project's .dal/ directory (or set DAL_SKILLS_PATH):

// .dal/calendar.skill.dal
skill "my_calendar" {
  category "office"
  description "Manage my custom calendar app via CLI and API calls."
  tools "run" "search" "read" "write"
}

Skills are loaded at startup and included in the agent prompt when the agent's config references them by name.

Runtime skill registration

From DAL or Rust, register skills programmatically:

let skills = [{
    "name": "data_pipeline",
    "category": "development",
    "description": "Run ETL pipelines and data transformations.",
    "tools": ["run", "read", "write", "search"]
}];
agent::register_runtime_skills(skills);

Runtime-registered skills persist across restarts (stored in the agent runtime snapshot).

Programmatic encouragement

The skills system includes built-in guidance that helps agents discover and use tools effectively:

For full details, see Skills and Registry.

11. Capabilities and types

Agent types: ai, system, worker, custom:<name>.

Capabilities are per-type (built-in or registry) and per-agent (config/mold). Use agent::validate_capabilities(agent_type, required_capabilities) to check a type; at runtime, an agent context’s capabilities are set at spawn (from type initializer or from config/mold).

For how capabilities are defined, set, and validated, see AGENT_CAPABILITIES.md.

12. RAG (retrieval)

RAG (retrieval-augmented generation) in dist_agent_lang is a lexical MVP: chunks from your indexed corpus are attached to the agent prompt as context blocks when enabled.

Full behavior, corpus layout, and context_blocks with source: rag are documented in RAG_MVP_SPEC.md. Env reference: CONFIG.md.

13. MCP (IDE bridge)

MCP (Model Context Protocol) is not a DAL keyword or builtin. It is a host protocol: a small stdio process (often Node) forwards tool calls from an MCP-capable editor (e.g. Cursor) to your agent’s HTTP API — the same behavior as calling POST /message or /task with curl.

Language-wide mental model (HTTP first, MCP optional, LSP separate): IDE_AND_AGENT_INTEGRATION.md. Env index: CONFIG.md.

14. References