Mistral Agents API: Comprehensive Visual Architecture Guide
Mistral Agents API: Comprehensive Visual Architecture Guide
Section titled “Mistral Agents API: Comprehensive Visual Architecture Guide”This document provides detailed visual representations of all key architectural patterns and data flows in the Mistral Agents API ecosystem.
Part 1: Comprehensive Diagrams
Section titled “Part 1: Comprehensive Diagrams”[All diagram content from comprehensive_guide.md is included here as well - see previous document for complete ASCII diagrams]
Part 2: Sequence Diagrams
Section titled “Part 2: Sequence Diagrams”Web Search Agent Interaction
Section titled “Web Search Agent Interaction”Client Mistral API Agent Logic Web Search LLM │ │ │ API │ ├─ POST /conversations │ │ │ │ {agent_id, inputs} │ │ │ │─────────────────────────────────> │ │ │ │ │ │ │ │ ├──Load Agent Config │ │ │ ├──Load Conversation History │ │ │ │ │ │ │ │ Agent Routing │ │ │ ├─────────────────────────────────────────────> │ │ │ Process │ │ │ w/Context │ │ │ │ │ │ │ <───────── │ │ Needs web search │ │ │ │ │ │ ├─────────────────web_search()─────────────────> │ │ │ │ │ │ │ │ Search │ │ │ │ Executed │ │ │ │<────────────────────── │ │ Results │ │ │ │ │ │ │ │ Append to History │ │ │ │ ├────────────────────────────────────────────────> │ │ │ │ Continue │ │ │ │ w/Results │ │ │ │ │ │ │ │ │ <───────── │ │ Final Response │ │ │ │ │ │ │ │ <─────────────Response──────────────── │ │ │ │ │ │ │Multi-Agent Handoff Pattern
Section titled “Multi-Agent Handoff Pattern”Client Manager Agent Specialist 1 Specialist 2 DB │ │ │ │ │ ├─ Query ─────────────────────────────> │ │ │ │ │ │ │ ├─Analyze Request──> │ │ │ │ │ │ │ │<─Needs Research─── │ │ │ │ │ │ │ ├─ Delegate to Specialist 1 ──────> │ │ │ │ │ │ │ Research ─────────────────> │ │ Done │ │ │ │ <────────────── │ │ ┌────────────┐ │ │ │ │ Store │ │ │ │ │ Results │─────────────> │ │ └────────────┘ │ │ │ Results │ │ │ <────────── │ │<─Research Complete───────── │ │ │ │ │ │ ├─ Delegate to Specialist 2 ──────────────────> │ │ Analyse │ │ │ <────────────────────── │ │<─Analysis Complete────── │ │ │ │ │ │ ├─ Synthesize Results ────────────> │ │ │ Combine │ │ │ <─────────── │ │ │ │ │ │<──Final Report───────────────────────────────── │ │ │ │ │ │ │Streaming Conversation Flow
Section titled “Streaming Conversation Flow”Client Mistral Server │ │ ├─ POST /conversations?stream=true │ │────────────────────────────────────> │ │ │ Process Request │ │ │<─ SSE: conversation.response.started │ │ │<─ SSE: message.output.delta "The"│ │ │ │<─ SSE: message.output.delta " weather" │ │ │<─ SSE: message.output.delta " is sunny" │ │ │ (Tool needed) │ │ │<─ SSE: tool.execution.started │ │ {name: "web_search"} │ │ │ │ Execute tool in background │ │ │<─ SSE: tool.execution.completed │ │ {result: "..."} │ │ │ │<─ SSE: message.output.delta " and 25°C" │ │ │<─ SSE: conversation.response.done│ │ {tokens: {...}} │ │ │Persistent Memory Retrieval
Section titled “Persistent Memory Retrieval”Turn 1 (Day 1): Client ─ "What's your name?" ─> Agent Agent ─ "I'm Alice" ──────────> DB
Turn 2 (Day 2): Client ─ "What did you say earlier?" ─> Agent │ ├─ Load Conversation History from DB │ ├─ Entry 1: User: "What's your name?" │ └─ Entry 2: Agent: "I'm Alice" │ ├─ Include in Context │ "Remember the conversation history: │ User: What's your name? │ Agent: I'm Alice" │ └─ Process with LLM
Agent ─ "I said my name is Alice" ──> ClientPart 3: Data Structure Diagrams
Section titled “Part 3: Data Structure Diagrams”Conversation Entry Object
Section titled “Conversation Entry Object”ConversationEntry { ├─ id: string (unique) │ └─ msg_xxxxxxxxx │ ├─ type: string │ ├─ message.input (user message) │ ├─ message.output (agent response) │ ├─ tool.execution (tool call & result) │ └─ function.result (custom tool) │ ├─ role: string │ ├─ user │ ├─ assistant │ └─ tool │ ├─ content: string | object | array │ └─ May include tool references │ ├─ created_at: ISO8601 timestamp ├─ completed_at: ISO8601 timestamp (optional) │ ├─ agent_id: string (optional) │ └─ ag_xxxxxxxxx │ ├─ model: string (optional) │ └─ mistral-medium-2505 │ ├─ conversation_id: string │ └─ conv_xxxxxxxxx │ └─ metadata: object (optional) └─ Custom fields}Tool Definition Structure
Section titled “Tool Definition Structure”Tool { ├─ type: string │ ├─ web_search (Brave search) │ ├─ web_search_premium (Premium search) │ ├─ code_interpreter (Python/JS execution) │ ├─ image_generation (DALL-E) │ ├─ document_library (RAG) │ └─ function (Custom tool) │ ├─ (if type == "function") │ └─ function { │ ├─ name: string │ │ └─ "get_weather" │ │ │ ├─ description: string │ │ └─ "Get current weather..." │ │ │ └─ parameters: JSONSchema │ ├─ type: "object" │ ├─ properties: { │ │ └─ location: {type: "string"} │ │ │ └─ required: ["location"] │ } │ └─ (if type == "web_search") └─ No parameters needed}Part 4: Processing Pipeline Flows
Section titled “Part 4: Processing Pipeline Flows”Request Processing Pipeline
Section titled “Request Processing Pipeline”REQUEST → VALIDATION → AUTH → RATE LIMIT → QUEUE → WORKER │ │ │ │ │ │ ├─> Parse ├─> Check ├─> API ├─> Check ├─> Route ├─> Load │ JSON │ Format │ Key │ Quota │ to │ Agent │ │ │ │ │ Pool │ └─────────────────────────────────────────────────────> │ ▼ <─ RESPONSE ◄─ SERIALIZE ◄─ PROCESS ◄─ GENERATE ◄─ STREAM │ │ │ │ ├─> Format ├─> JSON ├─> LLM ├─> Tools │ Headers │ Encode │ Forward │ Exec └────────────────────────────────────>LLM Forward Pass with Tools
Section titled “LLM Forward Pass with Tools”┌─ System Prompt (Agent Instructions)├─ Conversation History (Full Context)├─ New User Input└─ Tools Specification │ ▼┌──────────────────────┐│ LLM Processing ││ (Attention passes) │└──────────────────────┘ │ ┌────┴─────┐ │ │ ▼ ▼ Response Tool Call │ │ │ ┌───┴────────────────┐ │ ▼ ▼ │ Valid Schema? Error │ │ │ │ Yes Return │ │ Error │ ▼ │ Execute Tool │ │ │ ▼ │ Tool Result │ │ │ ▼ │ Append to History │ │ │ ▼ │ Loop back to LLM? │ │ │ ┌──┴──┐ │ │ │ │ Yes No │ │ │ └────┼─────┘ │ ▼ Return OutputPart 5: System Architecture
Section titled “Part 5: System Architecture”High-Level System Design
Section titled “High-Level System Design”┌──────────────────────────────────────────────────────────────┐│ CLIENT APPLICATIONS ││ (Web, Mobile, Desktop, CLI, etc.) │└──────────────────────────────────────────────────────────────┘ │ ▼┌──────────────────────────────────────────────────────────────┐│ MISTRAL API GATEWAY ││ ├─ Authentication (API Key verification) ││ ├─ Rate Limiting (Token bucket algorithm) ││ ├─ Request Validation (Schema validation) ││ └─ Routing (Direct to appropriate service) │└──────────────────────────────────────────────────────────────┘ │ │ │ ▼ ▼ ▼┌──────────────────┐┌──────────────────┐┌──────────────────┐│ Agents Service ││ Conversations ││ Tools Service │├──────────────────┤├──────────────────┤├──────────────────┤│ ├─ Agent CRUD ││ ├─ Start ││ ├─ Web Search ││ ├─ Versioning ││ ├─ Continue ││ ├─ Code Exec ││ ├─ Config ││ ├─ Restart ││ ├─ Image Gen ││ └─ Metadata ││ ├─ History ││ ├─ Doc Library ││ ││ └─ List ││ └─ Custom Tools │└────────┬────────┘└────────┬─────────┘└────────┬─────────┘ │ │ │ └──────────────────┼───────────────────┘ ▼ ┌──────────────────────────────────────┐ │ LLM EXECUTION ENGINE │ │ ├─ Model Selection │ │ ├─ Context Assembly │ │ ├─ Token Counting │ │ └─ Streaming Output │ └──────────────────────────────────────┘ │ ┌──────────────────┼──────────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌──────────┐ ┌─────────┐ │mistral- │ │mistral- │ │mistral- │ │small │ │medium │ │large │ └─────────┘ └──────────┘ └─────────┘ (Model Pool / Load Balancer) │ └──────────────────┬──────────────────┐ ▼ ▼ ┌─────────────┐ ┌────────────────┐ │Database │ │Cache Layer │ │├─ Agents │ │├─ Conversation │ │├─ Conversat │ ││ Context │ ││ ions │ │├─ Agent Config │ │├─ Entries │ │└─ Tool Results │ │└─ Metadata │ └────────────────┘ └─────────────┘Conversation State Database Schema
Section titled “Conversation State Database Schema”AGENTS TABLE────────────id (PK) │ VARCHARname │ VARCHARdescription │ TEXTmodel │ VARCHARinstructions │ TEXTversion │ INTcreated_at │ TIMESTAMPupdated_at │ TIMESTAMPtools (JSON) │ JSONBcompletion_args (JSON) │ JSONBowner_id │ VARCHAR (FK)status │ ENUM
CONVERSATIONS TABLE───────────────────id (PK) │ VARCHARagent_id (FK) │ VARCHARcreated_at │ TIMESTAMPupdated_at │ TIMESTAMPname │ VARCHARdescription │ TEXTowner_id │ VARCHAR (FK)status │ ENUMmetadata (JSON) │ JSONB
CONVERSATION_ENTRIES TABLE──────────────────────────id (PK) │ VARCHARconversation_id (FK) │ VARCHARtype │ ENUMrole │ ENUMcontent │ TEXT/JSONBcreated_at │ TIMESTAMPcompleted_at │ TIMESTAMPagent_id │ VARCHAR (FK)model │ VARCHARtool_name │ VARCHARtool_call_id │ VARCHARmetadata (JSON) │ JSONBparent_entry_id │ VARCHAR (FK, nullable)token_count │ INT
INDEXES───────idx_conv_agent │ CONVERSATIONS(agent_id)idx_entries_conv │ ENTRIES(conversation_id)idx_entries_created │ ENTRIES(created_at)idx_owner_conv │ CONVERSATIONS(owner_id)idx_agent_owner │ AGENTS(owner_id)Part 6: Error Handling Flow
Section titled “Part 6: Error Handling Flow”REQUEST PROCESSING │ ▼ ┌─────────┐ │ Error? │ └────┬────┘ │ ┌───┴───┐ │ │ No Yes │ │ ▼ ▼ Continue ┌──────────────────────────┐ │ Error Type? │ └──────────┬───────────────┘ │ ┌────────────┼────────────┐ ▼ ▼ ▼ ┌─────┐ ┌────────┐ ┌──────────┐ │Auth │ │Validation │ Rate │ │Error│ │Error │ Limit │ └──┬──┘ └────┬───────┘ └────┬───┘ │ │ │ ▼ ▼ ▼ 401 422 429 Unauthorized Invalid Too Many Request Requests │ │ │ └────────────┼────────────┘ ▼ ┌──────────────────────┐ │ Format Error │ │ Response │ │ { │ │ "status": "code", │ │ "error": "message", │ │ "type": "type_code" │ │ } │ └──────────────────────┘ │ ▼ Return to ClientPart 7: Deployment Architecture
Section titled “Part 7: Deployment Architecture”Single-Region Deployment
Section titled “Single-Region Deployment”┌─────────────────────────────────────────────────────┐│ REGION: us-east-1 │├─────────────────────────────────────────────────────┤│ ││ ┌────────────────────────────────────────────┐ ││ │ Load Balancer / API Gateway │ ││ └────────────────────────────────────────────┘ ││ │ ││ ┌──────────────────┼──────────────────────────┐ ││ │ │ │ ││ ▼ ▼ ▼ ││ ┌──────┐ ┌──────┐ ┌──────┐ ││ │Worker│ │Worker│ ... │Worker│ ││ │Pool-1│ │Pool-2│ │Pool-N│ ││ └──────┘ └──────┘ └──────┘ ││ (Auto-scaling) ││ │ ││ ▼ ││ ┌────────────────────────────────────────────┐ ││ │ Distributed Cache (Redis Cluster) │ ││ │ - Session state │ ││ │ - Rate limit counters │ ││ │ - Frequently accessed config │ ││ └────────────────────────────────────────────┘ ││ │ ││ ▼ ││ ┌────────────────────────────────────────────┐ ││ │ Primary Database (PostgreSQL) │ ││ │ - Agents │ ││ │ - Conversations │ ││ │ - Entries │ ││ └────────────────────────────────────────────┘ ││ │ │ ││ ▼ ▼ ││ ┌──────────┐ ┌───────────┐ ││ │ Hot │ │ Warm │ ││ │ Replicas │ │ Backups │ ││ └──────────┘ └───────────┘ ││ │└─────────────────────────────────────────────────┘This diagrams document provides comprehensive visual references for all major components and flows in the Mistral Agents API system.