ai-mirow-projects
/
swarms
mirror of https://github.com/kyegomez/swarms
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

structured docs outputs

Browse Source
dependabot/pip/pypdf-5.6.0
Kye Gomez 2 weeks ago
parent b02b413aa7
commit 764961c1a0
1 changed files with 283 additions and 135 deletions
Show Stats Download Patch File Download Diff File

248
docs/swarms/agents/structured_outputs.md
Unescape View File

@ -1,12 +1,15 @@
# Agentic Structured Outputs # :material-code-json: Agentic Structured Outputs
!!! 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. 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: Structured outputs are defined using JSON Schema format. Here's the basic structure:
```python === "Basic Schema"
```python title="Basic Tool Schema"
tools = [ tools = [
{ {
"type": "function", "type": "function",
@ -27,20 +30,63 @@ tools = [
] ]
``` ```
### 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: The following parameter types are supported:
- `string`: Text values | Type | Description | Example |
- `number`: Numeric values |------|-------------|---------|
- `boolean`: True/False values | `string` | Text values | `"Hello World"` |
- `object`: Nested objects | `number` | Numeric values | `42`, `3.14` |
- `array`: Lists or arrays | `boolean` | True/False values | `true`, `false` |
- `null`: Null values | `object` | Nested objects | `{"key": "value"}` |
| `array` | Lists or arrays | `[1, 2, 3]` |
| `null` | Null values | `null` |
## Implementation Steps ## :material-cog: Implementation Steps
!!! tip "Quick Start Guide"
Follow these steps to implement structured outputs in your agent:
### Step 1: Define Your Schema
1. **Define Your Schema**
```python ```python
tools = [ tools = [
{ {
@ -55,7 +101,10 @@ The following parameter types are supported:
"type": "string", "type": "string",
"description": "Stock ticker symbol" "description": "Stock ticker symbol"
}, },
# Add more parameters as needed "include_volume": {
"type": "boolean",
"description": "Include trading volume data"
}
}, },
"required": ["ticker"] "required": ["ticker"]
} }
@ -64,8 +113,9 @@ The following parameter types are supported:
] ]
``` ```
2. **Initialize the Agent** ### Step 2: Initialize the Agent
```python
```
from swarms import Agent from swarms import Agent
agent = Agent( agent = Agent(
@ -76,21 +126,26 @@ The following parameter types are supported:
) )
``` ```
3. **Run the Agent** ### Step 3: Run the Agent
```python ```python
response = agent.run("Your query here") response = agent.run("Your query here")
``` ```
4. **Parse the Output** ### Step 4: Parse the Output
```python ```python
from swarms.utils.str_to_dict import str_to_dict from swarms.utils.str_to_dict import str_to_dict
parsed_output = str_to_dict(response) parsed_output = str_to_dict(response)
``` ```
## Example Usage ## :material-code-braces: Example Usage
Here's a complete example using a financial agent: !!! example "Complete Financial Agent Example"
Here's a comprehensive example using a financial analysis agent:
=== "Python Implementation"
```python ```python
from dotenv import load_dotenv from dotenv import load_dotenv
@ -112,16 +167,16 @@ tools = [
"properties": { "properties": {
"ticker": { "ticker": {
"type": "string", "type": "string",
"description": "Stock ticker symbol" "description": "Stock ticker symbol (e.g., AAPL, GOOGL)"
}, },
"include_history": { "include_history": {
"type": "boolean", "type": "boolean",
"description": "Include historical data" "description": "Include historical data in the response"
}, },
"time": { "time": {
"type": "string", "type": "string",
"format": "date-time", "format": "date-time",
"description": "Time for stock data" "description": "Specific time for stock data (ISO format)"
} }
}, },
"required": ["ticker", "include_history", "time"] "required": ["ticker", "include_history", "time"]
@ -134,7 +189,7 @@ tools = [
agent = Agent( agent = Agent(
agent_name="Financial-Analysis-Agent", agent_name="Financial-Analysis-Agent",
agent_description="Personal finance advisor agent", agent_description="Personal finance advisor agent",
system_prompt="Your system prompt here", system_prompt="You are a helpful financial analysis assistant.",
max_loops=1, max_loops=1,
tools_list_dictionary=tools tools_list_dictionary=tools
) )
@ -144,42 +199,135 @@ response = agent.run("What is the current stock price for AAPL?")
# Parse structured output # Parse structured output
parsed_data = str_to_dict(response) parsed_data = str_to_dict(response)
print(f"Parsed response: {parsed_data}")
``` ```
## Best Practices === "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
!!! success "Schema Design"
- **Keep it simple**: Design schemas that are as simple as possible while meeting your needs
1. **Schema Design** - **Clear naming**: Use descriptive parameter names that clearly indicate their purpose
- 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
2. **Error Handling** - **Detailed descriptions**: Include comprehensive descriptions for each parameter
- Always validate the output format
- Implement proper error handling for parsing failures
- Use try-except blocks when converting strings to dictionaries
3. **Performance** - **Required fields**: Explicitly specify all required parameters
- Minimize the number of required parameters
- Use appropriate data types for each parameter
- Consider caching parsed results if used frequently
## Troubleshooting !!! info "Error Handling"
Common issues and solutions: - **Validate output**: Always validate the output format before processing
1. **Invalid Output Format** - **Exception handling**: Implement proper error handling for parsing failures
- Ensure your schema matches the expected output
- Verify all required fields are present
- Check for proper JSON formatting
2. **Parsing Errors** - **Safety first**: Use try-except blocks when converting strings to dictionaries
- Use `str_to_dict()` for reliable string-to-dictionary conversion
- Validate input strings before parsing
- Handle potential parsing exceptions
3. **Missing Fields** !!! 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
## :material-alert-circle: Troubleshooting
!!! warning "Common Issues"
### Invalid Output Format
!!! 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 - Verify all required fields are defined in the schema
- Check if the agent is properly configured - Check if the agent is properly configured with the tools
- Review the system prompt for clarity - 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"
}
}
```
---

Write Preview
Loading…
Cancel
Save