[Feedback] SDK/API usability issues blocking hackathon participants

[quotentiroler]

Summary

During the Autonomous Business Hackathon, we encountered multiple SDK usability issues that made the buyer/seller flow difficult to implement. Filing detailed issues in nevermined-io/payments-py but wanted to flag here for hackathon team awareness.

Key Pain Points

1. Discovery Flow Undocumented

No clear documentation on how a buyer discovers and calls agents:

• Had to reverse-engineer: get_all_plans() → get_plan_agents(plan_id) → get_service_token() → HTTP call
• Payments.create_task() exists but relationship to discovery unclear

2. Frequent 404 Errors

• /api/v1/protocol/all-plans intermittently returns 404 or empty results
• Agents registered and visible in dashboard don't appear in API discovery
• No error detail to distinguish auth vs not-found vs server issues

3. Registration Side Effects

• Running setup twice creates orphan agents (see [Bug] Cannot delete orphan agent due to circular plan dependency in dashboard #51)
• No idempotent registration or "get-or-create" pattern

4. SDK vs REST API Gaps

• Some operations work via curl but fail via SDK
• Method signatures don't always match REST API parameters

Impact

Multiple hackathon participants likely hit these issues. We saw many repos with non-functional buyers, suggesting discovery is a common blocker.

Detailed Issues

See nevermined-io/payments-py#158 for specific SDK issues and suggestions.

---

Related: #51 (orphan agent deletion bug)
Reporter: @quotentiroler