Skip to main content

​
Agent Structured Output

The MCPAgent supports structured output, allowing you to get strongly-typed Pydantic models instead of plain text responses. The agent becomes schema-aware and will intelligently retry to gather missing information until all required fields can be populated.

​
How it Works

When you provide an output_schema parameter, the agent:
  1. Understands requirements - The agent knows exactly what information it needs to collect
  2. Attempts structured output - At completion points, tries to format the result into your schema
  3. Intelligently retries - If required fields are missing, continues execution to gather the missing data
  4. Validates completeness - Only finishes when all required fields can be populated

​
Basic Example

import { z } from 'zod'
import { ChatOpenAI } from '@langchain/openai'
import { MCPAgent, MCPClient } from 'mcp-use'

// Define the schema using Zod
const WeatherInfo = z.object({
    city: z.string().describe('City name'),
    temperature: z.number().describe('Temperature in Celsius'),
    condition: z.string().describe('Weather condition'),
    humidity: z.number().describe('Humidity percentage')
})

// TypeScript type inferred from schema
type WeatherInfo = z.infer<typeof WeatherInfo>

async function main() {
    // Setup client and agent
    const client = new MCPClient({ mcpServers: {...} })
    const llm = new ChatOpenAI({ model: 'gpt-4o' })
    const agent = new MCPAgent({ llm, client })

    // Get structured output
    const weather = await agent.run(
        'Get the current weather in San Francisco',
        undefined, // maxSteps
        undefined, // manageConnector
        undefined, // externalHistory
        WeatherInfo // output schema
    )

    console.log(`Temperature in ${weather.city}: ${weather.temperature}°C`)
    console.log(`Condition: ${weather.condition}`)
    console.log(`Humidity: ${weather.humidity}%`)

    await client.closeAllSessions()
}

main().catch(console.error)

​
Key Benefits

  • Type Safety: Get Pydantic (Python) or Zod (TypeScript) models with full IDE support and validation
  • Intelligent Gathering: Agent knows what information is required and won’t stop until it has everything
  • Automatic Retry: Missing fields trigger continued execution automatically
  • Field Validation: Built-in validation for required fields, data types, and constraints
The agent will continue working until all required fields in your schema can be populated, ensuring you always get complete, structured data.