WorkGraph Example

This example models an assistant-style situation where incoming information, calendar context, and routine automation produce shared durable work.

Scenario

A calendar event says L is driving to a client visit on May 20 and the visit plan assumes pool car P. A new maintenance update says car P is in the workshop. The client expects a punctual arrival, so L should receive a reminder the day before the visit. WorkGraph does not infer the team policy. The agent reasons about the data, then records the durable commitment and dependencies. The standard persistent host grants the default namespace, so every call in this example uses default. An embedding host may use logistics instead only if it issues that exact namespace in the session’s WorkGraphNamespaceGrant.

1. Create The Work Items

{
  "tool": "workgraph_create",
  "arguments": {
    "namespace": "default",
    "title": "Verify client visit transport details",
    "description": "Confirm visit time, driver, planned car status, and replacement car.",
    "priority": "high",
    "labels": ["team-logistics", "transport"],
    "external_refs": [
      { "kind": "calendar_event", "id": "client-visit-2026-05-20" },
      { "kind": "maintenance_record", "id": "car-p-workshop-2026-05-18" }
    ]
  }
}

{
  "tool": "workgraph_create",
  "arguments": {
    "namespace": "default",
    "title": "Prepare L reminder for client visit transport change",
    "description": "Tell L that car P is unavailable and name the replacement car.",
    "priority": "high",
    "labels": ["team-logistics", "travel"],
    "due_at": "2026-05-19T08:00:00Z",
    "external_refs": [
      { "kind": "calendar_event", "id": "client-visit-2026-05-20" }
    ]
  }
}

2. Link The Dependency

{
  "tool": "workgraph_link",
  "arguments": {
    "namespace": "default",
    "kind": "blocks",
    "from_id": "work_verify_transport",
    "to_id": "work_prepare_l_reminder"
  }
}

The reminder item should not be ready until transport details are verified.

3. Ask WorkGraph What Is Ready

{
  "tool": "workgraph_ready",
  "arguments": {
    "namespace": "default",
    "labels": ["team-logistics"],
    "limit": 10
  }
}

The agent does not inspect blocker counts itself. It works from the ready list returned by WorkGraph.

4. Claim, Act, And Add Evidence

{
  "tool": "workgraph_claim",
  "arguments": {
    "namespace": "default",
    "id": "work_verify_transport",
    "expected_revision": 1,
    "owner": {
      "key": { "kind": "agent", "id": "example/logistics" },
      "display_name": "Example logistics"
    },
    "lease_seconds": 1200
  }
}

After checking the maintenance and vehicle data, the agent attaches evidence.

{
  "tool": "workgraph_add_evidence",
  "arguments": {
    "namespace": "default",
    "id": "work_verify_transport",
    "expected_revision": 2,
    "evidence": {
      "kind": "summary",
      "id": "transport-check-2026-05-18",
      "label": "Transport verified",
      "summary": "Car P is in workshop; replacement car is car Q."
    }
  }
}

Then it closes the blocker.

{
  "tool": "workgraph_close",
  "arguments": {
    "namespace": "default",
    "id": "work_verify_transport",
    "expected_revision": 3,
    "status": "completed"
  }
}

The dependent reminder can now become ready when its time gates allow it.

5. Join Work Under A Parent

Create a coordination item with explicit child terminal policies:

{
  "tool": "workgraph_create",
  "arguments": {
    "namespace": "default",
    "title": "Coordinate client visit transport change",
    "priority": "high",
    "failed_child_join_policy": "propagate",
    "cancelled_child_join_policy": "accept"
  }
}

Link each child to the returned parent ID. A parent edge points from child to parent. The first edge is shown below:

{
  "tool": "workgraph_link",
  "arguments": {
    "namespace": "default",
    "kind": "parent",
    "from_id": "work_verify_transport",
    "to_id": "work_coordinate_visit_change"
  }
}

The parent remains unready while the reminder child is active. A failed direct child propagates failure when the join is next observed; a cancelled direct child is accepted by this parent’s policy.

6. Put A Goal In A Session’s Attention

A trusted local operator can create a WorkItem and attention binding together:

rkat --realm home workgraph goal-create SESSION_ID \
  "Review client visit transport preparation" \
  --namespace default \
  --mode review \
  --completion-policy self-attest \
  --json

The binding projects the goal into that session without making the session the owner of graph truth. Pausing attention pauses projection, not the WorkItem.

7. Observe The Graph

A UI or operator can inspect the same realm without mutating it:

rkat --realm home workgraph snapshot --namespace default --json

or:

curl "http://127.0.0.1:8080/workgraph/snapshot?namespace=default"

Why This Is Not An Expert System

The LLM decides what matters from calendar data, maintenance records, team preferences, and user policy. WorkGraph only records the durable to-do spine: dependencies, readiness, claim state, evidence, and terminal truth.

Getting started

Concepts

Guides: Models And Hosting

Guides: Runtime Behavior

Guides: Orchestration

Examples: Foundations

Examples: Capabilities

Examples: Orchestration And Deployment

WorkGraph Example

WorkGraph Example

Scenario

1. Create The Work Items

2. Link The Dependency

3. Ask WorkGraph What Is Ready

4. Claim, Act, And Add Evidence

5. Join Work Under A Parent

6. Put A Goal In A Session’s Attention

7. Observe The Graph

Why This Is Not An Expert System

​WorkGraph Example

​Scenario

​1. Create The Work Items

​2. Link The Dependency

​3. Ask WorkGraph What Is Ready

​4. Claim, Act, And Add Evidence

​5. Join Work Under A Parent

​6. Put A Goal In A Session’s Attention

​7. Observe The Graph

​Why This Is Not An Expert System

WorkGraph Example

Scenario

1. Create The Work Items

2. Link The Dependency

3. Ask WorkGraph What Is Ready

4. Claim, Act, And Add Evidence

5. Join Work Under A Parent

6. Put A Goal In A Session’s Attention

7. Observe The Graph

Why This Is Not An Expert System