semantica/docs/integrations/crewai.md

title, description, icon

title	description	icon
CrewAI Integration	Give CrewAI crews a shared semantic knowledge graph, decision intelligence, and graph-based retrieval via three drop-in components.	users

Three drop-in components that bring Semantica's knowledge graph and decision intelligence into any CrewAI crew.

Installation

pip install "semantica[crewai]"

Requires crewai >= 0.80.0. If crewai is not installed, the integration still imports — every class carries the full Semantica API and degrades gracefully, but cannot be passed to a Crew.

Components at a Glance

• SemanticaKGTool — Agent(tools=[…]): 5 KG construction/query actions: extract entities, extract relations, add to graph, query graph, find related.
• SemanticaDecisionTool — Agent(tools=[…]): 5 decision intelligence actions: record decisions, find precedents, trace causal chains, analyze impact, check policies.
• SemanticaKnowledgeSource — Crew(knowledge_sources=[…]): Serializes a ContextGraph into CrewAI knowledge storage so every agent gets retrieval access to the graph.

Component Details

Lets agents actively **build and query** a shared `ContextGraph` mid-reasoning.

```python
from crewai import Agent, Crew, Task
from semantica.context import ContextGraph
from integrations.crewai import SemanticaKGTool

graph = ContextGraph()

analyst = Agent(
    role="Knowledge Analyst",
    goal="Build and explore a knowledge graph from documents",
    backstory="You map entities and relationships into a shared graph.",
    tools=[SemanticaKGTool(graph=graph)],
)

crew = Crew(
    agents=[analyst],
    tasks=[Task(
        description="Extract and link key entities from the brief",
        expected_output="JSON",
        agent=analyst,
    )],
)
crew.kickoff()
```

| Tool | Description |
| :------ | :------------- |
| `extract_entities` | Extract named entities from `text` |
| `extract_relations` | Extract relationships between entities in `text` |
| `add_to_graph` | Extract entities/relations from `text` and add them to the shared graph |
| `query_graph` | Keyword-search the graph by node id, type, and content using `query` |
| `find_related` | Find concepts related to `entity` within `hops` hops |

All actions return JSON so agents get parseable results.

**Sharing a graph:** the tool reads/writes whatever `graph` you pass in. When no `graph` is given, a fresh in-memory `ContextGraph()` is created (and a warning is logged) — two tool instances that each auto-create their own graph do **not** share knowledge. Pass the same `ContextGraph` to every agent that must share state.

Exposes Semantica's decision intelligence as a native CrewAI tool, backed by `AgentContext`.

```python
from crewai import Agent, Crew, Task
from integrations.crewai import SemanticaDecisionTool

planner = Agent(
    role="Decision Planner",
    goal="Make grounded, precedented decisions",
    backstory="You record decisions and validate them against policy.",
    tools=[SemanticaDecisionTool()],
)

crew = Crew(agents=[planner], tasks=[...])
```

When no `AgentContext` is passed, one is created in-memory with `decision_tracking=True` and its own `ContextGraph`, so decision actions work out of the box (a warning is logged — pass the same `AgentContext` to every agent that must share decision state). Missing optional fields in `record_decision` fall back to `category="general"`, `reasoning="agent decision"`, and `outcome="recorded"`. `find_precedents` returns up to `max_precedents` results. If a knowledge graph cannot trace causality, `trace_causal_chain` returns an explicit error rather than substituting similarity-based results.

| Tool | Description |
| :------ | :------------- |
| `record_decision` | Record a decision with reasoning, outcome, and confidence |
| `find_precedents` | Search for similar past decisions |
| `trace_causal_chain` | Trace the causal chain from a decision |
| `analyze_impact` | Assess downstream influence of a decision |
| `check_policy` | Validate a proposed decision against policy rules |

Gives **every agent in the crew** retrieval access to a `ContextGraph`.

```python
from crewai import Agent, Crew, Task
from semantica.context import ContextGraph
from integrations.crewai import SemanticaKnowledgeSource

graph = ContextGraph()
graph.add_node(node_id="privacy", node_type="policy", content="...")

researcher = Agent(
    role="Policy Researcher",
    goal="Answer questions from the knowledge base",
    backstory="You retrieve from graph knowledge to answer accurately.",
)

crew = Crew(
    agents=[researcher],
    tasks=[...],
    knowledge_sources=[SemanticaKnowledgeSource(graph=graph)],
)
```

On kickoff the graph's nodes and edges are serialized, chunked, and stored through CrewAI's knowledge pipeline.

> **Embedder required:** storing chunks goes through CrewAI's knowledge pipeline, which needs an embedder to be configured. Set `Crew(embedder=...)` (or provide the default credentials CrewAI falls back to, e.g. `OPENAI_API_KEY`). If no working embedder is configured, storage fails, an ERROR is logged, and agents will retrieve **nothing** — the crew still runs, but its knowledge queries return empty.

**Compatibility:** CrewAI's `BaseKnowledgeSource` contract changed between `0.80.x` and current releases (`load_content()` → `validate_content()`/`aadd()`). `SemanticaKnowledgeSource` implements both legacy and current methods, so it works across `crewai>=0.80.0`.

Checkpoints & Serialization

CrewAI serializes tools and knowledge sources to JSON for checkpointing/resume. Live Semantica state (ContextGraph, AgentContext, extractors) is excluded from that serialization — a restored tool/source comes back with a fresh in-memory ContextGraph and logs a warning. Until you re-attach the live graph/context, the restored objects answer queries against an empty graph, so re-wire them after resuming (e.g. restored_tool.graph = live_graph) before agents continue.

API Reference

from integrations.crewai import (
    SemanticaKGTool,          # BaseTool: KG construction/query actions
    SemanticaDecisionTool,    # BaseTool: decision intelligence actions
    SemanticaKnowledgeSource, # BaseKnowledgeSource: graph → crew knowledge
    CREWAI_AVAILABLE,         # bool: True if crewai is installed
)

All three classes are usable without crewai installed: they carry the full Semantica API and degrade gracefully.

See Also

• Context Module — AgentContext and ContextGraph backing the integration.
• Semantic Extraction — NERExtractor / RelationExtractor used by SemanticaKGTool.
• LLMs — Configure LLM providers for your crew's agents.
• Vector Store — Vector backend used by SemanticaDecisionTool.