Agents

Agents are the core unit of work in Lantern. An agent is a durable function that receives input, executes a series of steps (LLM calls, tool invocations, API requests), and produces output. This page covers how to create, configure, test, run, and schedule agents.

Creating an agent

There are three ways to create an agent from the dashboard:

1. AI-assisted creation

Describe what you want the agent to do in plain English. Lantern uses an LLM to generate the agent configuration, system prompt, and tool selection for you.

Navigate to Agents > New Agent and select AI-assisted. Enter a description like:

Monitor my GitHub repositories for new issues labeled "bug",
triage them by severity, and post a summary to Slack every morning.

The AI will propose a name, system prompt, model capability, connected tools, and a schedule. Review and adjust before creating.

[Screenshot: AI-assisted agent creation wizard]

2. Manual creation

For full control, use the manual creation form. You configure each field yourself:

• Name -- a unique identifier (lowercase, hyphens allowed)
• Description -- what this agent does (shown in the dashboard)
• System prompt -- the instructions the LLM follows
• Model -- the capability to use (e.g., "auto", "reasoning-large")
• Connectors -- which external services the agent can access
• Privacy level -- controls data handling (standard, strict, paranoid)

3. From a template

Lantern ships with built-in templates for common use cases: research agent, customer support, CI/CD guardian, and more. Select a template and customize it.

# From the CLI:
lantern init my-agent --template research

Configuring an agent

Instructions and system prompt

The system prompt is the most important configuration. It tells the LLM what role to play, what tools it has access to, and how to behave. Write clear, specific instructions:

You are a research assistant. When given a topic:
1. Generate 3-5 search queries
2. Search the web for each query
3. Read the top 3 results for each
4. Synthesize findings into a structured report with citations

Always cite your sources. If you cannot find reliable information,
say so rather than making things up.

Model selection

Lantern uses capability-based routing instead of hardcoded model names. This means your agent code never references "gpt-4" or "claude-3" directly. Instead, you specify what kind of capability you need:

• "auto" -- Lantern picks the best model for each step based on complexity and cost
• "reasoning-large" -- a powerful reasoning model (maps to Opus, GPT-5, etc.)
• "reasoning-small" -- a fast, cheap model for simple tasks (maps to Haiku, GPT-4o-mini, etc.)
• "code" -- optimized for code generation
• "vision" -- models that understand images

See Models for a full list of capabilities and how to configure providers.

Testing an agent

Every agent has a Playground tab in the dashboard. The playground lets you:

• Send test inputs and see streaming output in real time
• Inspect each step as it executes (timing, model used, tokens)
• Adjust the system prompt and re-run immediately
• View the full event stream and step trace

You can also run agents from the CLI for scripted testing:

lantern run my-agent \
  --input '{"topic": "quantum computing"}' \
  --stream

Running agents

Agents can be triggered in several ways:

• Dashboard playground -- manual runs for testing
• CLI -- lantern run <agent>
• REST API -- POST /api/agents/:name/runs
• Schedule -- cron-based recurring runs
• Surfaces -- triggered by messages on WhatsApp, Slack, etc.
• Webhooks -- triggered by external events (GitHub push, Stripe event, etc.)

Scheduling agents

You can schedule agents to run on a cron expression. See the Scheduling page for details on cron syntax, AI-assisted scheduling, and email delivery of results.

Agent lifecycle

Each agent run goes through these states:

1. Queued -- the run is waiting to be picked up
2. Running -- steps are actively executing
3. Completed -- all steps finished successfully
4. Failed -- a step failed after exhausting retries
5. Cancelled -- manually stopped by the user

Because Lantern uses durable execution, a run that crashes mid-step will automatically resume from the last completed step when the infrastructure recovers.