pgns-agent 0.1.5

Wrap any agent function in a production-ready A2A server

pgns-agent

Express.js for A2A agents.

Wrap any agent function in a production-ready A2A-compatible server, powered by pgns.

from pgns_agent import AgentServer

agent = AgentServer("my-agent", "Echoes input")

@agent.on_task
async def handle(task):
    return {"echo": task.input}

agent.listen(3000)

Quickstart

Install:

pip install pgns-agent

Configure (optional — omit for local dev mode):

export PGNS_API_KEY="your-api-key"

Run:

python agent.py

Your agent is now live. Verify the agent card at http://localhost:3000/.well-known/agent.json.

Features

• A2A protocol compliance — serves the standard Agent Card at /.well-known/agent.json
• Auto-provisioning — registers an agent card and roost on the pgns relay at startup
• Sync + async modes — handlers are always async, but the server can run standalone or embedded
• SSE streaming — stream task progress updates to callers via Server-Sent Events
• Task lifecycle — submitted → working → completed/failed with full status tracking
• Input-required flow — suspend a handler and request additional input from the caller
• Local dev mode — run without a pgns API key for local development and testing

Three entry points

Standalone server — start a self-contained HTTP server:

agent.listen(3000)

Mount into an existing app — get a Starlette/ASGI application to compose with FastAPI, Starlette, or any ASGI framework:

app = agent.app()

Serverless handler — get the raw ASGI callable for Lambda, Cloud Functions, etc.:

handler = agent.handler()

Framework adapters

Adapters let you wire existing agent frameworks into pgns-agent with zero glue code.

LangChain / LangGraph

pip install pgns-agent-langchain

from pgns_agent import AgentServer
from pgns_agent.adapters import LangChainAdapter

agent = AgentServer("my-langchain-agent", "Runs a LangChain chain")
agent.use(LangChainAdapter(my_runnable))
agent.listen(3000)

OpenAI Agents SDK

pip install pgns-agent-openai

Claude Agent SDK

pip install pgns-agent-claude

CrewAI

pip install pgns-agent-crewai

Testing

Use the built-in test client for unit testing — no server required:

client = agent.test_client()
resp = client.send_task({"text": "hello"})
assert resp.status == "completed"
assert resp.result == {"echo": {"text": "hello"}}

Documentation

Full documentation is available at docs.pgns.io/libraries/pgns-agent.

• API Reference
• GitHub

License

Apache 2.0