Quick Start

This guide gets you from zero to a working BindAI application in a few steps. By the end, you will:

Create a BindAI project
Configure an AI provider
Configure project settings
Optionally configure a project-scoped provider connection
Run a BindAI application
Create an agent
Add tools
Understand the basic project structure
Learn how workflows, memory, knowledge, and connections fit together
Know how to run BindAI through the REST API or Docker
Know where to continue next

Prerequisites

Before starting, complete the Installation guide. You should have:

Python 3.12 or newer
BindAI installed
A virtual environment available
Credentials for a supported provider, if required

Currently supported model providers include:

OpenAI
Anthropic
Google Gemini
Groq
Ollama
OpenRouter

Create a New Project

The BindAI CLI provides the project entry point for creating and working with BindAI applications. Create a new project:

bindai new my-ai-app

Enter the project:

cd my-ai-app

A generated project can contain application components such as:

my-ai-app/

├── agents/

├── tools/

├── workflows/

├── knowledge/

├── memory/

├── templates/

├── tests/

├── main.py

├── bindai.toml

└── .env.example

The exact generated contents may evolve as the BindAI project scaffold develops.

Configure Project Settings

BindAI projects use bindai.toml for project-level configuration. You can inspect the current configuration with:

bindai config show

Set the provider:

bindai config set provider openai

Set the model:

bindai config set model gpt-4.1-mini

Read an individual configuration value:

bindai config get provider

For example, the resulting bindai.toml can contain:

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

The project configuration controls the default provider and model used by the project.

Configure Environment Variables

Most hosted AI providers require an API key. If the generated project includes an example environment file, create your local environment file.

Windows PowerShell

Copy-Item .env.example .env

macOS / Linux

cp .env.example .env

Open .env and configure the credentials required by your selected provider. For OpenAI:

OPENAI_API_KEY=your_api_key_here

For Anthropic:

ANTHROPIC_API_KEY=your_api_key_here

For Google Gemini:

GEMINI_API_KEY=your_api_key_here

For Groq:

GROQ_API_KEY=your_api_key_here

For OpenRouter:

OPENROUTER_API_KEY=your_api_key_here

Ollama can be used with a local model service and does not normally require a hosted API key.

Never commit API keys or other secrets to source control.

Use Project-Scoped Provider Connections

BindAI can store provider credentials separately from project configuration using named provider connections. A project-scoped provider connection consists of:

A connection name
A provider name
Connection metadata stored in .bindai/connections.toml
The provider credential stored in the operating system credential store

Create a provider connection with:

bindai connections add

List configured connections:

bindai connections list

Remove a connection:

bindai connections remove

For example, you can create a connection named work for OpenAI. Then select that connection for the project:

bindai config set connection work

The project configuration will contain:

provider = "openai"
connection = "work"

The connection metadata identifies the provider, while the credential itself is stored separately in the operating system credential store. Provider credential resolution follows this precedence:

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

The configured connection must exist and must match the selected provider. You can verify the configured connection with:

bindai config get connection

You can also inspect the connection configuration with:

bindai connections list

Run the Project

From inside the generated project, run:

bindai run

This starts the BindAI application through the CLI. The exact application output depends on the generated project and its configuration. If the application requires provider credentials, make sure the appropriate environment variables or project-scoped provider connection are configured before running it.

Verify Your Installation

If you encounter an installation or configuration problem, run:

bindai doctor

The doctor command checks the BindAI environment and reports detected configuration or installation issues. For projects using a project-scoped provider connection, it also reports the configured connection and whether its stored credential is available. You can also verify the installed CLI version:

bindai version

Display the available CLI commands with:

bindai --help

Create an Agent

Agents are the central abstraction for building AI applications with BindAI. A basic agent can be created using the BindAI agent API:

from bindai import Agent

agent = Agent.builder().build()

A typical agent configuration can include a model and instructions:

from bindai import Agent

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

The model identifier should match a model available through the selected provider.

Provider and model availability can change independently of BindAI. Check the provider documentation when selecting a model.

Run an Agent

Once an agent has been configured, it can be executed with an input message:

result = agent.run("Explain what BindAI is.")

print(result.output)

The returned result contains the output produced by the agent execution. Agents can also be integrated into larger workflows and applications.

Add Tools

Tools allow agents to perform actions instead of only generating text. A tool can be implemented as a Python function and exposed through BindAI’s tool system. For example:

from bindai import Agent, tool


@tool
def add(a: int, b: int) -> int:
    return a + b

The tool can then be provided to an agent:

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

The agent can then use the registered tool when the model determines that the tool is appropriate. For more information, see the Tools documentation.

Change Providers

BindAI uses a provider abstraction so applications can work with different model providers. For example, an OpenAI model:

.model("openai:gpt-4.1")

An Anthropic model:

.model("anthropic:claude-sonnet-4")

An Ollama model:

.model("ollama:llama3")

Or an OpenRouter model:

.model("openrouter:your-model")

Other currently supported providers include Google Gemini and Groq. The exact model identifier depends on the provider and model you want to use. For more information, see Providers.

Add Memory

Agents can use memory to retain information across interactions. BindAI provides memory abstractions that allow applications to use different storage backends. Current memory capabilities include:

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

Conversation memory can be used to maintain conversational context. See the Memory documentation for more information.

Add Knowledge

Knowledge allows agents to work with information outside the model’s built-in knowledge. A typical knowledge pipeline can involve:

Documents

   │

   ▼

Ingestion

   │

   ▼

Parsing

   │

   ▼

Chunking

   │

   ▼

Embeddings

   │

   ▼

Storage / Retrieval

   │

   ▼

Search

   │

   ▼

Reranking

   │

   ▼

Agent Context

BindAI supports vector, BM25, and hybrid retrieval strategies. This provides the foundation for Retrieval-Augmented Generation (RAG) applications. See the Knowledge documentation for more information.

Use Workflows

When an application requires multiple execution steps, workflows can coordinate the process. A workflow can combine:

Agents
Tools
Conditions
Loops
Parallel execution
Retries
Timeouts
Scheduling
Human tasks
Human approval

For example:

Start

  │

  ▼

Agent

  │

  ▼

Condition

 ┌┴───────────┐

 ▼            ▼

Tool         Agent

 │             │

 └──────┬──────┘

        ▼

      Result

Workflows are useful when an application requires predictable multi-step execution instead of a single agent call. See the Workflows documentation.

Connect External Services

BindAI provides a Connections package for integrating external services with applications and workflows. Current integrations include:

Webhooks
GitHub
Slack
Discord
Notion
Jira
Resend
Vercel
Netlify
Google Sheets
Google Docs
Gmail
Google Drive

Connections are provided through the bindai-connections package. For example, install the package with:

pip install bindai-connections

See the Connections documentation for configuration and usage.

Use the REST API

BindAI also provides a REST API through the bindai-api package. Install it with:

pip install bindai-api

The API provides endpoints for:

Agent execution
Agent streaming
Workflow execution
Projects
Background automation runs
Run status
Health checks

Start the API locally with:

uvicorn bindai_api.app:app --host 0.0.0.0 --port 8000

The health endpoint is available at:

http://localhost:8000/health

The API uses an API key for protected endpoints. Configure:

BINDAI_API_KEY=your-secret-key

Then send the key using:

Authorization: Bearer your-secret-key

The REST API is documented in the API Reference.

Run with Docker

BindAI API can also be deployed using Docker. Build the API image:

docker build -t bindai-api .

Run it:

docker run --rm -p 8000:8000 \
  -e BINDAI_API_KEY=your-secret-key \
  bindai-api

Or use Docker Compose:

docker compose up --build

After the service starts, verify it with:

http://localhost:8000/health

See Deployment for more information.

BindAI v0.1 provides in-process background execution. Distributed queue-based workers and Kubernetes deployment are planned for future releases.

MCP and Tool Bridges

BindAI currently provides a lightweight HTTP-based MCP/tool bridge for tool discovery and invocation. The current implementation provides capabilities around:

Tool discovery
Tool invocation
MCP client connections
Integration with the BindAI tool system

For v0.1, this should be understood as a lightweight bridge rather than full MCP protocol compliance. Full MCP protocol support is planned for a future release. See MCP and Tool Bridges for more information.

Observability

BindAI provides an event-based observability foundation for tracking execution activity. Events can represent activity such as:

Agent execution
Model requests
Model responses
Tool execution
Workflow execution
Execution state changes

BindAI also provides an in-memory EventRecorder that can collect events associated with an execution. This provides a foundation for future tracing, metrics, and external observability integrations. See Events and Observability.

BindAI v0.1 provides lightweight in-memory event recording. OpenTelemetry, distributed tracing, and external observability backends are planned for future releases.

Project Structure

A BindAI project can be organized around several major components.

`agents/`

Contains agent definitions. Agents are responsible for interacting with language models and coordinating AI execution. Agents can work with:

Prompts and instructions
Tools
Memory
Knowledge
Retrieval
Provider integrations
Execution configuration
Other agents

`tools/`

Contains reusable tools that agents can execute. Tools can represent:

Python functions
Application services
External APIs
Database operations
Search functionality
External integrations
MCP-backed tools

BindAI provides a tool registry and execution system for managing these capabilities.

`workflows/`

Contains workflow definitions. BindAI workflows support execution patterns such as:

Sequential execution
Conditional branching
Loops
Parallel execution
Retries
Timeouts
Scheduling
Human approval
Human tasks

`knowledge/`

Contains knowledge-related application resources. BindAI’s knowledge system supports capabilities such as:

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

Knowledge can be connected to agents so retrieved information can be used as context during execution.

`memory/`

Contains memory-related application resources. BindAI supports multiple memory implementations, including:

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

`templates/`

Contains reusable workflow or application templates. Templates provide starting points for common BindAI execution patterns.

`tests/`

Contains application tests. Testing is an important part of developing reliable BindAI applications.

`main.py`

The application entry point. The exact contents depend on the project generated and the application being built.

`bindai.toml`

Project-level configuration. Use this file for BindAI project configuration supported by the application and CLI. For example:

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

The connection setting is optional. When configured, BindAI uses the named project-scoped provider connection during provider resolution. Configuration options may evolve as the project architecture develops.

Package Structure

BindAI is organized as a collection of packages that can be used together or independently depending on your application. The main packages include:

bindai

bindai-agent

bindai-automation

bindai-api

bindai-connections

bindai-runtime

bindai-mcp

The main bindai package provides the core public framework experience, while the other packages provide specialized capabilities such as agents, automation, APIs, integrations, runtime services, and MCP/tool integration.

Running Tests

For an application project, run:

pytest

For BindAI source development, the repository uses a multi-package uv workspace. From the repository root:

uv sync

Then run the relevant test suite.

Useful CLI Commands

Create a project:

bindai new my-app

Run the application:

bindai run

Inspect the project:

bindai inspect

Check the environment:

bindai doctor

Display the installed version:

bindai version

Display available commands:

bindai --help

Show project configuration:

bindai config show

Get a project configuration value:

bindai config get provider

Set a project configuration value:

bindai config set provider openai

Add a provider connection:

bindai connections add

List provider connections:

bindai connections list

Remove a provider connection:

bindai connections remove

What You’ve Learned

You have now seen the basic BindAI development workflow:

Created a BindAI project
Configured a model provider
Configured project settings
Learned how project-scoped provider connections work
Started a BindAI application
Learned the project structure
Created an agent
Added a tool
Learned how providers can be changed
Learned how memory works
Learned how knowledge and RAG fit into an application
Learned how workflows coordinate execution
Learned about external connections
Learned about the REST API
Learned about Docker deployment
Learned about background execution
Learned about BindAI’s observability foundation
Learned about the current MCP/tool bridge

You are now ready to explore the individual BindAI components in more depth.

Next Steps

Continue with:

For the overall implementation status, see the ROADMAP.

​Quick Start

​Prerequisites

​Create a New Project

​Configure Project Settings

​Configure Environment Variables

​Windows PowerShell

​macOS / Linux

​Use Project-Scoped Provider Connections

​Run the Project

​Verify Your Installation

​Create an Agent

​Run an Agent

​Add Tools

​Change Providers

​Add Memory

​Add Knowledge

​Use Workflows

​Connect External Services

​Use the REST API

​Run with Docker

​MCP and Tool Bridges

​Observability

​Project Structure

​agents/

​tools/

​workflows/

​knowledge/

​memory/

​templates/

​tests/

​main.py

​bindai.toml

​Package Structure

​Running Tests

​Useful CLI Commands

​What You’ve Learned

​Next Steps