https://github.com/statelyai/agent
Create state-machine-powered LLM agents using XState
https://github.com/statelyai/agent
agents ai llm state-machine statechart workflow
Last synced: 6 months ago
JSON representation
Create state-machine-powered LLM agents using XState
- Host: GitHub
- URL: https://github.com/statelyai/agent
- Owner: statelyai
- Created: 2023-12-21T22:03:31.000Z (almost 2 years ago)
- Default Branch: next
- Last Pushed: 2025-03-11T00:50:18.000Z (7 months ago)
- Last Synced: 2025-04-03T21:11:18.380Z (6 months ago)
- Topics: agents, ai, llm, state-machine, statechart, workflow
- Language: TypeScript
- Homepage: https://stately.ai/docs/agents
- Size: 1.43 MB
- Stars: 269
- Watchers: 15
- Forks: 18
- Open Issues: 6
-
Metadata Files:
- Readme: readme.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Stately Expert
Stately Expert is a flexible framework for building AI agents using state machines. Stately agents go beyond normal LLM-based AI agents by:
- Using state machines to guide the agent's behavior, powered by [XState](https://stately.ai/docs/xstate)
- Incorporating **observations**, **message history**, and **feedback** to the agent decision-making and text-generation processes, as needed
- Enabling custom **planning** abilities for agents to achieve specific goals based on state machine logic, observations, and feedback
- First-class integration with the [Vercel AI SDK](https://sdk.vercel.ai/) to easily support multiple model providers, such as OpenAI, Anthropic, Google, Mistral, Groq, Perplexity, and more
**Read the documentation: [stately.ai/docs/agents](https://stately.ai/docs/agents)**
# Stately Expert
Stately Expert is a framework for building intelligent AI agents that are guided by state machines and learn from experience. Rather than relying solely on LLM responses, agents use structured observations, feedback, and insights to make informed decisions and improve over time.
## Overview
Stately Expert combines state machines with reinforcement learning concepts to create agents that:
- Make decisions based on clear state transitions and goals
- Learn from past experiences and feedback
- Generate insights about state changes
- Improve decision-making through structured rewards
- Support multiple decision-making policies
The framework is built on [XState](https://stately.ai/docs/xstate) for state machine management and integrates with the [Vercel AI SDK](https://sdk.vercel.ai/) for flexible LLM support.
## Key Concepts
- **Observations**: Records of state transitions, containing:
- Previous state
- Event/action taken
- Resulting state
- Metadata about the transition
- **Decisions**: Actions the agent chooses to take based on:
- Current state
- Goal state
- Past observations
- Available feedback and insights
- Decision-making policy
- **Feedback**: Rewards or evaluations given to decisions, helping the agent learn which actions are effective
- **Insights**: Additional context about state transitions, helping the agent understand cause and effect
- **Episodes**: Complete sequences of state transitions, from initial state to goal state (similar to RL episodes)
## Quick Start
TODO
## Why Stately Expert?
Traditional LLM-based agents often make decisions with limited context and no ability to learn from experience. Stately Expert provides:
1. **Structured Decision Making**: State machines provide clear boundaries and valid transitions
2. **Learning from Experience**: Experts improve through feedback and observations
3. **Contextual Awareness**: Insights and observations inform better decisions
4. **Flexible Policies**: Different approaches for different needs
5. **Storage Integration**: Optional persistence of experiences and learning