IntentKit Development

Expert development guide for the IntentKit autonomous agent framework, enabling creation and management of AI agents with powerful capabilities.

Architecture

Package Structure

Follow this import hierarchy to avoid circular dependencies (left can never import right):

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

**intentkit/ (pip package):**

**app/:**

**scripts/:**

**tests/:**

**frontend/:**

Technology Stack

Development Rules

1. **Always use latest package versions**

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

3. **Use English for searches**

4. **Do not git commit unless specifically asked**

5. **Place imports at the beginning of files**

6. **Do not write dedicated documentation or example scripts after implementing features** (unless requested)

Step-by-Step Instructions

1. Environment Setup

Before any development work:

```bash

Activate virtual environment (required for all commands)

source .venv/bin/activate

```

2. Skills Development

When developing or modifying skills:

1. **Read the detailed guide:** `agent_docs/skill_development.md`

2. Follow the skills/ package structure

3. Extend LangChain's BaseTool for new skills

4. Register skills in the skills system

5. Test skills via `tests/skills/`

3. Core Agent Development

When working on agent systems:

1. Work within `intentkit/core/`

2. Leverage LangGraph for agent orchestration

3. Follow the import hierarchy (core is rightmost, can import all others)

4. Use Pydantic models from `models/` for type safety

5. Store state via SQLAlchemy models

4. Configuration Changes

When modifying system configuration:

1. Update `intentkit/config/`

2. Ensure database config, LLM API keys, and skill provider keys are properly managed

3. Never hardcode secrets

4. Use environment variables or secure config files

5. Code Quality Checks

After implementing features:

```bash

Format code

ruff format

Fix linting issues

ruff check --fix

Run tests

pytest

Verify type safety with BasedPyright (check for errors in changed files)

```

6. Testing Strategy

1. **Unit tests:** `tests/core/` for core functionality

2. **Integration tests:** `tests/skills/` for skill interactions

3. **API tests:** `tests/api/` for server endpoints

4. Run full test suite before considering work complete

7. Frontend Integration

When working with the UI:

1. Navigate to `frontend/`

2. Review `frontend/AGENTS.md` for architecture details

3. Ensure API contracts match between backend and frontend

4. Test agent management workflows end-to-end

8. Operations & Releases

For Git commits, pull requests, or releases:

1. **Read the detailed guide:** `agent_docs/ops_guide.md`

2. Follow versioning conventions

3. Update changelogs as required

4. Do not commit unless explicitly instructed

Key Constraints

Example Workflow

**Adding a new skill:**

1. Activate environment: `source .venv/bin/activate`

2. Read skill development guide: `agent_docs/skill_development.md`

3. Create skill class extending LangChain's BaseTool in `intentkit/skills/`

4. Register skill in skills system

5. Write integration test in `tests/skills/`

6. Run: `ruff format && ruff check --fix && pytest`

7. Verify BasedPyright shows no errors in changed files

8. Do not commit (unless instructed)

**Modifying core agent logic:**

1. Activate environment: `source .venv/bin/activate`

2. Work in `intentkit/core/`

3. Follow LangGraph patterns for agent orchestration

4. Use Pydantic models from `models/`, SQLAlchemy for persistence

5. Update relevant tests in `tests/core/`

6. Run: `ruff format && ruff check --fix && pytest`

7. Verify BasedPyright compliance

8. Do not commit (unless instructed)

Additional Resources