@@ -173,28 +173,6 @@ asyncio.run(manual_example())
173173- Real-time streaming applications
174174- Background job processing
175175
176- ## 📋 Features
177-
178- ✅ ** Trace-based Architecture** - Industry standard observability patterns
179- ✅ ** Async/Sync Support** - Native ` asyncio ` support with sync fallbacks
180- ✅ ** Context Managers** - Pythonic resource management with ` async with `
181- ✅ ** Type Safety** - Full Pydantic validation and type hints
182- ✅ ** Hierarchical Events** - Agent → Tool/Memory/Retriever relationships
183- ✅ ** Multi-Agent Support** - Sub-agents and complex workflows
184- ✅ ** Auto-flushing** - Automatic event batching and sending
185- ✅ ** Error Handling** - Built-in error tracking and reporting
186- ✅ ** Rich Metadata** - Snake_case to camelCase conversion
187-
188- ## 🏗️ Architecture
189-
190- ### Core Concepts
191-
192- - ** Trace** : A complete conversation/session (the main execution context)
193- - ** Agent** : An AI agent operating within a trace
194- - ** Tool** : External service calls (APIs, databases, etc.)
195- - ** Memory** : Data storage and retrieval operations
196- - ** Retriever** : Information search and retrieval operations
197-
198176### Event Hierarchy
199177
200178```
@@ -209,19 +187,6 @@ Trace
209187 └── Retriever 1 → success/error
210188```
211189
212- ## 📦 Installation
213-
214- ### From PyPI (Recommended)
215- ``` bash
216- pip install voltagent
217- ```
218-
219- ### From Source
220- ``` bash
221- git clone < repository-url>
222- cd voltagent-python
223- pip install -e .
224- ```
225190
226191### Environment Variables
227192
@@ -996,30 +961,6 @@ async def error_handling_example():
996961asyncio.run(error_handling_example())
997962```
998963
999- ## 🏷️ Event Types
1000-
1001- ### Agent Events
1002-
1003- - ` agent:start ` - Agent begins processing
1004- - ` agent:success ` - Agent completes successfully
1005- - ` agent:error ` - Agent encounters an error
1006-
1007- ### Tool Events
1008-
1009- - ` tool:start ` - Tool call begins
1010- - ` tool:success ` - Tool call succeeds
1011- - ` tool:error ` - Tool call fails
1012-
1013- ### Memory Events
1014-
1015- - ` memory:write_start ` / ` memory:write_success ` / ` memory:write_error `
1016-
1017- ### Retriever Events
1018-
1019- - ` retriever:start ` - Retrieval begins
1020- - ` retriever:success ` - Retrieval succeeds
1021- - ` retriever:error ` - Retrieval fails
1022-
1023964## 💡 Best Practices
1024965
1025966### General Guidelines
@@ -1036,60 +977,6 @@ asyncio.run(error_handling_example())
103697710 . ** Use snake_case in Python** - the SDK automatically converts to camelCase for the API
103797811 . ** Call ` await sdk.shutdown() ` ** before your application exits to ensure all events are sent
1038979
1039- ### Context Manager Best Practices
1040-
1041- ** When to use:** Most standard workflows, simple error handling needs, cleaner code preferred
1042-
1043- - ✅ ** Always prefer context managers** (` async with ` ) for automatic resource cleanup
1044- - ✅ ** Rely on automatic error handling** - context managers handle exceptions gracefully
1045- - ✅ ** Nest context managers** for hierarchical workflows
1046- - ✅ ** Let automatic completion handle success states** when exiting contexts
1047-
1048- ``` python
1049- # Good: Clean context manager usage
1050- async with sdk.trace(agentId = " my-agent" ) as trace:
1051- async with trace.add_agent({" name" : " Worker" }) as agent:
1052- tool = await agent.add_tool({" name" : " api-call" })
1053- await tool.success(output = {" result" : " done" })
1054- # Agent and trace automatically complete
1055- ```
1056-
1057- ### Manual Usage Best Practices
1058-
1059- ** When to use:** Long-running processes, complex error handling, custom resource management
1060-
1061- - ✅ ** Always use try/except/finally blocks** for proper error handling
1062- - ✅ ** Manually complete all resources** (traces, agents) in correct order
1063- - ✅ ** Handle cascade failures** - if a sub-agent fails, handle parent agent failures
1064- - ✅ ** Use progress tracking** for long-running processes
1065- - ✅ ** Implement custom retry logic** when needed
1066- - ✅ ** Save checkpoints** for resumable operations
1067-
1068- ``` python
1069- # Good: Proper manual resource management
1070- trace = None
1071- agent = None
1072- try :
1073- trace = await sdk.create_trace(agentId = " long-process" )
1074- agent = await trace.add_agent({" name" : " Processor" })
1075-
1076- # Process with checkpoints
1077- for step in range (total_steps):
1078- await process_step(step)
1079- await trace.update(metadata = {" progress" : step/ total_steps})
1080-
1081- await agent.success(output = {" completed" : True })
1082- await trace.end(status = TraceStatus.COMPLETED )
1083-
1084- except Exception as e:
1085- if agent:
1086- await agent.error(status_message = f " Failed: { e} " )
1087- if trace:
1088- await trace.end(status = TraceStatus.ERROR )
1089- finally :
1090- await sdk.shutdown()
1091- ```
1092-
1093980### Error Handling Patterns
1094981
1095982** Context Manager Error Handling:**
@@ -1211,17 +1098,7 @@ voltagent-python/
12111098- [ VoltAgent Platform] ( https://voltagent.dev )
12121099- [ Console Dashboard] ( https://console.voltagent.dev )
12131100- [ Documentation] ( https://docs.voltagent.dev )
1214- - [ TypeScript SDK] ( ../sdk/ )
1215- - [ API Reference] ( https://docs.voltagent.dev/api )
12161101
12171102## 📄 License
12181103
12191104MIT License - see LICENSE file for details.
1220-
1221- ## 🆘 Support
1222-
1223- For support and questions:
1224- - 📧 Create an issue on GitHub
1225- - 💬 Join our Discord community
1226- - 📖 Check documentation at [ docs.voltagent.dev] ( https://docs.voltagent.dev )
1227- - 🌐 Visit [ voltagent.dev] ( https://voltagent.dev ) for more information
0 commit comments