Project Structure

BindAI projects provide a consistent way to organize agents, tools, workflows, knowledge, memory, templates, configuration, connections, and tests. You can use BindAI components without creating a project, but a project provides a convenient structure for keeping an AI application organized as it grows.

Creating a Project

Create a new project with the BindAI CLI:

bindai new my-ai-app

Move into the project:

cd my-ai-app

The generated project provides a starting point for building a BindAI application. The project scaffold can evolve as BindAI’s CLI and templates develop, so the exact generated files may vary between versions.

Default Project Layout

A BindAI application can be organized around the following structure:

my-ai-app/

├── agents/

├── tools/

├── workflows/

├── knowledge/

├── memory/

├── templates/

├── tests/

├── .bindai/

│   └── connections.toml

├── .env

├── bindai.toml

└── main.py

Not every application needs every directory. Each component should be introduced when the application requires it. The .bindai/ directory is used for BindAI project metadata. Project-scoped provider connection metadata is stored in .bindai/connections.toml. Provider credentials are not stored in that file. They are stored separately in the operating system credential store.

Project Files

`main.py`

main.py can serve as the application’s entry point. A simple application can create an agent and execute it:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

result = agent.run("Hello!")

print(result.output)

The entry point can also start a larger application containing workflows, multiple agents, tools, or other BindAI components.

`bindai.toml`

bindai.toml is the project-level BindAI configuration file. It can be used to keep application configuration separate from Python source code. For example:

provider = "openai"
connection = "work"
model = "gpt-4.1-mini"

The provider setting selects the provider used by the project. The model setting configures the project’s default model. The optional connection setting selects a named project-scoped provider connection. When connection is configured, BindAI resolves the named connection and obtains its stored provider credential during provider resolution. Keep secrets such as API keys out of bindai.toml. Use environment variables, project-scoped provider connections, or another secure secret-management mechanism for credentials. You can inspect and modify project configuration through the CLI:

bindai config show

bindai config get provider

bindai config set provider openai

bindai config set model gpt-4.1-mini

bindai config set connection work

`.bindai/connections.toml`

.bindai/connections.toml contains metadata for project-scoped provider connections. For example:

[connections.work]
provider = "openai"

The connection metadata identifies which provider a named connection belongs to. The provider credential itself is not stored in connections.toml. Instead, BindAI stores the credential in the operating system credential store. This separation allows the project to reference a named provider credential without putting the credential directly into project configuration or source code. Connections can be managed through the CLI:

bindai connections add

bindai connections list

bindai connections remove

A project can then select the connection with:

bindai config set connection work

Provider credential resolution follows this precedence:

An explicitly supplied API key
The credential stored for the selected project connection
The provider environment variable

The selected connection must exist, must match the configured provider, and must have a stored credential available.

`.env`

The local .env file can contain environment variables required by the application. For example:

OPENAI_API_KEY=your_api_key_here

Other supported providers can use their corresponding environment variables:

ANTHROPIC_API_KEY=your_api_key_here
GEMINI_API_KEY=your_api_key_here
GROQ_API_KEY=your_api_key_here
OPENROUTER_API_KEY=your_api_key_here

Ollama generally uses a local model service rather than a hosted API key. A project-scoped provider connection can be used instead of storing a provider API key in .env. Never commit API keys or other secrets to source control.

Agents

The agents/ directory can contain application-specific agent definitions. For example:

agents/

├── assistant.py

├── researcher.py

├── planner.py

└── reviewer.py

A simple agent can be defined with Agent.builder():

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .instructions("You are a helpful assistant.")
    .build()
)

Larger applications can use multiple specialized agents. For example:

agents/

├── assistant.py

├── researcher.py

├── writer.py

└── reviewer.py

Each agent can have its own instructions, tools, memory, knowledge, retrieval configuration, and execution behavior.

Tools

The tools/ directory can contain reusable tools used by agents. For example:

tools/

├── calculator.py

├── search.py

├── weather.py

└── database.py

A tool can be defined with the BindAI tool decorator:

from bindai import tool


@tool
def echo(text: str) -> str:
    return text

The tool can then be supplied to an agent:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .tools(echo)
    .instructions("You are a helpful assistant.")
    .build()
)

Tools can represent Python functions, APIs, application services, database operations, search functionality, external connections, or MCP-backed capabilities.

Workflows

The workflows/ directory can contain workflow-related application code. For example:

workflows/

├── support.py

├── onboarding.py

└── reports.py

Workflows can coordinate:

Agents
Tools
Conditional execution
Loops
Parallel execution
Retries
Timeouts
Scheduling
Human tasks

Separating workflows from agents and tools makes larger applications easier to maintain. A workflow can also combine multiple specialized agents:

Workflow

   │

   ├── Research Agent

   │

   ├── Writing Agent

   │

   └── Review Agent

Knowledge

The knowledge/ directory can contain application resources used by knowledge and retrieval systems. For example:

knowledge/

├── docs/

├── manuals/

└── policies/

Knowledge resources can be processed through BindAI’s knowledge and retrieval pipeline. The knowledge system supports capabilities including:

Document ingestion
Parsing
Chunking
Embeddings
Metadata
Semantic retrieval
BM25 retrieval
Hybrid retrieval
Filtering
Reranking
Conversational retrieval
Knowledge pipelines

Knowledge can then be connected to an agent:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .knowledge(knowledge)
    .instructions("Answer questions using the available knowledge.")
    .build()
)

Memory

The memory/ directory can be used to organize application-specific memory resources or implementations. BindAI provides several memory implementations, including:

In-memory memory
SQLite
PostgreSQL
Vector memory
Pinecone
Chroma
Conversation memory
Custom memory implementations

Memory can be configured for an agent:

from bindai import Agent


agent = (
    Agent.builder()
    .name("assistant")
    .model("openai:gpt-4.1-mini")
    .memory(memory)
    .instructions("You are a helpful assistant.")
    .build()
)

The actual storage mechanism depends on the selected memory implementation.

Templates

The templates/ directory can contain reusable application or workflow templates. For example:

templates/

├── workflow-basic.md

├── workflow-condition.md

└── workflow-review.md

Templates can help teams standardize common application patterns. BindAI also provides workflow templates covering patterns such as:

Basic workflows
Conditions
Loops
Parallel execution
Human tasks
Retries
Timeouts
Scheduling

Tests

Store project tests inside the tests/ directory. For example:

tests/

├── test_agents.py

├── test_tools.py

└── test_workflows.py

Run the project’s tests with:

pytest

Tests should cover important application behavior, including agent execution, tool behavior, workflows, integrations, and other components used by the application.

External Service Connections

Applications that communicate with external services can organize connection-related code separately from agents and workflows. BindAI’s Connections package currently provides integrations for:

Webhooks
GitHub
Slack
Notion
Jira
Discord
Resend
Vercel
Netlify

For example:

connections/

├── github.py

├── slack.py

└── notifications.py

The exact organization is application-specific. Keeping external-service communication separate from agent logic makes integrations easier to test and replace.

These application-level external-service connections are separate from BindAI’s project-scoped provider connections. Project-scoped provider connections select stored AI provider credentials and are represented by .bindai/connections.toml.

MCP

Applications using Model Context Protocol can keep MCP-related configuration and integration code separate from core agent logic. BindAI’s current MCP support includes:

MCP client connections
Tool discovery
Tool calling
MCP tools exposed through the BindAI tool system

For example:

mcp/

├── servers.py

└── tools.py

MCP resources and advanced protocol capabilities can be added as the MCP implementation expands.

Organizing Larger Projects

As an application grows, organize components by responsibility. For example:

my-ai-app/

│

├── agents/

│   ├── assistant.py

│   ├── planner.py

│   └── researcher.py

│

├── tools/

│   ├── search.py

│   ├── calculator.py

│   └── database.py

│

├── workflows/

│   ├── support.py

│   ├── onboarding.py

│   └── reports.py

│

├── knowledge/

│   ├── docs/

│   ├── manuals/

│   └── policies/

│

├── memory/

│

├── templates/

│

├── connections/

│

├── mcp/

│

├── tests/

│   ├── test_agents.py

│   ├── test_tools.py

│   └── test_workflows.py

│

├── .bindai/

│   └── connections.toml

│

├── bindai.toml

├── main.py

└── .env

This structure keeps responsibilities separated as the application becomes more complex.

Separating Responsibilities

A useful way to think about the project structure is:

Application

    │

    ├── Configuration

    │     ├── bindai.toml

    │     └── .bindai/connections.toml

    │

    ├── Agents

    │     ├── Instructions

    │     ├── Tools

    │     ├── Memory

    │     └── Knowledge / Retrieval

    │

    ├── Workflows

    │     ├── Conditions

    │     ├── Loops

    │     ├── Parallel execution

    │     └── Human tasks

    │

    ├── Connections

    │     └── External services

    │

    ├── MCP

    │     └── External tools

    │

    └── Tests

Each layer has a focused responsibility while remaining composable with the others.

Multi-Agent Project Structure

Applications using multiple agents can organize specialists independently. For example:

agents/

├── coordinator.py

├── researcher.py

├── analyst.py

├── writer.py

└── reviewer.py

The agents can then participate in delegation or team-based execution. A larger application might follow this pattern:

Coordinator

    │

    ├── Researcher

    │

    ├── Analyst

    │

    ├── Writer

    │

    └── Reviewer

This organization works well when each agent has a clearly defined responsibility.

Environment and Source Control

Keep application secrets separate from source code. A typical project should include a .gitignore that excludes local environment files and other generated or sensitive content. For example:

.env

.venv/

__pycache__/

.pytest_cache/

Do not commit:

API keys
Access tokens
Passwords
Private credentials
Other sensitive configuration

The .env.example pattern can be used to document required environment variables without exposing their values. Project-scoped provider connection credentials should also never be committed to source control. The connection metadata in .bindai/connections.toml identifies the provider, while the actual credential remains in the operating system credential store.

Recommended Development Workflow

A typical BindAI project workflow is:

Create a project with bindai new.
Configure the project’s environment.
Configure the required provider.
Optionally create a project-scoped provider connection.
Select the provider connection in bindai.toml when one is configured.
Build agents inside agents/.
Add reusable tools inside tools/.
Add memory when persistent or conversational state is required.
Add knowledge and retrieval when application-specific information is required.
Add workflows when execution requires multiple coordinated steps.
Add external Connections when external services are required.
Add MCP integrations when external MCP tools are required.
Add templates for reusable application patterns.
Write tests inside tests/.
Run bindai doctor to validate the project environment and configured provider connection.
Run the application with the BindAI CLI.

The project structure is intentionally modular so an application can grow from a simple assistant into a larger AI system without placing all of its logic in a single module.

Minimal Project

Not every project needs the complete structure. A small application can start with only:

my-ai-app/

├── main.py

├── bindai.toml

└── .env

As requirements grow, additional directories and project metadata can be introduced:

my-ai-app/

├── agents/

├── tools/

├── workflows/

├── knowledge/

├── memory/

├── connections/

├── mcp/

├── tests/

└── .bindai/

    └── connections.toml

A project using a project-scoped provider connection can then configure it in bindai.toml:

provider = "openai"
connection = "work"
model = "gpt-4.1-mini"

This allows projects to remain simple at the beginning while still providing a path toward larger AI applications.

Next Steps

After understanding the project structure, continue with:

Getting Started

Core

Tools

Memory

Knowledge

Workflows

Projects

Templates

Connections

API Reference

Automation

Roadmap

01.5 project structure

Project Structure

Creating a Project

Default Project Layout

Project Files

`main.py`

`bindai.toml`

`.bindai/connections.toml`

`.env`

Agents

Tools

Workflows

Knowledge

Memory

Templates

Tests

External Service Connections

MCP

Organizing Larger Projects

Separating Responsibilities

Multi-Agent Project Structure

Environment and Source Control

Recommended Development Workflow

Minimal Project

Next Steps

​Project Structure

​Creating a Project

​Default Project Layout

​Project Files

​main.py

​bindai.toml

​.bindai/connections.toml

​.env

​Agents

​Tools

​Workflows

​Knowledge

​Memory

​Templates

​Tests

​External Service Connections

​MCP

​Organizing Larger Projects

​Separating Responsibilities

​Multi-Agent Project Structure

​Environment and Source Control

​Recommended Development Workflow

​Minimal Project

​Next Steps

Project Structure

Creating a Project

Default Project Layout

Project Files

`main.py`

`bindai.toml`

`.bindai/connections.toml`

`.env`

Agents

Tools

Workflows

Knowledge

Memory

Templates

Tests

External Service Connections

MCP

Organizing Larger Projects

Separating Responsibilities

Multi-Agent Project Structure

Environment and Source Control

Recommended Development Workflow

Minimal Project

Next Steps