PyAgentKit

A Python library for building tool-calling agents on top of locally-hosted LLMs via Ollama. PyAgentKit gives models that lack native function-calling support the ability to call tools through structured JSON output, retries, dependency injection, and lifecycle hooks.

Features

• Sync and async agents — Agent for synchronous use, AsyncAgent for asyncio-based workflows
• Tool registration — attach tools at the class level (shared across all instances) or at the instance level (per-agent)
• Structured JSON responses — agents respond in a validated, discriminated-union schema (final or tool_call)
• Pydantic response models — extend AgentResponse to add your own typed fields to every response
• Dependency injection — pass runtime dependencies (database connections, config, etc.) through AgentDependencies into tools without polluting tool signatures
• Retry logic — configurable retry budgets separately for tool calls and for response validation failures
• Approval gates — optionally require human confirmation before any tool is executed
• Lifecycle hooks — sync and async callbacks for tool calls, retries, successes, and final responses
• Validation hook — supply on_validate to run custom response logic and trigger retries or abort
• Agent composition — expose any agent as a tool that another agent can call via .as_tool()
• Token usage tracking — cumulative TokenUsage object updated after every LLM call
• Message history — persistent within a session, with optional trimming, save, and load
• Thinking support — pass think=True to enable chain-of-thought reasoning on supported models

Requirements

• Python 3.12+
• Ollama running locally (or at a reachable URL)
• A model pulled in Ollama

Installation

pip install pyagentkit

Project Structure

src/pyagentkit/
├── agent.py          # Synchronous Agent class
├── async_agent.py    # Asynchronous AsyncAgent class
├── definitions.py    # Pydantic models, type aliases, enums
└── exceptions.py     # Exception hierarchy

Core Concepts

Response Schema

Every agent responds in one of two JSON shapes, validated via Pydantic:

{
  "response": {
    "type": "tool_call",
    "message": "<why you're calling the tool>",
    "tool_call": { "name": "my_tool", "params": [{ "name": "x", "value": "42" }] }
  }
}

{
  "response": {
    "type": "final",
    "message": "<your answer or result of your operation(s)>"
  }
}

Exception Hierarchy

PyAgentKitError
├── ExceptionAgentError          # Recoverable response failure (triggers retry)
├── ExceptionAgentFatal          # Irrecoverable response failure
├── ExceptionToolError           # Recoverable tool failure (triggers retry)
├── ExceptionToolFatal           # Irrecoverable tool failure
├── ExceptionToolRetriesExhausted
├── ExceptionResponseRetriesExhausted
├── ExceptionEnvironmentError    # Ollama unreachable or model not found
├── ExceptionInvalidTool         # Tool missing docstring or malformed
└── ExceptionFatalError          # Wraps any fatal agent or tool exception
ExceptionUnhandledError          # Unhandled runtime exception (not a PyAgentKitError)

License

Apache 2.0