Skip to main content

pagent

pagent (English)

CI Coverage License: MIT

Language: 中文 | English · Docs · For agents · llms.txt

pagent is a small async Python library for an Agent + tools loop over OpenAI-compatible Chat Completions. Good for scripts, experiments, and teaching—transparent message history, your own tools.

Documentation

https://synclionpaw.github.io/pagent/ — install, quick start, tools, events, Wire, providers.

Install

Requires Python 3.11+.

pip

pip install pagent
pip install "pagent[search]"   # optional web_search tool

uv

uv is a fast Python package and project manager (official docs).

uv pip install pagent
uv pip install "pagent[search]"

# or in a uv-managed project
uv add pagent
uv add "pagent[search]"

uvx (terminal REPL)

export DEEPSEEK_API_KEY="your-key"
uvx pagent
uvx pagent --thread-id demo

conda

conda activate your-env
pip install pagent
pip install "pagent[search]"

Conda envs usually install PyPI packages with pip inside the activated environment. Check conda-forge if you prefer a conda package when available.

Quick start

import asyncio
import os

from pagent import Agent, LLM, Session, tool


@tool()
def get_weather(city: str) -> str:
    """Return a fake weather summary for the city."""
    return f"It's sunny in {city} today."


async def main() -> None:
    if not os.getenv("OPENAI_API_KEY"):
        raise SystemExit("Please set OPENAI_API_KEY first.")

    agent = Agent(
        llm=LLM("gpt-4o-mini"),
        session=Session("You are a concise assistant. Use tools when needed."),
        tools=[get_weather],
        max_turns=24,
    )

    result = await agent.run("What's the weather in Xiamen?")
    print(result.content)
    print(agent.stats)


asyncio.run(main())

run() returns RunEnd; use .content for the answer.

Streaming & events

One agent timeline — pick an API by consumer (not two different event systems):

API You get Best for
agent.run(prompt) Final RunEnd No streaming
agent.arun(prompt) Answer text str Simple typing effect in scripts
agent.arun_events(prompt) Python Event dataclasses In-process Python: CLI, services, match / types
agent.arun_wire(prompt) NDJSON lines (JSON-RPC 2.0) Cross-language / frontend: SSE, WebSocket, TS switch (method)

Wire serializes the same events as native Event; see docs/events.md and docs/wire.md.

Minimal event consumer (build your own UI or logs):

import asyncio

from pagent import (
    Agent,
    LLM,
    RunEnd,
    Session,
    TextDelta,
    ToolCallBegin,
    ToolResult,
)


async def main():
    agent = Agent(LLM("gpt-4o-mini"), Session("You are helpful."), tools=[])

    async for event in agent.arun_events("What is 2 + 2?"):
        if isinstance(event, TextDelta):
            print(event.text, end="", flush=True)
        elif isinstance(event, ToolCallBegin):
            print(f"\n[calling {event.name}]", flush=True)
        elif isinstance(event, ToolResult):
            print(f" {event.content}", flush=True)
        elif isinstance(event, RunEnd):
            print(f"\n\n(done, {event.content!r})")


asyncio.run(main())

Common events: TextDelta (answer stream), ReasoningDelta (model thinking, if supported), ToolCallBegin / ToolResult, RunEnd (final result with .content and .reasoning_content).

Full list: docs/events.md. Frontend / JSON: docs/wire.md — each line is {"jsonrpc":"2.0","method":"TextDelta","params":{...}}.

async for line in agent.arun_wire("Hello"):
    # send `line` over SSE / WebSocket (already ends with \n)
    ...

Runnable demos are grouped under examples/; start with examples/README.md.

Models & API keys

Class Env var
LLM("gpt-4o-mini") OPENAI_API_KEY
DeepSeek() DEEPSEEK_API_KEY
Ollama(...), Vllm, Sglang optional provider keys
from pagent import DeepSeek, Ollama

llm = DeepSeek("deepseek-v4-flash")
llm = Ollama("llama3.2")

Server must expose OpenAI-compatible /v1/chat/completions.

Examples

Command Description
uv run pagent Interactive pagentv4 terminal app
uv run python -m examples.pagentv4.thread_based.conversation_only Thread-based conversation persistence
uv run python -m examples.pagentv4.thread_based.code_runner CodeRunner with sandbox tools
uv run python -m examples.pagentv4.runner.return_types text / message / acp / event projections
uv run --with fastapi --with uvicorn python examples/wire_browser/server.py Wire NDJSON + browser UI

Guide: docs/reasoning.md. Full-stack wire demo: examples/wire_browser/.

export DEEPSEEK_API_KEY="your-key"
uv run python -m examples.pagentv4.thread_based.conversation_only

Optional built-in tools

from pagent import Agent, LLM, Session, web_search

agent = Agent(LLM("gpt-4o-mini"), Session("..."), tools=[web_search])

See clock, region in pagent.defaults.

Notes

  • Requires an OpenAI Chat Completions–compatible API.
  • A minimal embeddable loop—not a full coding-agent product with file edit/shell.
  • Development & internals: docs/development.md

License

MIT

Metadata

Release files for pagent 0.7.30

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pagent 0.7.30
File Size Uploaded Provenance Actions
pagent-0.7.30.tar.gz 200.5 kB With provenance Details for pagent-0.7.30.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pagent 0.7.30
File Interpreter ABI Platform Actions
pagent-0.7.30-py3-none-any.whl Python 3 none any Details for pagent-0.7.30-py3-none-any.whl

Total release size: 471.3 kB

Release files / pagent-0.7.30.tar.gz

Download URL pagent-0.7.30.tar.gz
Size 200.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1ae60bf6d9de87d7268a7c44b275fb0ccb47dad2638120d5f1f4d7a1ac2646a4
BLAKE2b-256 checksum
How to use checksums
d13ec50c7132d4916375782362b5e555586951431f249c0c5d60e3aeec499602
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Aug 25, 2026.

Transparency log

Release files / pagent-0.7.30-py3-none-any.whl

Download URL pagent-0.7.30-py3-none-any.whl
Size 270.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
07d4adb0b1319ebd40d1723bbfff601e9ef9dcc961aa631d1d0a416e6702e65b
BLAKE2b-256 checksum
How to use checksums
7f3aac0e7c782c44ca19294d9983f1f7d607e9080c49d5e35934ac209c5abc1d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Aug 25, 2026.

Transparency log

Security for pagent 0.7.30

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for pagent-0.7.30.tar.gz

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 Aug 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page