From 764961c1a07e4c7534f2cd0fd00244e6b03d337a Mon Sep 17 00:00:00 2001 From: Kye Gomez Date: Thu, 29 May 2025 16:49:08 -0700 Subject: [PATCH] structured docs outputs --- docs/swarms/agents/structured_outputs.md | 418 +++++++++++++++-------- 1 file changed, 283 insertions(+), 135 deletions(-) diff --git a/docs/swarms/agents/structured_outputs.md b/docs/swarms/agents/structured_outputs.md index 23383091..7d1d89e5 100644 --- a/docs/swarms/agents/structured_outputs.md +++ b/docs/swarms/agents/structured_outputs.md @@ -1,112 +1,99 @@ -# Agentic Structured Outputs +# :material-code-json: Agentic Structured Outputs -Structured outputs help ensure that your agents return data in a consistent, predictable format that can be easily parsed and processed by your application. This is particularly useful when building complex applications that require standardized data handling. +!!! abstract "Overview" + Structured outputs help ensure that your agents return data in a consistent, predictable format that can be easily parsed and processed by your application. This is particularly useful when building complex applications that require standardized data handling. -## Schema Definition +## :material-file-document-outline: Schema Definition Structured outputs are defined using JSON Schema format. Here's the basic structure: -```python -tools = [ - { - "type": "function", - "function": { - "name": "function_name", - "description": "Description of what the function does", - "parameters": { - "type": "object", - "properties": { - # Define your parameters here - }, - "required": [ - # List required parameters - ] +=== "Basic Schema" + + ```python title="Basic Tool Schema" + tools = [ + { + "type": "function", + "function": { + "name": "function_name", + "description": "Description of what the function does", + "parameters": { + "type": "object", + "properties": { + # Define your parameters here + }, + "required": [ + # List required parameters + ] + } } } - } -] -``` + ] + ``` -### Parameter Types +=== "Advanced Schema" + + ```python title="Advanced Tool Schema with Multiple Parameters" + tools = [ + { + "type": "function", + "function": { + "name": "advanced_function", + "description": "Advanced function with multiple parameter types", + "parameters": { + "type": "object", + "properties": { + "text_param": { + "type": "string", + "description": "A text parameter" + }, + "number_param": { + "type": "number", + "description": "A numeric parameter" + }, + "boolean_param": { + "type": "boolean", + "description": "A boolean parameter" + }, + "array_param": { + "type": "array", + "items": {"type": "string"}, + "description": "An array of strings" + } + }, + "required": ["text_param", "number_param"] + } + } + } + ] + ``` + +### :material-format-list-bulleted-type: Parameter Types The following parameter types are supported: -- `string`: Text values -- `number`: Numeric values -- `boolean`: True/False values -- `object`: Nested objects -- `array`: Lists or arrays -- `null`: Null values - -## Implementation Steps - -1. **Define Your Schema** - ```python - tools = [ - { - "type": "function", - "function": { - "name": "get_stock_price", - "description": "Retrieve stock price information", - "parameters": { - "type": "object", - "properties": { - "ticker": { - "type": "string", - "description": "Stock ticker symbol" - }, - # Add more parameters as needed - }, - "required": ["ticker"] - } - } - } - ] - ``` - -2. **Initialize the Agent** - ```python - from swarms import Agent - - agent = Agent( - agent_name="Your-Agent-Name", - agent_description="Agent description", - system_prompt="Your system prompt", - tools_list_dictionary=tools - ) - ``` - -3. **Run the Agent** - ```python - response = agent.run("Your query here") - ``` - -4. **Parse the Output** - ```python - from swarms.utils.str_to_dict import str_to_dict - - parsed_output = str_to_dict(response) - ``` - -## Example Usage - -Here's a complete example using a financial agent: +| Type | Description | Example | +|------|-------------|---------| +| `string` | Text values | `"Hello World"` | +| `number` | Numeric values | `42`, `3.14` | +| `boolean` | True/False values | `true`, `false` | +| `object` | Nested objects | `{"key": "value"}` | +| `array` | Lists or arrays | `[1, 2, 3]` | +| `null` | Null values | `null` | -```python -from dotenv import load_dotenv -from swarms import Agent -from swarms.utils.str_to_dict import str_to_dict +## :material-cog: Implementation Steps + +!!! tip "Quick Start Guide" + Follow these steps to implement structured outputs in your agent: -# Load environment variables -load_dotenv() +### Step 1: Define Your Schema -# Define tools with structured output schema +```python tools = [ { "type": "function", "function": { "name": "get_stock_price", - "description": "Retrieve the current stock price and related information", + "description": "Retrieve stock price information", "parameters": { "type": "object", "properties": { @@ -114,72 +101,233 @@ tools = [ "type": "string", "description": "Stock ticker symbol" }, - "include_history": { + "include_volume": { "type": "boolean", - "description": "Include historical data" - }, - "time": { - "type": "string", - "format": "date-time", - "description": "Time for stock data" + "description": "Include trading volume data" } }, - "required": ["ticker", "include_history", "time"] + "required": ["ticker"] } } } ] +``` + +### Step 2: Initialize the Agent + +``` +from swarms import Agent -# Initialize agent agent = Agent( - agent_name="Financial-Analysis-Agent", - agent_description="Personal finance advisor agent", - system_prompt="Your system prompt here", - max_loops=1, + agent_name="Your-Agent-Name", + agent_description="Agent description", + system_prompt="Your system prompt", tools_list_dictionary=tools ) +``` + +### Step 3: Run the Agent + +```python +response = agent.run("Your query here") +``` + +### Step 4: Parse the Output -# Run agent -response = agent.run("What is the current stock price for AAPL?") +```python +from swarms.utils.str_to_dict import str_to_dict -# Parse structured output -parsed_data = str_to_dict(response) +parsed_output = str_to_dict(response) ``` -## Best Practices +## :material-code-braces: Example Usage + +!!! example "Complete Financial Agent Example" + Here's a comprehensive example using a financial analysis agent: + +=== "Python Implementation" + + ```python + from dotenv import load_dotenv + from swarms import Agent + from swarms.utils.str_to_dict import str_to_dict + + # Load environment variables + load_dotenv() + + # Define tools with structured output schema + tools = [ + { + "type": "function", + "function": { + "name": "get_stock_price", + "description": "Retrieve the current stock price and related information", + "parameters": { + "type": "object", + "properties": { + "ticker": { + "type": "string", + "description": "Stock ticker symbol (e.g., AAPL, GOOGL)" + }, + "include_history": { + "type": "boolean", + "description": "Include historical data in the response" + }, + "time": { + "type": "string", + "format": "date-time", + "description": "Specific time for stock data (ISO format)" + } + }, + "required": ["ticker", "include_history", "time"] + } + } + } + ] + + # Initialize agent + agent = Agent( + agent_name="Financial-Analysis-Agent", + agent_description="Personal finance advisor agent", + system_prompt="You are a helpful financial analysis assistant.", + max_loops=1, + tools_list_dictionary=tools + ) + + # Run agent + response = agent.run("What is the current stock price for AAPL?") + + # Parse structured output + parsed_data = str_to_dict(response) + print(f"Parsed response: {parsed_data}") + ``` + +=== "Expected Output" + + ```json + { + "function_calls": [ + { + "name": "get_stock_price", + "arguments": { + "ticker": "AAPL", + "include_history": true, + "time": "2024-01-15T10:30:00Z" + } + } + ] + } + ``` + +## :material-check-circle: Best Practices -1. **Schema Design** - - Keep schemas as simple as possible while meeting your needs - - Use clear, descriptive parameter names - - Include detailed descriptions for each parameter - - Specify all required parameters explicitly +!!! success "Schema Design" + + - **Keep it simple**: Design schemas that are as simple as possible while meeting your needs + + - **Clear naming**: Use descriptive parameter names that clearly indicate their purpose + + - **Detailed descriptions**: Include comprehensive descriptions for each parameter + + - **Required fields**: Explicitly specify all required parameters -2. **Error Handling** - - Always validate the output format - - Implement proper error handling for parsing failures - - Use try-except blocks when converting strings to dictionaries +!!! info "Error Handling" + + - **Validate output**: Always validate the output format before processing + + - **Exception handling**: Implement proper error handling for parsing failures + + - **Safety first**: Use try-except blocks when converting strings to dictionaries -3. **Performance** - - Minimize the number of required parameters - - Use appropriate data types for each parameter - - Consider caching parsed results if used frequently +!!! performance "Performance Tips" + + - **Minimize requirements**: Keep the number of required parameters to a minimum + + - **Appropriate types**: Use the most appropriate data types for each parameter + + - **Caching**: Consider caching parsed results if they're used frequently -## Troubleshooting +## :material-alert-circle: Troubleshooting -Common issues and solutions: +!!! warning "Common Issues" -1. **Invalid Output Format** - - Ensure your schema matches the expected output - - Verify all required fields are present - - Check for proper JSON formatting +### Invalid Output Format -2. **Parsing Errors** - - Use `str_to_dict()` for reliable string-to-dictionary conversion - - Validate input strings before parsing - - Handle potential parsing exceptions +!!! failure "Problem" + The agent returns data in an unexpected format + +!!! success "Solution" + + - Ensure your schema matches the expected output structure + + - Verify all required fields are present in the response + + - Check for proper JSON formatting in the output + +### Parsing Errors + +!!! failure "Problem" + Errors occur when trying to parse the agent's response + +!!! success "Solution" + + ```python + from swarms.utils.str_to_dict import str_to_dict + + try: + parsed_data = str_to_dict(response) + except Exception as e: + print(f"Parsing error: {e}") + # Handle the error appropriately + ``` + +### Missing Fields + +!!! failure "Problem" + Required fields are missing from the output + +!!! success "Solution" + - Verify all required fields are defined in the schema + - Check if the agent is properly configured with the tools + - Review the system prompt for clarity and completeness + +## :material-lightbulb: Advanced Features + +!!! note "Pro Tips" + + === "Nested Objects" + + ```python title="nested_schema.py" + "properties": { + "user_info": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "age": {"type": "number"}, + "preferences": { + "type": "array", + "items": {"type": "string"} + } + } + } + } + ``` + + === "Conditional Fields" + + ```python title="conditional_schema.py" + "properties": { + "data_type": { + "type": "string", + "enum": ["stock", "crypto", "forex"] + }, + "symbol": {"type": "string"}, + "exchange": { + "type": "string", + "description": "Required for crypto and forex" + } + } + ``` -3. **Missing Fields** - - Verify all required fields are defined in the schema - - Check if the agent is properly configured - - Review the system prompt for clarity +---