IntentKit Development Assistant

Expert assistant for working with IntentKit, an autonomous agent framework for creating AI agents with powerful skills and capabilities.

Project Context

IntentKit is an open framework for building AI agents equipped with skills to fetch data, perform actions, and interact with environments. The project consists of:

Architecture Overview

Package Structure (Import Order - Left can never import Right)

```

utils → config → models → abstracts → clients → skills → core

```

1. **intentkit/core/** - Agent system driven by LangGraph

2. **intentkit/models/** - Entity models (Pydantic + SQLAlchemy)

3. **intentkit/config/** - System config (database, LLM/skill provider API keys)

4. **intentkit/skills/** - Skills system driven by LangChain's BaseTool

5. **intentkit/utils/** - Utility functions (logging, formatting)

6. **intentkit/abstracts/** - Interfaces for core and skills

Technology Stack

Development Guidelines

Code Quality Rules

1. Always use the latest package versions

2. Use English for all code comments and documentation

3. Use English for searches and queries

4. Place all imports at the beginning of files

5. Avoid creating unnecessary documentation or example scripts after implementation

6. Do NOT auto-commit unless explicitly requested

7. Ensure no `basedpyright` errors in changed files

8. Run linting before finalizing: `ruff format && ruff check --fix`

9. Run tests after changes: `pytest`

Architecture Rules

1. **Respect import order** to prevent circular dependencies:

- `utils` → `config` → `models` → `abstracts` → `clients` → `skills` → `core`

- Packages on the left can never import from packages on the right

2. **Use modern APIs**:

- SQLAlchemy 2.0 syntax (not legacy)

- Pydantic V2 (not V1)

3. **Skills Development**: When developing or modifying skills, consult `agent_docs/skill_development.md`

4. **Operations**: For Git commits, pull requests, or releases, consult `agent_docs/ops_guide.md`

Key Development Workflows

Setting Up Environment

```bash

Activate virtual environment

source .venv/bin/activate

Install dependencies

uv sync

```

Code Quality Checks

```bash

Format and lint

ruff format

ruff check --fix

Type checking (ensure no errors)

basedpyright

Run tests

pytest

```

Working with Skills

Skills are the core capabilities agents can use. They:

Frontend Development

For frontend work, refer to `frontend/AGENTS.md` for:

Common Tasks

Adding a New Skill

1. Check `agent_docs/skill_development.md` for patterns

2. Create skill class inheriting from `BaseTool`

3. Implement required methods

4. Add tests in `tests/skills/`

5. Register skill in appropriate configuration

Modifying Core Agent Logic

1. Locate relevant module in `intentkit/core/`

2. Respect the LangGraph architecture

3. Ensure changes don't break import order rules

4. Update tests in `tests/core/`

Database Model Changes

1. Update Pydantic models in `intentkit/models/`

2. Update corresponding SQLAlchemy models

3. Create migration script if needed

4. Test with both in-memory and storage operations

Important Notes

Resources