diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 50921aa0..a4140bc0 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -260,7 +260,8 @@ nav: - Twitter: "swarms_tools/twitter.md" - Swarms Cloud API: # - Overview: "swarms_cloud/main.md" - - Overview: "swarms_cloud/vision.md" + # - Overview: "swarms_cloud/vision.md" + - Overview: "swarms_cloud/launch.md" - Deploying Swarms on Google Cloud Run: "swarms_cloud/cloud_run.md" # - Swarms Cloud CLI: "swarms_cloud/cli.md" - Swarm APIs: diff --git a/docs/swarms_cloud/launch.md b/docs/swarms_cloud/launch.md new file mode 100644 index 00000000..2d53e47f --- /dev/null +++ b/docs/swarms_cloud/launch.md @@ -0,0 +1,369 @@ +# Swarms Cloud API Client Documentation + +## Overview +The Swarms Cloud API Client is a production-grade Python library for interacting with the Swarms Cloud Agent API. It provides a comprehensive interface for managing, executing, and monitoring cloud-based agents. + +## Installation +```bash +pip install swarms-cloud +``` + +## Quick Start +```python +from swarms_cloud import SwarmCloudAPI, AgentCreate + +# Initialize the client +client = SwarmCloudAPI( + base_url="https://swarmcloud-285321057562.us-central1.run.app", + api_key="your_api_key_here" +) + +# Create an agent +agent_data = AgentCreate( + name="TranslateAgent", + description="Translates text between languages", + code=""" + def main(request, store): + text = request.payload.get('text', '') + return f'Translated: {text}' + """, + requirements="requests==2.25.1", + envs="DEBUG=True" +) + +new_agent = client.create_agent(agent_data) +print(f"Created agent with ID: {new_agent.id}") +``` + +## Client Configuration + +### Constructor Parameters + +| Parameter | Type | Required | Default | Description | +|-----------|------|----------|----------|-------------| +| base_url | str | No | https://swarmcloud-285321057562.us-central1.run.app | The base URL of the SwarmCloud API | +| api_key | str | Yes | None | Your SwarmCloud API key | +| timeout | float | No | 10.0 | Request timeout in seconds | + +## Data Models + +### AgentCreate +Model for creating new agents. + +| Field | Type | Required | Default | Description | +|-------|------|----------|----------|-------------| +| name | str | Yes | - | Name of the agent | +| description | str | No | None | Description of the agent's purpose | +| code | str | Yes | - | Python code that defines the agent's behavior | +| requirements | str | No | None | Python package requirements (pip format) | +| envs | str | No | None | Environment variables for the agent | +| autoscaling | bool | No | False | Enable/disable concurrent execution scaling | + +### AgentUpdate +Model for updating existing agents. + +| Field | Type | Required | Default | Description | +|-------|------|----------|----------|-------------| +| name | str | No | None | Updated name of the agent | +| description | str | No | None | Updated description | +| code | str | No | None | Updated Python code | +| requirements | str | No | None | Updated package requirements | +| autoscaling | bool | No | None | Updated autoscaling setting | + +## API Methods + +### List Agents +Retrieve all available agents. + +```python +agents = client.list_agents() +for agent in agents: + print(f"Agent: {agent.name} (ID: {agent.id})") +``` + +**Returns**: List[AgentOut] + +### Create Agent +Create a new agent with the specified configuration. + +```python +agent_data = AgentCreate( + name="DataProcessor", + description="Processes incoming data streams", + code=""" + def main(request, store): + data = request.payload.get('data', []) + return {'processed': len(data)} + """, + requirements="pandas==1.4.0\nnumpy==1.21.0", + envs="PROCESSING_MODE=fast", + autoscaling=True +) + +new_agent = client.create_agent(agent_data) +``` + +**Returns**: AgentOut + +### Get Agent +Retrieve details of a specific agent. + +```python +agent = client.get_agent("agent_id_here") +print(f"Agent details: {agent}") +``` + +**Parameters**: +- agent_id (str): The unique identifier of the agent + +**Returns**: AgentOut + +### Update Agent +Update an existing agent's configuration. + +```python +update_data = AgentUpdate( + name="UpdatedProcessor", + description="Enhanced data processing capabilities", + code="def main(request, store):\n return {'status': 'updated'}" +) + +updated_agent = client.update_agent("agent_id_here", update_data) +``` + +**Parameters**: +- agent_id (str): The unique identifier of the agent +- update (AgentUpdate): The update data + +**Returns**: AgentOut + +### Execute Agent +Manually execute an agent with optional payload data. + +```python +# Execute with payload +result = client.execute_agent( + "agent_id_here", + payload={"text": "Hello, World!"} +) + +# Execute without payload +result = client.execute_agent("agent_id_here") +``` + +**Parameters**: +- agent_id (str): The unique identifier of the agent +- payload (Optional[Dict[str, Any]]): Execution payload data + +**Returns**: Dict[str, Any] + +### Get Agent History +Retrieve the execution history and logs for an agent. + +```python +history = client.get_agent_history("agent_id_here") +for execution in history.executions: + print(f"[{execution.timestamp}] {execution.log}") +``` + +**Parameters**: +- agent_id (str): The unique identifier of the agent + +**Returns**: AgentExecutionHistory + +### Batch Execute Agents +Execute multiple agents simultaneously with the same payload. + +```python +# Get list of agents +agents = client.list_agents() + +# Execute batch with payload +results = client.batch_execute_agents( + agents=agents[:3], # Execute first three agents + payload={"data": "test"} +) + +print(f"Batch execution results: {results}") +``` + +**Parameters**: +- agents (List[AgentOut]): List of agents to execute +- payload (Optional[Dict[str, Any]]): Shared execution payload + +**Returns**: List[Any] + +### Health Check +Check the API's health status. + +```python +status = client.health() +print(f"API Status: {status}") +``` + +**Returns**: Dict[str, Any] + +## Error Handling +The client uses exception handling to manage various error scenarios: + +```python +from swarms_cloud import SwarmCloudAPI +import httpx + +try: + client = SwarmCloudAPI(api_key="your_api_key_here") + agents = client.list_agents() +except httpx.HTTPError as http_err: + print(f"HTTP error occurred: {http_err}") +except Exception as err: + print(f"An unexpected error occurred: {err}") +finally: + client.close() +``` + +## Context Manager Support +The client can be used with Python's context manager: + +```python +with SwarmCloudAPI(api_key="your_api_key_here") as client: + status = client.health() + print(f"API Status: {status}") + # Client automatically closes after the with block +``` + +## Best Practices + +1. Always close the client when finished: +```python +client = SwarmCloudAPI(api_key="your_api_key_here") +try: + # Your code here +finally: + client.close() +``` + +2. Use context managers for automatic cleanup: +```python +with SwarmCloudAPI(api_key="your_api_key_here") as client: + # Your code here +``` + +3. Handle errors appropriately: +```python +try: + result = client.execute_agent("agent_id", payload={"data": "test"}) +except httpx.HTTPError as e: + logger.error(f"HTTP error: {e}") + # Handle error appropriately +``` + +4. Set appropriate timeouts for your use case: +```python +client = SwarmCloudAPI( + api_key="your_api_key_here", + timeout=30.0 # Longer timeout for complex operations +) +``` + +## Complete Example +Here's a complete example showcasing various features of the client: + +```python +from swarms_cloud import SwarmCloudAPI, AgentCreate, AgentUpdate +import httpx + +def main(): + with SwarmCloudAPI(api_key="your_api_key_here") as client: + # Create an agent + agent_data = AgentCreate( + name="DataAnalyzer", + description="Analyzes incoming data streams", + code=""" + def main(request, store): + data = request.payload.get('data', []) + return { + 'count': len(data), + 'summary': 'Data processed successfully' + } + """, + requirements="pandas==1.4.0", + autoscaling=True + ) + + try: + # Create the agent + new_agent = client.create_agent(agent_data) + print(f"Created agent: {new_agent.name} (ID: {new_agent.id})") + + # Execute the agent + result = client.execute_agent( + new_agent.id, + payload={"data": [1, 2, 3, 4, 5]} + ) + print(f"Execution result: {result}") + + # Update the agent + update_data = AgentUpdate( + description="Enhanced data analysis capabilities" + ) + updated_agent = client.update_agent(new_agent.id, update_data) + print(f"Updated agent: {updated_agent.name}") + + # Get execution history + history = client.get_agent_history(new_agent.id) + print(f"Execution history: {history}") + + except httpx.HTTPError as e: + print(f"HTTP error occurred: {e}") + except Exception as e: + print(f"Unexpected error: {e}") + +if __name__ == "__main__": + main() +``` + +## Logging +The client uses the `loguru` library for logging. You can configure the logging level and format: + +```python +from loguru import logger + +# Configure logging +logger.add("swarmcloud.log", rotation="500 MB") + +client = SwarmCloudAPI(api_key="your_api_key_here") +``` + +## Performance Considerations + +1. **Connection Reuse**: The client reuses HTTP connections by default, improving performance for multiple requests. + +2. **Timeout Configuration**: Set appropriate timeouts based on your use case: +```python +client = SwarmCloudAPI( + api_key="your_api_key_here", + timeout=5.0 # Shorter timeout for time-sensitive operations +) +``` + +3. **Batch Operations**: Use batch_execute_agents for multiple agent executions: +```python +results = client.batch_execute_agents( + agents=agents, + payload=shared_payload +) +``` + +## Rate Limiting +The client respects API rate limits but does not implement retry logic. Implement your own retry mechanism if needed: + +```python +from tenacity import retry, stop_after_attempt, wait_exponential + +@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=4, max=10)) +def execute_with_retry(client, agent_id, payload): + return client.execute_agent(agent_id, payload) +``` + +## Thread Safety +The client is not thread-safe by default. For concurrent usage, create separate client instances for each thread or implement appropriate synchronization mechanisms. \ No newline at end of file