<p align="center">
  <h1 align="center">🕸️ agentkit-mesh</h1>
  <p align="center">
    <strong>Agent-to-agent discovery and delegation via MCP</strong>
  </p>
  <p align="center">
    <a href="https://www.npmjs.com/package/agentkit-mesh"><img src="https://img.shields.io/npm/v/agentkit-mesh?label=npm" alt="npm version"></a>
    <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
    <a href="https://github.com/agentkitai/agentkit-mesh/actions"><img src="https://img.shields.io/github/actions/workflow/status/agentkitai/agentkit-mesh/ci.yml?branch=main" alt="CI"></a>
  </p>
</p>

---

Agents register their capabilities, discover each other by keyword / token-overlap matching, and delegate tasks. Registration and discovery are exposed as standard MCP tools; delegation is performed over HTTP (`POST /task`) to each agent's registered endpoint.

## Quick Start

```bash
npx agentkit-mesh
```

This starts an MCP server over stdio, ready to connect to Claude Desktop, OpenClaw, or any MCP client.

## MCP Configuration

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "agentkit-mesh": {
      "command": "npx",
      "args": ["agentkit-mesh"]
    }
  }
}
```

### OpenClaw

Add to your OpenClaw config:

```yaml
mcp:
  agentkit-mesh:
    command: npx agentkit-mesh
```

## Architecture

```
┌─────────────┐     MCP      ┌──────────────────┐
│  AI Agent A  │◄────────────►│                  │
└─────────────┘              │  agentkit-mesh   │
                             │                  │
┌─────────────┐     MCP      │  ┌────────────┐  │
│  AI Agent B  │◄────────────►│  │  Registry   │  │
└─────────────┘              │  │  (SQLite)   │  │
                             │  └────────────┘  │
┌─────────────┐     MCP      │  ┌────────────┐  │
│  AI Agent C  │◄────────────►│  │  Discovery  │  │
└─────────────┘              │  └────────────┘  │
                             │  ┌────────────┐  │
                             │  │ Delegation  │  │
                             │  └────────────┘  │
                             └──────────────────┘
```

## MCP Tools

### `mesh_register`

Register an agent with its capabilities.

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Unique agent name |
| `description` | string | What this agent does |
| `capabilities` | string[] | List of capabilities |
| `endpoint` | string | Agent's HTTP callback URL — receives `POST /task` (e.g. `http://host:port/task`) |

### `mesh_discover`

Discover agents whose description / capabilities overlap with the query tokens.
Matching is plain keyword / token-overlap (no embeddings or semantic search):
the query is lowercased and split into tokens, and each agent is scored by the
fraction of query tokens found in its description + capabilities.

| Parameter | Type | Description |
|-----------|------|-------------|
| `query` | string | Search query (e.g. "budget management") |
| `limit` | number? | Max results to return |

Returns agents ranked by token-overlap score with the matched capability tokens.

### `mesh_unregister`

Remove an agent from the registry.

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Agent name to remove |

### `mesh_delegate`

Delegate a task to another agent by name.

| Parameter | Type | Description |
|-----------|------|-------------|
| `targetName` | string | Name of the target agent |
| `task` | string | Task description to delegate |
| `context` | string? | Optional JSON context |

Delegation does **not** go over MCP. The mesh sends an HTTP `POST` to the target
agent's registered `endpoint` (its `POST /task` URL). Any agent that exposes such
an HTTP endpoint can participate — no MCP server required on the target side.

### Agent `POST /task` contract

The target agent must accept a JSON request body of the form:

```json
{
  "delegationId": "uuid",
  "task": "Get budget and cost center for Engineering",
  "context": { "depth": 1 },
  "callbackUrl": "http://mesh-host:8766/v1/delegations/<id>/result"
}
```

(`callbackUrl` is only present for async delegations.) The agent responds with one of:

- **Synchronous:** HTTP `200` and a JSON body `{ "result": "..." }` (or any JSON; it
  is returned to the caller as the delegation result).
- **Asynchronous:** HTTP `202` to accept the task, then later `POST` the result to
  `callbackUrl` with `{ "status": "completed" | "failed", "result"?: ..., "error"?: ... }`.
- **Failure:** any non-2xx status; the body text is surfaced as the error.

If the registered agent has `auth` configured, the mesh attaches it (e.g.
`Authorization: Bearer <token>`) to the outgoing request.

### Delegating over HTTP directly

The mesh also exposes the delegation flow over its own HTTP control plane:

```bash
agentkit-mesh serve --port 8766          # start the HTTP control plane

curl -X POST http://localhost:8766/v1/delegate \
  -H "Authorization: Bearer $MESH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{ "targetName": "finance-agent", "task": "Get Engineering budget" }'
```

#### Securing the control plane

The `/v1/*` routes (register, discover, delegate, …) require a shared secret.
Configure it with environment variables before starting `serve`:

| Env var | Required | Description |
|---------|----------|-------------|
| `MESH_TOKEN` | **yes** | Shared secret. Clients must send `Authorization: Bearer <MESH_TOKEN>`. If unset, **all `/v1/*` requests return `401`** (fail-closed). |
| `MESH_CORS_ORIGIN` | no | Allowed browser origin for CORS. Defaults to `http://localhost:8766` (never `*`). |

`/health` stays open (no auth) for liveness probes. This is a single shared
bearer secret — there are no per-agent keys, scopes, or rotation.

## Use Case: FormBridge

An HR agent filling an expense form discovers the Finance agent:

```typescript
import { AgentRegistry, DiscoveryEngine } from 'agentkit-mesh';

const registry = new AgentRegistry();

// Agents register themselves
registry.register({
  name: 'finance-agent',
  description: 'Budget management and expense approval',
  capabilities: ['budget', 'cost_center', 'expense_approval'],
  endpoint: 'http://localhost:4002/task',
});

// HR agent discovers who can help with budget fields
const discovery = new DiscoveryEngine();
const results = discovery.discover('budget cost center', registry);
// → [{ agent: finance-agent, score: 0.67, matchedCapabilities: ['budget', 'cost', 'center'] }]
```

See [examples/](examples/) for a runnable demo.

## Discovery: keyword / token-overlap matching

Discovery ships as plain keyword / token-overlap matching only — there is no
embedding model or semantic search. `DiscoveryEngine.discover()` tokenizes the
query, scores each agent by the fraction of query tokens that appear in its
description + capabilities, and returns the matches ranked by that score.
Resource-requirement filtering (scheme/host-aware URI matching) can further
narrow results. That is the full extent of the matching algorithm.

## Programmatic API

```typescript
import { AgentRegistry, DiscoveryEngine, DelegationClient, createServer } from 'agentkit-mesh';
```

All classes are exported for direct use without the MCP server layer.

## 🤝 Contributing

Contributions are welcome! Fork the repo, make your changes, and open a pull request. For major changes, open an issue first to discuss what you'd like to change.

## 🧰 AgentKit Ecosystem

| Project | Description | |
|---------|-------------|-|
| [AgentLens](https://github.com/agentkitai/agentlens) | Observability & audit trail for AI agents | |
| [Lore](https://github.com/agentkitai/lore) | Cross-agent memory and lesson sharing | |
| [AgentGate](https://github.com/agentkitai/agentgate) | Human-in-the-loop approval gateway | |
| [FormBridge](https://github.com/agentkitai/formbridge) | Agent-human mixed-mode forms | |
| [AgentEval](https://github.com/agentkitai/agenteval) | Testing & evaluation framework | |
| **agentkit-mesh** | Agent discovery & delegation | ⬅️ you are here |
| [agentkit-cli](https://github.com/agentkitai/agentkit-cli) | Unified CLI orchestrator | |
| [agentkit-guardrails](https://github.com/agentkitai/agentkit-guardrails) | Reactive policy guardrails | |

## License

[MIT](LICENSE) © AgentKit AI