IntentKit Agent Framework Assistant

Expert guidance for developing autonomous AI agents using the IntentKit framework.

Overview

IntentKit is an autonomous agent framework built on LangGraph that enables creation and management of AI agents with pluggable skills. This assistant helps you navigate the codebase, develop skills, and follow best practices.

Project Architecture

Core Package Structure (`intentkit/`)

The intentkit package follows a strict dependency hierarchy (left to right - left can never import right):

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

Application Structure (`app/`)

Supporting Directories

Technology Stack

| Component | Technology | Documentation |

|-----------|-----------|---------------|

| Package Manager | uv | - |

| Virtual Environment | .venv | Activate with `source .venv/bin/activate` |

| Code Formatter | ruff | Run `ruff format` after changes |

| Linter | ruff | Run `ruff check --fix` after changes |

| Type Checker | BasedPyright | Ensure no errors in changed files |

| API Framework | FastAPI | https://fastapi.tiangolo.com/ |

| Database ORM | SQLAlchemy 2.0 | https://docs.sqlalchemy.org/en/20/ |

| Data Models | Pydantic V2 | https://docs.pydantic.dev/latest/ |

| Testing | pytest | Run `pytest` after changes |

| Agent Framework | LangGraph | - |

| Skills Base | LangChain BaseTool | - |

Development Workflow

Step 1: Activate Environment

Always activate the virtual environment before starting work:

```bash

source .venv/bin/activate

```

Step 2: Understand Import Dependencies

Follow the strict dependency order when adding imports:

```

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

```

Never import from right to left to avoid circular dependencies.

Step 3: Development Guidelines

1. **Use Latest APIs**: Always use the newest version of each package

- SQLAlchemy: Use 2.0 API (not legacy 1.x patterns)

- Pydantic: Use V2 API (not obsolete V1 interfaces)

2. **Code Quality**:

- Place all imports at the beginning of files

- Use English for all code comments

- Use English for search queries

- Run linting after changes: `ruff format && ruff check --fix`

- Verify type checking: Check BasedPyright has no errors

- Run tests: `pytest`

3. **Version Control**:

- Do NOT auto-commit after coding unless explicitly requested

- See `agent_docs/ops_guide.md` for commit, PR, and release procedures

4. **Documentation**:

- No need to write dedicated documentation or example scripts after implementation

- Code should be self-documenting with clear comments

Step 4: Skills Development

When developing or modifying agent skills:

1. Read the comprehensive guide: `agent_docs/skill_development.md`

2. Skills extend LangChain's BaseTool

3. Skills live in `intentkit/skills/`

4. Skills can fetch data, perform actions, or interact with the environment

5. Test skills in `tests/skills/`

Step 5: Testing

Run the test suite after making changes:

```bash

pytest

```

Test organization:

Step 6: Operations

For Git operations, pull requests, or releases:

1. Read the operations guide: `agent_docs/ops_guide.md`

2. Only perform Git commits when explicitly requested

3. Follow the merge workflow: `feature branches → dev → main`

Common Tasks

Creating a New Skill

1. Navigate to `intentkit/skills/`

2. Create a new file or modify existing skill

3. Inherit from LangChain's BaseTool

4. Implement required methods

5. Add tests in `tests/skills/`

6. Consult `agent_docs/skill_development.md` for detailed patterns

Modifying Core Agent Logic

1. Navigate to `intentkit/core/`

2. Understand LangGraph state machine

3. Follow import dependency order

4. Update tests in `tests/core/`

5. Verify no circular imports

Adding Configuration

1. Navigate to `intentkit/config/`

2. Add configuration parameters

3. Update environment variable handling

4. Document required API keys or settings

Working with Models

1. Navigate to `intentkit/models/`

2. Create paired models:

- Pydantic model for in-memory operations

- SQLAlchemy model for database persistence

3. Use SQLAlchemy 2.0 patterns (not legacy)

4. Use Pydantic V2 features (not V1)

Quick Reference

```bash

Activate environment

source .venv/bin/activate

Format and lint

ruff format

ruff check --fix

Run tests

pytest

Start local API

python app/api_server.py

Run autonomous agent

python app/autonomous_runner.py

```

Important Constraints

When You Need Help