Contributing to the Inkeep Agent Framework

Thank you for your interest in contributing to the Agent Framework! This document provides guidelines and information for contributors.

Launch the Visual Builder

Step 1: Clone the repository

git clone https://github.com/inkeep/agents.git
cd agents

Step 2: Configure environment variables

cp agents-manage-api/.env.example agents-manage-api/.env && cp agents-run-api/.env.example agents-run-api/.env && cp agents-manage-ui/.env.example agents-manage-ui/.env && cp examples/.env.example examples/.env

Add your ANTHROPIC_API_KEY to an .env file at /agents-run-api/

ANTHROPIC_API_KEY=sk-ant-xyz789

Step 3: Setup and install

pnpm install

Step 4: Initialize database

pnpm --dir ./packages/agents-core db:push

Step 5: Run the agent framework

pnpm dev

Step 6: Start building!

Open http://localhost:3000 in the browser and start building agents.

Push your first graph

A key advantage of the Inkeep agent framework is its seamless code-to-visual workflow: define your agents programmatically, push them to the visual builder, and continue developing with the intuitive drag-and-drop interface.

Follow the steps below to push your first graph using the Inkeep CLI.

Step 1: Download the Inkeep CLI

pnpm install -g @inkeep/agents-cli

Step 2: Push a graph

cd examples
inkeep push basic.graph.ts

Step 3: Observe the graph in the visual builder

Set up live traces

Step 1: Launch docker containers

cd deploy/docker
docker compose up -d

Step 2: Fetch SigNoz API Key

Open http://localhost:3080 in the browser. Go to Settings → Workspace Settings → API Keys and copy the API key.

Step 3: Configure environment variable

Create a .env file at /agents-manage-ui/ with the following variable:

SIGNOZ_API_KEY=your-signoz-api-key-here

Step 4: View your live traces

Refresh the live traces panel on the right to see your agents in action.

Set up credentials

Step 1: Create .env file and generate encryption key

cp deploy/docker/.env.nango.example deploy/docker/.env && encryption_key=$(openssl rand -base64 32) && sed -i '' "s|REPLACE_WITH_BASE64_256BIT_ENCRYPTION_KEY|$encryption_key|" deploy/docker/.env && echo "Docker environment file created with auto-generated encryption key"

Step 2: Restart the containers

cd deploy/docker
docker compose up -d

Step 3: Get your Nango API key

Open the Nango Dashboard: http://localhost:3050 and navigate to Environment Settings → API Keys and copy the API key.

Step 4: Configure environment variables

Navigate back to the root directory and paste the below command. Enter your Nango API key when prompted:

cd ../../
printf "Enter your Nango API key: " && read key && sed -i '' "s|^NANGO_SECRET_KEY=.*|NANGO_SECRET_KEY=$key|" agents-manage-api/.env agents-run-api/.env agents-manage-ui/.env && echo "Application files updated with Nango API key"

Step 5: Start creating credentials!

Navigate to the Credentials tab in the left sidebar and click "Create credential".

Development Workflow

Git Hooks

This project uses Husky for Git hooks to maintain code quality. The hooks are automatically installed when you run pnpm install.

Pre-commit Hook

The pre-commit hook runs the following checks before allowing a commit:

1. Type checking - Ensures type safety across all packages
2. Tests - Runs the test suite

Bypassing Checks

While we recommend running all checks, there are legitimate cases where you might need to bypass them:

Skip typecheck only (tests still run):

SKIP_TYPECHECK=1 git commit -m "WIP: debugging issue"

Skip all hooks (use sparingly):

git commit --no-verify -m "emergency: hotfix for production"

Note: Use these bypass mechanisms sparingly. They're intended for:

• Work-in-progress commits that you'll fix before pushing
• Emergency fixes where speed is critical
• Commits that only touch non-code files (though hooks are smart enough to handle this)

Code Quality

Type Checking

Run type checking across all packages:

pnpm typecheck

Linting

Run the linter:

pnpm lint

Format code automatically:

pnpm format

Testing

Run tests:

pnpm test              # Run all tests
pnpm test:watch        # Run tests in watch mode
pnpm test:coverage     # Run tests with coverage report

Building

Build all packages:

pnpm build

Commit Messages

We follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• test: Test changes
• chore: Build process or auxiliary tool changes

Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Ensure all checks pass (pnpm typecheck && pnpm test)
5. Commit your changes (following commit message guidelines)
6. Push to your fork
7. Open a pull request

PR Guidelines

• Keep PRs focused on a single feature or fix
• Update tests for any behavior changes
• Update documentation as needed
• Ensure CI passes before requesting review

Continuous Integration

Our CI pipeline runs on all pull requests and includes:

• Type checking (pnpm typecheck)
• Tests (pnpm test)
• Build verification (pnpm build)

These checks must pass before a PR can be merged. The same checks run in pre-commit hooks to catch issues early.

Questions?

If you have questions about contributing, please:

1. Check existing issues and discussions
2. Open a new issue if your question isn't addressed
3. Reach out to the maintainers

Thank you for contributing!