IntentKit Autonomous Agent Development

Expert guidance for developing with IntentKit, an open and fair framework for building AI agents equipped with powerful skills.

What This Skill Does

This skill provides LLM agents with comprehensive knowledge of the IntentKit autonomous agent framework architecture, development patterns, and best practices. It enables agents to:

Project Architecture

Package Structure (`intentkit/`)

The intentkit package follows a strict import hierarchy to prevent circular dependencies:

**Import Order (left can import right, never reverse):**

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

1. **`intentkit/core/`** - Agent system powered by LangGraph

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

3. **`intentkit/config/`** - System configuration (database, API keys)

4. **`intentkit/skills/`** - Skills system using LangChain BaseTool

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

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

Application Structure (`app/`)

Supporting Directories

Development Instructions

Step 1: Environment Setup

Before any development work:

```bash

Activate virtual environment

source .venv/bin/activate

Verify environment is active before proceeding

```

Step 2: Technology Stack Requirements

Use these specific tools and versions:

- ⚠️ Use only 2.0 API patterns, not legacy APIs

- ⚠️ Use only V2 interfaces, not obsolete V1

Step 3: Code Organization Rules

1. **Import Hierarchy:** Respect the package import order to avoid circular dependencies

2. **Import Placement:** Always place imports at the beginning of files

3. **Language:** Use English for all code comments

4. **Latest Packages:** Always use the latest package versions

5. **No Auto-Commit:** Do not commit changes unless explicitly requested

Step 4: Skills Development

When developing or modifying agent skills:

1. Reference the detailed guide at `agent_docs/skill_development.md`

2. Skills are based on LangChain's `BaseTool`

3. Skills enable agents to fetch data, perform actions, and interact with environments

4. Follow the skills/ folder structure and conventions

Step 5: Quality Assurance

Before finalizing any changes:

```bash

1. Run linter and formatter

ruff format

ruff check --fix

2. Verify type checking

Ensure BasedPyright shows no errors in changed files

3. Run tests

pytest

4. Verify no circular imports

Check that import hierarchy is respected

```

Step 6: Testing

- `tests/core/` - Core package tests

- `tests/api/` - API server tests

- `tests/skills/` - Skill integration tests

Development Patterns

Model Development

Configuration Management

Agent System Development

Git Operations

When performing Git operations (commits, pull requests, releases), reference the detailed guide at `agent_docs/ops_guide.md`.

Key Constraints

1. **No Unnecessary Documentation:** Do not write dedicated documentation or example scripts after implementation unless explicitly requested

2. **English Only:** All code, comments, and searches must be in English

3. **Import Order:** Strictly follow the package import hierarchy

4. **Modern APIs Only:** Use SQLAlchemy 2.0 and Pydantic V2 patterns exclusively

5. **Type Safety:** Ensure BasedPyright validation passes

6. **Test Coverage:** Write and run tests for all changes

Example Workflow

```python

1. Activate environment

source .venv/bin/activate

2. Make changes following import hierarchy

intentkit/skills/new_skill.py

from langchain.tools import BaseTool

from intentkit.models import MyModel # OK: skills can import models

from intentkit.config import get_api_key # OK: skills can import config

class NewSkill(BaseTool):

name = "new_skill"

description = "Description of what this skill does"

def _run(self, query: str) -> str:

# Implementation

pass

3. Write tests

tests/skills/test_new_skill.py

4. Quality checks

ruff format && ruff check --fix

pytest

5. Verify BasedPyright shows no errors

```

Additional Resources

Notes