Agent Integration with Knowledge Graph

This document describes how to integrate knowledge graph capabilities with AIECS agents.

Overview

The knowledge graph integration provides agents with:

Persistent Knowledge Storage: Store and retrieve entities and relations
Graph-Aware Reasoning: Use graph structure for multi-hop reasoning
Knowledge-Augmented ReAct Loop: Automatic knowledge retrieval during reasoning
Graph Query Tools: Built-in tools for graph operations

Agent Types

1. HybridAgent (Original)

The original HybridAgent provides standard ReAct loop functionality without knowledge graph integration.

Use When:

You don’t need knowledge graph capabilities
You want backward compatibility
Simple tool-based reasoning is sufficient

Example:

from aiecs.domain.agent import HybridAgent, AgentConfiguration
from aiecs.llm import OpenAIClient

agent = HybridAgent(
    agent_id="hybrid_1",
    name="Standard Hybrid Agent",
    llm_client=llm_client,
    tools=["web_search", "calculator"],
    config=AgentConfiguration()
)

2. KnowledgeAwareAgent (Enhanced)

The KnowledgeAwareAgent extends HybridAgent with knowledge graph integration.

Features:

Knowledge-augmented ReAct loop (Retrieve → Reason → Act → Observe)
Automatic knowledge retrieval before reasoning
Graph reasoning tool integration
Knowledge-guided action selection

Use When:

You need knowledge graph capabilities
You want multi-hop reasoning
You need persistent knowledge storage
You want graph-augmented prompts

Example:

from aiecs.domain.agent import KnowledgeAwareAgent, AgentConfiguration
from aiecs.infrastructure.graph_storage import InMemoryGraphStore

# Create graph store
graph_store = InMemoryGraphStore()
await graph_store.initialize()

# Create knowledge-aware agent
agent = KnowledgeAwareAgent(
    agent_id="kg_agent_1",
    name="Knowledge-Aware Agent",
    llm_client=llm_client,
    tools=["web_search"],
    config=AgentConfiguration(),
    graph_store=graph_store
)

await agent.initialize()

3. GraphAwareAgentMixin (Reusable)

The GraphAwareAgentMixin provides reusable graph functionality for any agent class.

Features:

Knowledge formatting utilities
Graph query helpers
Knowledge context management
Can be mixed into any agent

Use When:

You want to add graph capabilities to a custom agent
You need reusable graph utilities
You want consistent knowledge formatting

Example:

from aiecs.domain.agent import BaseAIAgent, GraphAwareAgentMixin
from aiecs.infrastructure.graph_storage import InMemoryGraphStore

class CustomGraphAgent(BaseAIAgent, GraphAwareAgentMixin):
    def __init__(self, agent_id, name, config, graph_store):
        super().__init__(agent_id, name, AgentType.DEVELOPER, config)
        self.graph_store = graph_store

# Use mixin methods
agent = CustomGraphAgent(..., graph_store=graph_store)
neighbors = await agent.get_entity_neighbors("alice")
formatted = agent.format_entities(neighbors)

Integration Patterns

Pattern 1: Direct Integration

Use KnowledgeAwareAgent for full knowledge graph integration.

from aiecs.domain.agent import KnowledgeAwareAgent
from aiecs.infrastructure.graph_storage import InMemoryGraphStore

graph_store = InMemoryGraphStore()
await graph_store.initialize()

agent = KnowledgeAwareAgent(
    agent_id="agent_1",
    name="KG Agent",
    llm_client=llm_client,
    tools=[],
    config=config,
    graph_store=graph_store
)

await agent.initialize()

Pattern 2: Mixin Integration

Use GraphAwareAgentMixin to add graph capabilities to custom agents.

from aiecs.domain.agent import BaseAIAgent, GraphAwareAgentMixin

class MyAgent(BaseAIAgent, GraphAwareAgentMixin):
    def __init__(self, graph_store, ...):
        super().__init__(...)
        self.graph_store = graph_store

Pattern 3: Conditional Integration

Enable/disable graph capabilities based on configuration.

agent = KnowledgeAwareAgent(
    ...,
    graph_store=graph_store if use_kg else None,
    enable_graph_reasoning=use_kg
)

Graph Store Options

InMemoryGraphStore

Use For:

Development and testing
Small graphs (< 100K nodes)
Prototyping
Temporary knowledge

Example:

from aiecs.infrastructure.graph_storage import InMemoryGraphStore

graph_store = InMemoryGraphStore()
await graph_store.initialize()

SQLiteGraphStore

Use For:

Production applications
Persistent knowledge storage
Medium-sized graphs (< 1M nodes)
Single-process applications

Example:

from aiecs.infrastructure.graph_storage import SQLiteGraphStore

graph_store = SQLiteGraphStore(db_path="knowledge.db")
await graph_store.initialize()

Available Tools

GraphSearchTool

Provides multiple search modes for knowledge graph queries.

Modes:

vector - Vector similarity search
graph - Graph traversal search
hybrid - Combined vector + graph search
pagerank - Personalized PageRank
multihop - Multi-hop neighbor retrieval
filtered - Filtered retrieval
traverse - Pattern-based traversal

Example:

# Agent automatically has access to graph_search tool
result = await agent.execute_task({
    "description": "Find people who work at TechCorp"
})

GraphReasoningTool

Provides reasoning capabilities over the knowledge graph.

Modes:

query_plan - Plan complex queries
multi_hop - Multi-hop reasoning
inference - Logical inference
evidence_synthesis - Evidence-based reasoning
full_reasoning - Complete reasoning pipeline

Example:

# Agent automatically has access to graph_reasoning tool
result = await agent.execute_task({
    "description": "How is Alice connected to TechCorp?"
})

Knowledge-Augmented ReAct Loop

The KnowledgeAwareAgent uses an enhanced ReAct loop:

RETRIEVE: Get relevant knowledge from graph
THINK: LLM reasons with retrieved knowledge
ACT: Execute tool or provide answer
OBSERVE: Review results and continue

Benefits:

Agents have context from knowledge graph
Better reasoning with structured knowledge
Automatic knowledge retrieval
Transparent process (visible in reasoning steps)

Retrieval Strategies

The agent supports multiple retrieval strategies configured via AgentConfiguration.retrieval_strategy:

"vector": Semantic similarity search using embeddings
"graph": Graph traversal from seed entities
"hybrid": Combined vector + graph search (default)
"auto": Automatic strategy selection based on query

See Knowledge Retrieval Configuration Guide for details.

Caching

Knowledge retrieval results are cached by default to improve performance:

Cache Backend: Redis (if available) or in-memory fallback
Cache TTL: Configurable via AgentConfiguration.cache_ttl (default: 300 seconds)
Cache Key: Based on query text and retrieval strategy

See Metrics and Monitoring Guide for cache performance tracking.

Best Practices

1. Graph Store Initialization

Always initialize the graph store before creating the agent:

graph_store = InMemoryGraphStore()
await graph_store.initialize()

agent = KnowledgeAwareAgent(..., graph_store=graph_store)
await agent.initialize()

2. Graceful Degradation

Handle cases where graph store is unavailable:

if graph_store and agent.validate_graph_store():
    # Use graph capabilities
    neighbors = await agent.get_entity_neighbors("alice")
else:
    # Fall back to standard behavior
    pass

3. Knowledge Formatting

Use mixin methods for consistent formatting:

# Format entities for display
formatted = agent.format_entities(entities)

# Format path for explanation
path_str = agent.format_path(path)

4. Error Handling

Always handle errors gracefully:

try:
    result = await agent.execute_task(task, context)
except Exception as e:
    logger.error(f"Task execution failed: {e}")
    # Handle error

5. Resource Cleanup

Always close graph store when done:

try:
    # Use agent
    result = await agent.execute_task(task)
finally:
    await agent.shutdown()
    await graph_store.close()

Performance Considerations

Knowledge Retrieval

Retrieval happens before each reasoning step
Limit retrieval to relevant entities
Cache retrieved knowledge when possible

Graph Store Selection

InMemoryGraphStore: Fast but not persistent
SQLiteGraphStore: Persistent but slower
Choose based on your requirements

Query Optimization

Use appropriate search modes
Limit result sets
Filter by entity types when possible

Troubleshooting

Graph Store Not Available

Symptom: Warnings about graph store not available

Solution: Ensure graph store is initialized before agent creation

Knowledge Not Retrieved

Symptom: No knowledge retrieved during reasoning

Solution: Check that enable_graph_reasoning=True and graph store has data

Tool Not Found

Symptom: graph_search or graph_reasoning tool not available

Solution: Ensure graph store is provided to KnowledgeAwareAgent

Next Steps

See examples in docs/knowledge_graph/examples/
Read tool documentation in docs/knowledge_graph/tools/
Check reasoning engine docs in docs/knowledge_graph/reasoning/