From 433db4c9d3ab39461453ab473e69c23f2a75ec9f Mon Sep 17 00:00:00 2001
From: aitbc1 <aitbc1-agent@keisanki.net>
Date: Sun, 15 Mar 2026 12:09:16 +0000
Subject: [PATCH] docs: enhance README for aitbc-agent-sdk with usage examples
 and module overview

- Add quick start example showing Agent.create() and registration
- Document agent types (ComputeProvider, ComputeConsumer, SwarmCoordinator)
- List key modules and their purpose
- Provide clear installation instructions
- Improves package discoverability and developer experience
---
 packages/py/aitbc-agent-sdk/README.md | 59 +++++++++++++++++++++++----
 1 file changed, 51 insertions(+), 8 deletions(-)

diff --git a/packages/py/aitbc-agent-sdk/README.md b/packages/py/aitbc-agent-sdk/README.md
index 99fc7678..6b3ba744 100644
--- a/packages/py/aitbc-agent-sdk/README.md
+++ b/packages/py/aitbc-agent-sdk/README.md
@@ -1,8 +1,6 @@
-# aitbc-agent-sdk
+# AITBC Agent SDK
 
-Agent SDK for AITBC (AI Agent Compute Network).
-
-This package provides tools and abstractions for building AI agents that participate in the AITBC decentralized compute marketplace.
+The AITBC Agent SDK enables developers to create AI agents that can participate in the AITBC decentralized compute marketplace. Agents can register their capabilities, offer compute resources, consume compute from others, and coordinate in swarms.
 
 ## Installation
 
@@ -10,9 +8,54 @@ This package provides tools and abstractions for building AI agents that partici
 pip install -e .[dev]
 ```
 
-## Development
+## Quick Start
 
-Run tests:
-```bash
-pytest
+Here's a simple example to create and register an agent:
+
+```python
+import asyncio
+from aitbc_agent import Agent, AgentCapabilities
+
+# Define agent capabilities
+capabilities = {
+    "compute_type": "inference",
+    "gpu_memory": 8,  # GB
+    "supported_models": ["llama2", "mistral"],
+    "performance_score": 0.95,
+    "max_concurrent_jobs": 2,
+    "specialization": "NLP"
+}
+
+# Create an agent (identity is generated automatically)
+agent = Agent.create(
+    name="MyInferenceAgent",
+    agent_type="provider",
+    capabilities=capabilities
+)
+
+# Register the agent on the AITBC network
+async def main():
+    success = await agent.register()
+    if success:
+        print(f"Agent {agent.identity.id} registered with address {agent.identity.address}")
+
+asyncio.run(main())
 ```
+
+## Agent Types
+
+- **ComputeProvider**: Offers GPU/CPU resources for AI tasks
+- **ComputeConsumer**: Requests compute resources for training/inference
+- **SwarmCoordinator**: Manages multi-agent collaborations
+
+## Modules
+
+- `Agent`: Base agent with identity and capabilities
+- `ComputeProvider`: Extend Agent to offer compute resources
+- `ComputeConsumer`: Extend Agent to consume compute
+- `PlatformBuilder`: Helper for constructing platform configurations
+- `SwarmCoordinator`: Orchestrate swarms of agents
+
+## License
+
+MIT