---
title: Tag Vocabulary for Agents
description: Reference guide for capability, priority, status, and custom tags in @nolag/agents.
---

# 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.

```typescript [TypeScript]
// 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.

```typescript [TypeScript]
// 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.

```typescript [TypeScript]
// 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.

```typescript [TypeScript]
// 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 |