IntentKit Development Guide
Expert assistant for developing with IntentKit, an autonomous agent framework for creating AI agents with powerful skills.
Project Architecture
Core Package Structure (`intentkit/`)
Published as a pip package with the following organization:
**`intentkit/core/`** - Agent system powered by LangGraph**`intentkit/models/`** - Entity models (Pydantic for memory, SQLAlchemy for persistence)**`intentkit/config/`** - System configuration (database, LLM provider keys, skill provider keys)**`intentkit/skills/`** - Skills system based on LangChain's BaseTool for data fetching and actions**`intentkit/utils/`** - Utility functions (logging, formatting, etc.)**`intentkit/abstracts/`** - Interfaces for core and skills modulesApplication Structure (`app/`)
Local API serverAutonomous runnerBackground schedulerCan be used via package integration or standalone local API + frontendSupporting Directories
**`scripts/`** - Agent management, manual operations, migrations**`tests/`** - Integration tests for core, API, and skills**`frontend/`** - Next.js application (see `frontend/AGENTS.md` for details)Technology Stack
Development Tools
**Package Manager:** uv**Virtual Environment:** `.venv` - Always activate with `source .venv/bin/activate` before running commands**Linting:** ruff - Run `ruff format & ruff check --fix` after final edits**Type Checking:** BasedPyright - Ensure no errors in changed filesCore Technologies
**API Framework:** FastAPI - https://fastapi.tiangolo.com/**ORM:** SQLAlchemy 2.0 (use modern API, not legacy) - https://docs.sqlalchemy.org/en/20/**Models:** Pydantic V2 (avoid V1 interfaces) - https://docs.pydantic.dev/latest/**Testing:** pytest - Run after final editsDevelopment Guidelines
Package Dependency Order
To avoid circular dependencies in `intentkit/`, follow this import hierarchy (left packages can NEVER import right packages):
```
utils → config → models → abstracts → clients → skills → core
```
Required Practices
1. ✅ Always use latest package versions
2. ✅ Use English for all code comments
3. ✅ Use English for searches
4. ✅ Place imports at the beginning of files
5. ❌ Do NOT git commit after coding unless specifically requested
6. ❌ Do NOT write dedicated documentation or example scripts after implementing features
Code Quality Checklist
Before completing any task:
1. Activate virtual environment: `source .venv/bin/activate`
2. Run linting: `ruff format & ruff check --fix`
3. Check types: Ensure no BasedPyright errors
4. Run tests: `pytest`
Specialized Guides
Skills Development
When developing or modifying skills, refer to: `agent_docs/skill_development.md`
Operations
For Git commits, pull requests, or releases, refer to: `agent_docs/ops_guide.md`
Common Workflows
Setting Up Development Environment
```bash
source .venv/bin/activate
```
Code Quality Workflow
```bash
Format and lint
ruff format
ruff check --fix
Run tests
pytest
```
Working with IntentKit Package
The framework uses:
**LangGraph** for agent orchestration**LangChain BaseTool** for skill implementations**Pydantic V2** for data validation**SQLAlchemy 2.0** for database operationsArchitecture Notes
IntentKit can be used as a library in custom projectsOr run as standalone local API + frontend (no-auth mode)Skills enable agents to fetch data, perform actions, and interact with environmentModels exist in dual forms: Pydantic (memory) and SQLAlchemy (storage)Key Constraints
Respect package dependency order to prevent circular importsUse SQLAlchemy 2.0 API patterns onlyUse Pydantic V2 patterns onlyMaintain English-only codebaseRun quality checks before finalizing changes