Naylence Agent SDK (Python)
The Naylence Agent SDK is the official toolkit for building agents and clients on the Naylence Agentic Fabric. It gives you a clean, typed, async-first API for composing tasks, streaming results, and wiring agents together—locally or across a distributed fabric.
If you're new to Naylence, start here. For lower‑level transport/fabric internals, see naylence‑runtime.
Highlights
- Ergonomic agent model — subclass
BaseAgent(one-shot) orBackgroundTaskAgent(long‑running/streaming) and focus on your logic. - Typed messages & tasks — Pydantic models for
Task,Message,Artifact, and JSON‑RPC A2A operations. - Async all the way — non‑blocking lifecycle with easy scatter‑gather helpers (
Agent.broadcast,Agent.run_many). - Remote proxies — call agents by address or capabilities via
Agent.remote_*helpers. - Streaming & cancellation — subscribe to live status/artifacts; cancel in‑flight work.
- FastAPI integration — drop‐in JSON‑RPC router (
create_agent_router) and/agent.jsonmetadata endpoint. - Security ready — works with runtime security profiles; strict‑overlay requires the
naylence‑advanced‑securityadd‑on.
Install
pip install naylence-agent-sdk
Python 3.12+ is required.
Quickstart (minimal)
import asyncio
from typing import Any
from naylence.fame.core import FameFabric
from naylence.agent import Agent, BaseAgent
class EchoAgent(BaseAgent):
async def run_task(self, payload: Any, id: Any) -> Any:
return payload
async def main():
async with FameFabric.create() as fabric:
address = await fabric.serve(EchoAgent())
echo = Agent.remote_by_address(address)
print(await echo.run_task("Hello, world!", None))
asyncio.run(main())
For a gentle, runnable tour—from single‑process to distributed orchestration—use the Examples repo: https://github.com/naylence/naylence-examples-python.
Core concepts
Agents & tasks
- Implement
run_task(payload, id)for simple one‑shot work, or overridestart_task(...)/get_task_status(...)for background jobs. Message.partscarries either text (TextPart) or structured data (DataPart).- Long‑running flows stream
TaskStatusUpdateEventandTaskArtifactUpdateEventuntil terminal (COMPLETED/FAILED/CANCELED).
Remote proxies
Agent.remote_by_address("echo@fame.fabric")to call a known address.Agent.remote_by_capabilities(["agent"])to call by capability (fabric does resolution).
Streaming & cancel
subscribe_to_task_updates(...)yields status/artifacts live.cancel_task(...)requests cooperative cancellation when supported by the agent.
RPC operations
- A2A JSON‑RPC methods (
tasks/send,.../get,.../cancel, etc.) are provided for task lifecycle. - Custom functions can be exposed via the RPC mixin in the underlying fabric (e.g., streaming operations).
FastAPI router
- Use
create_agent_router(agent)to expose a JSON‑RPC endpoint (default:/fame/v1/jsonrpc) andGET /agent.jsonto return anAgentCard.
Choosing an agent base class
BaseAgent— great for synchronous/short tasks; the default fallback packages your return value into aTask(COMPLETED).BackgroundTaskAgent— best for long‑running/streaming work. You implementrun_background_task(...); the base manages queues, TTLs, and end‑of‑stream.
Both base classes include sensible defaults (poll‑based streaming, simple auth pass‑through). You can override any part of the lifecycle.
Development workflow
- Add your agents in a project with the SDK.
- Use
FameFabric.create()in tests or local scripts to host agents in‑process. - For distributed setups, operate a sentinel/fabric with naylence‑runtime (or your infra) and connect agents remotely.
- Use the Examples repo (https://github.com/naylence/naylence-examples-python) to learn patterns like scatter‑gather, RPC streaming, cancellation, and security tiers.
API Documentation
To generate API documentation from source:
# Generate Markdown docs to docs/api/
poetry run docs-gen
# Or specify a custom output directory
poetry run docs-gen --out path/to/output
The generated docs are Markdown files compatible with Nextra and other documentation systems.
Security notes
The SDK runs on the Naylence fabric’s security profiles:
- direct / gated / overlay modes work out‑of‑the‑box with the open‑source stack.
- strict‑overlay (sealed overlay encryption + SPIFFE/X.509 identities) is available only with the
naylence‑advanced‑securitypackage.
See repo links below for the advanced add‑on and images that bundle it.
Links
- Agent SDK (this repo): https://github.com/naylence/naylence-agent-sdk-python
- Examples (Python): https://github.com/naylence/naylence-examples-python
- Runtime (fabric & transports): https://github.com/naylence/naylence-runtime-python
- Advanced Security add‑on: https://github.com/naylence/naylence-advanced-security-python
Docker images:
- OSS:
naylence/agent-sdk-python - Advanced:
naylence/agent-sdk-adv-python(includesnaylence-advanced-security; BSL-licensed add-on)
License & support
- License: Apache‑2.0 (SDK).
- Issues: please use the appropriate GitHub repo (SDK, Runtime, Examples, Advanced Security).
1 maintainer
Metadata
1 maintainer
Release files for naylence-agent-sdk 0.4.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| naylence_agent_sdk-0.4.12.tar.gz | 37.4 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| naylence_agent_sdk-0.4.12-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 81.0 kB
Release files / naylence_agent_sdk-0.4.12.tar.gz
| Download URL | naylence_agent_sdk-0.4.12.tar.gz |
|---|---|
| Size | 37.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
238d901f4fb8f4f31afee05684dc8ebf11ad5899ba486ec0669fc64565bf54b0
|
|
BLAKE2b-256 checksum How to use checksums |
414480d3daed5722e3077e18c8a74d6dd31877051e06637b477235f6e28ba798
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 18, 2026.
Transparency logRelease files / naylence_agent_sdk-0.4.12-py3-none-any.whl
| Download URL | naylence_agent_sdk-0.4.12-py3-none-any.whl |
|---|---|
| Size | 43.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8febc8c1917f15ce702f9ec9f0a4afce2eeb0d5037aa53c06ec89d398b64254b
|
|
BLAKE2b-256 checksum How to use checksums |
cdb1fe925ed44c64ead54dcdff2307f72f3b5b354526b14a076078ae157d4201
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 Apr 18, 2026.
Transparency logSecurity for naylence-agent-sdk 0.4.12
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
All 2 files in this release have been uploaded with provenance metadata.
Attestation for naylence_agent_sdk-0.4.12.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 Apr 18, 2026.
Transparency logA 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.
