Tag Vocabulary

Tags control task routing, prioritization, and filtering in @nolag/agents.

Capability Tags

Capability tags describe what a worker agent can do. When an orchestrator dispatches a task with required capabilities, only workers whose registered capabilities include all of the required tags will receive the task.

// Worker registers capabilities
room.handoff.register({
  capabilities: ["research", "finance", "summarization"],
});

// Orchestrator dispatches with required capabilities
await room.handoff.dispatch({
  type: "analyze-earnings",
  payload: { ticker: "ACME" },
  capabilities: ["research", "finance"],  // Worker must have BOTH tags
});

Common capability tags

Tag	Description
`research`	Web research, data gathering, source verification
`drafting`	Content creation, report writing, email composition
`review`	Quality review, fact-checking, compliance checks
`summarization`	Text summarization, key point extraction
`finance`	Financial analysis, calculations, reporting
`code`	Code generation, review, debugging
`translation`	Language translation, localization
`customer-support`	User queries, issue resolution, FAQ

These are conventions, not enforced values. Use any string that makes sense for your domain.

Priority Tags

Priority tags control the order in which workers process tasks. Workers process higher-priority tasks first when multiple tasks are queued. Workers can also filter which priority levels they accept.

// Dispatch with priority
await room.handoff.dispatch({
  type: "generate-report",
  payload: { ... },
  capabilities: ["drafting"],
  priority: "urgent",  // Workers process urgent tasks first
});

// Workers can filter by priority
room.handoff.register({
  capabilities: ["drafting"],
  priorityFilter: ["urgent", "normal"],  // Ignore "low" priority
});

Standard priority levels

Priority	Description
`urgent`	Processed immediately, preempts normal work
`normal`	Default priority for most tasks
`low`	Background work, processed when no higher-priority tasks are queued

Status Tags

Status tags are automatically managed by the Handoff pattern to track task lifecycle. You don't set these directly - they're emitted as events via the Observe pattern.

// Tasks have automatic status tracking
room.observe.on("task:dispatched", (e) => {
  // status: "pending"
});

room.observe.on("task:claimed", (e) => {
  // status: "in_progress"
});

room.observe.on("task:completed", (e) => {
  // status: "completed"
});

room.observe.on("task:failed", (e) => {
  // status: "failed"
});

Task status lifecycle

Status	Description
`pending`	Task dispatched, waiting for a worker to claim
`in_progress`	Worker has claimed the task and is processing
`completed`	Worker finished successfully
`failed`	Worker reported an error
`timed_out`	No worker claimed the task before the timeout

Custom Tags

Beyond capabilities and priorities, you can attach arbitrary key-value tags to both tasks and agents. Custom tags are useful for routing by department, region, confidentiality level, or any other dimension specific to your application.

// Custom tags on tasks
await room.handoff.dispatch({
  type: "review",
  payload: { document },
  capabilities: ["review"],
  tags: {
    department: "legal",
    region: "eu-west",
    confidentiality: "internal",
  },
});

// Custom tags on agents
room.handoff.register({
  capabilities: ["review"],
  tags: {
    department: "legal",
    clearance: "confidential",
  },
});

Custom tag patterns

Pattern	Example	Use case
Department routing	`department: "legal"`	Route tasks to department-specific agents
Region affinity	`region: "eu-west"`	Keep data processing within a geographic region
Tenant isolation	`tenantId: "acme-corp"`	Multi-tenant agent systems
Model selection	`model: "gpt-4"`	Route to agents running specific LLM models
Confidentiality	`confidentiality: "internal"`	Restrict sensitive tasks to cleared agents