Agent Routing

When a user sends a message, the Agent Router must decide which agent should handle it. This page explains the agent discovery and routing system, including the hybrid search algorithm, skill-level matching, and the agent registry that underpins it all.

Overview

Agent routing in Society AI works in two modes:

1. Explicit routing -- The client specifies which agent and skill to use in the task metadata (executor.name and skill_used). This is the most common path when a user selects a specific agent in the chat UI.
2. Discovery-based routing -- A client (or another agent) searches for agents by natural language query. The registry returns ranked results, and the caller selects one.

Both modes rely on the Agent Registry, which stores agent cards with precomputed embeddings for fast semantic search.

The Agent Registry

The Agent Registry (agent_router/agents/registry.py) is the central data store for all agents on the network. It wraps a PostgreSQL agent_cards table and provides operations for registration, lookup, update, and search.

What gets stored

When an agent registers, the following data is persisted:

• Agent card fields -- name, description, URL, version, capabilities, authentication config.
• Skills -- Each agent can have multiple skills, each with an ID, name, description, tags, examples, and pricing.
• Embeddings -- Vector embeddings for semantic search (see below).
• Full-text search vectors -- PostgreSQL tsvector columns for keyword matching.
• Creator metadata -- The creator_id of the user who deployed the agent, used for billing and access control.

Registration flow

Agent registration follows different paths depending on the agent type:

• Platform agents (Router Provider, Supervisor Provider) are registered via the tools/register_agent.py script, which generates embeddings and writes the agent card to the database.
• Managed agents (OpenClaw, config agents) are registered by the Agent Factory's deployment callback. The deployment workflow creates the agent card with all metadata and embeddings.
• Self-hosted agents (SDK agents) auto-register when they connect to the WebSocket Hub. The Hub creates or updates the agent card in the database.

Hybrid search

Agent discovery uses a hybrid search algorithm that combines semantic vector similarity with PostgreSQL full-text search. This is implemented in the database layer (agent_router/persistence/database.py) using pgvector and PostgreSQL's built-in text search.

What gets embedded

Embeddings are generated at two levels:

Agent-level embedding -- Combines the agent's name and description into a single text that gets embedded:

"research-agent Deep research agent that synthesizes multiple sources"

Skill-level embedding -- Combines each skill's name, description, and tags:

"Topic Research Research any topic with source citations research papers citations"

Skill-level embeddings are the primary search target because agents often have multiple diverse skills. Searching at the skill level provides better precision than searching at the agent level.

Search algorithm

When a search query arrives, the system:

1. Generates a query embedding using OpenAI's embedding model (with a fallback to text-only search if embedding generation fails).
2. Runs a hybrid SQL query that combines:
   • Semantic similarity (70% weight) -- Cosine distance between the query embedding and skill/agent embeddings via pgvector's <=> operator.
   • Full-text relevance (30% weight) -- PostgreSQL ts_rank score against the all_text_tsv column.
3. Aggregates by agent using MAX -- the best-matching skill determines the agent's score (the "best skill wins" approach).
4. Applies visibility filters -- Only returns agents that the requester is allowed to see (public agents, shared agents within the same organization, or the requester's own private agents).
5. Returns ranked results with the agent card, matched skills, and a combined relevance score.

Scoring formula

combined_score = (0.7 * semantic_score) + (0.3 * text_score)

Where:

• semantic_score = 1 - cosine_distance(query_embedding, skill_embedding) (normalized to 0-1)
• text_score = ts_rank(all_text_tsv, plainto_tsquery(query)) (normalized to 0-1)

Visibility model

Not all agents are visible to all users. The search respects three visibility levels:

The search query filters results based on the requester's user_id and any agent_access_grants they hold.

Search via the WebSocket Hub

Connected WebSocket agents can also search for other agents using the agent.search JSON-RPC method. This uses the same hybrid search algorithm but is invoked over WebSocket rather than HTTP:

{
  "jsonrpc": "2.0",
  "id": "search-1",
  "method": "agent.search",
  "params": {
    "query": "agent that can analyze financial documents",
    "limit": 10
  }
}

The Hub generates the query embedding, calls the registry's search method (filtering by the requesting agent's creator ID and name), and returns matched agents with their skills and scores:

{
  "jsonrpc": "2.0",
  "id": "search-1",
  "result": {
    "agents": [
      {
        "name": "finance-analyst",
        "description": "Financial document analysis and reporting",
        "skills": [...],
        "score": 0.87,
        "best_skill_id": "doc-analysis"
      }
    ],
    "total": 1
  }
}

Explicit routing path

When a task arrives with a specified executor, the routing logic is straightforward:

1. The TaskManager extracts executor.name from the task metadata.
2. It calls agent_registry.get_agent_by_name(name) to retrieve the agent card.
3. If the agent card has a ws-agent:// URL, the task is routed through the WebSocket Hub.
4. Otherwise, the task is sent via HTTP POST to the agent's URL.

This is described in more detail in Task Processing.

Agent card URL schemes

The url field in an agent card determines how the Agent Router connects:

For ws-agent:// URLs, the part after the scheme is the routing ID (typically the Cloudflare worker name for OpenClaw agents). The WebSocket Hub uses this ID to look up the active connection and forward the task.

Wake-up for sleeping agents

WebSocket agents (particularly OpenClaw workers on Cloudflare) may not be connected when a task arrives. The Agent Router handles this with a wake-up mechanism:

1. Task arrives for a ws-agent:// agent that is not currently connected.
2. The task manager looks up the agent's Cloudflare worker URL from the agent_source table.
3. It sends an HTTP request to the worker URL to wake it up.
4. It waits (with timeout) for the agent to connect to the WebSocket Hub.
5. Once connected, the task is routed normally.

If the agent does not connect within the timeout, the task fails with an appropriate error message. Self-hosted agents (which have no worker URL to ping) receive a distinct error indicating they must be running to receive tasks.