Agent
Use Agent to turn text into structured JSON with a large language model. Define the expected fields in outputSchema and choose whether to use one model or compare several models.
Overview
Type: agent
The configuration schema exposes OpenAI. Configure its credentials in the service deployment or supply the apiKey override. With multiple configured models, choose consensus voting, the first settled result, or all results. Agreement between models does not establish factual correctness.
Configuration
Put these fields in the step's config object. The examples below are configuration fragments; see Execute workflows for the full request format. Supply their referenced input variables in context.
Provider (legacy)
- Type: Enum
- Required: No
- Schema default:
openai. Supplyproviderexplicitly when not usingproviders. - Options:
openai - Description: LLM provider for single-provider mode (legacy configuration)
Model (legacy)
- Type: String
- Required: No
- Schema default:
gpt-4o-mini. Supplymodelexplicitly when not usingproviders. - Description: Model identifier for single-provider mode
- Examples:
gpt-4o-mini,gpt-4o,gpt-4.1-mini,gpt-4.1
Providers
- Type: Array of Objects
- Required: No
- Description: Model configurations for single-model or multi-model execution
Each provider object contains:
provider
- Type: Enum
- Required: Yes
- Options:
openai - Description: Provider name
model
- Type: String
- Required: Yes
- Description: Model identifier
weight
- Type: Number
- Required: No
- Default:
1 - Description: Weight for voting in consensus mode
temperature
- Type: Number
- Required: No
- Description: Override temperature for this specific provider
Code
Mode
- Type: Enum
- Required: No
- Options:
single,consensus,fastest,all - Description: Execution mode (auto-detected if not specified)
Modes:
single: Execute with one provider (default when 1 provider configured)consensus: Execute all providers and vote on results (default when multiple providers configured)fastest: Return the first settled result, including a failureall: Execute all providers and return all results
Voting
- Type: Object
- Required: No
- Description: Voting configuration for consensus mode
strategy
- Type: Enum
- Required: No
- Default:
majority - Options:
majority,weighted,unanimous - Description: Voting strategy
minAgreement
- Type: Number
- Required: No
- Default:
0.66 - Min:
0 - Max:
1 - Description: Minimum average agreement across the schema's top-level fields, from 0 to 1
Code
System prompt
- Type: String
- Required: No
- Templatable: Yes
- Multiline: Yes
- Description: System instructions that define the agent's role and behavior
Code
Input
- Type: String
- Required: Yes
- Templatable: Yes
- Multiline: Yes
- Description: User message or input to send to the agent
Code
Output schema
The converter supports object properties, required fields, string enums and lengths, numeric bounds, integers, booleans, arrays, and null. Other JSON Schema keywords are not enforced by this converter.
- Type: Object (JSON Schema)
- Required: Yes for execution. Although the configuration schema marks it optional, the current structured-output SDK requires a schema in every mode.
- Description: Expected output structure using JSON Schema format
type
- Type: String
- Required: Specify
objectexplicitly. The schema converter usestypeto build validation; the declared schema default is not applied automatically. - Description: Schema type
properties
- Type: Object
- Required: Yes
- Description: Object properties definition
required
- Type: Array of Strings
- Required: No
- Description: List of required property names
Code
Temperature
- Type: Number
- Required: No
- Schema default:
0.3; supply it explicitly if needed. The handler does not apply this default at runtime. - Min:
0 - Max:
2 - Description: Controls sampling randomness where supported by the selected model. Low values do not guarantee identical or correct outputs.
Max tokens
- Type: Number
- Required: No
- Schema default:
2000 - Min:
1 - Max:
16000 - Description: Declared token-limit setting. The current handler sends this as
maxTokens, but the installed SDK expectsmaxOutputTokens, so this setting does not currently enforce an output limit.
Timeout
- Type: Number
- Required: No
- Default:
60 - Min:
10 - Max:
300 - Description: Per-provider timeout in seconds. The step timeout defaults to 30 seconds. The workflow request timeout (
options.timeout) defaults to and is capped at 30 seconds. This setting does not extend either timeout.
API key
- Type: String
- Required: No
- Templatable: Yes
- Description: Override API key (uses global configuration if not provided)
Output
The Agent step returns different outputs based on the execution mode:
Single mode
Code
Consensus mode
Code
Fastest mode
Code
All mode
Code
Accessing the output
Code
Examples
Simple sentiment analysis
Code
Call analysis with system prompt
Code
Multi-model consensus
Code
Fastest response mode
Code
All providers mode
Code
Execution modes
Single mode
Executes with one configured model. If providers is present, uses its first entry; otherwise uses provider and model.
When to use:
- Simple classification tasks
- Cost-effective operations
- Trusted single model is sufficient
Consensus mode
Executes multiple models and votes on the results for each field. Agreement measures how consistently the configured models answered; it does not establish factual correctness.
When to use:
- Structured extraction requiring consistency checks
- Comparing outputs before human review or independent validation
Voting strategies:
majority: Each model gets one vote, winner is most common valueweighted: Models vote with their specified weightunanimous: All models must agree (100% agreement required)
Fastest mode
Executes all models in parallel and returns the first settled result. If the first result is a failure, the step fails even if another provider could succeed. Losing results are discarded, but the underlying provider requests are not cancelled.
When to use:
- Time-sensitive operations
- Comparing response latency across configured models
All mode
Executes all models and returns all results for comparison or ensemble processing.
When to use:
- A/B testing different models
- Comparative analysis
- Ensemble techniques
- Research and development
Error handling
Validation errors
Missing providers for multi-provider modes:
Code
Missing output schema for consensus:
Code
Consensus errors
Insufficient agreement:
Code
Unanimous voting failed:
Code
Execution errors
Timeout:
Code
General errors:
Code
Best practices
Schema design
- Define clear, specific output schemas
- Use enums for classification fields
- Include required fields for critical data
- Keep schemas simple and focused
- Validate schema structure before deployment
Prompt engineering
- Be specific and clear in your instructions
- Provide context in the system prompt
- Include examples when helpful
- Use consistent terminology
- Test prompts with different inputs
Temperature settings
For models that support temperature, start with a low value for extraction or classification and test higher values for content generation. Check the model's accepted range. The configuration schema's 0-2 range does not establish what every model accepts, and lower values do not guarantee correctness or identical results.
Multi-model strategy
- Use consensus to measure agreement, with independent validation for consequential decisions
- Set appropriate weights based on model capabilities
- Adjust
minAgreementbased on risk tolerance - Use
fastestmode for latency-sensitive operations - Use
allmode for testing and comparison
Cost optimization
- Compare the cost and quality of models supported by your provider
- Account for every configured provider call in multi-provider modes
- Do not rely on
maxTokensas an enforced cap in the current handler - Use single mode when consensus isn't needed
- Monitor token usage in outputs
Performance
- Set realistic timeout values
- Use
fastestwhen latency matters and a failure from the first settled request is acceptable. - Cache responses when appropriate
- Batch similar requests when possible
Security
- Never expose API keys in logs
- Use environment variables for credentials
- Validate and sanitize user inputs
- Review agent outputs before using in production
- Limit how often callers execute workflows to stay within provider rate limits.
Common use cases
- Content moderation: Classify user-generated content for policy violations
- Data extraction: Extract structured data from unstructured text
- Sentiment analysis: Analyze customer feedback and reviews
- Call transcript analysis: Evaluate customer service interactions
- Document classification: Categorize documents by type or topic
- Support triage: Classify urgency from customer requests
- Email parsing: Extract appointment details, contact info, action items
- Document review assistance: Extract clauses for a qualified reviewer
- Product categorization: Classify products from descriptions
- Lead scoring: Evaluate sales leads from communication
- Resume screening: Extract qualifications and match to requirements
- Survey analysis: Analyze open-ended survey responses
Troubleshooting
Schema validation failures
- Verify JSON Schema syntax is correct
- Ensure property types match expected data
- Check that required fields are specified
- Test schema with simple examples first
Inconsistent outputs
- Lower temperature where the model supports it, then test whether output consistency improves.
- Improve system prompt clarity
- Add examples to guide the model
- Use consensus mode to compare model agreement, and validate the result independently.
- Increase
minAgreementthreshold
Low agreement in consensus
- Review if models are interpreting instructions differently
- Simplify the output schema
- Make the system prompt more specific
- Check if input data is ambiguous
- Consider adjusting provider weights
High costs
- Use smaller models when appropriate
- Use a provider-side output limit where available; the current handler does not enforce
maxTokens - Optimize system prompts to be concise
- Switch from consensus to single mode when acceptable
- Monitor usage patterns and adjust