Skip to main content

​
Contributing to AgenticAI Core SDK

Thank you for your interest in contributing to the AgenticAI Core SDK! This document provides guidelines and instructions for contributing to the project.

​
Ways to Contribute

There are many ways to contribute to AgenticAI Core:
  • 🐛 Report Bugs - Help us identify and fix issues
  • ✨ Suggest Features - Share ideas for new functionality
  • 📝 Improve Documentation - Enhance guides, examples, and API docs
  • 💻 Submit Code - Fix bugs or implement new features
  • 🧪 Write Tests - Improve test coverage
  • 📖 Share Examples - Contribute real-world usage examples

​
Getting Started

​
1. Fork and Clone

# Fork the repository on GitHub
# Then clone your fork
git clone https://github.com/YOUR_USERNAME/agentic-core.git
cd agentic-core

​
2. Set Up Development Environment

# Create a virtual environment
python3.10 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with all dependencies
pip install -e ".[dev,docs]"

​
3. Create a Branch

git checkout -b feature/your-feature-name
# or
git checkout -b fix/bug-description

​
Development Workflow

​
Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=agenticai_core --cov-report=html

# Run specific test file
pytest tests/test_app.py

​
Code Style

We use the following tools to maintain code quality: 
# Format code with black
black src/

# Sort imports with isort
isort src/

# Lint with ruff
ruff check src/

# Type check with mypy
mypy src/

​
Pre-commit Checks

Before committing, ensure:
  1. ✅ All tests pass
  2. ✅ Code is formatted with black
  3. ✅ Linting passes
  4. ✅ Type hints are added for new code
  5. ✅ Docstrings are added for public APIs

​
Documentation

When adding or modifying public APIs:
  1. Add Docstrings - Use Google/NumPy style
  2. Update API Docs - Add corresponding .md files in docs/api/
  3. Add Examples - Include usage examples in docstrings
  4. Update Guides - Update user guides if needed
Build and preview documentation: 
mkdocs serve

​
Coding Standards

​
Python Style

  • Follow PEP 8 guidelines
  • Use type hints for function signatures
  • Maximum line length: 88 characters (black default)
  • Use meaningful variable and function names

​
Docstring Format

Use Google-style docstrings: 
def my_function(param1: str, param2: int) -> bool:
    """Short description of the function.
    
    Longer description explaining the function's behavior,
    edge cases, and usage patterns.
    
    Args:
        param1: Description of param1.
        param2: Description of param2.
        
    Returns:
        Description of return value.
        
    Raises:
        ValueError: When param2 is negative.
        
    Example:
        ```python
        result = my_function("test", 42)
        print(result)  # True
""" if param2 < 0: raise ValueError(“param2 must be non-negative”) return True 

### Commit Messages

Follow conventional commit format:
type(scope): subject body (optional) footer (optional) 

**Types:**

- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks

**Examples:**
feat(agent): add support for streaming responses fix(memory): resolve session cleanup issue docs(api): add examples for Tool.register decorator 

## Pull Request Process

### 1. Update Your Branch

Sync with upstream main branch.

<!--
```bash
# Sync with upstream main
git remote add upstream https://github.com/agenticai/agentic-core.git
git fetch upstream
git rebase upstream/main
—>

​
2. Push Changes

git push origin feature/your-feature-name

​
3. Create Pull Request

  1. Go to GitHub and create a Pull Request
  2. Fill out the PR template:
    • Description: What does this PR do?
    • Related Issue: Link to related issue(s)
    • Testing: How was this tested?
    • Breaking Changes: Any breaking changes?

​
4. Code Review

  • Address reviewer feedback
  • Keep the PR focused and small
  • Update documentation as needed
  • Ensure CI/CD checks pass

​
5. Merge

Once approved, your PR will be merged by a maintainer.

​
Reporting Bugs

​
Before Reporting

  1. Check if the bug has already been reported
  2. Try to reproduce with the latest version
  3. Gather relevant information

​
Bug Report Template

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Create agent with...
2. Call method...
3. See error

**Expected behavior**
What you expected to happen.

**Actual behavior**
What actually happened.

**Environment:**
- Python version:
- AgenticAI Core version:
- OS:

**Additional context**
Any other relevant information.

​
Suggesting Features

We welcome feature suggestions! Please:
  1. Check if similar features have been requested
  2. Describe the use case clearly
  3. Explain why this would benefit users
  4. Consider implementation complexity

​
Feature Request Template

**Feature Description**
Clear description of the proposed feature.

**Use Case**
Why is this feature needed? What problem does it solve?

**Proposed Solution**
How should this feature work?

**Alternatives Considered**
Other approaches you've thought about.

**Additional Context**
Any other relevant information.

​
Code of Conduct

​
Our Pledge

We are committed to providing a welcoming and inclusive environment for all contributors.

​
Our Standards

Positive behavior:
  • Using welcoming and inclusive language
  • Being respectful of differing viewpoints
  • Gracefully accepting constructive criticism
  • Focusing on what’s best for the community
Unacceptable behavior:
  • Harassment, discrimination, or offensive comments
  • Trolling, insulting/derogatory comments
  • Public or private harassment
  • Publishing others’ private information

​
Enforcement

Instances of unacceptable behavior may be reported to Support.

​
Development Setup Details

​
Project Structure

agentic-core/
├── src/
│   └── agenticai_core/
│       ├── designtime/      # Design-time models
│       ├── runtime/          # Runtime execution
│       ├── api/              # API clients
│       └── cli/              # CLI tools
├── tests/                    # Test suite
├── docs/                     # Documentation source
├── examples/                 # Example applications
└── mkdocs.yml               # Documentation config

​
Dependencies

Core dependencies:
  • pydantic>=2.0 - Data validation
  • typing-extensions - Type hints support
Development dependencies:
  • pytest - Testing framework
  • pytest-cov - Coverage reporting
  • black - Code formatter
  • ruff - Fast Python linter
  • mypy - Type checker
Documentation dependencies:
  • mkdocs - Documentation generator
  • mkdocs-material - Material theme
  • mkdocstrings[python] - API docs from docstrings

​
Running Specific Tests

# Test specific module
pytest tests/designtime/

# Test with verbose output
pytest -v

# Test with specific marker
pytest -m "not slow"

# Test with debugging
pytest -s --pdb