Skip to main content

​
WorkGraph

Use this guide when an agent should coordinate durable work across sessions, compaction, restarts, schedules, or multiple agents.
Agents write general WorkGraph items through tools. RPC and REST are public observability surfaces; the CLI also has narrow session-goal and attention controls for trusted local operators.

​
Create Work

Use workgraph_create for a durable commitment. 
{
  "title": "Prepare dentist transport reminder",
  "description": "Create a reminder for L to explain to A that car P is in the workshop.",
  "namespace": "homecare",
  "priority": "high",
  "labels": ["family-logistics", "autism-support"],
  "due_at": "2026-05-19T08:00:00Z",
  "external_refs": [
    {
      "kind": "calendar_event",
      "id": "dentist-a-2026-05-20"
    }
  ]
}
Use workgraph_link to describe relationships. 
{
  "kind": "blocks",
  "from_id": "work_check_car_status",
  "to_id": "work_prepare_dentist_reminder",
  "namespace": "homecare"
}
For blocks, the target is not ready until the blocker is terminally resolved. Use related, parent, supersedes, or derived_from when readiness should not be blocked.

​
Find Ready Work

Use workgraph_ready instead of inferring readiness. 
{
  "namespace": "homecare",
  "labels": ["family-logistics"],
  "limit": 10
}
Ready work is non-terminal, not blocked, due or eligible, and claimable.

​
Claim Before Shared Work

Use workgraph_claim before doing durable work. Include the current expected_revision. 
{
  "id": "work_prepare_dentist_reminder",
  "namespace": "homecare",
  "expected_revision": 3,
  "owner": {
    "key": { "kind": "agent", "id": "homecore/logistics-agent" },
    "display_name": "Homecore logistics agent"
  },
  "lease_seconds": 1800
}
If a write returns a stale revision error, reload with workgraph_get or workgraph_snapshot, then decide whether the action still makes sense.

​
Update And Add Evidence

Use workgraph_update for title, description, priority, labels, due gates, and external references. Use workgraph_add_evidence for proof of progress or completion. 
{
  "id": "work_prepare_dentist_reminder",
  "namespace": "homecare",
  "expected_revision": 4,
  "evidence": {
    "kind": "notification",
    "id": "sms-draft-l-2026-05-19",
    "label": "Reminder prepared",
    "summary": "Reminder explains that car P is unavailable and names the replacement car."
  }
}
Evidence refs point to external or Meerkat-owned artifacts. WorkGraph stores the reference, not the artifact bytes.

​
Close Or Release

Use workgraph_close only when terminal truth exists. 
{
  "id": "work_prepare_dentist_reminder",
  "namespace": "homecare",
  "expected_revision": 5,
  "status": "completed"
}
Use workgraph_release if you stop before terminal completion and another agent should be able to claim the item.

​
Observe From Host Surfaces

Operators and UIs can inspect WorkGraph without broad graph mutation:
  • CLI: rkat workgraph list, show, ready, snapshot, events; plus narrow goal-* and attention-* controls for session-bound goals
  • REST: GET /workgraph/items, /workgraph/ready, /workgraph/snapshot, /workgraph/events, plus public POST /workgraph/goal/status and /workgraph/attention/list observability routes
  • RPC: workgraph/get, workgraph/list, workgraph/ready, workgraph/snapshot, workgraph/events, plus public workgraph/goal/status and workgraph/attention/list observability methods
Goal and attention mutation APIs are trusted in-process host/runtime authority. The CLI exposes only the local session-first subset it can complete safely; public REST and JSON-RPC keep these as observability-only.

​
Agent Instruction Manual

When skills are enabled and WorkGraph capability is available, agents can load the workgraph-workflow companion skill for operating guidance.