@ -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:
Structured outputs are defined using JSON Schema format. Here's the basic structure:
```python
=== "Basic Schema"
tools = [
{
```python title="Basic Tool Schema"
"type": "function",
tools = [
"function": {
{
"name": "function_name",
"type": "function",
"description": "Description of what the function does",
"function": {
"parameters": {
"name": "function_name",
"type": "object",
"description": "Description of what the function does",
"properties": {
"parameters": {
# Define your parameters here
"type": "object",
},
"properties": {
"required": [
# Define your parameters here
# List required parameters
},
]
"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:
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]` |
## Implementation Steps
| `null` | Null values | `null` |
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:
```python ## :material-cog: Implementation Steps
from dotenv import load_dotenv
from swarms import Agent !!! tip "Quick Start Guide"
from swarms.utils.str_to_dict import str_to_dict Follow these steps to implement structured outputs in your agent:
# Load environment variables
### Step 1: Define Your Schema
load_dotenv()
# Define tools with structured output schema ```python
tools = [
tools = [
{
{
"type": "function",
"type": "function",
"function": {
"function": {
"name": "get_stock_price",
"name": "get_stock_price",
"description": "Retrieve the current stock price and related information",
"description": "Retrieve stock price information",
"parameters": {
"parameters": {
"type": "object",
"type": "object",
"properties": {
"properties": {
@ -114,72 +101,233 @@ tools = [
"type": "string",
"type": "string",
"description": "Stock ticker symbol"
"description": "Stock ticker symbol"
},
},
"include_history ": {
"include_volume ": {
"type": "boolean",
"type": "boolean",
"description": "Include historical data"
"description": "Include trading volume data"
},
"time": {
"type": "string",
"format": "date-time",
"description": "Time for stock data"
}
}
},
},
"required": ["ticker", "include_history", "time" ]
"required": ["ticker"]
}
}
}
}
}
}
]
]
```
### Step 2: Initialize the Agent
```
from swarms import Agent
# Initialize agent
agent = Agent(
agent = Agent(
agent_name="Financial-Analysis-Agent",
agent_name="Your-Agent-Name",
agent_description="Personal finance advisor agent",
agent_description="Agent description",
system_prompt="Your system prompt here",
system_prompt="Your system prompt",
max_loops=1,
tools_list_dictionary=tools
tools_list_dictionary=tools
)
)
```
### Step 3: Run the Agent
```python
response = agent.run("Your query here")
```
### Step 4: Parse the Output
# Run agent
```python
response = agent.run("What is the current stock price for AAPL?")
from swarms.utils.str_to_dict import str_to_dict
# Parse structured output
parsed_output = str_to_dict(response)
parsed_data = 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**
!!! success "Schema Design"
- Keep schemas as simple as possible while meeting your needs
- Use clear, descriptive parameter names
- **Keep it simple** : Design schemas that are as simple as possible while meeting your needs
- Include detailed descriptions for each parameter
- Specify all required parameters explicitly
- **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**
!!! info "Error Handling"
- Always validate the output format
- Implement proper error handling for parsing failures
- **Validate output** : Always validate the output format before processing
- Use try-except blocks when converting strings to dictionaries
- **Exception handling** : Implement proper error handling for parsing failures
- **Safety first** : Use try-except blocks when converting strings to dictionaries
3. **Performance**
!!! performance "Performance Tips"
- Minimize the number of required parameters
- Use appropriate data types for each parameter
- **Minimize requirements** : Keep the number of required parameters to a minimum
- Consider caching parsed results if used frequently
- **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**
### Invalid Output Format
- Ensure your schema matches the expected output
- Verify all required fields are present
- Check for proper JSON formatting
2. **Parsing Errors**
!!! failure "Problem"
- Use `str_to_dict()` for reliable string-to-dictionary conversion
The agent returns data in an unexpected format
- Validate input strings before parsing
- Handle potential parsing exceptions
!!! 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
Kye Gomez
1 week ago