I Built a Full-Stack AI Agent with Laravel, Vue, MCP, and RAG — Here’s How It Works

┌─────────────────────────────────────────────────────────────┐ │ Vue 3 Frontend │ │ (Pinia Store, SSE EventSource Reader, Reactive UI Tree) │ └──────────────┬──────────────────────────────▲───────────────┘ │ 1. POST /api/agent/chat │ 7. SSE Event Stream ▼ │ (Tokens, Tool Status) ┌──────────────────────────────────────────────┴──────────────┐ │ Laravel Orchestrator │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ State Machine (ChatSession, Message, Context Budget) │ │ │ └───────────┬───────────────────────────────▲───────────┘ │ │ │ 2. Build Prompt & Tools │ │ │ ▼ │ │ │ ┌────────────────────────┐ ┌─────────────┴───────────┐ │ │ │ Anthropic API │ │ Hybrid RAG Pipeline │ │ │ │ (Claude 3.5/3.7) │ │ (Postgres + pgvector) │ │ │ └───────────┬────────────┘ └─────────────▲───────────┘ │ │ │ 3. Tool Call Requested │ 4. Vector/BM25│ │ ▼ │ Search │ │ ┌───────────────────────────────────────────┴───────────┐ │ │ │ MCP Client Manager │ │ │ └───────────┬───────────────────────────────────────────┘ │ └──────────────┼──────────────────────────────────────────────┘ │ 5. JSON-RPC (stdio / SSE) ▼ ┌─────────────────────────────────────────────────────────────┐ │ Decoupled MCP Servers │ │ ┌───────────────────────┐ ┌───────────────────────┐ │ │ │ Postgres DB Inspector│ │ GitHub / Jira Worker │ │ │ └───────────────────────┘ └───────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ 

namespace App\Enums; enum AgentStatus: string { case Pending = 'pending'; case Thinking = 'thinking'; case ExecutingTool = 'executing_tool'; case AwaitingInput = 'awaiting_input'; case Streaming = 'streaming'; case Completed = 'completed'; case Failed = 'failed'; } 

namespace App\Services\Agent; use App\Enums\AgentStatus; use App\Models\AgentRun; use App\Models\Conversation; use App\Services\Mcp\McpClientManager; use App\Services\Rag\RagRetriever; use Generator; use Illuminate\Support\Facades\Log; class AgentOrchestrator { private const MAX_ITERATIONS = 8; public function __construct( protected McpClientManager $mcpManager, protected RagRetriever $ragRetriever, protected AnthropicClient $llmClient ) {} /** * Executes the agent loop, yielding SSE-formatted events along the way. * * @return Generator<string, mixed> */ public function run(Conversation $conversation, string $userPrompt): Generator { $run = AgentRun::create([ 'conversation_id' => $conversation->id, 'status' => AgentStatus::Pending, 'iteration_count' => 0, ]); // 1. Fetch relevant RAG context documents yield ['event' => 'status', 'data' => ['message' => 'Searching knowledge base...']]; $retrievedContext = $this->ragRetriever->retrieve($userPrompt, limit: 5); // 2. Build initial message history $conversation->messages()->create([ 'role' => 'user', 'content' => $userPrompt, ]); $availableTools = $this->mcpManager->getAllToolDefinitions(); $systemPrompt = $this->buildSystemPrompt($retrievedContext); $iteration = 0; $run->update(['status' => AgentStatus::Thinking]); while ($iteration < self::MAX_ITERATIONS) { $iteration++; $run->increment('iteration_count'); $messages = $conversation->getSanitizedMessageHistory(); $responseStream = $this->llmClient->streamConversation( system: $systemPrompt, messages: $messages, tools: $availableTools ); $currentToolCall = null; $accumulatedContent = ''; foreach ($responseStream as $chunk) { if ($chunk['type'] === 'text_delta') { $accumulatedContent .= $chunk['text']; yield ['event' => 'token', 'data' => ['delta' => $chunk['text']]]; } elseif ($chunk['type'] === 'tool_use_start') { $run->update(['status' => AgentStatus::ExecutingTool]); $currentToolCall = [ 'id' => $chunk['id'], 'name' => $chunk['name'], 'input' => '', ]; yield ['event' => 'tool_start', 'data' => ['name' => $chunk['name'], 'id' => $chunk['id']]]; } elseif ($chunk['type'] === 'tool_use_delta') { $currentToolCall['input'] .= $chunk['input_json_delta']; } elseif ($chunk['type'] === 'tool_use_stop') { yield ['event' => 'tool_executing', 'data' => ['id' => $currentToolCall['id']]]; // Parse inputs and execute via MCP $parsedArgs = json_decode($currentToolCall['input'], true) ?? []; $toolResult = $this->executeToolWithCircuitBreaker( $currentToolCall['name'], $parsedArgs ); // Persist model tool request and the tool execution result $conversation->messages()->create([ 'role' => 'assistant', 'content' => [ ['type' => 'tool_use', 'id' => $currentToolCall['id'], 'name' => $currentToolCall['name'], 'input' => $parsedArgs] ] ]); $conversation->messages()->create([ 'role' => 'user', 'content' => [ ['type' => 'tool_result', 'tool_use_id' => $currentToolCall['id'], 'content' => json_encode($toolResult)] ] ]); yield ['event' => 'tool_complete', 'data' => [ 'id' => $currentToolCall['id'], 'result' => $toolResult ]]; // Loop back to give the tool result to the LLM continue 2; } } // If we reached here without a tool call, the model produced its final response if (!empty($accumulatedContent)) { $conversation->messages()->create([ 'role' => 'assistant', 'content' => $accumulatedContent, ]); } $run->update(['status' => AgentStatus::Completed]); yield ['event' => 'done', 'data' => ['run_id' => $run->id]]; return; } $run->update(['status' => AgentStatus::Failed, 'error' => 'Max iterations exceeded']); yield ['event' => 'error', 'data' => ['message' => 'Agent execution reached cycle limit without resolving.']]; } private function executeToolWithCircuitBreaker(string $toolName, array $arguments): array { try { return $this->mcpManager->executeTool($toolName, $arguments); } catch (\Throwable $e) { Log::error("Tool execution failed: {$toolName}", ['error' => $e->getMessage()]); return [ 'is_error' => true, 'content' => "Error executing tool '{$toolName}': " . $e->getMessage(), ]; } } private function buildSystemPrompt(array $contextDocs): string { $contextSection = collect($contextDocs)->map(function ($doc, $idx) { return "<document index=\"{$idx}\">\n<title>{$doc['title']}</title>\n<content>{$doc['content']}</content>\n</document>"; })->implode("\n\n"); return <<<PROMPT You are an advanced enterprise intelligence agent with direct access to internal databases, APIs, and analytical tools. Always prioritize using verified context documents before making assumptions. CRITICAL INSTRUCTIONS: 1. Always ground your answers in the provided knowledge base context when possible. 2. If you need data you do not have, check your available tools and execute them. 3. If a tool returns an error, evaluate whether you can retry with altered parameters or explain the limitation to the user. 4. Output your reasoning concisely before making tool calls. CONTEXT DOCUMENTS: {$contextSection} PROMPT; } } 

┌─────────────────────────────────────────────────────────────┐ │ Laravel Host Process │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ McpClientManager │ │ │ └──────────┬───────────────────────────────▲──────────┘ │ │ │ JSON-RPC 2.0 Request │ JSON-RPC │ │ │ (tools/call) │ Response │ │ ▼ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ ProcessTransport (proc_open) │ │ │ └──────────┬───────────────────────────────▲──────────┘ │ └──────────────┼───────────────────────────────┼──────────────┘ │ STDIN │ STDOUT ▼ │ ┌─────────────────────────────────────────────────────────────┐ │ External MCP Server (Node/Python) │ │ e.g., @modelcontextprotocol/server-postgres │ └─────────────────────────────────────────────────────────────┘ 

namespace App\Services\Mcp; use RuntimeException; use Symfony\Component\Process\Process; class McpProcessClient { /** @var resource|null */ private $process = null; /** @var array<int, resource> */ private array $pipes = []; private int $requestId = 0; public function __construct( protected string $command, protected array $environment = [] ) {} public function start(): void { $descriptorSpec = [ 0 => ['pipe', 'r'], // STDIN 1 => ['pipe', 'w'], // STDOUT 2 => ['pipe', 'w'], // STDERR ]; $this->process = proc_open( $this->command, $descriptorSpec, $this->pipes, base_path(), array_merge($_ENV, $this->environment) ); if (!is_resource($this->process)) { throw new RuntimeException("Failed to spawn MCP Server process: {$this->command}"); } // Initialize MCP connection handshake $this->sendNotification('notifications/initialized'); } /** * Lists all tools advertised by this MCP server. */ public function listTools(): array { $response = $this->sendRequest('tools/list', []); // Map the MCP tool format to Anthropic's expected tool format return array_map(function ($tool) { return [ 'name' => $tool['name'], 'description' => $tool['description'] ?? '', 'input_schema' => $tool['inputSchema'], ]; }, $response['result']['tools'] ?? []); } /** * Executes a specific tool by name with arguments. */ public function callTool(string $name, array $arguments): array { $response = $this->sendRequest('tools/call', [ 'name' => $name, 'arguments' => $arguments, ]); if (isset($response['error'])) { throw new RuntimeException("MCP Error [{$response['error']['code']}]: {$response['error']['message']}"); } return $response['result'] ?? []; } private function sendRequest(string $method, array $params): array { $this->requestId++; $payload = [ 'jsonrpc' => '2.0', 'id' => $this->requestId, 'method' => $method, 'params' => (object) $params, ]; $json = json_encode($payload) . "\n"; fwrite($this->pipes[0], $json); fflush($this->pipes[0]); $rawResponse = fgets($this->pipes[1]); if ($rawResponse === false) { $err = stream_get_contents($this->pipes[2]); throw new RuntimeException("MCP Server closed pipe unexpectedly: {$err}"); } return json_decode($rawResponse, true) ?? []; } private function sendNotification(string $method, array $params = []): void { $payload = [ 'jsonrpc' => '2.0', 'method' => $method, 'params' => (object) $params, ]; fwrite($this->pipes[0], json_encode($payload) . "\n"); fflush($this->pipes[0]); } public function __destruct() { if (is_resource($this->process)) { foreach ($this->pipes as $pipe) { if (is_resource($pipe)) { fclose($pipe); } } proc_close($this->process); } } } 

namespace App\Services\Mcp; class McpClientManager { /** @var array<string, McpProcessClient> */ protected array $clients = []; public function __construct() { $this->bootServers(); } protected function bootServers(): void { $servers = config('mcp.servers', []); foreach ($servers as $name => $cfg) { $client = new McpProcessClient($cfg['command'], $cfg['env'] ?? []); $client->start(); $this->clients[$name] = $client; } } public function getAllToolDefinitions(): array { $allTools = []; foreach ($this->clients as $serverName => $client) { foreach ($client->listTools() as $tool) { // Namespace tool to prevent collisions: e.g. postgres__querySource：https://dev.to/hosseinhezami/i-built-a-full-stack-ai-agent-with-laravel-vue-mcp-and-rag-heres-how-it-works-538o
My favorites