What is the Semantic Layer?¶
A service that stores information about all your agents, so they can find each other by describing what they need — not by knowing exact addresses.
Without it¶
# Hardcoded. Breaks when you add/move agents.
response = await call("http://analyst:8001", "analyze sales")
response = await call("http://reporter:8002", "write report")
With it¶
from abi_core.common.semantic_tools import tool_find_agent
# Searches by meaning. Works even if you say it differently.
agent = await tool_find_agent.ainvoke("examine revenue data")
# → Returns the analyst agent with its address
What it includes¶
Component |
What it does |
|---|---|
Weaviate |
Database that understands meaning (finds similar descriptions) |
MCP Server |
Provides tools like find_agent, register_agent, search_tools |
Embedding Mesh |
Converts text descriptions into searchable numbers |
Agent Cards |
JSON files describing what each agent can do |
Tool Cards |
JSON files describing available tools |
Tool Cards |
JSON files describing available tools |
Add it to your project¶
abi-core create project my-app --with-semantic-layer
Or add to an existing project:
abi-core add service semantic-layer
This creates:
services/semantic_layer/
├── embedding_mesh/ ← Embedding generation + Weaviate CRUD
├── agent_cards/ ← Agent card JSON files (auto-indexed)
├── tool_cards/ ← Tool card JSON files (auto-indexed)
├── config/
├── main.py
├── Dockerfile
└── requirements.txt
How it works at startup¶
Semantic Layer reads all JSON files from
agent_cards/andtool_cards/Generates embeddings for each card’s description + skills + tags
Stores them in Weaviate collections
Exposes MCP tools for search (
find_agent,list_agents,search_tool_registry)
Use it from your agent¶
from abi_core.common.semantic_tools import tool_find_agent, tool_list_agents, MCPToolkit
# Find one agent
agent = await tool_find_agent.ainvoke("write reports")
# Find multiple agents
agents = await tool_list_agents.ainvoke("discuss and share opinions")
# Call any custom MCP tool
toolkit = MCPToolkit()
result = await toolkit.store_document(content="...", metadata={...})