Docs / Examples

Field service example

A field-service company hosts dispatch, inventory, and customer communication capabilities behind governed CHP boundaries.

Plain English

The business can expose scheduling as a capability without giving every caller direct access to its dispatch system.

Why it exists

This example keeps the protocol grounded in a concrete operational workflow before explaining abstractions.

Formal definition

Field service maps schedule_technician, query_inventory, and notify_customer into separate hosted capability contracts with policy and evidence.

Concrete example

Ground the concept before the schema.

Planning Agent invokes schedule_technician at ServiceOpsHost under manager_approval and receives Confirmed Appointment.

schedule_technicianInvokable

Finds an available qualified technician and reserves a service window.

host: ServiceOpsHostpolicy: approval_requiredv1.0.0

Policy boundary

Approval required

manager_approval

A manager must approve technician scheduling before the host returns a confirmed appointment.

Invocation trace

  1. 01 Actor

    Planning Agent

  2. 02 Capability

    schedule_technician

  3. 03 Host

    ServiceOpsHost

  4. 04 Policy

    manager_approval

  5. 05 Context

    job_context

  6. 06 Result

    Confirmed Appointment

field-service-manifest.json
json
{  "id": "service-ops-host",  "version": "0.1.0",  "protocol_version": "0.1",  "kind": "service",  "capabilities": [{    "id": "schedule_technician",    "version": "1.0.0",    "description": "Finds an available qualified technician and reserves a service window.",    "status": "experimental",    "modes": ["sync"],    "emits": ["execution_started", "execution_completed", "execution_denied"],    "policy": {      "risk_tier": "high",      "auth_required": true,      "approval_required": true,      "allowed_actors": ["agent://planning-assistant"]    },    "metadata": {      "required_permissions": ["service:dispatch"],      "lifecycle": "invokable"    }  }],  "evidence": {    "store": "local-append-only",    "append_only": true  }}

Relationships

Where this sits in the protocol.

Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.

schedule_technician composes with query_inventory.

notify_customer runs after a confirmed appointment.

Evidence connects the full service workflow by correlation ID.

Visual model

  1. 01InventoryHost checks required parts.
  2. 02ServiceOpsHost schedules the technician.
  3. 03CustomerCommsHost sends the notification.

Implementation notes

  • Keep each host boundary separate.
  • Use one correlation ID across the composed workflow.
  • Test policy denial before connecting the workflow to an agent.

Common mistakes

  • Making one giant workflow capability for every step.
  • Hiding manager approval inside app glue.
  • Losing evidence across host boundaries.

Related concepts

Keep reading through the boundary.

Composition →Map your first capability →Examples →