Applications

An Application is a concrete BindAI runtime object representing a business application inside a project. Applications provide a focused container for agents and expose convenient execution methods for those agents. An application is normally created with an ApplicationConfiguration and then populated with one or more Agent instances.

What Is an Application?

The current BindAI implementation provides a concrete:

from bindai_application import Application

An application is created with an ApplicationConfiguration:

from bindai_application import Application, ApplicationConfiguration

application = Application(
    ApplicationConfiguration(
        name="customer-support",
        description="Customer support AI application",
    )
)

The application stores its agents by name and provides methods for adding, retrieving, and executing them. Conceptually:

Project
   |
   +---- Application
           |
           +---- Agent
           +---- Agent
           +---- Agent

A project can contain multiple applications.

Application Configuration

Every Application is created with an ApplicationConfiguration.

from bindai_application import ApplicationConfiguration

configuration = ApplicationConfiguration(
    name="customer-support",
    description="Customer support AI application",
)

The configuration currently contains:

Field	Type	Default	Description
`name`	`str`	required	Application name
`description`	`str`	`""`	Application description

ApplicationConfiguration is a dataclass using slots. The application exposes its configured name through:

application.name

which returns:

application.configuration.name

Creating an Application

A minimal application can be created with only a name:

from bindai_application import Application, ApplicationConfiguration

application = Application(
    ApplicationConfiguration(
        name="support",
    )
)

A description can also be provided:

application = Application(
    ApplicationConfiguration(
        name="support",
        description="Customer support assistant",
    )
)

The application itself does not require agents at construction time. Agents can be added afterwards.

Agents

Agents are the primary executable resources currently managed directly by an Application. The application stores agents in:

application.agents

The collection is a dictionary keyed by agent name:

dict[str, Agent]

An agent can be registered with:

application.add_agent(agent)

For example:

application.add_agent(support_agent)

Adding another agent with the same name replaces the existing entry.

Retrieving Agents

An agent can be retrieved by name:

agent = application.agent("support")

The lookup uses the application’s agent dictionary. If the requested name does not exist, the normal Python dictionary lookup behavior applies and a KeyError is raised.

Running an Agent

Applications provide a convenience method for executing an agent:

result = application.run(
    agent="support",
    message="How do I reset my password?",
)

The application:

Looks up the agent by name.
Calls the agent’s chat() method.
Returns the result from the agent.

Conceptually:

Application
    |
    v
agent("support")
    |
    v
Agent.chat(message)
    |
    v
Result

The application does not implement the model execution itself. The underlying Agent is responsible for the actual agent execution.

Streaming

Applications also expose streaming through:

stream = application.stream(
    agent="support",
    message="Explain our support process.",
)

This delegates to:

agent.stream_chat(message)

The exact stream behavior therefore comes from the underlying Agent implementation. Conceptually:

Application
    |
    v
Agent
    |
    v
Agent.stream_chat()
    |
    v
Streaming output

This is useful for interactive applications where output should be consumed incrementally.

Multiple Agents

An application can contain multiple agents:

application.add_agent(faq_agent)
application.add_agent(billing_agent)
application.add_agent(escalation_agent)

They can then be selected by name:

application.run(
    agent="faq",
    message="What are your support hours?",
)

or:

application.run(
    agent="billing",
    message="Why was I charged twice?",
)

This makes the application a useful boundary for related specialist agents.

Example Application

A simple application might look like:

from bindai_application import Application, ApplicationConfiguration

application = Application(
    ApplicationConfiguration(
        name="customer-support",
        description="Customer support application",
    )
)

application.add_agent(faq_agent)
application.add_agent(billing_agent)

result = application.run(
    agent="faq",
    message="What are your support hours?",
)

The application provides the named entry point while the agents provide the actual AI behavior.

Application and Agent Responsibilities

Applications and agents have different responsibilities.

Application

The application provides:

application identity
agent registration
agent lookup
agent execution helpers
agent streaming helpers

Agent

The agent provides:

model-driven execution
instructions
tools
memory/context behavior
provider interaction
agent-specific execution behavior

A useful mental model is:

Application
    |
    +---- Agent A
    |
    +---- Agent B
    |
    └---- Agent C

The application organizes the agents. The agents perform the AI work.

Workflows

The current Application class initializes:

application.workflows

as:

dict[str, object]

This is currently a generic application-level collection. It is not a dedicated WorkflowRegistry and does not currently expose application methods such as:

application.add_workflow(...)
application.workflow(...)

For structured workflow registration and scheduling, the project-level Project provides:

project.workflows
project.scheduler
project.add_workflow(...)
project.add_schedule(...)

Therefore, applications should not be documented as if they currently provide a complete workflow-management API.

Knowledge

The current Application class initializes:

application.knowledge

as:

dict[str, object]

This is currently a generic application-level collection. It does not by itself implement a complete knowledge-management or RAG system. BindAI’s dedicated knowledge and retrieval components should be used when implementing:

document ingestion
retrieval
embeddings
vector stores
RAG pipelines
knowledge search

The presence of application.knowledge should therefore not be interpreted as automatic knowledge retrieval.

Memory

The current Application class also initializes:

application.memories

as:

dict[str, object]

This is currently a generic application-level collection. It should not be confused with the agent memory system. Agent memory is part of agent execution and context management. The application-level memories collection is currently an extension point for application-owned memory-related resources.

Application Resources

The current concrete application object contains:

application.configuration
application.agents
application.workflows
application.knowledge
application.memories

The most fully implemented resource is the agent collection. The other collections should currently be treated according to their actual implementation rather than as complete application subsystems.

Connections

Applications can use BindAI connections and external services through the broader BindAI ecosystem. Current connection types include:

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

However, Application itself does not currently contain a dedicated connection registry. Connections are provided by the bindai-connections package and can be composed into applications through tools, workflows, or other application-level components.

Tools

Agents can use tools as part of their execution. The application itself does not currently expose a dedicated tool registry. Project-level shared tools are provided through:

project.tools

and can be registered with:

project.add_tool(tool)

Tools can then be incorporated into the appropriate agent or execution configuration. The application should therefore not be treated as a second independent tool-management system.

Project and Application Relationship

A Project can contain multiple applications. For example:

Project
│
├── Customer Support Application
│   ├── FAQ Agent
│   ├── Billing Agent
│   └── Escalation Agent
│
├── HR Application
│   ├── HR Assistant
│   └── Policy Agent
│
└── Engineering Application
    ├── Code Review Agent
    └── Documentation Agent

The project stores applications by name:

project.applications

Applications can be added with:

project.add_application(application)

and retrieved with:

project.application("customer-support")

The project also provides convenience execution methods:

project.run(
    application="customer-support",
    agent="faq",
    message="What are your support hours?",
)

and:

project.stream(
    application="customer-support",
    agent="faq",
    message="Explain the support process.",
)

These methods delegate execution to the selected application.

Application Boundaries

Applications are useful when a project contains several distinct business domains. Good examples include:

Customer Support
Human Resources
Finance
Engineering
Sales
Procurement
Fleet Management

Each application can maintain its own set of agents. For example:

Project
│
├── HR
│   ├── HR Assistant
│   └── Policy Agent
│
└── Finance
    ├── Finance Assistant
    └── Invoice Agent

This keeps agent responsibilities organized around meaningful business capabilities.

Application Isolation

Applications have separate agent collections. For example:

Application A
└── agents

Application B
└── agents

Adding an agent to one application does not automatically add it to another application. Applications can therefore provide a useful organizational boundary for agent configuration. Other forms of isolation depend on how the surrounding project and application resources are configured. The framework should not be assumed to provide automatic security isolation merely because two agents belong to different Application objects.

Python Helpers

Application provides several Python convenience methods.

Membership

You can check whether an agent exists:

if "support" in application:
    ...

This checks the application’s agent collection.

Length

len(application)

returns the number of registered agents.

Iteration

You can iterate over the application’s agents:

for agent in application:
    print(agent.name)

Iteration returns the agent objects stored in the application.

Application API

The current public Application API includes:

Construction

Application(configuration)

Configuration

application.configuration
application.name

Agent management

application.agents
application.add_agent(agent)
application.agent(name)

Execution

application.run(
    agent=...,
    message=...,
)

application.stream(
    agent=...,
    message=...,
)

Application-level collections

application.workflows
application.knowledge
application.memories

Python helpers

name in application
len(application)

for agent in application:
    ...

Application Lifecycle

A typical application lifecycle is:

Create Configuration
       |
       v
Create Application
       |
       v
Register Agents
       |
       v
Run or Stream Agent
       |
       v
Return Result

Example:

from bindai_application import Application, ApplicationConfiguration

application = Application(
    ApplicationConfiguration(
        name="research",
        description="Research assistant",
    )
)

application.add_agent(research_agent)

result = application.run(
    agent="researcher",
    message="Research this topic.",
)

Application Entry Points

An application can be reached through different surrounding interfaces. For example:

User
 |
 +---- Python
 |
 +---- REST API
 |
 +---- Webhook
 |
 +---- Automation
 |
 v
Application
 |
 v
Agent

These entry points are not all implemented directly by the Application class. For example, the REST API is provided by the separate bindai-api package. The application provides the Python-level execution interface that those surrounding systems can call.

REST API Integration

The BindAI REST API can expose configured projects and their applications. The API’s agent endpoints operate on the configured BindAI application:

GET  /api/v1/agents
POST /api/v1/agents/{agent_name}/run
POST /api/v1/agents/{agent_name}/stream

The API application must first be configured with a BindAI application using:

from bindai_api import configure_application

configure_application(application)

The REST API does not automatically discover every Application object in the Python process.

Streaming and REST

Application-level streaming:

application.stream(
    agent="assistant",
    message="Tell me about this topic.",
)

is distinct from the REST API’s HTTP streaming endpoint. The application delegates to the agent’s stream_chat() method. The REST API wraps the resulting stream in its HTTP response mechanism. The current REST API uses a plain HTTP StreamingResponse; it is not documented as an SSE protocol.

Error Handling

Application-level execution delegates to the selected agent:

application.run(
    agent="assistant",
    message="Hello",
)

Therefore, provider errors, tool errors, configuration errors, and other execution failures depend on the underlying agent and its runtime components. The application does not currently define a separate application-wide error-handling framework. Applications exposed through external APIs should handle errors at the API or service boundary and avoid exposing sensitive internal details.

Security

An Application object does not itself provide authentication or authorization. Security should be implemented at the appropriate surrounding layer. For example:

Client
   |
   v
Authentication
   |
   v
Application/API
   |
   v
Agent
   |
   v
Tools / Providers

When applications use sensitive tools or data, consider:

authentication
authorization
API key protection
tool permissions
knowledge access
memory isolation
provider credentials
external connection credentials
sensitive output handling

The REST API provides API-key authentication separately from the Application class.

Recommended Usage

Use Application when you want a concrete container for related agents. A simple application can be:

from bindai_application import Application, ApplicationConfiguration

application = Application(
    ApplicationConfiguration(
        name="customer-support",
        description="Customer support assistant",
    )
)

application.add_agent(support_agent)

result = application.run(
    agent="support",
    message="I need help with my account.",
)

For larger systems, a project can contain multiple applications:

Project
│
├── Customer Support
│   ├── FAQ Agent
│   ├── Billing Agent
│   └── Escalation Agent
│
├── HR
│   ├── HR Assistant
│   └── Policy Agent
│
└── Engineering
    ├── Code Review Agent
    └── Documentation Agent

Current Scope

The current Application implementation is intentionally lightweight. It directly provides:

application configuration
application identity
agent registration
agent lookup
agent execution
agent streaming
Python collection helpers

It currently initializes additional collections for:

workflows
knowledge
memories

but these are generic dictionaries rather than complete dedicated subsystems. The application does not currently provide:

a built-in workflow registry
a built-in workflow scheduler
a built-in tool registry
a built-in connection registry
a built-in knowledge database
a built-in memory database
authentication
authorization
distributed execution
persistence
multi-tenant isolation

These capabilities are provided by other BindAI packages or can be layered around the application.

Package

Applications are provided by the bindai-application package. The core implementation contains:

bindai-application/
└── src/
    └── bindai_application/
        ├── application.py
        ├── configuration.py
        └── __init__.py

The package depends on the BindAI agent package.

Application vs Project

Project	Application
Top-level project container	Business application container
Can contain multiple applications	Contains multiple agents
Owns shared tools	Owns agent registration
Owns workflow registry	Provides agent execution helpers
Owns workflow scheduler	Provides agent streaming helpers
Owns project configuration	Owns application configuration
Provides project-level execution helpers	Delegates execution to agents

In simple terms: Project → organizes applications and shared project resources. Application → organizes and executes agents for a business domain.

Summary

The current BindAI Application is a concrete, lightweight runtime container for related agents. Its primary responsibilities are:

Application
│
├── Configuration
│
├── Agents
│   ├── Agent A
│   ├── Agent B
│   └── Agent C
│
├── Workflow collection
├── Knowledge collection
└── Memory collection

The main implemented execution path is:

Application
    |
    v
Agent
    |
    +---- chat()
    |
    └---- stream_chat()

For project-level organization, shared tools, workflow registration, and scheduling, use Project. For agent behavior and execution, use Agent. This separation keeps the current BindAI architecture lightweight while allowing applications and projects to compose the framework’s more specialized subsystems.

​Applications

​What Is an Application?

​Application Configuration

​Creating an Application

​Agents

​Retrieving Agents

​Running an Agent

​Streaming

​Multiple Agents

​Example Application

​Application and Agent Responsibilities

​Application

​Agent

​Workflows

​Knowledge

​Memory

​Application Resources

​Connections

​Tools

​Project and Application Relationship

​Application Boundaries

​Application Isolation

​Python Helpers

​Membership

​Length

​Iteration

​Application API

​Construction

​Configuration

​Agent management

​Execution

​Application-level collections

​Python helpers

​Application Lifecycle

​Application Entry Points

​REST API Integration

​Streaming and REST

​Error Handling

​Security

​Recommended Usage

​Current Scope

​Package

​Application vs Project

​Summary