# 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) or `BackgroundTaskAgent` (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.json` metadata endpoint.
* **Security ready** — works with runtime security profiles; **strict‑overlay** requires the `naylence‑advanced‑security` add‑on.
---
## Install
```bash
pip install naylence-agent-sdk
```
> Python **3.12+** is required.
---
## Quickstart (minimal)
```python
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](https://github.com/naylence/naylence-examples-python).
---
## Core concepts
**Agents & tasks**
* Implement `run_task(payload, id)` for simple one‑shot work, or override `start_task(...)`/`get_task_status(...)` for background jobs.
* `Message.parts` carries either text (`TextPart`) or structured data (`DataPart`).
* Long‑running flows stream `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` until 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`) and `GET /agent.json` to return an `AgentCard`.
---
## Choosing an agent base class
* **`BaseAgent`** — great for synchronous/short tasks; the default fallback packages your return value into a `Task(COMPLETED)`.
* **`BackgroundTaskAgent`** — best for long‑running/streaming work. You implement `run_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](https://github.com/naylence/naylence-examples-python)) to learn patterns like scatter‑gather, RPC streaming, cancellation, and security tiers.
---
## 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‑security`** package.
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](https://github.com/naylence/naylence-agent-sdk-python)
* **Examples (Python):** [https://github.com/naylence/naylence-examples-python](https://github.com/naylence/naylence-examples-python)
* **Runtime (fabric & transports):** [https://github.com/naylence/naylence-runtime-python](https://github.com/naylence/naylence-runtime-python)
* **Advanced Security add‑on:** [https://github.com/naylence/naylence-advanced-security-python](https://github.com/naylence/naylence-advanced-security-python)
Docker images:
* OSS: `naylence/agent-sdk-python`
* Advanced: `naylence/agent-sdk-adv-python` (includes `naylence-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).
Raw data
{
"_id": null,
"home_page": null,
"name": "naylence-agent-sdk",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "messaging, ai, agents, platform, naylence",
"author": "naylencedev@gmail.com",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ca/cb/c8c5f80b150951a747c62972816158b5b7e69493c88b03b674a0bad1d98e/naylence_agent_sdk-0.1.27.tar.gz",
"platform": null,
"description": "# Naylence Agent SDK (Python)\n\nThe **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\u2014locally or across a distributed fabric.\n\n> If you're new to Naylence, start here. For lower\u2011level transport/fabric internals, see **naylence\u2011runtime**.\n\n---\n\n## Highlights\n\n* **Ergonomic agent model** \u2014 subclass `BaseAgent` (one-shot) or `BackgroundTaskAgent` (long\u2011running/streaming) and focus on your logic.\n* **Typed messages & tasks** \u2014 Pydantic models for `Task`, `Message`, `Artifact`, and JSON\u2011RPC A2A operations.\n* **Async all the way** \u2014 non\u2011blocking lifecycle with easy scatter\u2011gather helpers (`Agent.broadcast`, `Agent.run_many`).\n* **Remote proxies** \u2014 call agents by **address** or **capabilities** via `Agent.remote_*` helpers.\n* **Streaming & cancellation** \u2014 subscribe to live status/artifacts; cancel in\u2011flight work.\n* **FastAPI integration** \u2014 drop\u2010in JSON\u2011RPC router (`create_agent_router`) and `/agent.json` metadata endpoint.\n* **Security ready** \u2014 works with runtime security profiles; **strict\u2011overlay** requires the `naylence\u2011advanced\u2011security` add\u2011on.\n\n---\n\n## Install\n\n```bash\npip install naylence-agent-sdk\n```\n\n> Python **3.12+** is required.\n\n---\n\n## Quickstart (minimal)\n\n```python\nimport asyncio\nfrom typing import Any\nfrom naylence.fame.core import FameFabric\nfrom naylence.agent import Agent, BaseAgent\n\nclass EchoAgent(BaseAgent):\n async def run_task(self, payload: Any, id: Any) -> Any:\n return payload\n\nasync def main():\n async with FameFabric.create() as fabric:\n address = await fabric.serve(EchoAgent())\n echo = Agent.remote_by_address(address)\n print(await echo.run_task(\"Hello, world!\", None))\n\nasyncio.run(main())\n```\n\nFor a gentle, runnable tour\u2014from single\u2011process to distributed orchestration\u2014use the **Examples** repo: [https://github.com/naylence/naylence-examples-python](https://github.com/naylence/naylence-examples-python).\n\n---\n\n## Core concepts\n\n**Agents & tasks**\n\n* Implement `run_task(payload, id)` for simple one\u2011shot work, or override `start_task(...)`/`get_task_status(...)` for background jobs.\n* `Message.parts` carries either text (`TextPart`) or structured data (`DataPart`).\n* Long\u2011running flows stream `TaskStatusUpdateEvent` and `TaskArtifactUpdateEvent` until terminal (`COMPLETED`/`FAILED`/`CANCELED`).\n\n**Remote proxies**\n\n* `Agent.remote_by_address(\"echo@fame.fabric\")` to call a known address.\n* `Agent.remote_by_capabilities([\"agent\"])` to call by capability (fabric does resolution).\n\n**Streaming & cancel**\n\n* `subscribe_to_task_updates(...)` yields status/artifacts live.\n* `cancel_task(...)` requests cooperative cancellation when supported by the agent.\n\n**RPC operations**\n\n* A2A JSON\u2011RPC methods (`tasks/send`, `.../get`, `.../cancel`, etc.) are provided for task lifecycle.\n* Custom functions can be exposed via the RPC mixin in the underlying fabric (e.g., streaming operations).\n\n**FastAPI router**\n\n* Use `create_agent_router(agent)` to expose a JSON\u2011RPC endpoint (default: `/fame/v1/jsonrpc`) and `GET /agent.json` to return an `AgentCard`.\n\n---\n\n## Choosing an agent base class\n\n* **`BaseAgent`** \u2014 great for synchronous/short tasks; the default fallback packages your return value into a `Task(COMPLETED)`.\n* **`BackgroundTaskAgent`** \u2014 best for long\u2011running/streaming work. You implement `run_background_task(...)`; the base manages queues, TTLs, and end\u2011of\u2011stream.\n\nBoth base classes include sensible defaults (poll\u2011based streaming, simple auth pass\u2011through). You can override any part of the lifecycle.\n\n---\n\n## Development workflow\n\n* Add your agents in a project with the SDK.\n* Use `FameFabric.create()` in tests or local scripts to host agents in\u2011process.\n* For distributed setups, operate a sentinel/fabric with **naylence\u2011runtime** (or your infra) and connect agents remotely.\n* Use the **Examples** repo ([https://github.com/naylence/naylence-examples-python](https://github.com/naylence/naylence-examples-python)) to learn patterns like scatter\u2011gather, RPC streaming, cancellation, and security tiers.\n\n---\n\n## Security notes\n\nThe SDK runs on the Naylence fabric\u2019s security profiles:\n\n* **direct / gated / overlay** modes work out\u2011of\u2011the\u2011box with the open\u2011source stack.\n* **strict\u2011overlay** (sealed overlay encryption + SPIFFE/X.509 identities) is available **only** with the **`naylence\u2011advanced\u2011security`** package.\n\nSee repo links below for the advanced add\u2011on and images that bundle it.\n\n---\n\n## Links\n\n* **Agent SDK (this repo):** [https://github.com/naylence/naylence-agent-sdk-python](https://github.com/naylence/naylence-agent-sdk-python)\n* **Examples (Python):** [https://github.com/naylence/naylence-examples-python](https://github.com/naylence/naylence-examples-python)\n* **Runtime (fabric & transports):** [https://github.com/naylence/naylence-runtime-python](https://github.com/naylence/naylence-runtime-python)\n* **Advanced Security add\u2011on:** [https://github.com/naylence/naylence-advanced-security-python](https://github.com/naylence/naylence-advanced-security-python)\n\nDocker images:\n\n* OSS: `naylence/agent-sdk-python`\n* Advanced: `naylence/agent-sdk-adv-python` (includes `naylence-advanced-security`; BSL-licensed add-on)\n\n---\n\n## License & support\n\n* **License:** Apache\u20112.0 (SDK). \n* **Issues:** please use the appropriate GitHub repo (SDK, Runtime, Examples, Advanced Security).\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Naylence Agent SDK",
"version": "0.1.27",
"project_urls": {
"Bug Tracker": "https://github.com/naylence/naylence-agent-sdk-python/issues",
"Documentation": "https://github.com/naylence/naylence-agent-sdk-python#readme",
"Homepage": "https://github.com/naylence/naylence-agent-sdk-python",
"Repository": "https://github.com/naylence/naylence-agent-sdk-python"
},
"split_keywords": [
"messaging",
" ai",
" agents",
" platform",
" naylence"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "06b45cff1b77b7bb1a07f309d9ce8e68a3fb6a122318b103e782b2c1e6145ef5",
"md5": "62379b38d7ff0882b84990a5777c6704",
"sha256": "2f6acb5aafa358f470fa4989747fd85fd2b29ed4556ab29bdb03af00f7dcc040"
},
"downloads": -1,
"filename": "naylence_agent_sdk-0.1.27-py3-none-any.whl",
"has_sig": false,
"md5_digest": "62379b38d7ff0882b84990a5777c6704",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 27363,
"upload_time": "2025-09-05T00:50:00",
"upload_time_iso_8601": "2025-09-05T00:50:00.059348Z",
"url": "https://files.pythonhosted.org/packages/06/b4/5cff1b77b7bb1a07f309d9ce8e68a3fb6a122318b103e782b2c1e6145ef5/naylence_agent_sdk-0.1.27-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "cacbc8c5f80b150951a747c62972816158b5b7e69493c88b03b674a0bad1d98e",
"md5": "97daea61208de8262fb011de1c09fcae",
"sha256": "7827e0a5606bcda4fd9bb7557b8dd55f000e9cf310ca0a06abac417f3cdd86fe"
},
"downloads": -1,
"filename": "naylence_agent_sdk-0.1.27.tar.gz",
"has_sig": false,
"md5_digest": "97daea61208de8262fb011de1c09fcae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 23835,
"upload_time": "2025-09-05T00:50:02",
"upload_time_iso_8601": "2025-09-05T00:50:02.908286Z",
"url": "https://files.pythonhosted.org/packages/ca/cb/c8c5f80b150951a747c62972816158b5b7e69493c88b03b674a0bad1d98e/naylence_agent_sdk-0.1.27.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-05 00:50:02",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "naylence",
"github_project": "naylence-agent-sdk-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "naylence-agent-sdk"
}
JSON
