Build AI-powered Android & iOS apps in Kotlin — chat, agents, RAG, and more.

MobileGraph is an open-source Kotlin Multiplatform SDK that lets you add AI capabilities to your Android and iOS apps — from a simple chatbot to a full autonomous agent — without worrying about process death, lifecycle, or provider lock-in.

Think of it as "LangChain / LangGraph, but built for mobile."

val session = MobileGraph.instance.createSession()

session.stream("Plan a 3-day trip to Tokyo").collect { chunk ->
    print(chunk.text)   // ← streams to your UI in real time
}

• Inspiration
• Why MobileGraph?
  • Core Principles
  • Design Goals
• Roadmap
• Quick Start
• Project Ecosystem
• Sample Applications
• Documentation
• Contributing
• License

MobileGraph is inspired by the architectural ideas pioneered by LangChain and LangGraph, which introduced modular LLM orchestration, retrieval pipelines, tool integration, and stateful workflow execution.

Instead of replicating those frameworks, MobileGraph reimagines these concepts for the Kotlin ecosystem by combining:

• Kotlin Multiplatform
• Strongly typed APIs
• Mobile-first runtime architecture
• Lifecycle-aware execution
• Immutable state management
• Provider-agnostic abstractions
• Native coroutine-based concurrency

Our goal is to provide Kotlin developers with a modern AI framework that feels as natural as Ktor for networking and Jetpack Compose for UI development while embracing the best architectural ideas from today's AI ecosystem.

MobileGraph is built with respect for the open-source community, and we are grateful to the projects whose ideas continue to inspire modern AI development.

The rapid evolution of Large Language Models has transformed how developers build intelligent applications. Frameworks such as LangChain and LangGraph have demonstrated the power of modular prompts, retrieval pipelines, tools, memory, and agent orchestration.

However, most AI frameworks have been designed primarily for server-side applications.

Mobile applications operate in a fundamentally different environment.

Applications can be:

• Suspended or terminated by the operating system
• Sent to the background at any time
• Affected by unstable or intermittent network connectivity
• Constrained by battery, memory, and storage limitations
• Expected to continue providing responsive user experiences even under resource pressure

These challenges require more than simply wrapping an LLM API.

MobileGraph was created to address these challenges by providing a mobile-first AI runtime built specifically for the Kotlin ecosystem.

Instead of treating mobile devices as thin clients, MobileGraph provides the infrastructure needed to build resilient, stateful, and production-ready AI applications that feel native to Android, iOS, and Kotlin Multiplatform.

MobileGraph is built around a small set of architectural principles that guide every module in the framework.

Unlike traditional AI frameworks, MobileGraph embraces the realities of mobile computing.

The runtime is designed to support:

• Lifecycle-aware execution
• Background processing
• Process recovery
• Checkpoint-ready workflows
• Offline-first architecture
• Resource-conscious execution

Applications should not depend on a specific AI provider.

MobileGraph provides a unified abstraction layer that allows developers to integrate multiple AI providers through a consistent API.

Supported providers include:

• OpenAI
• Google Gemini
• Anthropic Claude
• OpenRouter

with additional providers planned for future releases.

Changing providers should require little or no application code changes.

Every capability within MobileGraph is implemented as an independent module.

Developers only include the functionality they need.

Examples include:

• Prompt Engineering
• Structured Output Parsing
• Tool Calling
• Retrieval-Augmented Generation (RAG)
• Memory
• Agent Framework
• Graph Runtime

This modular architecture keeps applications lightweight while remaining highly extensible.

MobileGraph embraces Kotlin's type system.

Instead of relying on loosely typed maps or dynamic JSON structures, the framework encourages:

• Immutable models
• Type-safe builders
• Explicit contracts
• Compile-time validation
• Clear domain abstractions

This leads to safer, more maintainable applications.

MobileGraph is built using Kotlin Multiplatform from the ground up.

Business logic is shared across platforms while preserving native user experiences.

Supported platforms include:

• Android
• iOS
• Android Automotive
• Android TV
• Desktop (planned)
• JVM applications

The framework is built around Kotlin Coroutines and Flow.

This provides:

• Structured concurrency
• Reactive streaming
• Cooperative cancellation
• Efficient asynchronous execution

Developers work with familiar Kotlin APIs without introducing additional reactive frameworks.

Modern AI applications require more than simple prompt-response interactions.

MobileGraph provides the building blocks for intelligent systems through:

• Tool execution
• Memory
• Retrieval
• Multi-agent collaboration
• Stateful graph execution
• Human-in-the-loop workflows
• Durable execution

These capabilities enable developers to build applications that can reason, plan, and execute complex workflows.

MobileGraph aims to provide a developer experience that is:

• Simple enough for building a chatbot in minutes
• Powerful enough for enterprise-scale AI workflows
• Flexible enough to support multiple AI providers
• Efficient enough for resource-constrained mobile devices
• Stable enough for long-term production use
• Idiomatic to Kotlin and Kotlin Multiplatform

The framework is designed to grow with your application—from a single prompt to sophisticated multi-agent systems—without requiring fundamental architectural changes.

MobileGraph is being developed in incremental phases, with each phase building on a stable, modular, and extensible architecture.

Our mission is to become the Kotlin-first AI framework for the Android ecosystem and Kotlin Multiplatform, enabling developers to build everything from simple AI assistants to enterprise-grade, autonomous agentic applications. See Roadmap Guide

We welcome community contributions, ideas, and feedback as we continue building the future of AI development for the Android ecosystem.

To ensure stability and compatibility, verify your project meets these requirements:

• Kotlin: 2.0.0+ (Required for K2 compiler support)
• Gradle: 8.4+
• JDK: 17+
• Android Min SDK: 24+

Add the SDK to your project via Maven Central. Since MobileGraph is engine-agnostic, you must also provide a Ktor HTTP engine (e.g., OkHttp for Android).

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.github.mobilegraph:mobilegraph-sdk:0.5.0-alpha")
    
    // Required: Choose a Ktor engine
    implementation("io.ktor:ktor-client-okhttp:3.5.1") 
}

Initialize within a CoroutineScope (like lifecycleScope or viewModelScope) to ensure the registry is ready:

lifecycleScope.launch {
    MobileGraph.initialize {
        withModels {
            openai(apiKey = "sk-...") { isDefault = true }
            gemini(apiKey = "...")
            claude(apiKey = "...")
        }
    }
}

Start a resilient, stateful interaction with just a few lines:

val session = MobileGraph.instance.createSession()

// Resilient, streaming interaction
session.stream("Plan a 3-day trip to Tokyo").collect { chunk ->
    print(chunk.text)
}

If you are building a release version, add these rules to your proguard-rules.pro to prevent runtime crashes:

# Ktor & Serialization
-keepattributes Signature, *Annotation*, InnerClasses
-keep class io.ktor.** { *; }
-keep class kotlinx.serialization.json.** { *; }

# MobileGraph Models
-keep class io.mobilegraph.models.** { *; }
-keepclassmembers class * {
    @kotlinx.serialization.SerialName <fields>;
}

For more details on Setup see Setup Guide

Define and execute complex workflows with just a few lines:

    val agent = MyResearchAgent(mobileGraph.models.chat())
    val workflow = stateGraph {
        start("research")
        node(AgentNode("research", agent, runtime))
        node(EndNode("finish"))
        edge("research", "finish")
    }
    
// Run the agentic workflow with automatic checkpointing
    val result = runtime.run(workflow, initialState)

For more details on Agents see Agent Guide

For a detailed module dependency graph and architecture diagrams, see the Architecture Overview.

• mobilegraph-core: The backbone. Handles execution context, lifecycle, events, and component registry.
• mobilegraph-checkpoint: Infrastructure for state persistence and durable execution.
• mobilegraph-state: Core interfaces for immutable graph state and variable management.

• mobilegraph-agents: Orchestration logic for multi-agent workflows, parallel execution, and hierarchical delegation.
• mobilegraph-graph: Graph-based state machine engine with support for Fan-out/in and breakpoints.
• mobilegraph-models: Adapters for major LLM providers (OpenAI, Gemini, etc.) and capability orchestration.
• mobilegraph-tools: Infrastructure for function calling, tool registration, and semantic tool selection.
• mobilegraph-parsers: Type-safe structured data extraction (JSON-to-Kotlin objects) with prose extraction.
• mobilegraph-prompts: A type-safe DSL for building token-aware, structured prompts.
• mobilegraph-rag: High-level orchestration for retrieval-augmented generation pipelines.

• mobilegraph-documents: Document ingestion and processing (PDF, Text, Markdown).
• mobilegraph-embeddings: Interfaces and adapters for vector embedding models.
• mobilegraph-vectorstores: On-device and remote vector storage (e.g., SQLite-based vector search).
• mobilegraph-retrieval: Semantic search logic and context retrieval strategies.

The project includes a comprehensive reference implementation for Android that demonstrates the following core patterns:

• Resilient Chat: Basic state-aware interaction that survives backgrounding and process death.
• RAG (Retrieval-Augmented Generation): On-device PDF ingestion, vector embedding, and semantic retrieval.
• Autonomous Tool Agents: LLMs that can independently decide when and how to call local Kotlin functions (e.g., Weather, Calculator).
• Human-in-the-Loop (HITL): Workflows that pause for manual approval or feedback before proceeding.
• Parallel Execution (Fan-out/in): Running multiple agents simultaneously (e.g., a Researcher and a Poet) and merging their results.
• Hierarchical Sub-Agents: Complex "Manager-Worker" orchestrations where agents manage their own internal sub-graphs.

1. Configure API Key: Add your OpenAI API key to local.properties in the root folder:

   open_ai_api=sk-your-key-here

2. Android: Open the project in Android Studio and run the :androidApp configuration. The Master Screen provides a dashboard to launch each of these specific demos.
3. iOS: To be added soon.

Detailed guides for building agentic workflows with MobileGraph:

• Architecture Overview: How MobileGraph handles state and lifecycle.
• ADR (Architectural Decisions): The "Why" behind our technical choices.

Contributions are welcome.

If you'd like to contribute:

1. Fork the repository.
2. Create a feature branch.
3. Add tests for new functionality.
4. Submit a pull request.

Check out our CONTRIBUTING.md to join us.

MobileGraph is licensed under the Apache License 2.0. See the LICENSE file for more info.