kubiya_agent
resource allows you to create and manage AI agents in the Kubiya platform. Agents are intelligent assistants that can perform various tasks, integrate with external systems, and execute workflows.
Agents are the core building blocks of your Kubiya automation. They can be configured with specific tools, integrations, and access controls to match your organization’s needs.
Prerequisites
Before using this resource, ensure you have:- A Kubiya account with API access
- An API key (generated from Kubiya dashboard under Admin → Kubiya API Keys)
- At least one runner configured (or use “kubiya-hosted” for cloud execution)
Quick Start
Configuration Examples
Configure an agent with predefined tasks that users can execute:
Advanced Configurations
Agent with Inline Tools
Agent with Inline Tools
Create an agent with custom tools defined directly in the configuration:
Agent with Workflow Execution
Agent with Workflow Execution
Configure an agent that can execute complex, multi-step workflows:
Arguments Reference
Required Arguments
The name of the agent. Must be unique within your organization.
The runner to use for agent execution. Use “kubiya-hosted” for cloud execution or specify your own runner name.
A detailed description of the agent’s purpose and capabilities.
System instructions that define the agent’s behavior and capabilities. These instructions guide how the agent responds to user queries and executes tasks.
Optional Arguments
The LLM model to use for the agent. Available options:
gpt-4o
- GPT-4 Optimized (recommended)gpt-4
- GPT-4gpt-3.5-turbo
- GPT-3.5 Turboazure/gpt-4
- Azure OpenAI GPT-4
Docker image for the agent runtime environment. Use custom images for specialized functionality.
Enable debug mode for detailed logging and troubleshooting.
List of integration names the agent can access. Must match exactly with configured integrations in your Kubiya account.
List of user emails who can access the agent. If not specified, the agent is accessible to all organization members.
List of group names that can access the agent. Use for team-based access control.
List of source IDs for knowledge bases and workflows that the agent can utilize.
List of tool source URLs or IDs. These provide the agent with additional capabilities and tools.
List of secret names the agent can access for secure operations.
Map of environment variables available to the agent during execution.
List of predefined tasks that users can execute. Each task object contains:
Task identifier used for execution.
The prompt that will be executed when the task is triggered.
Human-readable description of what the task does.
List of reference links that provide additional context or documentation for the agent.
Attributes Reference
In addition to all arguments above, the following attributes are exported:The unique identifier of the agent.
The email of the user who created the agent.
The timestamp when the agent was created.
Import
Agents can be imported using their ID:Best Practices
Security
- Store sensitive information in secrets, not in environment variables
- Use specific access controls with users and groups
- Regularly audit agent permissions and access patterns
Performance
- Choose the appropriate model for your use case (balance cost vs capability)
- Use custom Docker images for specialized environments
- Enable debug mode only when troubleshooting
Maintenance
- Use descriptive names that indicate the agent’s purpose
- Include comprehensive instructions to ensure consistent behavior
- Store Terraform configurations in version control
- Test agents in non-production runners first
User Experience
- Provide clear conversation starters for common tasks
- Use groups for team-based access rather than individual users
- Include helpful links and documentation references
Compatibility
Requirements:
- Kubiya Terraform Provider version >= 1.0.0
- Terraform >= 1.0
- Some features may require specific Kubiya platform tier (Enterprise features)
Important Considerations:
- Custom Docker images must be accessible from the runner environment
- Integration names must match exactly with configured integrations in your Kubiya account
- Debug mode should not be used in production environments
Troubleshooting
Agent Not Responding
Agent Not Responding
- Check if the runner is active and accessible
- Verify that all required integrations are properly configured
- Enable debug mode to get detailed logs
- Ensure the agent has proper access permissions
Integration Access Issues
Integration Access Issues
- Verify integration names match exactly with your Kubiya account configuration
- Check that the agent’s groups/users have access to the integrations
- Ensure integrations are properly authenticated and active
Custom Docker Image Issues
Custom Docker Image Issues
- Ensure the image is accessible from the runner environment
- Check that required dependencies are installed in the image
- Verify environment variables are properly configured
- Test the image independently before using with the agent