> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/conversations-and-orchestration/capability-match-guide.md).

# Capability Matching

> The `capabilityMatch` behavior rule condition enables **config-driven agent discovery**. An orchestrating agent can dynamically find other agents that declare a specific skill, without hardcoding agent IDs. This is the foundation of EDDI's A2A (Agent-to-Agent) soft routing.

## How It Works

```
┌───────────────────────────┐
│  Agent A (Orchestrator)   │
│  behavior.json:           │
│    condition:              │
│      capabilityMatch       │
│      skill: "translation"  │
│                            │
│  If SUCCESS → action:      │
│    "delegate_to_translator"│
└──────────┬────────────────┘
           │ queries registry
           ▼
┌───────────────────────────┐
│  CapabilityRegistryService │
│                            │
│  Index:                    │
│  "translation" →           │
│    Agent B (confidence:high)│
│    Agent C (confidence:med) │
└──────────┬────────────────┘
           │ matched agent IDs
           ▼
┌───────────────────────────┐
│  Conversation Memory:      │
│  capabilityMatch.results = │
│  ["agent-b-id", "agent-c"] │
└───────────────────────────┘
```

1. **Agent B and C** declare capabilities in their `AgentConfiguration`:

   ```json
   { "capabilities": [{ "skill": "translation", "confidence": "high" }] }
   ```
2. **Agent A** (the orchestrator) uses `capabilityMatch` in its behavior rules
3. When the condition evaluates, it queries the `CapabilityRegistryService`
4. Matching agent IDs are stored in memory as `capabilityMatch.results`
5. Downstream tasks (group orchestration, httpCalls, LLM tools) can consume the results

***

## Configuration

### behavior.json

```json
{
  "name": "Route to specialist",
  "actions": ["delegate_to_specialist"],
  "conditions": [
    {
      "type": "capabilityMatch",
      "configs": {
        "skill": "language-translation",
        "strategy": "highest_confidence",
        "minResults": "1"
      }
    }
  ]
}
```

### Config Keys

| Key          | Required | Default              | Description                                                                 |
| ------------ | -------- | -------------------- | --------------------------------------------------------------------------- |
| `skill`      | Yes      | —                    | Skill name to search for (case-insensitive)                                 |
| `strategy`   | No       | `highest_confidence` | Selection strategy: `highest_confidence`, `round_robin`, `random`, or `all` |
| `minResults` | No       | `1`                  | Minimum number of matching agents for SUCCESS                               |

### Selection Strategies

| Strategy             | Behavior                                                                                                 |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| `highest_confidence` | Sort matches by confidence (high → medium → low)                                                         |
| `round_robin`        | Deterministic rotation — a per-skill counter advances one position on each query (for load distribution) |
| `random`             | Shuffle matches randomly                                                                                 |
| `all`                | Return all matches in natural order                                                                      |

***

## Template Variables

The `skill` and `strategy` values are **Qute template expressions** (single braces, as everywhere else in EDDI), resolved against the conversation memory at evaluation time, enabling dynamic routing. `minResults` is not templated: it is read as a literal integer when the rule is loaded, and a value that is not a number falls back to `1`.

```json
{
  "type": "capabilityMatch",
  "configs": {
    "skill": "{properties.requiredSkill}",
    "strategy": "{context.routingStrategy}",
    "minResults": "1"
  }
}
```

The `skill` and `strategy` values are resolved using `IMemoryItemConverter.convert(memory)` — the same data map available to system prompts and httpCalls templates.

* A `skill` that renders blank (for example because the property is not set yet) makes the condition **FAIL** without querying the registry.
* A `strategy` that renders blank falls back to `highest_confidence`.
* Double-brace `{{ … }}` is **not** Qute syntax and is not resolved; configs written that way (the form an earlier Javadoc showed) must be changed to single braces.

***

## Agent Capability Declaration

Agents declare capabilities in their `AgentConfiguration` (an agent's name lives on its descriptor, not here — the agent store rejects unknown fields such as `name` with a `400`):

```json
{
  "capabilities": [
    {
      "skill": "language-translation",
      "confidence": "high",
      "attributes": {
        "languages": "en,de,fr,es",
        "domain": "legal"
      }
    },
    {
      "skill": "summarization",
      "confidence": "medium",
      "attributes": {}
    }
  ]
}
```

### Capability Fields

| Field        | Required | Default  | Description                                             |
| ------------ | -------- | -------- | ------------------------------------------------------- |
| `skill`      | Yes      | —        | Unique skill identifier (lowercased for indexing)       |
| `confidence` | No       | `medium` | Self-declared confidence level: `high`, `medium`, `low` |
| `attributes` | No       | `{}`     | Key-value metadata for fine-grained filtering           |

***

## Consuming Results

When `capabilityMatch` evaluates to SUCCESS, the matching agent IDs are stored in conversation memory:

```
Memory key: capabilityMatch.results
Value: ["agent-b-id", "agent-c-id"]
```

### Example 1: Action Delegation

The simplest pattern — match a skill, then fire an action that another task (e.g., LLM, httpCalls) reacts to:

```json
{
  "name": "Delegate to translator",
  "actions": ["call_translation_agent"],
  "conditions": [
    {
      "type": "capabilityMatch",
      "configs": {
        "skill": "language-translation",
        "strategy": "highest_confidence",
        "minResults": "1"
      }
    }
  ]
}
```

The LLM task or httpCalls task listens for the `call_translation_agent` action and can access the discovered agents via memory.

### Example 2: Dynamic Group Composition

Use the discovered agents to dynamically compose a group conversation:

**behavior.json:**

```json
{
  "name": "Assemble expert panel",
  "actions": ["create_expert_group"],
  "conditions": [
    {
      "type": "capabilityMatch",
      "configs": {
        "skill": "legal-analysis",
        "strategy": "all",
        "minResults": "2"
      }
    }
  ]
}
```

The rule only decides *that* experts exist; assembling them is a separate step. EDDI has no built-in LLM tool that creates a group from an ordinary conversation. Groups are created and started through the MCP server or the REST API:

| Step                                        | MCP tool (EDDI's `/mcp` server)                                                                                           | REST                                   |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- |
| Create the panel from the matched agent IDs | `create_group` (`memberAgentIds` as a comma-separated list, `style` e.g. `ROUND_TABLE`)                                   | `POST /groupstore/groups`              |
| Run the discussion                          | `discuss_with_group` (waits for the result) or `start_group_discussion` (returns at once; poll `read_group_conversation`) | `POST /groups/{groupId}/conversations` |

The `create_expert_group` action is the signal for whatever client drives that (an MCP client such as an assistant connected to `/mcp`, or your own application calling REST) to act on the conversation's outcome.

Inside a group discussion that is already running, members can grow the panel themselves: with `dynamicAgents.enabled` and `dynamicAgents.allowRecruitment` set on the group, a member's LLM gets `findAgentsByCapability` to locate a specialist and `recruitAgent` to bring it in from the next round — see [Group Conversations](https://docs.labs.ai/conversations-and-orchestration/group-conversations.md#recruitment).

> The matched agent IDs are written with `storeData` into the current step's data store under the key `capabilityMatch.results`, so Java tasks and tools can read them. They are **not** reachable from a template: `{memory.current.*}` resolves against the step's `conversationOutput`, which only the `addConversationOutput*` methods populate — and the key itself contains a dot, so it would not be addressable as `.capabilityMatch.results` even if it were there.

### Example 3: Template-Based Routing with Properties

Use PropertySetter to capture the user's intent, then route dynamically — see [Template Variables](#template-variables) for how `{properties.requiredSkill}` is resolved.

**property.json (PropertySetterTask):**

```json
{
  "setOnActions": [{
    "actions": ["user_request_specialist"],
    "setProperties": [{
      "name": "requiredSkill",
      "valueString": "{memory.current.intent}",
      "scope": "conversation"
    }]
  }]
}
```

**behavior.json:**

```json
{
  "name": "Find specialist for user request",
  "actions": ["specialist_found"],
  "conditions": [
    {
      "type": "capabilityMatch",
      "configs": {
        "skill": "{properties.requiredSkill}",
        "strategy": "highest_confidence",
        "minResults": "1"
      }
    }
  ]
}
```

***

## Attribute Filtering

The `CapabilityRegistryService` also supports fine-grained attribute matching via the `findBySkillAndAttributes` API. This is available to in-process Java callers only — no REST endpoint, MCP tool or behavior rule config currently exposes attribute filtering (`/capabilities`, the A2A `/.well-known/capabilities` endpoint and the `findAgentsByCapability` tool all call the skill-only overload). Example:

```java
// Find translation agents that support German
var matches = registry.findBySkillAndAttributes(
    "language-translation",
    Map.of("languages", "de"),
    "highest_confidence"
);
```

Comma-separated attribute values are matched with `contains` — `"en,de,fr"` matches `"de"`.

***

## Metrics

The `CapabilityRegistryService` exposes metrics at `/q/metrics`:

| Metric                                       | Description                                                                                                                                                                                                    |
| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eddi.capability.query.count`                | Total number of capability queries                                                                                                                                                                             |
| `eddi.capability.query.time`                 | Query execution time distribution                                                                                                                                                                              |
| `eddi.capability.strategy.applied{strategy}` | How often each selection strategy was applied                                                                                                                                                                  |
| `eddi.capability.miss.count`                 | Queries for a skill that no registered agent offers. It is not incremented when candidates exist but are removed later by attribute or access filtering, so it does not count every query that returns nothing |

### Audit

Each selection made by a `capabilityMatch` condition writes a `CAPABILITY_SELECTION` audit entry carrying the skill, the strategy, the candidate agent ids and the selected agent id, so routing decisions can be reviewed afterwards. Collection is best-effort: no entry is written when auditing is disabled for the conversation or the collector fails, so do not treat the trail as complete (see [audit-ledger.md](https://docs.labs.ai/security-and-compliance/audit-ledger.md)).

### REST

The registry can also be queried over REST with `GET /capabilities` and `GET /capabilities/skills` (admin and editor roles).

***

## ContentTypeMatcher — Attachment Routing

A companion condition for routing based on **attachment MIME types**:

```json
{
  "name": "Process image attachments",
  "actions": ["analyze_image"],
  "conditions": [
    {
      "type": "contentTypeMatcher",
      "configs": {
        "mimeType": "image/*",
        "minCount": "1"
      }
    }
  ]
}
```

| Config     | Default | Description                                                      |
| ---------- | ------- | ---------------------------------------------------------------- |
| `mimeType` | —       | MIME type pattern (supports `*/*`, `image/*`, `application/pdf`) |
| `minCount` | `1`     | Minimum number of matching attachments                           |

This condition reads from the `attachments` memory key populated by the attachment pipeline (see `docs/attachments-guide.md`).
