Organizing your AgenticAPI project with a clear folder structure enhances maintainability and scalability, especially when building action-oriented APIs for AI agents. This guide recommends a standard directory layout to separate application logic, verb definitions, utilities, and documentation, ensuring a clean and modular codebase.
Recommended Structure #
Below is a suggested folder structure for an AgenticAPI project:
Plaintext
my-agenticapi-project/
├── data/ # Static data or mock data files
│ ├── documents.json # Example data for testing
├── docs/ # Documentation files
│ ├── introduction/ # Introduction docs
│ ├── getting-started/ # Getting Started docs
├── static/ # Static files (e.g., HTML, JS for UI)
│ ├── index.html # Web interface for testing
│ ├── http_client.js # Client-side request utilities
├── utils/ # Utility modules
│ ├── __init__.py
│ ├── config.py # Configuration (e.g., API keys)
│ ├── format.py # Response formatting helpers
├── verbs/ # Action verb implementations
│ ├── __init__.py
│ ├── base.py # Base verb class
│ ├── summarize.py # SUMMARIZE verb logic
│ ├── fetch.py # FETCH verb logic
│ ├── notify.py # NOTIFY verb logic
├── __init__.py # Package initialization
├── main.py # FastAPI application entry point
├── README.md # Project overview
├── requirements.txt # Dependency list
├── setup.py # Package setup and versioning
├── test_main.py # Unit tests
Directory Breakdown #
data/: Stores static or mock data (e.g., JSON files for testingFETCHorSUMMARIZEverbs). Replace with a database in production.docs/: Contains markdown documentation, organized by category (e.g.,introduction,getting-started).static/: Holds front-end assets for a web-based testing interface, such as HTML and JavaScript.utils/: Includes reusable modules for configuration (e.g., API keys) and response formatting.verbs/: Defines action verbs as Python modules, each implementing a custom verb (e.g.,SUMMARIZE,FETCH).main.py: The FastAPI application, defining endpoints and middleware for custom verbs.requirements.txt: Lists dependencies for reproducibility.setup.py: Configures the project as a Python package with versioning (e.g.,0.3.0).test_main.py: Contains unit tests for endpoints and verbs.
Creating the Structure #
To set up this structure:
Bash
# Create project directory
mkdir my-agenticapi-project
cd my-agenticapi-project
# Create subdirectories
mkdir data docs docs/introduction docs/getting-started static utils verbs
# Create empty files
touch data/documents.json
touch docs/introduction/what_is_agenticapi.md
touch docs/introduction/why_use_agenticapi.md
touch docs/introduction/key_features.md
touch docs/getting-started/installation.md
touch docs/getting-started/project-structure.md
touch static/index.html
touch static/http_client.js
touch utils/__init__.py
touch utils/config.py
touch utils/format.py
touch verbs/__init__.py
touch verbs/base.py
touch verbs/summarize.py
touch verbs/fetch.py
touch verbs/notify.py
touch __init__.py
touch main.py
touch README.md
touch requirements.txt
touch setup.py
touch test_main.pyCustomizing the Structure #
- Small Projects: Omit
docs/orstatic/if not needed. - Large Projects: Add submodules (e.g.,
verbs/acquire/,verbs/compute/) or separate data sources (e.g.,data/external/). - Testing: Expand
test_main.pywith unit tests for each verb.
Next Steps #
- Follow the Installation guide to set up dependencies.
- Try the Quick Start to build your first verb.
- Learn about ACTION Taxonomy for implementation details.
