PyAgentic
A declarative, type-safe framework for building AI agents with OpenAI integration. PyAgentic lets you create sophisticated LLM agents using clean Python class syntax, with full support for tools, persistent state, agent linking, and agent inheritance.
Documentation
Read the Getting Started!
Complete documentation, tutorials, and examples can be found here
Features
- Declarative Design - Define agents with simple class-based syntax and decorators
- Powerful Tools - Easy
@tooldecoration with automatic OpenAI schema generation - Persistent State - Stateful agents with
Statefields that persist across conversations - Agent Linking - Compose complex workflows by linking agents together
- Structured Responses - Type-safe Pydantic responses with full tool execution details
- Dynamic Constraints - Use
refto create smart parameter validation - Inheritance & Extensions - Build agent hierarchies and mix in cross-cutting capabilities
- Native Async Support - Built for scalable applications with async/await throughout
- Type Safety - Complete typing support with validation and IDE autocompletion
Quick Start
Installation
pip install pyagentic-core
Simple Agent Example
from pyagentic import BaseAgent, tool, State, spec
class ResearchAgent(BaseAgent):
__system_message__ = "I help with research tasks and maintain a collection of papers"
# Persistent state that survives across conversations
paper_count: State[int] = spec.State(default=0)
current_topic: State[str] = spec.State(default="general", access="write")
@tool("Search for academic papers")
def search_papers(self, query: str, max_results: int = 5) -> str:
# Your search logic here
self.paper_count += max_results
return f"Found {max_results} papers about '{query}'"
# Create and use the agent
agent = ResearchAgent(model="openai::gpt-4", api_key="your-key")
response = await agent("Help me research machine learning papers")
# Access structured response data
print(response.final_output) # Natural language response
print(len(response.tool_responses)) # Number of tools called
print(agent.paper_count) # Persistent state
Advanced Features
Agent Linking
Create multi-agent workflows where agents can call other agents as tools:
class DatabaseAgent(BaseAgent):
__system_message__ = "I query databases"
__description__ = "Retrieves data from SQL databases"
@tool("Execute SQL query")
def query(self, sql: str) -> str: ...
class WebAgent(BaseAgent):
__system_message__ = "I search the web"
__description__ = "Searches the internet"
@tool("search")
def search(self, terms: list[str]) -> str: ...
class ReportAgent(BaseAgent):
__system_message__ = "I generate business reports"
database: DatabaseAgent # Linked agent appears as a tool
searcher: WebAgent
@tool("Create visualization")
def create_chart(self, data: str) -> str: ...
# The report agent can automatically coordinate with the database agent
report_agent = ReportAgent(database=DatabaseAgent(...), searcher=WebAgent(...))
response = await report_agent("Generate a plot of the latest financial data")
Dynamic Parameter Constraints
Use ref with Pydantic computed fields to create intelligent parameter validation:
from pydantic import BaseModel, computed_field
from pyagentic import ref, spec
class DatasetState(BaseModel):
available_datasets: list = []
@computed_field
@property
def dataset_names(self) -> list[str]:
return [ds['name'] for ds in self.available_datasets]
class DataAgent(BaseAgent):
__system_message__ = "I manage datasets"
datasets: State[DatasetState] = spec.State(default_factory=DatasetState)
@tool("Analyze specific dataset")
def analyze(
self,
dataset: str = spec.Param(
description="Dataset to analyze",
values=ref.datasets.dataset_names # LLM can only pick from available datasets
)) -> str: ...
Contributing
Contribution is welcome! Whether it's bug fixes, new features, documentation improvements, or examples, help is appreciated.
Development Setup
-
Clone the repository
git clone https://github.com/your-username/pyagentic.git cd pyagentic
-
Install dependencies with uv
# Install uv if you haven't already pip install uv # Install all dependencies including dev tools uv sync --group dev
Code Quality
Several tools are used to maintain code quality:
Formatting with Black
# Format all Python files
uv run black -l99 pyagentic tests
# Check formatting without making changes
uv run black -l99 --check pyagentic tests
Linting with Flake8
# Run linting checks
uv run flake8 --max-line-length=99 pyagentic tests
Testing
# Run all tests
uv run pytest tests
# Run tests with coverage
uv run coverage run -m pytest tests
Documentation
Documentation is built with MkDocs and deployed automatically:
Local Development
# Install docs dependencies
uv sync --group docs
# Serve docs locally (auto-reloads on changes)
uv run task serve-docs
# Build docs to ./site/
uv run task build-docs
Docs are automatically deployed on pushes to main via GitHub Actions.
Submitting Changes
-
Create a feature branch
git checkout -b feature/your-feature-name
-
Make your changes following the code style guidelines
-
Run the full test suite
uv run black pyagentic tests uv run flake8 pyagentic tests --max-line-length=99 uv run pytest
-
Commit with conventional commit messages
git commit -m "feat: add new agent linking feature" git commit -m "fix: resolve context persistence issue" git commit -m "docs: improve getting started guide"
-
Push and create a Pull Request
git push origin feature/your-feature-name
Conventional Commits
Conventional commits are used for automatic versioning:
feat:- New features (minor version bump)fix:- Bug fixes (patch version bump)docs:- Documentation changestest:- Test additions or improvementsrefactor:- Code refactoringstyle:- Code style changes (formatting, etc.)
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
1 maintainer
Metadata
1 maintainer
Release files for pyagentic-core 2.2.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pyagentic_core-2.2.2.tar.gz | 52.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pyagentic_core-2.2.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 118.8 kB
Release files / pyagentic_core-2.2.2.tar.gz
| Download URL | pyagentic_core-2.2.2.tar.gz |
|---|---|
| Size | 52.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5254baba253f72667cc11f514b6288846bef826ab406b2d8a20ef46dd1a23a60
|
|
BLAKE2b-256 checksum How to use checksums |
95cbca26e01baf33f6bea4babf86e693135ab2c59c8273b514a3e50c9bf91401
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 23, 2025.
Transparency logRelease files / pyagentic_core-2.2.2-py3-none-any.whl
| Download URL | pyagentic_core-2.2.2-py3-none-any.whl |
|---|---|
| Size | 65.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ea1d8c9bafafc6af2cba33ee1db029cc9533004b4f505aee710fa009ee3f67ff
|
|
BLAKE2b-256 checksum How to use checksums |
da5c577d3a2e371352634768719dd35a29254211f9c44156e55d51a88801545f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.12.8
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 23, 2025.
Transparency log
