semantica/docs/integrations/agno.md

Agno Integration

Semantica's Agno integration (semantica[agno]) wires the full Semantica semantic intelligence stack into the Agno agentic framework via five focused components.

Installation

# Core integration
pip install semantica[agno]

# With a graph store backend
pip install semantica[agno,graph-neo4j]
pip install semantica[agno,graph-falkordb]

# Full stack
pip install semantica[agno,graph-neo4j,vectorstore-pgvector]

Components at a Glance

Class	Agno Primitive	Semantica Backing
AgnoContextStore	AgentMemory(db=…)	AgentContext + VectorStore
AgnoKnowledgeGraph	Agent(knowledge=…)	ContextGraph + KG pipeline
AgnoDecisionKit	Agent(tools=[…])	DecisionQuery, CausalChainAnalyzer, PolicyEngine
AgnoKGToolkit	Agent(tools=[…])	NERExtractor, RelationExtractor, Reasoner
AgnoSharedContext	Team-level	Shared ContextGraph across agents

---

1. AgnoContextStore

Replaces Agno's flat conversation storage with a hybrid vector + context graph memory store. Implements agno.memory.db.base.MemoryDb.

from agno.agent import Agent
from agno.memory import AgentMemory
from agno.models.openai import OpenAIChat

from semantica.context import ContextGraph
from semantica.vector_store import VectorStore
from integrations.agno import AgnoContextStore

store = AgnoContextStore(
    vector_store=VectorStore(backend="faiss"),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
    graph_expansion=True,
    session_id="user_session_42",
)

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    memory=AgentMemory(db=store),
    description="A financially aware assistant with persistent decision intelligence.",
)

agent.print_response("Recommend a portfolio allocation for a risk-averse investor.")

Key behaviours

• upsert_memory() — stores text in AgentContext (vector index + graph node)
• read_memories() — hybrid retrieval: vector similarity + optional graph hop expansion
• record_decision() — records a structured decision with reasoning & outcome
• find_precedents() — returns semantically similar historical decisions

---

2. AgnoKnowledgeGraph

Gives Agno agents a queryable ContextGraph instead of a flat document store. Ingested documents pass through the full Semantica extraction pipeline.

from agno.agent import Agent
from agno.models.openai import OpenAIChat

from semantica.kg import GraphBuilder
from semantica.semantic_extract import NERExtractor, RelationExtractor
from integrations.agno import AgnoKnowledgeGraph

kg = AgnoKnowledgeGraph(
    graph_builder=GraphBuilder(),
    ner_extractor=NERExtractor(),
    relation_extractor=RelationExtractor(),
)

# Ingest local files
kg.load("regulatory_docs/", recursive=True)

# Ingest raw text
kg.load(texts=["Basel IV capital requirements apply from January 2026."])

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    knowledge=kg,
    search_knowledge=True,
)

Ingestion pipeline

parse → NER → relation extract → graph build → vector index

Search: multi-hop GraphRAG

vector retrieval → entity lookup → graph hop expansion → context injection

Get entity subgraph

ctx = kg.get_graph_context("Basel IV")
# Returns a text summary of the entity's immediate neighbourhood in the graph

---

3. AgnoDecisionKit

Exposes Semantica's decision intelligence as native Agno tools.

from agno.agent import Agent
from agno.models.openai import OpenAIChat

from semantica.context import AgentContext
from integrations.agno import AgnoDecisionKit

ctx = AgentContext(decision_tracking=True)

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[AgnoDecisionKit(context=ctx)],
    show_tool_calls=True,
)

agent.print_response("Should we approve this mortgage application?")

Tools

Tool	Description	Key Parameters
record_decision	Record decision with reasoning and outcome	category, scenario, reasoning, outcome, confidence, entities
find_precedents	Search for similar past decisions	scenario, category, limit
trace_causal_chain	Trace causal chain of a decision	decision_id, depth
analyze_impact	Assess downstream influence of a decision	decision_id
check_policy	Validate decision against policy rules	decision_data, policy_rules
get_decision_summary	Summarise decision history by category	category, since, limit

Example agent turn

User: Should we approve this mortgage application?

Agent [tool: find_precedents]         → 12 similar mortgage approvals found
Agent [tool: check_policy]            → complies with lending policy v2.3
Agent [tool: record_decision]         → recorded: loan_approval / approved / confidence=0.94
Agent: Based on 12 historical precedents and full policy compliance, I recommend
       approval. Credit score 740, 22% down payment, DTI 31% — all within thresholds.

---

4. AgnoKGToolkit

Lets agents actively build and query the context graph during reasoning.

from agno.agent import Agent
from agno.models.openai import OpenAIChat

from integrations.agno import AgnoKGToolkit

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[AgnoKGToolkit()],
    show_tool_calls=True,
)

agent.print_response(
    "Extract entities and relationships from this article and store them in the knowledge graph."
)

Tools

Tool	Description
extract_entities	Extract named entities from text
extract_relations	Extract relationships between entities
add_to_graph	Add entities / relations to the context graph
query_graph	Query the graph (natural-language or Cypher)
find_related	Find concepts related to a given entity
infer_facts	Apply rules to infer new facts from the graph
export_subgraph	Export a subgraph as RDF / JSON-LD

---

5. AgnoSharedContext

A single ContextGraph shared across an Agno Team. Each agent gets a role-scoped view via bind_agent().

from agno.agent import Agent
from agno.team import Team
from agno.models.openai import OpenAIChat

from semantica.context import ContextGraph
from semantica.vector_store import VectorStore
from integrations.agno import AgnoSharedContext, AgnoDecisionKit, AgnoKGToolkit

shared = AgnoSharedContext(
    vector_store=VectorStore(backend="faiss"),
    knowledge_graph=ContextGraph(advanced_analytics=True),
    decision_tracking=True,
)

research_agent = Agent(
    name="Researcher",
    model=OpenAIChat(id="gpt-4o"),
    memory=shared.bind_agent("researcher"),
    tools=[AgnoKGToolkit(context=shared)],
)

decision_agent = Agent(
    name="Analyst",
    model=OpenAIChat(id="gpt-4o"),
    memory=shared.bind_agent("analyst"),
    tools=[AgnoDecisionKit(context=shared)],
)

team = Team(
    name="Research & Decision Team",
    agents=[research_agent, decision_agent],
    mode="coordinate",
)

team.print_response(
    "Analyse the competitive landscape and recommend our product strategy."
)

Shared memory pool

Memories written by one agent are immediately visible to all other agents in the team. Each agent's writes are tagged with their role so they can be filtered independently.

Shared decisions

# Record a team-level decision
decision_id = shared.record_decision(
    category="strategy",
    scenario="Expand to EU market",
    reasoning="Strong demand signals from Q1 survey",
    outcome="approved",
    confidence=0.87,
    agent_role="cfo",
)

# Query precedents across all agents' history
precedents = shared.find_precedents("market expansion")

# Get cross-agent analytics
insights = shared.get_shared_insights()

---

Use Cases

Regulated Industry Agents (Finance, Healthcare, Legal)

Agents that log every decision with full provenance, reasoning chain, and policy compliance check for audit trails.

kit = AgnoDecisionKit(context=ctx)
# Every agent turn: find_precedents → check_policy → record_decision

Long-Running Research Agents

Agents that accumulate a persistent ContextGraph over days or weeks, enabling multi-hop reasoning over a growing knowledge base.

kg = AgnoKnowledgeGraph(graph_builder=GraphBuilder(), ...)
# Agents load new documents continuously; search benefits from the growing graph

Enterprise Multi-Agent Coordination

Teams using AgnoSharedContext to prevent contradictory decisions and share structured knowledge across specialist agents.

GraphRAG Customer Support

Support agents that retrieve answers via graph traversal, providing more contextually grounded responses than flat vector search.

Explainable AI Pipelines

Every agent step, entity reference, and causal chain is traceable back to a source document or prior decision.

---

API Reference

from integrations.agno import (
    AgnoContextStore,       # MemoryDb implementation
    AgnoKnowledgeGraph,     # AgentKnowledge implementation
    AgnoDecisionKit,        # Decision intelligence Toolkit
    AgnoKGToolkit,          # Knowledge graph Toolkit
    AgnoSharedContext,      # Team-level shared context
    AGNO_AVAILABLE,         # bool — True if agno is installed
)

All five classes are usable without agno installed — they carry the full Semantica API and degrade gracefully when passed to Agno constructors.