Morphik Agent

The Morphik Agent is an intelligent assistant that autonomously uses various tools to answer complex queries and perform sophisticated analysis tasks. Unlike traditional retrieval-augmented generation (RAG) systems that follow a fixed pipeline, the agent can dynamically decide which tools to use, execute code, analyze documents, and even save insights to memory for future reference.

​

How It Works

​

Architecture Overview

The Morphik Agent operates using a function-calling LLM (Large Language Model) that can:

1. Analyze the Query: Understand what the user is asking for
2. Plan Tool Usage: Decide which tools are needed to answer the query
3. Execute Tools: Call the appropriate tools with the right parameters
4. Process Results: Analyze tool outputs and decide if more tools are needed
5. Generate Response: Provide a comprehensive answer with structured content

​

Tool Ecosystem

The agent has access to eight core tools:

​

Document Operations

• retrieve_chunks: Search and retrieve relevant text/image chunks
• retrieve_document: Get full document content or metadata
• document_analyzer: Extract entities, facts, summaries, sentiment
• list_documents: Discover available documents

​

Knowledge Operations

• knowledge_graph_query: Query entities, relationships, and paths
• list_graphs: Discover available knowledge graphs

​

Computation

• execute_code: Run Python code in a secure sandbox

​

Memory

• save_to_memory: Store insights for future queries

​

Key Capabilities

​

1. Multi-Step Analysis

The agent can break down complex requests into multiple steps:

# User asks: "Analyze sales trends and predict next quarter"
# Agent autonomously:
# 1. Lists sales documents
# 2. Retrieves sales data chunks  
# 3. Analyzes trends using document_analyzer
# 4. Executes Python code for predictions
# 5. Saves insights to memory
# 6. Generates comprehensive report

result = db.agent_query(
    "Analyze our sales trends over the last year and predict "
    "performance for next quarter. Save key insights for future reference."
)

​

2. Code Execution

The agent can write and execute Python code for calculations, data analysis, and visualization:

# Agent can automatically write code like this:
"""
import pandas as pd
import matplotlib.pyplot as plt

# Parse sales data from retrieved chunks
sales_data = [...]  # Data from document chunks
df = pd.DataFrame(sales_data)

# Calculate growth rate
growth_rate = (df['Q4'] - df['Q1']) / df['Q1'] * 100

# Create visualization
plt.plot(df['quarter'], df['sales'])
plt.title('Sales Trends')
plt.savefig('sales_trends.png')

print(f"Growth rate: {growth_rate:.2f}%")
"""

​

3. Knowledge Graph Exploration

The agent can navigate complex relationships in your data:

result = db.agent_query(
    "How are our enterprise customers connected to our premium products? "
    "Show me the relationship paths and identify expansion opportunities."
)

# Agent might:
# 1. List available graphs
# 2. Query for enterprise customer entities
# 3. Find paths to premium products
# 4. Analyze relationship strengths
# 5. Generate expansion strategy

​

4. Memory and Context

The agent can remember important insights across queries:

# First interaction
result1 = db.agent_query("Analyze customer churn patterns and save findings")

# Later interaction - agent remembers previous analysis
result2 = db.agent_query("Based on our churn analysis, what retention strategies should we implement?")

​

Response Structure

The agent returns a rich, structured response with four components:

​

1. Final Response (response)

The main textual answer to your query.

​

2. Tool History (tool_history)

Complete audit trail of all tool executions:

[
  {
    "tool_name": "list_documents",
    "tool_args": {"filters": {"department": "sales"}},
    "tool_result": "Found 15 sales documents..."
  },
  {
    "tool_name": "execute_code", 
    "tool_args": {"code": "growth_rate = (Q4 - Q1) / Q1 * 100"},
    "tool_result": "Growth rate: 23.5%"
  }
]

​

3. Display Objects (display_objects)

Structured content for rich presentation:

[
  {
    "type": "text",
    "content": "## Sales Analysis\nGrowth rate increased by 23.5%...",
    "source": "doc123-chunk1"
  },
  {
    "type": "image",
    "content": "<base64_image_data>",
    "caption": "Sales trend chart showing quarterly growth",
    "source": "doc456-chart2"
  }
]

​

4. Sources (sources)

Attribution for all referenced content:

[
  {
    "sourceId": "doc123-chunk1",
    "documentName": "Q3 Sales Report",
    "documentId": "123",
    "content": "Sales increased significantly..."
  }
]

​

When to Use the Agent

​

Choose agent_query for:

✅ Complex Analysis Tasks

• Multi-step analysis requiring different tools
• Data analysis with calculations
• Research requiring document discovery

✅ Computation Requirements

• Statistical analysis
• Data visualization
• Mathematical calculations

✅ Knowledge Graph Exploration

• Relationship discovery
• Entity connection analysis
• Path finding between concepts

✅ Multi-Modal Content

• Analyzing both text and images
• Extracting information from charts/diagrams

✅ Memory-Dependent Tasks

• Building on previous analysis
• Maintaining context across queries

​

Choose regular query for:

✅ Simple Q&A

• Direct questions about document content
• Quick information retrieval
• Straightforward fact-finding

✅ Performance-Critical Applications

• When speed is more important than depth
• Simple document lookup scenarios

​

Best Practices

​

1. Query Design

Be Specific About Goals:

# Good: Clear outcome desired
"Analyze customer satisfaction scores, identify trends, and recommend improvements"

# Less optimal: Vague request  
"Tell me about customers"

Include Analysis Context:

# Good: Provides direction
"Calculate quarterly revenue growth and compare to industry benchmarks"

# Less optimal: Missing context
"Show me revenue numbers"

​

2. Response Processing

Check Tool History for Understanding:

result = db.agent_query("Complex analysis request")

# Understand what the agent did
for tool in result["tool_history"]:
    print(f"Used {tool['tool_name']} with {tool['tool_args']}")

Use Display Objects for Rich Content:

for obj in result["display_objects"]:
    if obj["type"] == "image":
        # Display image in UI with caption
        display_image(obj["content"], caption=obj["caption"])
    elif obj["type"] == "text":
        # Render markdown content
        render_markdown(obj["content"])

​

3. Error Handling

def safe_agent_query(query):
    try:
        result = db.agent_query(query)
        
        # Check for errors in response
        if "error" in result.get("response", "").lower():
            return {"error": "Agent encountered an error", "details": result["response"]}
            
        # Check if any tools failed
        failed_tools = [
            tool for tool in result.get("tool_history", [])
            if "error" in str(tool.get("tool_result", "")).lower()
        ]
        
        if failed_tools:
            return {"error": "Some tools failed", "failed_tools": failed_tools}
            
        return result
        
    except Exception as e:
        return {"error": "Agent query failed", "exception": str(e)}

​

4. Memory Usage

# Use memory for cumulative analysis
queries = [
    "Analyze customer segments and save key characteristics",
    "Based on customer segments, identify high-value opportunities", 
    "Create action plan for the top 3 opportunities identified"
]

for query in queries:
    result = db.agent_query(query)
    print(f"Query: {query}")
    print(f"Response: {result['response']}\n")

​

Performance Considerations

​

Response Time

• Agent queries typically take 10-60 seconds depending on complexity
• Each tool call adds processing time
• Complex code execution can extend response time

​

Cost Implications

• Uses more LLM tokens than regular queries
• Cloud deployments may have usage limits
• Tool execution (especially code) consumes additional resources

​

Context Window Management

• Very complex queries may hit LLM context limits
• Agent automatically manages context but extremely long sessions may fail
• Consider breaking very complex tasks into smaller queries

​

Security Model

​

Code Execution Sandbox

• Python code runs in a secure, isolated environment
• No access to file system or network
• Limited to approved libraries and functions
• Execution time limits prevent infinite loops

​

Data Access

• Agent respects same access controls as other Morphik operations
• Cannot access documents outside user’s permissions
• Memory storage follows same security model

​

Tool Limitations

• Tools cannot perform destructive operations
• No ability to modify or delete documents
• Read-only access to knowledge graphs
• Memory is scoped to user/session

​

Comparison with Traditional RAG

​

Future Roadmap

The Morphik Agent will continue to evolve with:

• Additional Tools: Web search, API integrations, file operations
• Improved Planning: Better tool selection and optimization
• Enhanced Memory: Longer-term memory with better organization
• Custom Tools: User-defined tools and functions
• Multi-Agent Orchestration: Specialized agents for different domains

The agent represents a significant evolution from traditional RAG systems, enabling complex analytical workflows that were previously impossible with simple retrieval-based approaches.