Concepts

Agents

An agent is an autonomous worker backed by an LLM. It has:

• A role — the system prompt that defines its personality and capabilities
• A model — the underlying LLM (Claude, GPT-4o, etc.)
• Optional MCP servers — external tools the agent can invoke
• A manager — another agent it reports to (enables hierarchies)

Agents are stateful across tasks. They remember previous interactions through the message bus and can receive tasks from other agents, from humans, or via the API.

Agent statuses:

• active — ready to accept tasks
• running — currently executing a task
• paused — manually paused; will not accept new tasks
• archived — soft-deleted; hidden from the main view

Tasks

A task is a unit of work assigned to an agent. Every task has:

• title — short human-readable label
• input — the full prompt or payload sent to the agent
• assignee — the agent that will run it
• requester — the agent or user that created it (optional)
• priority — low, normal, or high
• status — see lifecycle below

Task lifecycle

pending → running → done
                  ↘ error
                  ↘ waiting  (blocked on approval)

Tasks in waiting status are paused until a human approves or rejects them. This is useful for high-stakes actions (e.g. sending an email, deploying code).

Epics

An epic is a container for related tasks. Use epics to group work by project, sprint, or goal. Epics track overall progress as a percentage of completed tasks and expose a timeline view.

Epic types: feature, marketing, qa,research, ops.

Message Bus

The message bus is FleetRun's internal event stream. Every significant event is published to the bus:

• Task state changes (task.started, task.done, task.error)
• Agent-to-agent messages (agent.message)
• Tool call results (tool.result)
• Human approvals (approval.granted, approval.rejected)
• System events (agent.paused, provider.error)

All messages are stored in the database and visible in the Bus view. You can filter by type, agent, and time range.

Agents can also subscribe to the bus via their role prompt. For example, a supervisor agent can react to task.error events and automatically spawn a recovery task.

Secrets

Secrets are encrypted key-value pairs scoped to an agent or to the whole org. Agents reference secrets in their role prompts using the {secret:MY_KEY} placeholder syntax, which is substituted at runtime before the prompt is sent to the LLM.

Secrets are never logged or included in message bus events. They are decrypted only at execution time, inside the agent worker process.

• Org-scoped — available to all agents
• Agent-scoped — available only to the owning agent

MCP Servers

MCP (Model Context Protocol) is the open standard for connecting LLMs to external tools. FleetRun ships with 16 built-in MCP integrations (Slack, GitHub, Linear, etc.) and supports custom MCP servers via stdio or HTTP transport.

Each MCP server exposes a set of tools the agent can call. Tool calls are visible in real time in the task dock and logged to the message bus.

Adding a custom MCP server

// In Settings → MCPs, add a custom server:
{
  "name": "my-tool",
  "transport": "stdio",
  "command": "node",
  "args": ["/path/to/mcp-server.js"],
  "env": {
    "API_KEY": "{secret:MY_API_KEY}"
  }
}

The agent worker spawns the MCP server as a child process. Tool schemas are fetched via the MCP initialize handshake and injected into the LLM context.

Providers

A provider is a configured LLM API connection. Each provider has a key, a base URL, and a list of models. FleetRun validates the key on save and surfaces model availability in the agent creation wizard.

Supported providers: Anthropic, OpenAI, OpenRouter, Azure OpenAI, Ollama (local).

Teams

Teams are groups of agents with a shared purpose. Assigning agents to a team makes it easy to delegate tasks to a group rather than a specific agent. FleetRun will route the task to the most available agent in the team based on current load.