Skip to main content

Manage Agents

Lattice lets you run AI agents locally on your machine. There are two core primitives:

  • Agents – Autonomous background workers that execute tasks independently
  • Sessions – Interactive chat conversations with context history

Quick Reference

bash
# Start an autonomous agent
ada agents start "Analyze this codebase for security issues"

# Interactive chat session
ada chat

# List running agents
ada agents list

# List past sessions
ada sessions list

Agents

Agents are autonomous AI workers that run tasks in the background. You give them a task, they work independently, and you check on results later.

Start an Agent

bash
ada agents start "Your task description here"

Options:

  • --format <format> – Output format (text, json, table)
  • --wait – Wait for agent to complete before returning
  • --workspace <id> – Run agent in specific workspace

Example:

bash
ada agents start "Review the authentication code and suggest improvements" --wait

List Agents

bash
ada agents list

Options:

  • --verbose – Show detailed agent information
  • --format <format> – Output format (text, json, table, csv)
  • --workspace <id> – Filter by workspace

Check Agent Status

bash
ada agents status <agent_id>

Or check all agents:

bash
ada agents status

Stop an Agent

bash
ada agents stop <agent_id>

Options:

  • --force – Force stop without graceful shutdown
  • --yes – Skip confirmation prompt

Interactive Agent Dashboard

For a full-screen interactive view of all running agents:

bash
ada agents

This opens an interactive dashboard (requires TTY).

Sessions

Sessions are interactive chat conversations. Unlike agents, sessions are real-time back-and-forth conversations with context preserved across messages.

Start a Chat Session

bash
ada chat

Options:

  • --session <id> – Resume a specific session
  • --provider <name> – Use a specific LLM provider
  • --model <name> – Use a specific model
  • --no-daemon – Run without the lattice daemon

List Sessions

bash
ada sessions list

Options:

  • --verbose – Show detailed session information
  • --format <format> – Output format (text, json, table)
  • --session-type <type> – Filter by session type

Resume a Session

bash
ada sessions resume <session_id>

Or resume the most recent session:

bash
ada sessions resume

View Session Details

bash
ada sessions info <session_id>

Or view the last session:

bash
ada sessions info --last

Delete a Session

bash
ada sessions delete <session_id>

Options:

  • --force – Skip confirmation prompt

Workspaces

Workspaces organize your agents and sessions into logical groups.

List Workspaces

bash
ada workspaces list

Create a Workspace

bash
ada workspaces create --name "my-project" --description "Project workspace"

Set Active Workspace

bash
ada workspaces select --id <workspace_id>

Show Current Workspace

bash
ada workspaces current

Low-Level Control (lattice-ctl)

For advanced control, use lattice-ctl directly:

Agent Commands

bash
# Start agent
lattice-ctl agents start --name "my-agent"

# Stop agent
lattice-ctl agents stop <agent_id>

# List agents
lattice-ctl agents list

Session Commands

bash
# List sessions
lattice-ctl sessions list

# Get session details
lattice-ctl sessions get <session_id>

# Create session
lattice-ctl sessions create --workspace-id <id> --title "My Session"

# Delete session
lattice-ctl sessions delete <session_id>

Task Commands

bash
# Send task to agent
lattice-ctl tasks send --agent-id <id> --description "Task description"

# Check task status
lattice-ctl tasks status --agent-id <id> --task-id <task_id>

Agents vs Sessions: When to Use Which

Use CaseUse AgentsUse Sessions
Background analysis✓
Code review✓
Interactive debugging✓
Q&A conversation✓
Long-running automation✓
Real-time collaboration✓
Fire-and-forget tasks✓

Next Steps