Rig: A Rust LLM Framework That Separates Providers from Agent Orchestration

What Problem Rig Solves and Who It Targets

Rig addresses a specific pain for Rust developers who want to build LLM-powered applications without being locked into a single provider. The library offers a unified interface over 20+ model providers and 10+ vector store integrations. That means you can write code against one API and switch between OpenAI, Anthropic, or others by changing configuration rather than rewriting calls. The target audience is engineers who value Rust's performance and type safety but do not want to hand-roll HTTP clients, streaming handling, and tool-calling logic for each vendor. It also targets teams that need agentic workflows, not just single completion calls. The README lists real users like St Jude, Nethermind, and ilert, which suggests the library has moved beyond toy examples, though you should not take those names as an endorsement of maturity. The project is explicit about its current state: the warning at the top says 'Here be dragons' and states that future updates will contain breaking changes. That honesty is useful, but it also tells you this is not a tool for a risk-averse production environment without a plan for frequent migration.

The Core Split: rig-core and rig-agent

The most interesting architectural decision in Rig is the separation between rig-core and rig-agent. Rig-core holds provider-neutral messages, completion models, portable tools, memory and vector-store contracts, and built-in provider mappings. Rig-agent contains the classic builder, prompt and streaming traits, typed hooks, contextual tools, extraction, and a serializable AgentRun state machine. The root rig facade re-exports both, so most code depends only on rig. This split matters because it lets you use provider abstractions without pulling in the agent runtime, or vice versa. It also makes the portable core theoretically usable in environments where the full agent runtime is too heavy. The README states that rig-agent remains enabled by default, so you get the classic runtime out of the box. The separation is not just cosmetic: it allows the core to support browser-WASM while the agent runtime also supports it, but MCP is native-only. If you need MCP, you cannot run it in a WASM target. That is a concrete constraint that comes directly from this design.

How It Works: Providers, Completion, Embeddings, and Agentic Workflows

Rig's mechanism revolves around a unified trait-based interface for LLM completion and embedding workflows. You define a model provider, and the library handles the underlying protocol. The features list includes support for transcription, audio generation, and image generation, which goes beyond text-only LLM calls. For agentic workflows, Rig supports multi-turn streaming and prompting. The classic runtime is enabled by default, and it includes a serializable AgentRun state machine. That serializability is a notable design point: it means an agent's state can be saved, resumed, or transmitted, which is useful for long-running or distributed tasks. The README also mentions full GenAI Semantic Convention compatibility, which is an OpenTelemetry specification for generative AI systems. That means Rig can emit telemetry that follows a standard semantic convention, which is valuable for teams that already use OpenTelemetry. The exact data flow is not detailed in the README, but the presence of typed hooks and contextual tools suggests that you can inject custom logic at specific points in the agent loop. Without running the code, I cannot confirm the ergonomics, but the structure is clear enough to see that Rig is not just a thin HTTP wrapper.

Getting Started: Commands and Configuration

The README does not include a full quickstart code block in the cleaned version, but it points to the official docs at rig.rs/docs and the crate API reference at docs.rs/rig/latest/rig/. The typical Rust workflow applies: add rig as a dependency in your Cargo.toml, then import the facade. A simple example is mentioned in the table of contents, but the content is truncated. Based on the repository layout, you would create a completion model from a provider, then call it with a prompt. The README states that most code depends only on rig, meaning you do not need to reference rig-core or rig-agent directly unless you need finer control. The crate is published on crates.io, so cargo add rig should work, but the exact version matters. The latest release at the time of writing is v0.42.0, and the project releases frequently, roughly monthly. Because of the breaking-change warning, you should pin your dependency to a specific version and read the changelog before upgrading. The docs site likely contains migration paths, but the README itself does not list them.

Integrations and Target Support: What You Get and What You Lose

Rig lists 20+ model providers and 10+ vector store integrations under singular interfaces. The README does not enumerate them, but the claim is that you can swap providers without changing your application logic. It also supports embeddings, which is necessary for retrieval-augmented generation. The target support section mentions browser-WASM (wasm32-unknown-unknown) for the portable core and classic runtime, but WASI is not supported. That is a significant limitation: if you are targeting server-side WebAssembly with WASI, Rig will not work. Also, rig-rmcp and MCP are native-only, so any MCP-based tooling cannot run in a browser context. For teams building browser-based AI features, the WASM support is a differentiator, but the native-only MCP restriction could be a dealbreaker if you rely on the Model Context Protocol. The README does not specify which providers or vector stores are supported, so you must check the docs to confirm your specific backend is included. That is a verification step before adoption.

The Breaking Change Warning and Maintenance Cost

The README opens with a warning that future updates will contain breaking changes. That is not a generic disclaimer; it is a direct statement from the maintainers. They say they plan to ship a torrent of features and will annotate changes with migration paths. This means upgrading Rig is not a simple bump of a version number. You should budget time for code changes when new releases come out. The release cadence is fast: v0.42.0 in August 2026, v0.41.0 in July, and v0.40.0 in early July. That is roughly one release per month. For a library at version 0.42, the API is still in flux, and semver does not guarantee backward compatibility before 1.0. The project is not archived and has an active default branch, so maintenance is ongoing, but the cost is on you as the adopter. The MIT license is permissive, so you can fork and patch if needed, but you would be maintaining a fork against an upstream that moves quickly. If you cannot tolerate that churn, wait for a 1.0 release or look elsewhere.

Alternatives and How They Differ

The most direct alternative to Rig is the async-openai crate, which provides a Rust client for OpenAI's API. The difference in approach is significant: async-openai is provider-specific, so you cannot switch to Anthropic or another provider without changing libraries. Rig's unified interface is the main reason to choose it over a single-provider client. Another alternative is to write your own abstraction layer over HTTP APIs, which gives you full control but requires you to handle streaming, tool calling, and error handling yourself. Rig does that work for you, but you trade control for convention. For agent orchestration, you could use a language-agnostic framework like LangChain, but that is Python-first and not native Rust. Rig's Rust-native design means you get compile-time checks and memory safety, which matters for performance-sensitive applications. The trade-off is that Rig is younger and less stable than a Python ecosystem. If you need provider flexibility and are comfortable with Rust's ecosystem, Rig is a reasonable choice. If you only ever call one provider, a dedicated client is simpler.

License and Usage Implications

Rig is released under the MIT license. That is a permissive license that allows commercial use, modification, and redistribution, with the requirement to include the original copyright notice. For engineering teams, this means you can embed Rig in proprietary software without paying a fee or opening your source code. The README does not mention any dual licensing or additional terms. The project is associated with 0xPlaygrounds and a related product called Ryzome, but the library itself is MIT. You should still review the full license text in the repository before making legal decisions, but the identifier is clear. The maintenance cost is not a legal issue but a practical one: because the project is pre-1.0 and evolving, you need to track changes. The MIT license gives you the freedom to fork if the project stalls, which is a safety net. That is a concrete advantage over a copyleft license if you plan to distribute a closed-source application.

Editorial conclusion

Adopt Rig if you are building LLM applications in Rust and want a single interface across many providers, with a default agent runtime and portable core that can target WASM. Do not adopt it if you need stability above all, since the README warns that future updates will contain breaking changes. Before committing, verify that your target provider and vector store are in the supported list, confirm that MCP is not required in a WASM context (it is native-only), and review the migration notes for the version you plan to use, as the project is evolving rapidly.

Official sources

1. 0xPlaygrounds/rig on GitHub
2. License: MIT
3. Project website
4. README
5. Releases