IntentKit Development Assistant

Expert development assistant for the IntentKit autonomous agent framework. Provides comprehensive guidance on architecture, development patterns, testing, and operations for building AI agents with powerful skills.

What is IntentKit?

IntentKit is an autonomous agent framework that enables creation and management of AI agents with capabilities. It provides a complete package for building, deploying, and managing AI agents with a skills-based architecture powered by LangGraph and LangChain.

Project Structure

The IntentKit project is organized into several key directories:

IntentKit Package (`intentkit/`)

Published as a pip package with the following structure:

**`intentkit/core/`** - Agent system driven by LangGraph

**`intentkit/models/`** - Entity models with both Pydantic models (memory) and SQLAlchemy models (storage)

**`intentkit/config/`** - System-level configuration (database, LLM provider API keys, skill provider API keys)

**`intentkit/skills/`** - Skills system based on LangChain's BaseTool for data fetching, actions, and environment interaction

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

**`intentkit/abstracts/`** - Interfaces for core and skills modules

IntentKit App (`app/`)

Contains:

Local API server

Autonomous runner

Background scheduler

Users can either use the intentkit package in their own projects for customization or start the local API and frontend for local development/single-user use (no-auth).

Scripts (`scripts/`)

Agent management scripts

Manual operation scripts

Migration scripts

Integration Tests (`tests/`)

Core package testing: `tests/core/`

API server testing: `tests/api/`

Skill integration testing: `tests/skills/`

Frontend (`frontend/`)

Next.js application for managing agents. See `frontend/AGENTS.md` for detailed architecture and development guidelines.

Technology Stack

Package Management

**Package manager**: uv

**Virtual environment**: `.venv`

- Always activate with `source .venv/bin/activate` before running commands

Code Quality Tools

**Linter**: ruff

- Run `ruff format && ruff check --fix` after final edits

**Language Server**: BasedPyright

- Ensure changed files have no `basedpyright` errors

Core Technologies

**API framework**: FastAPI ([docs](https://fastapi.tiangolo.com/))

**DB ORM**: SQLAlchemy 2.0 ([docs](https://docs.sqlalchemy.org/en/20/))

- ⚠️ Use SQLAlchemy 2.0 API only, not legacy methods

**Model validation**: Pydantic V2 ([docs](https://docs.pydantic.dev/latest/))

- ⚠️ Do not use obsolete V1 interfaces

**Testing**: pytest

- Run `pytest` after final edits

Development Rules

1. **Always use the latest version of packages**

2. **Use English for all code comments**

3. **Use English for searches**

4. **Do not git commit automatically unless specifically requested**

5. **Place imports at the beginning of files in new code**

6. **No need to write dedicated documentation or example scripts after implementing functionality**

Architecture Guidelines

Avoiding Circular Dependencies

Package import order in `intentkit/` (left packages can never import right packages):

```

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

```

Follow this hierarchy strictly to prevent circular import issues.

Skills Development

When developing or modifying skills, refer to the detailed guide: **`agent_docs/skill_development.md`**

Skills are built on LangChain's `BaseTool` and enable agents to:

Fetch data from external sources

Perform actions in the environment

Interact with APIs and services

Operations Guide

For Git operations, pull requests, or releases, refer to: **`agent_docs/ops_guide.md`**

Development Workflow

1. Environment Setup

```bash

Activate virtual environment

source .venv/bin/activate

Install dependencies with uv

uv pip install -e .

```

2. Development Cycle

```bash

Make code changes following architecture guidelines

Format and lint code

ruff format

ruff check --fix

Verify with language server (check for basedpyright errors)

Run tests

pytest

```

3. Key Development Areas

**Working on Core Agent System (`intentkit/core/`)**

LangGraph-based agent orchestration

State management and transitions

Agent execution flows

**Working on Skills (`intentkit/skills/`)**

Consult `agent_docs/skill_development.md`

Extend LangChain's `BaseTool`

Implement skill registration and discovery

**Working on Models (`intentkit/models/`)**

Define Pydantic models for runtime validation

Define SQLAlchemy models for persistence

Ensure both model types stay in sync

**Working on API (`app/`)**

FastAPI route definitions

Request/response validation

Background task scheduling

Important Constraints

Import Order Enforcement

Respect the package dependency hierarchy to avoid circular imports:

`utils` and `config` are foundational

`models` and `abstracts` depend on foundational packages

`clients` and `skills` depend on models/abstracts

`core` sits at the top and can import from all others

SQLAlchemy 2.0 Usage

Only use SQLAlchemy 2.0 APIs. Legacy patterns from 1.x are prohibited.

Pydantic V2 Only

Use only Pydantic V2 APIs. V1 interfaces are deprecated and must not be used.

Testing Requirements

Always run `pytest` after changes to ensure integration tests pass.

Code Quality Gates

All code must pass `ruff format` and `ruff check --fix`

All code must have zero `basedpyright` errors

Best Practices

1. **Activate virtual environment first** - Always run `source .venv/bin/activate` before any development tasks

2. **Follow the import hierarchy** - Respect the package dependency order

3. **Read specialized guides** - Consult `agent_docs/skill_development.md` for skills, `agent_docs/ops_guide.md` for operations

4. **Use modern APIs** - SQLAlchemy 2.0 and Pydantic V2 only

5. **Test thoroughly** - Run pytest after changes

6. **Lint before committing** - Run ruff format and check

7. **Check type errors** - Verify basedpyright reports no errors

8. **English everywhere** - Code comments, searches, and documentation in English

Resources

Frontend architecture: `frontend/AGENTS.md`

Skill development: `agent_docs/skill_development.md`

Operations guide: `agent_docs/ops_guide.md`

FastAPI docs: https://fastapi.tiangolo.com/

SQLAlchemy 2.0 docs: https://docs.sqlalchemy.org/en/20/

Pydantic V2 docs: https://docs.pydantic.dev/latest/

IntentKit Development Assistant

IntentKit Development Assistant

What is IntentKit?

Project Structure

IntentKit Package (`intentkit/`)

IntentKit App (`app/`)

Scripts (`scripts/`)

Integration Tests (`tests/`)

Frontend (`frontend/`)

Technology Stack

Package Management

Code Quality Tools

Core Technologies

Development Rules

Architecture Guidelines

Avoiding Circular Dependencies

Skills Development

Operations Guide

Development Workflow

1. Environment Setup

Activate virtual environment

Install dependencies with uv

2. Development Cycle

Make code changes following architecture guidelines

Format and lint code

Verify with language server (check for basedpyright errors)

Run tests

3. Key Development Areas

Important Constraints

Import Order Enforcement

SQLAlchemy 2.0 Usage

Pydantic V2 Only

Testing Requirements

Code Quality Gates

Best Practices

Resources

Reviews (0)