Python Agent SDK

The Python Agent package lets you build Paranet actors in pure Python. While it generates Paraflow code under the hood, it is designed specifically for Task Execution and External Integration rather than complex workflow orchestration.

When to use Python Actors

Python actors are the right choice when you need to:

• Interface with Hardware/Sim: Connect to NVIDIA Omniverse Isaac Sim, ROS, or specialized hardware drivers.
• Heavy Lift Computation: Run ML models or manipulate large data arrays that would be cumbersome in a DSL.
• Rapid Prototyping: Deploy a new skill quickly using familiar syntax.

Important Architectural Considerations

1. Logic vs. Execution

In the Paranet architecture, Rules define logic and Tasks define execution. The Python SDK currently focuses on Tasks. If your agent requires complex, persistent sub-goals or long-running durable state, it is recommended to write the "Orchestrator" in Paraflow and call your Python code as a "Skill Provider."

2. Data Persistence & The Ledger

By default, data passed through Skill Requests is recorded in the Paranet Ledger.

Performance Note: For data-heavy applications (GB-scale), passing raw data through skill requests can create a storage bottleneck. Consider using a custom data store (e.g., PostgreSQL or a shared file system) and passing a reference/URI in your Python skill request instead of the full payload.

3. Async & Blocking

Python actors run in a managed runtime. To avoid performance degradation in federated nodes, ensure you are not running long-blocking synchronous calls that could starve the actor's ability to respond to heartbeats or sync requests.

Installation

pip install paranet_agent

When using this in Isaac Sim, remember that you need to install it within the Python environment bundled with Isaac Sim.

Usage

Once registered, every Python actor is treated exactly like any Paraflow actor:
it advertises skills, receives PnCP requests, benefits from Negative‑Trust‑Security (NTS) certificates that are issued automatically, and can be observed, audited, and orchestrated by any other node that is affiliated with yours.

Implementing an actor with the Python Agent package involves creating a class that defines the actor's behavior and the data types used by that actor (e.g. input/output types). The types, actor class and actor class methods are annotated with Python decorators to declare how they map to Paranet concepts like actor, skill request, etc.

Once you've implemented your actors, you need to implement these steps in order

1. register the actors
2. start the agent runtime
3. deploy the actors

Learning More

API	Purpose	Where to Learn More
Decorators	Define an an actor's types, skills and requests	Decorators
Conversations	Managing the conversations of long-running skills	Conversation Class
Actor	Making Paranet requests	Actor Class
Registration	Making Paranet requests	Registration
Agent Runtime	Making Paranet requests	Connector
Deployment	Making Paranet requests	Deployment

---