HeartBeatAgents

Core Concepts

View as Markdown

Understand the fundamental building blocks of HeartBeatAgents: agents, conversations, tools, memory, channels, integrations, and standing orders.

HeartBeatAgents is built around a handful of core concepts. Understanding these will help you design effective agents and get the most out of the platform.

Agents

An agent is an autonomous AI entity with a defined role, personality, and set of capabilities. Each agent has a primary LLM provider and model, standing orders that govern its behavior, access to specific tools and channels, and its own memory store. Agents operate independently, and you can run multiple agents, each specialized for a different function (support, sales, engineering, etc.).

Key properties: name, description, provider, model, standing orders, autonomy level (Supervised, Semi-auto, Autonomous), status (active, paused, archived).

Conversations

A conversation is a thread of messages between a user and an agent. Conversations maintain state across multiple turns and can span hours, days, or weeks. Each conversation belongs to a specific agent and is associated with a specific channel: the primary unit of interaction, and the source of episodic memory.

Key properties: conversation ID, agent ID, channel, participant identities, message history, status (active, resolved, escalated), metadata.

Tools

Tools are discrete capabilities that an agent can invoke during a conversation. Each tool has a name, a description (which the LLM reads to understand when to use it), input parameters, and an execution handler. Every agent has a fixed set of these built in from the start, code execution, file access, memory, skills, delegating to other agents, and more, with no integration required. See Built-In Tools for the full list. Integrations add more on top: connect a Stripe integration, and tools like stripe_get_customer and stripe_create_refund become available.

Key properties: tool name, description, parameter schema, integration source (or "built-in"), required permissions, rate limits.

Planning

A goal stated in plain language is broken into a dependency-ordered sequence of steps, shown to you for approval, editing, or rejection, before anything runs. See Planning.

Live Preview

An agent can run a real dev server or long-running process inside its sandboxed workspace and hand you back a live, working preview, not a description of one. See Live Preview.

Delegation

An agent can hand a subtask to another agent it's been granted access to and get the result back, the same way a person delegates to a teammate. See Delegation.

Memory

Memory gives agents continuity across conversations, implemented as three types:

  • Episodic: Stores conversation history. Enables agents to recall prior interactions.
  • Semantic: Stores extracted facts and knowledge: preferences, account information, decisions.
  • Procedural: Stores learned behavioral patterns, so agents reuse successful multi-step processes for recurring task types.

All memory types use vector embeddings for retrieval, so agents find relevant memories by semantic similarity, not just keyword matching.

Channels

Channels are communication platforms where agents interact with users: Slack, Discord, Telegram, WhatsApp, and the built-in web chat. Each channel has its own adapter that normalizes messages into a standard format; an agent can be connected to multiple channels simultaneously, with conversations maintaining context regardless of which channel they occur on. See the Channels Guide for setup steps.

Voice

Voice is a real-time, spoken conversation with an agent in the browser, separate from the text-based channels above. It needs a LiveKit project (transport) and a speech provider (Deepgram or ElevenLabs) connected before it works. See Voice and Voice Setup.

Integrations

Integrations connect an agent to external services, typically authenticating via OAuth 2.0. Connecting an integration automatically discovers and exposes its tools to your agents: Google Workspace, Microsoft 365, GitHub, Jira, HubSpot, Salesforce, Stripe, Notion, and more. See the Integrations Guide for the full catalog and security model.

Standing Orders

Standing orders are persistent instructions that define an agent's behavior across all conversations. Unlike a single system prompt, they're structured (role definitions, behavioral rules, knowledge boundaries, escalation policies, operational limits), and every change is saved as a new version automatically, so there's always a record of what changed and when. They're the single most important factor in determining agent quality.

Key properties: order text, version number, created date, active status, associated agent, change history.

Scheduling an agent to run on its own, on a cron or interval trigger, is a related but separate feature: see Monitors.