Intent & Expertise

Two primitives for agent coordination: intent prevents collisions, expertise enables routing.

Intent: "I'm about to do this"

Before an agent takes a significant action on an entity, it declares its intent. Other agents checking the same entity see the intent and can avoid conflicts.

{
  "tool": "declare_intent",
  "arguments": {
    "entity_id": "ENT_7f82",
    "action": "Syncing to Salesforce",
    "ttl_seconds": 300
  }
}

Intents are short-lived - they auto-expire after the TTL (default: 5 minutes). They're stored as memory entries with entry_type: "intent" and automatically cleaned up.

Why Intents Matter

Without intents:

Agent A: Resolves ENT_7f82, starts syncing to Salesforce
Agent B: Resolves ENT_7f82, also starts syncing to Salesforce
Result: Duplicate sync, potential data corruption

With intents:

Agent A: Declares intent "Syncing to Salesforce" on ENT_7f82
Agent B: Resolves ENT_7f82, sees Agent A's intent
Agent B: Skips sync, moves to next entity
Result: No conflict

Checking Intents

When you call resolve_with_memory, active intents are included in the memory response. Agents should check for intents before taking action:

{
  "tool": "resolve_with_memory",
  "arguments": {
    "source_name": "crm",
    "external_id": "cus_123",
    "data": { "email": "[email protected]" }
  }
}

Response includes:

{
  "entity_id": "ENT_7f82",
  "memory": [
    {
      "entry_type": "intent",
      "title": "Syncing to Salesforce",
      "author": "crm-agent",
      "created_at": "2026-03-06T14:30:00Z",
      "metadata": { "ttl_seconds": 300 }
    }
  ]
}

Expertise: "Who knows about this?"

Query which agents have experience with a particular entity or domain. Useful for routing work to the right agent.

{
  "tool": "query_expertise",
  "arguments": {
    "domain": "salesforce",
    "entity_id": "ENT_7f82"
  }
}

Response:

{
  "experts": [
    {
      "agent": "crm-agent",
      "entries": 12,
      "last_active": "2026-03-06T14:30:00Z",
      "domains": ["salesforce", "crm", "sync"]
    }
  ]
}

Expertise is derived from memory entries. An agent that has stored many decisions, investigations, or patterns about Salesforce entities is considered an expert in that domain.

Storing Expertise

Agents declare expertise explicitly:

{
  "tool": "memorize",
  "arguments": {
    "entity_id": "ENT_7f82",
    "entry_type": "expertise",
    "slug": "salesforce-sync-expert",
    "title": "Salesforce sync specialist",
    "content": "Handles all CRM sync operations. Knows Salesforce API limits and field mappings."
  }
}

Use Cases

• Task routing: Before creating a task, query expertise to find the best agent for the job
• Escalation: If a general agent encounters a domain-specific issue, find the expert agent
• Load balancing: Distribute work based on agent expertise and current activity

API

Declare Intent

POST /v1/memory
Content-Type: application/json
X-API-Key: kn_live_...

{
  "entry_type": "intent",
  "slug": "sync-ent-7f82",
  "title": "Syncing to Salesforce",
  "content": "Agent is currently syncing this entity to Salesforce.",
  "linked_entities": ["ENT_7f82"],
  "author": "crm-agent",
  "metadata": {
    "ttl_seconds": 300
  }
}

Query Expertise

GET /v1/memory/search?entry_type=expertise&q=salesforce
X-API-Key: kn_live_...

MCP Tools

Tool	Description
declare_intent	Declare what you're about to do (auto-expires)
query_expertise	Find agents with experience in a domain

Best Practices

• Always declare intent before mutations. Merges, splits, CRM syncs, external API calls - anything that changes state should have an intent declared first.
• Keep TTLs short. 5 minutes is usually enough. If your operation takes longer, extend the TTL.
• Use expertise for routing, not authentication. Expertise tells you who CAN do something, not who is ALLOWED to. Use RBAC for permissions.
• Check intents in resolve_with_memory. The MCP server instructions tell agents to use resolve_with_memory instead of plain resolve. This ensures they see active intents.