agno/CONTRIBUTING.md

Contributing to agno

Agno is an open-source project and we welcome contributions.

👩‍💻 How to contribute

Please follow the fork and pull request workflow:

• Fork the repository.
• Create a new branch for your feature.
  • Add your feature or improvement.
  • Ensure your Pull Request follows our guidelines (see below).
  • Send a pull request.
  • We appreciate your support & input!

Pull Request Guidelines

To maintain a clear and organized project history, please adhere to the following guidelines when submitting Pull Requests:

1. Title Format: Your PR title must start with a type tag enclosed in square brackets, followed by a space and a concise subject.
   • Example: [feat] Add user authentication
   • Valid types: [feat], [fix], [cookbook], [test], [refactor], [chore], [style], [revert], [release].
2. Link to a Ready Issue: Every PR must reference the issue it addresses using keywords like fixes #<issue_number>, closes #<issue_number>, or resolves #<issue_number>.
   • Example: This PR fixes #42 by implementing the new login flow.
   • Open an issue first and wait for a maintainer to triage it. Only start work once a maintainer has added the ready label.
   • PRs from external contributors that don't link an issue, or whose linked issue is not labeled ready, are closed automatically, and only a maintainer can reopen them. Once the issue is marked ready, comment on the closed PR and a maintainer will review it for reopening. Don't delete or force-push the branch in the meantime, otherwise it can't be reopened.
3. Use the PR Template: Keep every section of the PR template in your description. PRs missing most of its sections are closed automatically.
4. No Duplicate PRs: Before submitting, search the open pull requests to confirm no one else is already working on the same issue. If a similar PR exists, explain in your description why your approach is better.
5. Respect Assigned Issues: If a GitHub issue is already assigned to someone, do not open a PR for it without first asking the maintainers in the issue comments and getting confirmation. This helps reduce noise and avoids duplicate effort.
6. AI-Generated PRs: If your PR was entirely generated by an AI tool (Copilot, Claude Code, Cursor, etc.), you must disclose this in the PR template. AI-generated PRs are held to the same quality bar as any other contribution — they must include tests, pass CI, and demonstrate that the author has reviewed and understands the changes. Low-effort AI-generated PRs that don't meet these standards will be closed without review.

These guidelines are enforced automatically by our PR Lint workflow.

Development setup

1. Clone the repository.
2. Check if you have uv installed by running uv --version.
   • If you have uv installed, you can skip this step.
   • If you don't have uv installed, you can install it by running pip install uv.
3. Create a virtual environment:
   • For Unix, use ./scripts/dev_setup.sh.
   • For Windows, use .\scripts\dev_setup.bat.
   • This setup will:
     • Create a .venv virtual environment in the current directory.
     • Install the required packages.
     • Install the agno package in editable mode.
4. Activate the virtual environment:
   • On Unix: source .venv/bin/activate
   • On Windows: .venv\Scripts\activate

From here on you have to use uv pip install to install missing packages

On Unix, dev_setup.sh installs local editable agnoctl[dev] and agno[demo] into .venv, including development tools and demo dependencies for cookbook work. Use ./scripts/demo_setup.sh for a separate .venvs/demo environment with the same dependencies, then activate it with source .venvs/demo/bin/activate. Both scripts use Python 3.12 and recreate only their target environment on each run; deactivate any active environment first. Individual cookbooks may require additional dependencies, credentials, or services.

Formatting and validation

Ensure your code meets our quality standards by running the appropriate formatting and validation script before submitting a pull request:

• For Unix:
  • ./scripts/format.sh
  • ./scripts/validate.sh
• For Windows:
  • .\scripts\format.bat
  • .\scripts\validate.bat

These scripts will perform code formatting with ruff and static type checks with mypy.

Local testing

Before submitting a pull request, ensure all tests pass locally:

1. Do the development setup above.

2. Run the test suite ./scripts/test.sh

3. Run specific test files or test cases: pytest ./libs/agno/tests/unit/utils/test_string.py or whatever file you want to test.

Make sure all tests pass before submitting your pull request. If you add new features, include appropriate test coverage.

Adding a new Vector Database

1. Setup your local environment by following the Development setup.
2. Create a new directory under libs/agno/agno/vectordb for the new vector database.
3. Create a Class for your VectorDb that implements the VectorDb interface
   • Your Class will be in the libs/agno/agno/vectordb/<your_db>/<your_db>.py file.
   • The VectorDb interface is defined in libs/agno/agno/vectordb/base.py
   • Import your VectorDb Class in libs/agno/agno/vectordb/<your_db>/__init__.py.
   • Checkout the libs/agno/agno/vectordb/pgvector/pgvector file for an example.
4. Add a recipe for using your VectorDb under cookbook/07_knowledge/09_archive/vector_dbs/<your_db>.
   • Checkout cookbook/07_knowledge/09_archive/vector_dbs/pgvector_db for an example.
5. Important: Format and validate your code by running ./scripts/format.sh and ./scripts/validate.sh.
6. Submit a pull request.

Adding a new Model Provider

1. Setup your local environment by following the Development setup.
2. Create a new directory under libs/agno/agno/models for the new Model provider.
3. If the Model provider supports the OpenAI API spec:
   • Create a Class for your LLM provider that inherits the OpenAILike Class from libs/agno/agno/models/openai/like.py.
   • Your Class will be in the libs/agno/agno/models/<your_model>/<your_model>.py file.
   • Import your Class in the libs/agno/agno/models/<your_model>/__init__.py file.
   • Checkout the agno/models/together/together.py file for an example.
4. If the Model provider does not support the OpenAI API spec:
   • Reach out to us on Discord or open an issue to discuss the best way to integrate your LLM provider.
   • Checkout agno/models/anthropic/claude.py or agno/models/cohere/chat.py for inspiration.
5. Register your model provider in libs/agno/agno/models/utils.py:
   • Add exactly one row to the _PROVIDERS table, keyed by a stable provider key, with the value (module, class_name, default_name, default_provider). default_name and default_provider are your class's default name and (lowercased) provider attributes. This single table is the source of truth: the construction registry (MODEL_PROVIDER_CLASSES) and the (provider, name) resolution indices are all derived from it, so you do not edit any other map. Use a lowercase, hyphenated key, typically matching your module directory (e.g. "meta" for models/meta/, "openai-chat" for the chat variant).

     "yourprovider": ("agno.models.yourprovider", "YourModel", "YourModel", "yourprovider"),
     

   • This covers both the string format (model="yourprovider:model-name") and rebuilding a model saved to the database. If your class shares a display provider string with another class (e.g. an OpenAI-compatible provider reporting "openai"), the serialized name you list is what tells them apart; if its display string differs from the key (e.g. "inceptionlabs" vs key "inception"), the alias is derived automatically. Only the default key for an ambiguous display string (e.g. "azure" -> AzureOpenAI) lives in _AMBIGUOUS_PROVIDER_DEFAULTS.
   • CI enforces registration: test_every_model_subclass_is_registered statically discovers every concrete Model subclass and fails if one is missing. If your class is an abstract base rather than a user-selectable provider, add it to that test's allowlist instead.
6. Add a recipe for using your Model provider under cookbook/90_models/<your_model>.
   • Checkout agno/cookbook/90_models/aws/claude for an example.
   • Show both the model class and string syntax in your examples
7. Important: Format and validate your code by running ./scripts/format.sh and ./scripts/validate.sh.
8. Submit a pull request.

Adding a new Tool.

1. Setup your local environment by following the Development setup.
2. Create a new directory under libs/agno/agno/tools for the new Tool.
3. Create a Class for your Tool that inherits the Toolkit Class from libs/agno/agno/tools/toolkit.py.
   • Your Class will be in libs/agno/agno/tools/<your_tool>.py.
   • Make sure to register all functions in your class via a flag.
   • Checkout the agno/tools/youtube.py file for an example.
   • If your tool requires an API key, checkout the agno/tools/serpapi.py as well.
4. Add a recipe for using your Tool under cookbook/91_tools/<your_tool>.
   • Checkout agno/cookbook/91_tools/youtube_tools.py for an example.
5. Important: Format and validate your code by running ./scripts/format.sh and ./scripts/validate.sh.
6. Submit a pull request.

Message us on Discord if you have any questions or need help with credits.

📚 Resources

• Documentation
• Discord
• Support Resources

📝 License

This project is licensed under the terms of the Apache-2.0 license