Capability-native Python for the agentic era.

Agnara Project is the open-source home of the Agnara ecosystem — a Python framework and engineering initiative focused on building explicit, inspectable, maintainable, and agent-ready software.

Agnara is designed for a world where applications are increasingly created, inspected, operated, and extended by both humans and AI agents.

The project explores how Python applications can expose their capabilities as explicit, typed, machine-readable contracts without sacrificing clarity for human developers.

Agnara is an open-source Python framework for building applications around explicit capabilities.

Instead of treating application functionality as an accidental collection of functions, routes, commands, jobs, and integrations, Agnara promotes a capability-first model where application behavior can be declared, inspected, composed, validated, governed, and executed consistently.

The goal is simple:

Make application capabilities understandable to both humans and machines.

Agnara is being designed around principles such as:

• explicit application capabilities
• typed contracts
• dependency-aware execution
• inspectable architecture
• deterministic application composition
• policy-aware operations
• structured execution
• observable outcomes
• protocol-neutral application logic
• agent-friendly discovery
• maintainable Python design

Traditional frameworks were primarily designed for humans writing applications that other humans would operate through predefined interfaces.

Software development is changing.

AI agents can now:

• inspect repositories
• understand APIs
• generate code
• execute workflows
• invoke tools
• reason about application capabilities
• participate in software maintenance
• operate increasingly complex systems

This creates a new architectural requirement.

Applications should not merely work.

They should also be able to explain:

• what they can do
• what inputs they require
• what they return
• what they depend on
• what effects they may produce
• what policies govern execution
• how they can be safely invoked

Agnara is being built around that idea.

At the center of Agnara is the concept of a capability.

A capability represents something an application knows how to do.

Conceptually:

Application
    │
    ├── Capability
    │      ├── identity
    │      ├── description
    │      ├── inputs
    │      ├── outputs
    │      ├── dependencies
    │      ├── metadata
    │      ├── policies
    │      └── execution
    │
    ├── Capability
    │      └── ...
    │
    └── Runtime
           ├── discovery
           ├── planning
           ├── validation
           ├── dependency resolution
           ├── execution
           └── observability

This model allows application behavior to become an explicit architectural primitive rather than something inferred indirectly from implementation details.

Agnara does not treat human usability and agent usability as competing goals.

The ecosystem is designed for both.

Developers should be able to:

• understand the architecture
• read the code naturally
• discover application behavior
• reason about dependencies
• debug execution
• test components independently
• maintain systems without unnecessary framework magic

AI coding and operational agents should be able to:

• inspect repository instructions
• discover available capabilities
• understand typed contracts
• identify dependencies
• reason about execution boundaries
• follow repository-specific skills
• execute deterministic validation workflows
• contribute without relying on undocumented assumptions

A well-designed repository should be understandable before it is modified.

A well-designed application should be inspectable before it is executed.

Agnara favors architecture that can be inspected and reasoned about.

Framework convenience should not require developers to surrender understanding of their application.

Important behavior should be visible.

Dependencies should be identifiable.

Contracts should be explicit.

Execution should be traceable.

Errors should be meaningful.

Automation should remain understandable.

The framework should help developers manage complexity rather than hide it.

Application logic should not need to belong permanently to a particular transport.

A capability represents application behavior independently from the mechanism used to expose or invoke it.

This architectural direction allows the ecosystem to evolve toward multiple interfaces while preserving a common application model.

Conceptually:

                    ┌─────────────┐
                    │   Humans    │
                    └──────┬──────┘
                           │
                           ▼
┌──────────┐        ┌─────────────┐        ┌──────────┐
│ AI Agent │ ─────► │ Capabilities│ ◄───── │ Services │
└──────────┘        └──────┬──────┘        └──────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │   Runtime   │
                    └─────────────┘

The capability remains the architectural contract.

Interfaces become ways of interacting with that contract.

Inspectability is a first-class concern.

Agnara aims to make it possible to reason about an application before execution.

That includes understanding concepts such as:

capabilities
      ↓
contracts
      ↓
dependencies
      ↓
policies
      ↓
execution plans
      ↓
runtime
      ↓
outcomes

This becomes increasingly important as applications are operated not only by developers but also by autonomous systems.

Application behavior should be modeled explicitly around what the system can do.

Important architectural relationships should be visible rather than hidden behind framework behavior.

Developers and agents should be able to understand application structure before executing it.

Types should contribute to executable and machine-readable application contracts.

Dependencies are part of application architecture and should be modeled accordingly.

Systems should be able to reason about operational constraints and effects before execution.

Core application behavior should remain independent from any single transport or interface.

Architecture, documentation, APIs, errors, and tooling should remain understandable to developers.

Repositories and applications should provide enough explicit structure for AI agents to work safely and predictably.

Examples, releases, tests, and historical references should remain reproducible.

Examples and supporting repositories should demonstrate real software-engineering practices rather than disposable demo code.

Agnara is evolving toward an architecture where application capabilities can move through a consistent lifecycle:

Declare
   ↓
Describe
   ↓
Validate
   ↓
Discover
   ↓
Resolve
   ↓
Plan
   ↓
Authorize
   ↓
Execute
   ↓
Observe
   ↓
Return

Not every stage necessarily belongs to every application or framework release.

The important principle is that these concerns can be modeled explicitly instead of being scattered across unrelated infrastructure.

Agnara maintains professional reference applications that preserve how the framework behaves at particular stages of its evolution.

These repositories are not disposable tutorials.

They are versioned architectural references.

A historical reference application may preserve:

• framework APIs available at that point in time
• recommended architectural patterns
• testing strategies
• agent workflows
• dependency patterns
• security practices
• capability design
• execution behavior
• documentation conventions

Once a historical reference reaches its final state, it can remain intentionally frozen.

This allows future developers to inspect not only what Agnara becomes, but also how it evolved.

Framework evolution
        │
        ├── Release
        │     └── Historical references
        │
        ├── Release
        │     └── Historical references
        │
        ├── Release
        │     └── Historical references
        │
        └── ...

The organization therefore becomes a living architectural history without requiring this README to maintain a manual catalog of every project.

API documentation explains individual interfaces.

Reference applications explain how those interfaces become software.

Agnara uses both.

Reference implementations are intended to demonstrate how framework concepts interact in realistic, reproducible projects.

This makes the ecosystem useful for:

• developers learning Agnara
• contributors working on the framework
• architects evaluating its design
• AI coding agents operating inside Agnara projects
• researchers exploring agent-oriented software architecture

The repositories themselves become part of the documentation.

Agnara is developed openly.

The core framework is currently available at:

Core Framework
https://github.com/Blandskron/agnara

Python Package
https://pypi.org/project/agnara/

Agnara Project Organization
https://github.com/agnara-project

During the framework's early development, the core repository remains under its original GitHub location.

As the project reaches the appropriate level of maturity, stability, governance, and ecosystem readiness, the organization is intended to become the long-term home of the broader Agnara ecosystem.

Agnara Project is intended to grow naturally around the framework.

The ecosystem may include:

Agnara
│
├── Core Framework
│
├── Historical References
│
├── Reference Architectures
│
├── Integrations
│
├── Developer Tooling
│
├── Agent Tooling
│
├── Educational Implementations
│
├── Architectural Experiments
└── Ecosystem Infrastructure

The exact repositories can evolve without changing the fundamental purpose of the organization.

Agnara is still evolving.

Its architecture, APIs, runtime, integrations, and tooling will continue to mature.

That evolution is intentional.

The project favors:

clarity over magic
contracts over assumptions
inspection over opacity
composition over coupling
evidence over claims
evolution over premature stability

Historical references preserve where the framework has been.

The core framework defines where it is today.

The architecture defines where it is going.

Agnara is open source and welcomes thoughtful contributions.

Contributors can participate through:

• framework development
• bug reports
• testing
• documentation
• architectural discussion
• reference implementations
• integrations
• developer tooling
• agent-oriented tooling

AI-assisted contributions are welcome.

The standard remains the same regardless of whether code is written by a human, an AI agent, or both:

correctness, tests, documentation, maintainability, security, and engineering quality.

Agnara is not being built simply to add another abstraction layer to Python.

It explores a broader question:

What should a Python application framework look like when humans and AI agents are both first-class participants in software systems?

The answer will continue to evolve with the framework.

The principles remain clear:

explicit architecture, inspectable capabilities, maintainable systems, and software designed to be understood before it is operated.

GitHub
https://github.com/Blandskron/agnara

PyPI
https://pypi.org/project/agnara/

Agnara Project
https://github.com/agnara-project

Agnara Project
Capability-native Python for the agentic era.

Explicit. Inspectable. Agent-ready.