review: use asyncio.wait_for (py3.9-safe) in integration test; document Tools/Secrets helpers in README

- asyncio.timeout is 3.11+, but the package targets python ^3.9; switch the frame
  collector to asyncio.wait_for so the live test runs on 3.9/3.10 too.
- README had no Tools/Secrets section (shipped in 5.12.0/5.12.1); add one with the
  registry create/list/duplicate/delete flow and the toolRefs note.

Author: abhishekmishragithub

README.md

@@ -17,6 +17,7 @@ pip install smallestai
 - [Quickstart](#quickstart-create-an-agent-and-call-it)
 - [Text-to-speech and speech-to-text](#text-to-speech-and-speech-to-text-models)
 - [Agent crew: your own LLM](#agent-crew-your-own-llm-in-the-middle)
+- [Reusable tools and secrets](#reusable-tools-and-secrets)
 - [CLI](#cli)
 - [Async client](#async-client)
 - [Environments](#environments)
@@ -113,6 +114,44 @@ A flat directory (`server.py` + `requirements.txt` at the root) is the simplest
 layout; a `src/` layout with a `pyproject.toml` also works (declare all runtime
 deps in the pyproject).
 
+## Reusable tools and secrets
+
+Build a tool once in your org's registry and reference it from any agent, and store
+API keys in a write-only secrets vault. `Tools` and `Secrets` wrap the `/tool` and
+`/secret` endpoints; both default to the `SMALLEST_API_KEY` environment variable.
+
+```python
+from smallestai.atoms.helpers import Tools, Secrets
+
+tools = Tools()  # or Tools(api_key="sk_...")
+created = tools.create(
+    {
+        "name": "get_order_status",
+        "description": "Look up an order status by id",
+        "type": "api_call",
+        "method": "GET",
+        "url": "https://api.example.com/orders",
+        "parameters": [
+            {"name": "order_id", "type": "text", "description": "order id", "required": True}
+        ],
+    }
+)
+tool_id = created["data"]["toolId"]
+tools.list()
+tools.duplicate(tool_id)
+tools.delete(tool_id)
+
+# secrets are write-only: the value is encrypted at rest and never returned
+secrets = Secrets()
+secrets.create(name="example_api_key", value="...")
+secrets.list()  # names and metadata only
+```
+
+Reference a saved tool from an agent with `toolRefs: ["<toolId>"]` on its single-prompt
+config. The tool must exist in the registry first, or the reference is dropped when the
+agent runs. Referencing a tool makes it available; the agent only calls it when its
+prompt says to.
+
 ## CLI
 
 ```sh

tests/custom/test_realtime_integration.py

@@ -60,18 +60,23 @@ async def run():
         got_audio = False
         async with websockets.connect(url, ssl=ssl.create_default_context(), open_timeout=20) as ws:
             # Collect frames for up to 15s: the session, then the agent's first spoken turn.
+            # asyncio.wait_for (not asyncio.timeout) so this runs on Python 3.9+.
+            loop = asyncio.get_event_loop()
+            deadline = loop.time() + 15
             try:
-                async with asyncio.timeout(15):
-                    while True:
-                        raw = await ws.recv()
-                        msg = json.loads(raw) if isinstance(raw, (str, bytes)) else {}
-                        t = msg.get("type", "")
-                        types.append(t)
-                        # audio arrives as base64 payloads on audio/response events
-                        if "audio" in t or msg.get("audio") or "audio" in msg.get("data", {}):
-                            got_audio = True
-                        if got_audio and len(types) >= 3:
-                            break
+                while True:
+                    remaining = deadline - loop.time()
+                    if remaining <= 0:
+                        break
+                    raw = await asyncio.wait_for(ws.recv(), timeout=remaining)
+                    msg = json.loads(raw) if isinstance(raw, (str, bytes)) else {}
+                    t = msg.get("type", "")
+                    types.append(t)
+                    # audio arrives as base64 payloads on audio/response events
+                    if "audio" in t or msg.get("audio") or "audio" in msg.get("data", {}):
+                        got_audio = True
+                    if got_audio and len(types) >= 3:
+                        break
             except (asyncio.TimeoutError, websockets.ConnectionClosed):
                 pass
         return types, got_audio