Connect an entity (Python)

Same flow as the TypeScript guide, but with the platools Python package.

The goal

A Python asyncio service that connects to Platos and serves tool calls. Same architecture as the TS version; pick whichever runtime your stack already runs.

Steps

1. Register the entity in Platos.

   Sidebar -> Entities -> "New entity". Copy the serviceSecret shown once.

2. Install.

   pip install platools
   

   Python 3.10+ required.

3. Connect.

   import asyncio
   import os
   from platools import connect
   
   async def main():
       conn = connect(
           url=os.environ.get("PLATOS_URL", "wss://platos.example.com/connections"),
           service_secret=os.environ["PLATOS_SERVICE_SECRET"],
       )
   
       @conn.tool(
           "send_email",
           input_schema={
               "type": "object",
               "properties": {
                   "to": {"type": "string", "format": "email"},
                   "body": {"type": "string"},
               },
               "required": ["to", "body"],
           },
       )
       async def send_email(args, ctx):
           # ctx.user_token is X-Platos-User-Token, opaque to us.
           await mailer.send(args)
           return {"ok": True}
   
       await conn.start()
   
   asyncio.run(main())
   

4. Run.

   PLATOS_SERVICE_SECRET=ent_secret_... python -m my_entity
   

5. Wire to an agent.

   Same as the TS path: agent's Tools tab, toggle the entity's tools on.

Verify

• The entity's status flips to "online" in the dashboard.
• A turn that prompts "send an email" calls into your Python handler.
• Wire-test from /agent-entities/{id}/wire-test.

HMAC nonce signing

The Python SDK signs {ts}.{nonce}.{body} with the service secret and keeps an LRU of recent nonces (100k, matching the TS SDK). Replays within the window are rejected. You do not call this directly; the SDK wraps it.

Asyncio integration

The SDK is asyncio-native. To run alongside an existing event loop (FastAPI, aiohttp), await conn.start() inside a long-lived task; do not block the loop.

Next steps

• Connect an entity (TypeScript) for the Node variant.
• Consume Platos via MCP.