update

Author: sansyrox

docs_src/src/pages/documentation/en/api_reference/agents.mdx

@@ -0,0 +1,363 @@
+export const description =
+  'Robyn AI Agents provide intelligent functionality for building AI-powered applications with conversation memory, context awareness, and pluggable agent runners. This is an experimental feature.'
+
+# AI Agents (Experimental)
+
+> **⚠️ Experimental Feature**: AI Agents are currently experimental and the API may change in future versions. Use with caution in production environments.
+
+Robyn includes built-in AI agent capabilities that allow you to create intelligent applications with conversation memory, context awareness, and pluggable agent runners. The AI module provides abstractions for memory storage and agent execution that can be easily integrated into your Robyn applications.
+
+## Quick Start
+
+```python
+from robyn import Robyn
+from robyn.ai import agent, memory
+
+app = Robyn(__file__)
+
+# Create memory instance
+mem = memory(provider="inmemory", user_id="user123")
+
+# Create agent with memory
+chat_agent = agent(runner="simple", memory=mem)
+
+@app.get("/chat")
+async def chat_endpoint(request):
+    query = request.query_params.get("q", [""])[0]
+    if not query:
+        return {"error": "Query required"}
+    
+    # Run agent with conversation history
+    result = await chat_agent.run(query, history=True)
+    return result
+
+app.start()
+```
+
+## Features
+
+### 🧠 **Memory System**
+- Multiple provider support (InMemory, Mem0)
+- Persistent conversation history
+- Semantic search capabilities
+- Context-aware responses
+
+### 🤖 **Agent Runners**
+- Simple runner with OpenAI integration
+- LangGraph runner for complex workflows
+- Custom runner support
+- Async execution
+
+### 🔧 **Easy Integration**
+- Minimal setup required
+- Type-safe configuration
+- Environment variable support
+- Error handling with fallbacks
+
+## Memory System
+
+The memory system provides persistent storage for conversation history and context. It supports multiple providers and offers a consistent interface for storing and retrieving conversation data.
+
+### Memory Providers
+
+#### InMemory Provider
+
+The simplest provider that stores data in memory. Data is lost when the application restarts.
+
+```python
+from robyn.ai import memory
+
+# Create in-memory storage
+mem = memory(provider="inmemory", user_id="user123")
+
+# Add messages
+await mem.add("Hello, how are you?")
+await mem.add("I'm doing great, thanks!")
+
+# Retrieve all messages
+messages = await mem.get()
+
+# Clear memory
+await mem.clear()
+```
+
+#### Mem0 Provider
+
+Integration with Mem0 for advanced memory capabilities including semantic search and persistence.
+
+```python
+from robyn.ai import memory
+
+# Create Mem0 memory instance
+mem = memory(
+    provider="mem0",
+    user_id="user123",
+    # Mem0 configuration
+    vector_store={
+        "provider": "chroma",
+        "config": {"collection_name": "robyn_memory"}
+    }
+)
+
+# Add messages with metadata
+await mem.add("I love pizza", metadata={"category": "food_preference"})
+
+# Search with query
+results = await mem.get(query="food preferences")
+```
+
+### Memory API
+
+The Memory class provides these key methods:
+
+- `add(message, metadata=None)` - Store a message with optional metadata
+- `get(query=None)` - Retrieve messages, optionally filtered by query
+- `clear()` - Clear all stored messages for the user
+
+## Agent System
+
+Agents provide the execution layer for AI functionality. They can use different runners and integrate with memory for context-aware responses.
+
+### Agent Runners
+
+#### Simple Runner
+
+A runner with OpenAI integration that provides intelligent responses:
+
+```python
+from robyn.ai import agent, configure
+
+# Configure with OpenAI API key
+config = configure(openai_api_key="your-openai-key")
+
+# Create simple agent
+simple_agent = agent(runner="simple", config=config)
+
+# Use the agent
+result = await simple_agent.run("What's the weather like?")
+# Returns structured response with AI-generated content
+```
+
+#### LangGraph Runner
+
+Integration with LangGraph for complex workflow execution:
+
+```python
+from robyn.ai import agent, memory
+
+# Create memory
+mem = memory(provider="inmemory", user_id="user123")
+
+# Create LangGraph agent with custom workflow
+graph_agent = agent(
+    runner="langgraph:path/to/workflow.json",
+    memory=mem
+)
+
+# Execute with context
+result = await graph_agent.run("Process this request", history=True)
+```
+
+#### Custom Runners
+
+Create your own agent runners by extending the `AgentRunner` class:
+
+```python
+from robyn.ai import AgentRunner, Agent
+from typing import Dict, Any
+
+class CustomAgentRunner(AgentRunner):
+    async def run(self, query: str, **kwargs) -> Dict[str, Any]:
+        # Implement custom agent logic
+        return {
+            "response": f"Custom response to: {query}",
+            "processed": True
+        }
+
+# Use custom runner
+custom_agent = Agent(runner=CustomAgentRunner())
+```
+
+### Agent API
+
+The Agent class provides:
+
+- `run(query, history=False, **kwargs)` - Execute the agent with optional history context
+- Automatic memory integration when provided
+- Support for custom runners and configuration
+
+## Configuration
+
+### Environment Variables
+
+Robyn AI supports configuration through environment variables:
+
+```bash
+# OpenAI Configuration
+export OPENAI_API_KEY="your-openai-key"
+export AI_MODEL="gpt-4o"
+export AI_TEMPERATURE="0.7"
+export AI_MAX_TOKENS="1000"
+
+# Mem0 Configuration
+export MEM0_API_KEY="your-mem0-key"
+
+# LangGraph Configuration
+export LANGGRAPH_API_KEY="your-langgraph-key"
+```
+
+### Programmatic Configuration
+
+```python
+from robyn.ai import configure, agent, memory
+
+# Create configuration
+config = configure(
+    openai_api_key="your-key",
+    model="gpt-4",
+    temperature=0.7,
+    max_tokens=1000
+)
+
+# Create agent with config
+chat_agent = agent(runner="simple", config=config)
+
+# Or configure memory
+mem = memory(
+    provider="mem0",
+    user_id="user123",
+    vector_store={"provider": "chroma"}
+)
+```
+
+## Complete Example
+
+Here's a comprehensive example showing all features:
+
+```python
+from robyn import Robyn
+from robyn.ai import agent, memory, configure
+
+app = Robyn(__file__)
+
+# Configure AI settings
+config = configure(
+    openai_api_key="your-openai-key",
+    model="gpt-4o",
+    temperature=0.7
+)
+
+# Create memory with Mem0 provider
+mem = memory(
+    provider="mem0",
+    user_id="guest",
+    vector_store={"provider": "chroma"}
+)
+
+# Create agent with memory and config
+chat_agent = agent(runner="simple", memory=mem, config=config)
+
+@app.get("/")
+async def home():
+    return {"message": "Robyn AI Chat API"}
+
+@app.post("/chat")  
+async def chat(request):
+    """Chat with AI agent"""
+    data = request.json()
+    query = data.get("query", "")
+    include_history = data.get("history", True)
+    
+    if not query:
+        return {"error": "Query is required"}
+    
+    try:
+        result = await chat_agent.run(query, history=include_history)
+        return {
+            "query": query,
+            "response": result.get("response"),
+            "history_included": include_history,
+            "metadata": result.get("metadata", {})
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+@app.get("/memory")
+async def get_memory():
+    """Retrieve conversation history"""
+    try:
+        memories = await mem.get()
+        return {"memories": memories, "count": len(memories)}
+    except Exception as e:
+        return {"error": str(e)}
+
+@app.delete("/memory")
+async def clear_memory():
+    """Clear conversation history"""
+    try:
+        await mem.clear()
+        return {"message": "Memory cleared"}
+    except Exception as e:
+        return {"error": str(e)}
+
+@app.post("/memory")
+async def add_memory(request):
+    """Add message to memory"""
+    data = request.json()
+    message = data.get("message", "")
+    metadata = data.get("metadata", {})
+    
+    if not message:
+        return {"error": "Message is required"}
+    
+    try:
+        await mem.add(message, metadata)
+        return {"message": "Added to memory"}
+    except Exception as e:
+        return {"error": str(e)}
+
+if __name__ == "__main__":
+    app.start(host="127.0.0.1", port=8080)
+```
+
+## Best Practices
+
+1. **User Isolation**: Always use unique user IDs to isolate memory between different users
+2. **Error Handling**: Wrap AI operations in try-catch blocks as external services may fail
+3. **Memory Management**: Regularly clear or archive old memories to prevent unbounded growth
+4. **Configuration**: Store sensitive configuration (API keys, etc.) in environment variables
+5. **Testing**: Test thoroughly as this is an experimental feature
+6. **Rate Limiting**: Implement rate limiting for public-facing AI endpoints
+7. **Monitoring**: Log agent interactions for debugging and analytics
+8. **Fallbacks**: Always provide fallback responses when AI services are unavailable
+
+## Troubleshooting
+
+### Common Issues
+
+**ImportError for required packages**: Install the required packages:
+```bash
+pip install openai mem0ai langgraph
+```
+
+**Memory not persisting**: Ensure you're using a persistent provider like Mem0, not the in-memory provider for production.
+
+**Agent timeouts**: Complex workflows may take time. Consider implementing timeout handling in your endpoints.
+
+**API changes**: As this is experimental, monitor for API changes in future Robyn releases.
+
+**OpenAI API errors**: Ensure your API key is valid and you have sufficient credits. Implement retry logic for transient errors.
+
+## What are AI Agents?
+
+AI Agents in Robyn are intelligent components that can understand natural language queries, maintain conversation context through memory systems, and provide intelligent responses using various AI providers like OpenAI or custom implementations.
+
+They're designed to be:
+- **Context-aware**: Remember previous interactions
+- **Extensible**: Support custom runners and memory providers  
+- **Production-ready**: Include error handling, fallbacks, and monitoring
+- **Easy to integrate**: Minimal setup with sensible defaults
+
+> **Note**: This feature is experimental and may evolve significantly. Please provide feedback and report issues to help improve the implementation.
+
+For more information about the underlying AI concepts, see the [AI module documentation](./ai.mdx).

docs_src/src/pages/documentation/en/api_reference/mcps.mdx

@@ -1,4 +1,6 @@
-# MCPs (Model Context Protocol)
+# MCPs (Model Context Protocol) - Experimental
+
+> **⚠️ Experimental Feature**: MCP support is currently experimental and the API may change in future versions. Use with caution in production environments.
 
 Robyn now supports the Model Context Protocol (MCP), allowing your applications to serve as MCP servers that can be connected to by AI applications like Claude Desktop.