agent-pulse

💓 Pulse API Reference

Agent presence and liveness. Send heartbeats to report status, track what each agent is doing, and query which agents are alive — all in real time via WebSocket or REST.

✅ Live — agent-pulse is available now. Create a project to get your API key.

🔑 Base URL: https://api.agenttool.dev/v1/pulse · All endpoints require Authorization: Bearer YOUR_API_KEY

Why agent presence?

In multi-agent systems, knowing which agents are alive and what they're doing is fundamental. Without presence tracking:

  • Coordination fails — agents can't delegate to peers they can't see
  • Failures go silent — a crashed agent looks the same as an idle one
  • Dashboards are blind — operators have no visibility into fleet state
  • Recovery stalls — no way to detect and restart stalled agents

agent-pulse gives every agent a heartbeat — a lightweight signal that says "I'm here, and here's what I'm doing."

Status Values

StatusMeaning
"idle"Agent is alive but not actively working
"thinking"Agent is processing or reasoning
"learning"Agent is ingesting data or updating models
"error"Agent encountered an error and needs attention

Send Heartbeat

PUT /v1/pulse/{id}

Send a heartbeat for an agent. Creates the agent's presence record on first call, updates it on subsequent calls. Agents that stop sending heartbeats are marked stale after 60 seconds.

Request Body

FieldTypeRequiredDescription
statusstring✓"idle", "thinking", "learning", or "error"
taskstringShort description of current task
metadataobjectArbitrary key-value metadata
didstringDecentralized identifier for cross-system identity
curl 
curl -X PUT https://api.agenttool.dev/v1/pulse/my-agent \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "thinking",
    "task": "processing user query",
    "metadata": {"model": "claude-opus-4-6", "queue_depth": 3}
  }'
Response · 200
{
  "id": "my-agent",
  "status": "thinking",
  "task": "processing user query",
  "last_heartbeat": "2026-03-22T14:30:00Z",
  "alive": true
}
SDK · TypeScript
import { AgentTool } from "@agenttool/sdk"  // v0.5.1
const at = new AgentTool()

await at.pulse.heartbeat("my-agent", { status: "thinking", task: "processing" })
SDK · Python
from agenttool import AgentTool  # v0.5.1
at = AgentTool()

at.pulse.heartbeat("my-agent", "thinking", task="processing user query")

Get Agent State

GET /v1/pulse/{id}

Retrieve the current state of a specific agent — status, task, last heartbeat time, and whether it's still alive.

curl 
curl https://api.agenttool.dev/v1/pulse/my-agent \
  -H "Authorization: Bearer YOUR_API_KEY"
Response · 200
{
  "id": "my-agent",
  "status": "thinking",
  "task": "processing user query",
  "metadata": { "model": "claude-opus-4-6", "queue_depth": 3 },
  "last_heartbeat": "2026-03-22T14:30:00Z",
  "alive": true
}
SDK · TypeScript
const state = await at.pulse.get("my-agent")
console.log(state.status, state.task)  // "thinking" "processing user query"
SDK · Python
state = at.pulse.get("my-agent")
print(state.status, state.task)  # "thinking" "processing user query"

List Alive Agents

GET /v1/pulse

List all agents that have sent a heartbeat within the liveness window. Returns each agent's current status and task.

curl 
curl https://api.agenttool.dev/v1/pulse \
  -H "Authorization: Bearer YOUR_API_KEY"
Response · 200
{
  "agents": [
    {
      "id": "my-agent",
      "status": "thinking",
      "task": "processing user query",
      "last_heartbeat": "2026-03-22T14:30:00Z",
      "alive": true
    },
    {
      "id": "search-agent",
      "status": "idle",
      "task": null,
      "last_heartbeat": "2026-03-22T14:29:45Z",
      "alive": true
    }
  ],
  "count": 2
}
SDK · TypeScript
const { agents } = await at.pulse.list()
for (const agent of agents) {
  console.log(`${agent.id}: ${agent.status}`)
}
SDK · Python
agents = at.pulse.list()
for agent in agents:
    print(f"{agent.id}: {agent.status}")

SDK Quick Reference

📦 Install: pip install agenttool-sdk or npm install @agenttool/sdk · SDK v0.5.1+

TypeScript / JavaScript
import { AgentTool } from "@agenttool/sdk"  // v0.5.1
const at = new AgentTool()  // reads AT_API_KEY from env

// Send heartbeat
await at.pulse.heartbeat("my-agent", { status: "thinking", task: "processing" })

// Get single agent state
const state = await at.pulse.get("my-agent")

// List all alive agents
const { agents } = await at.pulse.list()
Python
from agenttool import AgentTool  # v0.5.1
at = AgentTool()  # reads AT_API_KEY from env

# Send heartbeat
at.pulse.heartbeat("my-agent", "thinking", task="processing user query")

# Get single agent state
state = at.pulse.get("my-agent")

# List all alive agents
agents = at.pulse.list()

Use Cases

📡 Fleet monitoring
Build dashboards that show every agent's status in real time. Know instantly when an agent goes down or enters an error state.

🔄 Auto-recovery
Detect stale agents and automatically restart them. Combine with webhooks to trigger recovery workflows when heartbeats stop.

🤝 Agent coordination
Agents check peer status before delegating tasks. Only route work to agents that are alive and idle — avoid sending tasks into the void.

📊 Capacity planning
Track how many agents are thinking vs idle over time. Use metadata fields to monitor queue depth and model usage across your fleet.