Structured Output Example

What This Example Demonstrates

This example showcases structured output generation using AgentScope with Pydantic models. It demonstrates how to constrain AI model outputs to follow specific data structures and formats, ensuring consistent and parseable responses.

Key Features:

Structured Data Generation: Forces agent responses to conform to predefined schemas
Pydantic Integration: Uses Pydantic models to define output structure with validation
Type Safety: Ensures output data types match expected formats
Field Validation: Includes constraints like age limits (0-120) and enum choices
JSON Output: Generates clean, structured JSON responses

Example Models:

TableModel: Structured person information
- name: Person's name (string)
- age: Person's age (integer,0-120)
- intro: One-sentence introduction (string)
- honors: List of honors/achievements (array of strings)
ChoiceModel: Constrained choice selection
- choice: Must be one of "apple", "banana", or "orange"

Use Cases:

Data Extraction: Extract structured information from unstructured text
Form Generation: Generate consistent data for databases or APIs
Survey Responses: Ensure responses fit predefined categories
Content Classification: Categorize content into specific types

How to Run This Example

Set Environment Variable:

export DASHSCOPE_API_KEY="your_dashscope_api_key_here"

Run the script:
```
python main.py
```
Expected Output: The program will generate two structured responses like below:

Structured Output 1:
{
    "name": "Albert Einstein",
    "age": 76,
    "intro": 1,
    "honors": [
        "Nobel Prize in Physics (1921)",
        "Copley Medal (1925)"
    ]
}
Structured Output 2:
{
    "choice": "apple"
}

💡Note: The specific content will vary with each run since the agent generates different responses, but the JSON structure will always conform to the predefined Pydantic models (TableModel and ChoiceModel).

How It Works:

The agent receives a query along with a structured_model parameter
The agent generates a response that conforms to the Pydantic model schema
The structured data is returned in res.metadata as a validated JSON object
Pydantic ensures all field types and constraints are satisfied

Custom Pydantic Models

Create your own structured output models for specific use cases, for example:

from typing import Optional
from pydantic import BaseModel, Field, EmailStr

class BusinessModel(BaseModel):
    """Business information extraction model."""

    company_name: str = Field(description="Name of the company")
    industry: str = Field(description="Industry sector")
    founded_year: int = Field(description="Year founded", ge=1800, le=2024)
    headquarters: str = Field(description="Location of headquarters")
    employee_count: Optional[int] = Field(description="Number of employees", ge=1)
    email: Optional[EmailStr] = Field(description="Contact email address")
    website: Optional[str] = Field(description="Company website URL")

# Usage
query = Msg("user", "Tell me about Tesla Inc.", "user")
res = await agent(query, structured_model=BusinessModel)

Best Practices for Structured Output

Use Descriptive Field Names: Make field purposes clear
Add Field Descriptions: Help the agent understand what data to generate
Set Validation Constraints: Use Pydantic validators for data integrity
Choose Appropriate Types: Use specific types like EmailStr, datetime, etc.

3.6 KiB Raw Blame History