Agents and Tasks

Agents and tasks are core concepts in Lattice. Understanding them is essential to building with Lattice.

What is an Agent?

An agent is an autonomous AI worker that executes a task on your behalf. Once started, an agent works independently to complete its task, and you can check on its progress or stop it if needed.

Creating an Agent

Start a new agent with a task:

bash

ada agents start "Analyze the code in my project and identify potential improvements"

The daemon creates a new agent with a unique ID and returns immediately. The agent runs in the background.

Output:

Agent ID: agent_abc123
Status: running
Task: Analyze the code in my project and identify potential improvements

Agent Lifecycle

START → RUNNING → COMPLETED (or FAILED or STOPPED)

START: Agent is created with a task

bash

ada agents start "Write unit tests for my API"
# Agent ID: agent_def456

RUNNING: Agent actively executes its task

The daemon manages the agent's execution:

Sends the task to the configured LLM provider
LLM processes and generates output
Agent receives and processes the response
Agent updates its status

COMPLETED: Agent finished successfully

bash

ada agents status agent_def456
# Status: completed
# Result: [output from agent]

FAILED: Agent encountered an error

bash

ada agents status agent_def456
# Status: failed
# Error: [error message]

STOPPED: Agent was manually stopped

bash

ada agents stop agent_def456
# Agent stopped by user

Agents vs Sessions

Important: Agents are different from chat sessions.

Aspect	Agents	Sessions
What they are	Autonomous workers executing tasks	Chat conversation history
How you create them	`ada agents start <TASK>`	`ada chat` (automatic)
How they run	Background, independent	Interactive, requires user input
Persistence	Survive terminal close	Saved for later resumption
Use case	Automated work, background jobs	Interactive conversations

Agent example:

bash

ada agents start "Summarize all files in my project"
# Runs in background until done

Session example:

bash

ada chat
# Interactive conversation you control

What is a Task?

A task is a unit of work you assign to an agent. It's the specific thing you're asking the agent to do.

Task Examples

bash

# Analytical task
ada agents start "Review the authentication code and identify security issues"

# Creative task
ada agents start "Generate a blog post outline about distributed systems"

# Coding task
ada agents start "Refactor the database queries to improve performance"

# Research task
ada agents start "Gather information about the latest AI trends"

Task Execution

When you submit a task:

Daemon receives the task - ada agents start "..."
Agent created - Unique ID generated, stored in database
Task queued - Added to agent's work queue
Agent processes task - Sends to LLM provider
LLM generates response - Streams back through daemon
Agent returns result - Stored in local database
You check status - View results with ada agents status

Managing Agents

List All Agents

bash

ada agents list

Output:

ID               Type    Status      Created
──────────────────────────────────────────────────
agent_abc123     agent   completed   2024-12-22T10:30:00Z
agent_def456     agent   running     2024-12-22T10:35:00Z
agent_ghi789     agent   failed      2024-12-22T10:40:00Z

Check Agent Status

bash

ada agents status agent_abc123

Output:

Agent ID: agent_abc123
Status: completed
Task: Analyze the code and identify issues
Created: 2024-12-22T10:30:00Z
Completed: 2024-12-22T10:35:00Z
Result: Found 3 potential issues: [...]

Stop a Running Agent

bash

ada agents stop agent_def456

The agent gracefully stops and saves any partial results.

Agent Storage and Persistence

All agent data is stored in your local SQLite database:

~/.lovelace/lattice/lattice.db
├── agents table
│   ├── agent_abc123 (task: "Analyze code")
│   ├── agent_def456 (task: "Write tests")
│   └── agent_ghi789 (task: "Generate docs")
└── tasks table
    ├── Task 1 (for agent_abc123)
    ├── Task 2 (for agent_def456)
    └── Task 3 (for agent_ghi789)

Recovery After Restart

If the daemon crashes or you restart your computer:

bash

# Restart the daemon
lattice-ctl daemon start

# Previously running agents are recovered
ada agents list
# Shows agents that were running before the crash

Agent state is restored from the database. Long-running agents can resume from where they left off.

Workspace Agents

For team collaboration, Lattice supports workspace agents. These are agents tied to a workspace rather than running directly on your local machine.

bash

# Create a workspace agent
ada agents create --workspace-id <workspace-id> --task "Do some work"

# List workspace agents
ada agents list --workspace <workspace-id>

# Manage workspace agent lifecycle
ada agents status <agent-id>
ada agents stop <agent-id>
ada agents delete <agent-id>

Workspace agents can be paused, resumed, and checkpointed for advanced workflow scenarios.

Common Agent Patterns

Background Analysis

bash

# Start an analysis that runs in the background
ada agents start "Analyze all log files and summarize errors"

# Do other work while it runs
ada chat

# Check progress later
ada agents status agent_xyz

Batch Processing

bash

# Start multiple agents for different files
ada agents start "Process data/file1.csv"
ada agents start "Process data/file2.csv"
ada agents start "Process data/file3.csv"

# Monitor all agents
ada agents list

# Collect results
ada agents status agent_1
ada agents status agent_2
ada agents status agent_3

Supervision

bash

# Start an agent to continuously monitor something
ada agents start "Monitor system health every minute"

# Check its status periodically
ada agents status agent_monitor

# Stop when done
ada agents stop agent_monitor

Agents and Providers

Agents use your configured LLM provider:

bash

# Configure a provider first
ada config provider set anthropic --api-key sk-...

# Then agents use it automatically
ada agents start "Task description"

If you have multiple providers configured, agents use the active one:

bash

# Switch providers
ada config provider activate openai

# New agents use OpenAI
ada agents start "New task"

# Old agents used Anthropic (their provider doesn't change)

API/IPC Methods

If you're building clients that interact with lattice, the daemon exposes these IPC methods for agent management:

json

// Start agent
{
  "method": "startAgent",
  "params": { "task": "Task description" }
}

// Stop agent
{
  "method": "stopAgent",
  "params": { "agentId": "agent_abc123" }
}

// List agents
{
  "method": "listAgents",
  "params": {}
}

// Get agent status
{
  "method": "agents.get",
  "params": { "agentId": "agent_abc123" }
}

// Workspace agent management
{
  "method": "agents.create",
  "params": { "workspaceId": "...", "task": "..." }
}

Responses are JSON in the same format with success and data/error fields.

Key Differences: Agents vs Sessions

Use agents when you need:

Autonomous, unattended execution
Background processing
Fire-and-forget tasks
Long-running operations

Use sessions when you need:

Interactive conversation
Real-time feedback
User guidance
Multi-turn dialogue

Troubleshooting

Agent fails immediately

bash

# Check the error
ada agents status agent_xyz
# Status: failed
# Error: [error message]

# Common causes:
# - Task is unclear or too vague
# - Provider not configured
# - Provider API key invalid

Agent seems stuck

bash

# Check if it's actually running
ada agents status agent_xyz

# If stuck, stop it
ada agents stop agent_xyz

# Try a simpler task
ada agents start "Simple task"

Can't find agent ID

bash

# List all agents
ada agents list

# Find the one you're looking for
# Use the ID from the list
ada agents status <id-from-list>

Next Steps

Quickstart → - Get agents running
Sessions → - Interactive chat vs agents
Provider Configuration → - Configure LLM providers for agents
Privacy Model → - How agent data is stored

Lovelace Developer Portal

Agents and Tasks

What is an Agent?

Creating an Agent

Agent Lifecycle

Agents vs Sessions

What is a Task?

Task Examples

Task Execution

Managing Agents

List All Agents

Check Agent Status

Stop a Running Agent

Agent Storage and Persistence

Recovery After Restart

Workspace Agents

Common Agent Patterns

Background Analysis

Batch Processing

Supervision

Agents and Providers

API/IPC Methods

Key Differences: Agents vs Sessions

Troubleshooting

Agent fails immediately

Agent seems stuck

Can't find agent ID

Next Steps

Lovelace Developer Portal