pyagentic-core 2.9.0a1

Build LLM Agents in a Pythonic way

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 @tool decoration with automatic OpenAI schema generation
• Persistent State - Stateful agents with State fields 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 ref to 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

1. Clone the repository

   git clone https://github.com/your-username/pyagentic.git
   cd pyagentic
   

2. 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

1. Create a feature branch

   git checkout -b feature/your-feature-name
   

2. Make your changes following the code style guidelines

3. Run the full test suite

   uv run black pyagentic tests
   uv run flake8 pyagentic tests --max-line-length=99
   uv run pytest
   

4. 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"
   

5. 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 changes
• test: - Test additions or improvements
• refactor: - Code refactoring
• style: - Code style changes (formatting, etc.)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.