@ -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.
## Schema Definition
## :material-file-document-outline: Schema Definition
Structured outputs are defined using JSON Schema format. Here's the basic structure:
```python
=== "Basic Schema"
```python title="Basic Tool Schema"
tools = [
{
"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:
- `string` : Text values
- `number` : Numeric values
- `boolean` : True/False values
- `object` : Nested objects
- `array` : Lists or arrays
- `null` : Null values
| 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` |
## 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
tools = [
{
@ -55,7 +101,10 @@ The following parameter types are supported:
"type": "string",
"description": "Stock ticker symbol"
},
# Add more parameters as needed
"include_volume": {
"type": "boolean",
"description": "Include trading volume data"
}
},
"required": ["ticker"]
}
@ -64,8 +113,9 @@ The following parameter types are supported:
]
```
2. **Initialize the Agent**
```python
### Step 2: Initialize the Agent
```
from swarms import Agent
agent = Agent(
@ -76,21 +126,26 @@ The following parameter types are supported:
)
```
3. **Run the Agent**
### Step 3: Run the Agent
```python
response = agent.run("Your query here")
```
4. **Parse the Output**
### Step 4: Parse the Output
```python
from swarms.utils.str_to_dict import str_to_dict
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
from dotenv import load_dotenv
@ -112,16 +167,16 @@ tools = [
"properties": {
"ticker": {
"type": "string",
"description": "Stock ticker symbol"
"description": "Stock ticker symbol (e.g., AAPL, GOOGL) "
},
"include_history": {
"type": "boolean",
"description": "Include historical data"
"description": "Include historical data in the response "
},
"time": {
"type": "string",
"format": "date-time",
"description": "Time for stock data "
"description": "Specific time for stock data (ISO format) "
}
},
"required": ["ticker", "include_history", "time"]
@ -134,7 +189,7 @@ tools = [
agent = Agent(
agent_name="Financial-Analysis-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,
tools_list_dictionary=tools
)
@ -144,42 +199,135 @@ 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}")
```
## 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**
- 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
- **Clear naming** : Use descriptive parameter names that clearly indicate their purpose
2. **Error Handling**
- Always validate the output format
- Implement proper error handling for parsing failures
- Use try-except blocks when converting strings to dictionaries
- **Detailed descriptions** : Include comprehensive descriptions for each parameter
3. **Performance**
- Minimize the number of required parameters
- Use appropriate data types for each parameter
- Consider caching parsed results if used frequently
- **Required fields** : Explicitly specify all required parameters
## Troubleshooting
!!! info "Error Handling"
Common issues and solutions:
- **Validate output** : Always validate the output format before processing
1. **Invalid Output Format**
- Ensure your schema matches the expected output
- Verify all required fields are present
- Check for proper JSON formatting
- **Exception handling** : Implement proper error handling for parsing failures
2. **Parsing Errors**
- Use `str_to_dict()` for reliable string-to-dictionary conversion
- Validate input strings before parsing
- Handle potential parsing exceptions
- **Safety first** : Use try-except blocks when converting strings to dictionaries
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
- Check if the agent is properly configured
- Review the system prompt for clarity
- 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"
}
}
```
---
Kye Gomez
1 week ago