Provider Settings
The Provider tab controls which AI model your agent uses, how it connects, and how responses are formatted. These settings directly impact agent performance, cost, and capabilities.
Provider Selection
Choose the AI model provider that powers your agent.Available Providers
- OpenAI
- Claude (Anthropic)
- Gemini (Google)
OpenAI’s GPT models - Industry-leading language models with broad capabilities.
Best for:- Complex reasoning tasks
- Creative content generation
- Advanced problem-solving
- When you need GPT-4’s latest features
- ✅ GPT-5 is most capable model available
- ✅ Extensive training on diverse data
- ✅ Strong general intelligence
- ✅ Excellent for creative tasks
- ✅ Fast inference
- ⚠️ Requires OpenAI API key
- ⚠️ Costs based on token usage
- ⚠️ Rate limits apply to your API key
Provider Comparison
| Feature | OpenAI | Claude | Gemini | |---------|-----------|---------|---------|---------| | Setup | API Key | API Key | API Key | | Cost | Usage-based | Usage-based | Usage-based | | Best at | General intelligence | Long context | Multimodal | | Speed | Fast | Moderate | Fast | | Context | 128K | 200K | 32K-128K | | Learning Curve | Low | Low | Moderate |AI Model Selection
Once you’ve selected a provider, choose the specific model version.OpenAI Models
GPT-4 (gpt-4)
GPT-4 (gpt-4)
- Use for: Complex reasoning, creative writing, advanced problem-solving
- Context: 8K tokens (gpt-4) or 128K tokens (gpt-4-turbo)
- Speed: Slower than GPT-3.5
- Cost: Higher (more expensive per token)
- Complex customer service scenarios
- Content generation requiring creativity
- Multi-step reasoning tasks
- When accuracy is critical
- Legal document analysis
- Complex troubleshooting
- Strategic planning
- Creative content creation
GPT-4 Turbo (gpt-4-turbo)
GPT-4 Turbo (gpt-4-turbo)
- Use for: Most production workloads requiring GPT-4 quality
- Context: 128K tokens
- Speed: Faster than GPT-4
- Cost: Lower than GPT-4, higher than GPT-3.5
- Production deployments
- Long document processing
- High-volume workflows
- Cost-sensitive advanced tasks
GPT-3.5 Turbo (gpt-3.5-turbo)
GPT-3.5 Turbo (gpt-3.5-turbo)
- Use for: Simple, straightforward tasks at scale
- Context: 16K tokens
- Speed: Very fast
- Cost: Lowest
- Simple classification
- Basic customer service
- Data extraction
- High-volume, simple workflows
- Complex reasoning
- Creative tasks
- Nuanced decision-making
Claude Models
Claude Opus (claude-3-opus)
Claude Opus (claude-3-opus)
- Use for: Highest-accuracy, most complex tasks
- Context: 200K tokens
- Speed: Moderate
- Cost: Highest tier
- Long document analysis
- Complex instruction following
- High-stakes decisions
- Research and analysis
- Legal contract review
- Research synthesis
- Complex data analysis
- High-value customer interactions
Claude Sonnet (claude-3-sonnet)
Claude Sonnet (claude-3-sonnet)
- Use for: Production workloads needing good quality
- Context: 200K tokens
- Speed: Fast
- Cost: Mid-tier
- Most production use cases
- Customer service
- Content generation
- Data processing
Claude Haiku (claude-3-haiku)
Claude Haiku (claude-3-haiku)
- Use for: Simple, high-volume tasks
- Context: 200K tokens
- Speed: Very fast
- Cost: Lowest tier
- Simple classification
- Basic processing
- High-volume workflows
- Cost-sensitive applications
Gemini Models
Gemini Pro (gemini-pro)
Gemini Pro (gemini-pro)
- Use for: Complex tasks, multimodal applications
- Context: 32K tokens (expanding to 128K)
- Speed: Fast
- Cost: Competitive
- Multimodal tasks (text + images)
- General intelligence tasks
- Google ecosystem integration
- Cost-effective alternative to GPT-4
Gemini Pro Vision (gemini-pro-vision)
Gemini Pro Vision (gemini-pro-vision)
- Use for: Tasks requiring image understanding
- Context: Handles images + text
- Speed: Fast
- Cost: Similar to Gemini Pro
- Document processing with images
- Visual content analysis
- Multimodal customer service
- Screenshot analysis
Model Selection Guide
How to Choose a Model
-
How complex is the task?
- Simple → GPT-3.5, Claude Haiku, or Workforce
- Moderate → GPT-4 Turbo, Claude Sonnet
- Complex → GPT-4, Claude Opus
-
How much context is needed?
- Short (< 16K tokens) → Any model
- Long (16K-128K) → GPT-4 Turbo, Claude models
- Very long (> 128K) → Claude Opus/Sonnet
-
How critical is speed?
- Must be fast → GPT-3.5, Claude Haiku, Gemini
- Moderate → GPT-4 Turbo, Claude Sonnet
- Can be slower → GPT-4, Claude Opus
-
What’s your budget?
- Minimal → Workforce, GPT-3.5, Claude Haiku
- Moderate → GPT-4 Turbo, Claude Sonnet, Gemini
- Premium → GPT-4, Claude Opus
-
Do you need multimodal?
- Yes → Gemini Pro Vision, GPT-4 Vision
- No → Any text model
API Key Configuration
For OpenAI, Claude, and Gemini, you need to provide an API key from the respective provider. This section provides detailed, step-by-step instructions for obtaining and configuring API keys for each provider.Getting an OpenAI API Key
OpenAI provides access to GPT-4, GPT-4 Turbo, and GPT-3.5 Turbo models.Create an OpenAI Account
- Visit platform.openai.com/signup
- Click Sign up in the top right corner
- Choose your sign-up method:
- Continue with Google
- Continue with Microsoft Account
- Continue with Apple
- Or use your email address
- If using email:
- Enter your email address
- Create a strong password
- Click Continue
- Check your email for verification link
- Click the verification link to confirm your email
- Complete your profile:
- Enter your first and last name
- Optionally add your organization name
- Accept OpenAI’s Terms of Service and Privacy Policy
- Click Continue
- Verify your phone number:
- Select your country code
- Enter your phone number
- Click Send code
- Enter the 6-digit verification code sent via SMS
- Click Verify
Set Up Billing (Required for API Access)
- In the OpenAI dashboard, click your profile icon in the top right
- Select Manage account from the dropdown
- In the left sidebar, click Billing
- Click Add payment method
- Enter your payment information:
- Credit or debit card number
- Expiration date
- CVV security code
- Billing address (name, address, city, state, ZIP, country)
- Click Add payment method to save
- Set up usage limits (highly recommended):
- Click Usage limits in the Billing section
- Set a Hard limit (e.g., $50/month) - API will stop working when reached
- Set a Soft limit (e.g., $40/month) - You’ll receive an email notification
- Click Save
Create Your API Key
- From the main dashboard, click API keys in the left sidebar
- Or navigate directly to platform.openai.com/api-keys
- Click the + Create new secret key button
- In the popup dialog:
- Name: Give your key a descriptive name (e.g., “QuivaWorks Production” or “QuivaWorks Development”)
- Project: Select “Default project” (or create a new project if you want to organize by use case)
- Permissions: Leave as “All” for full access, or select “Restricted” if you want to limit specific endpoints
- Click Create secret key
- CRITICAL: Copy your API key immediately
- The key will look like:
sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx - Click the Copy button or manually select and copy the entire key
- Store it securely in a password manager or secure notes
- This is the ONLY time you’ll see this key - it cannot be retrieved later
- The key will look like:
- Click Done once you’ve saved the key

Add Key to QuivaWorks
- In quiva.ai, open your agent configuration
- Click the Provider tab
- Select OpenAI from the Provider dropdown
- Choose your desired model (GPT-4, GPT-4 Turbo, or GPT-3.5 Turbo)
- In the API Key field:
- Paste your OpenAI API key
- The field will show
sk-proj-xxxxx...(masked for security)
- Click outside the field or press Enter to save
- The key is now encrypted and securely stored
- Test your configuration by running a test query
Monitor Your Usage
- Visit platform.openai.com/usage
- View your daily and monthly usage
- Check costs by model type
- Review your current spend against limits
- Set up email notifications for usage alerts
- Check usage weekly, especially when first deploying
- Look for unexpected spikes that might indicate issues
- Understand which agents/models cost the most
- Adjust limits as needed based on actual usage
Troubleshooting OpenAI API Keys
Troubleshooting OpenAI API Keys
- Verify you copied the entire key including
sk-proj-prefix - Ensure no extra spaces at the beginning or end
- Check the key hasn’t been deleted in OpenAI dashboard
- Confirm billing is set up (API won’t work without payment method)
- You’ve hit your usage limit
- Add more credits or increase your usage limit
- Check your billing page for current balance
- You’re making too many requests too quickly
- Implement rate limiting in your application
- Consider upgrading to a higher tier
- Space out your API calls
- Some accounts require organization membership
- Ask your organization admin to add you
- Or create your own organization
Getting an Anthropic API Key (Claude)
Anthropic provides access to Claude 3 models: Opus, Sonnet, and Haiku.Create an Anthropic Account
- Visit console.anthropic.com
- Click Sign Up in the top right corner
- Enter your email address
- Create a strong password
- Click Continue
- Check your email for a verification message from Anthropic
- Click the Verify Email link in the email
- You’ll be redirected back to the Anthropic Console
- Complete your profile:
- Enter your full name
- Optionally add company/organization name
- Select your use case from the dropdown:
- Research
- Education
- Personal/Hobby
- Business/Production
- Accept Anthropic’s Terms of Service and Privacy Policy
- Click Complete Setup
Set Up Billing
- In the Anthropic Console, click Billing in the left sidebar
- Or navigate to console.anthropic.com/settings/billing
- Click Add payment method
- Enter your payment information:
- Card number
- Expiration date (MM/YY)
- CVC security code
- Cardholder name
- Billing address (street, city, state/province, postal code, country)
- Click Add card
- Set budget limits (recommended):
- Click Usage limits tab
- Set Monthly budget (e.g., $100)
- Set Email notification threshold (e.g., 80% of budget)
- Click Save limits
- Verify your payment method is active:
- You should see your card listed with last 4 digits
- Status should show “Active”
Create Your API Key
- In the left sidebar, click API Keys
- Or navigate to console.anthropic.com/settings/keys
- Click Create Key button
- In the dialog that appears:
- Name: Enter a descriptive name for your key
- Examples: “QuivaWorks Production”, “Customer Service Agent”, “Development Testing”
- Workspace: Leave as default (or select specific workspace if you have multiple)
- Name: Enter a descriptive name for your key
- Click Create Key
- CRITICAL: Copy your API key immediately
- The key will look like:
sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx - Click the Copy to clipboard icon
- Or manually select and copy the entire key
- Store it securely - this is the only time you’ll see it
- The key will look like:
- Check the confirmation box: “I have saved this key somewhere safe”
- Click Done

Add Key to QuivaWorks
- In quiva.ai, open your agent configuration
- Navigate to the Provider tab
- Select Claude from the Provider dropdown
- Choose your desired model:
- Claude 3 Opus - Most capable, highest cost
- Claude 3 Sonnet - Balanced performance and cost (recommended)
- Claude 3 Haiku - Fast and cost-effective
- In the API Key field:
- Paste your Anthropic API key (starts with
sk-ant-) - The field will mask the key for security
- Paste your Anthropic API key (starts with
- Press Enter or click outside the field to save
- QuivaWorks encrypts and securely stores your key
- Test your configuration:
- Click Test in the flow builder
- Run a sample query
- Verify the agent responds correctly
Monitor Your Usage
- Visit the Anthropic Console: console.anthropic.com
- Click Usage in the left sidebar
- View your usage dashboard:
- Current month costs - Total spend so far
- Daily usage graph - See usage trends
- Usage by model - Compare costs across Claude models
- Requests and tokens - Volume metrics
- Set up usage alerts:
- Go to Billing → Usage limits
- Configure email notifications
- Get alerts at 50%, 80%, and 100% of budget
- Review usage weekly
- Compare costs across different agents/models
- Look for unexpected spikes
- Optimize prompts and context to reduce token usage
- Consider switching to Sonnet or Haiku if Opus costs are high
Troubleshooting Anthropic API Keys
Troubleshooting Anthropic API Keys
- Confirm you copied the complete key including
sk-ant-prefix - Check for extra spaces at start or end of key
- Verify the key hasn’t been deleted in Anthropic Console
- Ensure billing is set up (required for API access)
- You’re sending requests too quickly
- Anthropic has rate limits per tier
- Wait a moment before retrying
- Consider spreading requests over time
- Check if you need to request a rate limit increase
- Your account balance is too low
- Add more credits to your account
- Check your billing page for current balance
- Verify your payment method is valid
- Verify you’re using the correct model name
- Check model availability for your account tier
- Some models require specific access
- Wait 1-2 minutes for key to propagate
- Clear your browser cache
- Try copying the key again
- Create a new key if issues persist
Getting a Google AI API Key (Gemini)
Google provides access to Gemini Pro and Gemini Pro Vision models.Create a Google Account (if needed)
- Visit accounts.google.com/signup
- Fill in the sign-up form:
- First and last name
- Username (will be your email: [email protected])
- Password (create a strong password)
- Confirm password
- Click Next
- Enter verification information:
- Phone number (for account recovery)
- Recovery email address (optional but recommended)
- Date of birth
- Gender
- Click Next
- Review and accept Google’s Terms of Service and Privacy Policy
- Click I agree
Access Google AI Studio
- Visit ai.google.dev
- Click Get started or Sign in in the top right
- Sign in with your Google account
- Click Get API Key or navigate to aistudio.google.com/app/apikey
- You’ll see the API Keys page in Google AI Studio
Create a Google Cloud Project
- On the API Keys page, you’ll be prompted to create or select a project
- If you don’t have a project:
- Click Create a new project in the dropdown
- Or click Create a new Google Cloud project
- You’ll be redirected to Google Cloud Console
- Create your project:
- Enter a Project name (e.g., “QuivaWorks Agents”, “AI Development”)
- Project ID will auto-generate (you can customize it)
- Location: Select your organization (or leave as “No organization”)
- Click Create
- Wait for the project to be created (takes 10-30 seconds)
- You’ll be redirected back to Google AI Studio
Enable Google AI API
- Once your project is created, you need to enable the API:
- In Google AI Studio, you’ll see a prompt to enable the API
- Click Enable API or Enable Google AI for [Your Project]
- This activates the Gemini API for your project
- Wait for the API to be enabled (usually instant)
Create Your API Key
- On the API Keys page in Google AI Studio, click Create API Key
- In the dialog:
- Select a Google Cloud project: Choose the project you just created
- If you only have one project, it will be auto-selected
- Click Create API key in existing project
- Your API key will be generated immediately
- The key will look like:
AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
- The key will look like:
- CRITICAL: Copy your API key immediately
- Click the Copy icon next to the key
- Or manually select and copy the entire key
- Store it securely in a password manager
- The key will remain visible in the API Keys list for future reference

Add Key to QuivaWorks
- In quiva.ai, open your agent configuration
- Go to the Provider tab
- Select Gemini from the Provider dropdown
- Choose your desired model:
- Gemini Pro - Best for text tasks
- Gemini Pro Vision - For multimodal (text + images)
- In the API Key field:
- Paste your Google AI API key (starts with
AIza) - The field will mask most of the key for security
- Paste your Google AI API key (starts with
- Press Enter or click outside the field to save
- The key is encrypted and stored securely
- Test your setup:
- Run a test query in the flow builder
- Verify the agent responds using Gemini
Set Up Billing (Optional)
- Visit console.cloud.google.com/billing
- Select your project from the dropdown at the top
- Click Link a billing account
- If you don’t have a billing account:
- Click Create billing account
- Enter your information:
- Account name
- Country
- Currency
- Add payment method (credit/debit card)
- Complete billing address
- Accept terms and click Submit and enable billing
- Link the billing account to your project
- Set up budget alerts (highly recommended):
- Go to Billing → Budgets & alerts
- Click Create budget
- Set budget amount (e.g., $50/month)
- Configure alert thresholds (50%, 90%, 100%)
- Add email recipients for alerts
- Click Finish
Monitor Your Usage
- Visit Google Cloud Console: console.cloud.google.com
- Select your project from the dropdown
- Navigate to APIs & Services → Dashboard
- Find Generative Language API in the list
- Click on it to view:
- Requests - Number of API calls
- Quota usage - Percentage of free tier used
- Errors - Any failed requests
- For detailed usage:
- Go to Billing → Reports
- Filter by service: “Generative Language API”
- View costs over time (if billing enabled)
- Check weekly to understand usage patterns
- Monitor quota usage to avoid hitting limits
- Set up billing alerts before hitting free tier limits
- Optimize prompts to reduce token usage
Troubleshooting Google AI API Keys
Troubleshooting Google AI API Keys
- Confirm you copied the complete key starting with
AIza - Remove any spaces at the start or end
- Verify the key hasn’t been deleted or restricted
- Check that the API is enabled for your project
- Ensure the project exists in Google Cloud Console
- Verify the API key is associated with the correct project
- Check that you have permission to access the project
- Go to Google Cloud Console
- Navigate to APIs & Services → Library
- Search for “Generative Language API”
- Click on it and click Enable
- Wait a few minutes for changes to propagate
- You’ve hit your free tier or quota limits
- Wait for the quota to reset (usually daily)
- Enable billing to increase limits
- Or request a quota increase
- Check that your Google account has permission to use the API
- Verify the API key has not been restricted
- Ensure billing is set up if required
- API enablement can take a few minutes
- Wait 5-10 minutes after creating key
- Try creating a new key
- Check Google Cloud Console for service status
Adding Your API Key to QuivaWorks
Once you have an API key from any provider, follow these steps to add it to QuivaWorks:Open Agent Configuration
- Navigate to Hub in the left sidebar
- Open the flow containing your agent
- Click on your agent step to open configuration
- Select the Provider tab
Select Provider and Model
- Choose your provider from the Provider dropdown:
- OpenAI
- Claude (Anthropic)
- Gemini (Google)
- Select your desired Model from the model dropdown
- The API Key field will appear below
Enter Your API Key
- Click in the API Key field
- Paste your API key:
- OpenAI: Starts with
sk-proj- - Claude: Starts with
sk-ant- - Gemini: Starts with
AIza
- OpenAI: Starts with
- The field will automatically mask the key for security
- You’ll see something like:
sk-proj-xxxxxxxxxxxx...
- You’ll see something like:
- Press Enter or click outside the field
- The key is now saved and encrypted
Test Your Configuration
- Click the Save button to save your agent configuration
- Click Test in the top right of the flow builder
- Enter a test prompt in the trigger body
- Click Run Test
- Verify the agent responds successfully using your chosen model
- If you see an error, check the troubleshooting section for your provider
Deploy
- Click Deploy in the top right
- Your agent is now live and will use your configured API key
- Monitor usage on the provider’s dashboard
Managing Multiple Keys
You can use different API keys for different agents: Strategy 1: Shared Key- Use one key across all agents
- Simpler management
- All agents share rate limits
- Combined billing
- Different key for each agent or use case
- Isolated rate limits
- Easier cost tracking
- More granular control
- Development key for testing
- Production key for live agents
- Prevents test agents from consuming production quota
Output Schema
Define the exact structure your agent must return. When configured, the agent will automatically validate its output and retry if it doesn’t match.What is an Output Schema?
An output schema is a JSON Schema definition that specifies:- Required fields
- Field types (string, number, boolean, object, array)
- Field descriptions (which guide the agent)
- Validation rules
When to Use Output Schemas
- Use Output Schema
- Skip Output Schema
- Structured data extraction
- Integration with other systems
- Consistent field names and types
- Automated processing of results
- Validation of agent responses
- Lead qualification (return structured lead data)
- Invoice processing (extract specific fields)
- Data entry (populate database fields)
- API responses (return JSON for webhooks)
- Multi-step flows (pass structured data between steps)
Defining an Output Schema
Use natural language JSON Schema format: Simple Example:Schema Features
Field Types
Field Types
Optional Fields
Optional Fields
Enums / Allowed Values
Enums / Allowed Values
Nested Objects
Nested Objects
Arrays
Arrays
Field Descriptions as Instructions
Field Descriptions as Instructions
Auto-Correction and Validation
When an output schema is defined:- Agent generates response based on your instructions
- Automatic validation checks if response matches schema
- If invalid: Agent automatically retries with corrections
- If valid: Response is returned to the flow
- Max retries: 3 attempts before marking as error
Output Schema Examples
Lead Qualification
Lead Qualification
Invoice Processing
Invoice Processing
Customer Service Triage
Customer Service Triage
Content Analysis
Content Analysis
Best Practices
Choose the right model for the task
Choose the right model for the task
- Simple classification → GPT-3.5, Claude Haiku, Workforce
- Standard workflows → GPT-4 Turbo, Claude Sonnet, Gemini
- Complex reasoning → GPT-4, Claude Opus
Start with Workforce, upgrade when needed
Start with Workforce, upgrade when needed
- Initial development and testing
- Simple to moderate complexity tasks
- Cost-conscious production workloads
- You need specific provider features
- Task complexity exceeds Workforce capability
- You’ve exhausted included usage
- Performance requirements demand it
Test models before committing
Test models before committing
- Try 5-10 test cases with each
- Compare accuracy, speed, and cost
- Consider edge cases
- Calculate projected monthly costs
- Choose based on data, not assumptions
Use output schemas for structured data
Use output schemas for structured data
- Extracting specific fields from documents
- Integrating with other systems
- Populating databases
- Passing data between flow steps
- Building APIs
- Generating natural language responses
- Creating conversational experiences
- Writing creative content
- Providing human-readable explanations
Write descriptive schema fields
Write descriptive schema fields
Secure your API keys
Secure your API keys
- Never commit keys to repositories
- Use separate keys for dev/prod
- Rotate keys periodically (every 90 days)
- Set spending limits on provider platforms
- Monitor usage for anomalies
- Revoke compromised keys immediately
- Use read-only keys when possible
Monitor costs and usage
Monitor costs and usage
- Tokens per request
- Requests per day
- Cost per agent
- Total monthly spend
- Switch to cheaper models for simple tasks
- Reduce token limits if possible
- Use Smart Context to minimize memory
- Batch similar requests when appropriate
Troubleshooting
API key not working
API key not working
- Is the key copied correctly (no extra spaces)?
- Is the key active on provider platform?
- Have you exceeded rate limits?
- Is billing set up on provider account?
- Is the key for the correct provider?
- Generate a new key
- Check provider dashboard for issues
- Ensure billing is configured
- Wait a few minutes and retry
Output doesn't match schema
Output doesn't match schema
- Schema is too complex or ambiguous
- Field descriptions aren’t clear enough
- Required data isn’t in the input
- Agent instructions conflict with schema
- Simplify the schema
- Add clearer field descriptions
- Make optional fields nullable
- Update agent instructions to mention schema fields
- Test with various inputs
Agent responses are inconsistent
Agent responses are inconsistent
- Model temperature too high (if configurable)
- Instructions too vague
- Not enough context provided
- No output schema to enforce structure
- Add output schema for structured tasks
- Make instructions more specific
- Include examples in instructions
- Provide more context in prompts
- Consider using a more capable model
Costs higher than expected
Costs higher than expected
- Are you using the most expensive model?
- Are token limits set too high?
- Is Smart Context disabled?
- Are you making unnecessary API calls?
- Switch to Workforce or cheaper models
- Reduce token limits
- Enable Smart Context
- Cache common responses
- Batch requests when possible
- Use output schemas to reduce retries