Skip to main content
Agents are AI-powered assistants that can use tools to solve open-ended tasks. Unlike workflows that follow predetermined paths, agents make intelligent decisions about which tools to use and when, adapting their approach based on the task at hand.

​
What Are Agents?

Think of agents as intelligent assistants that can orchestrate your workflows. You give them a goal, provide them with tools (integrations and workflows), and they figure out how to accomplish the task by deciding which tools to use and when. Key Characteristics:
  • Adaptive: Different approaches for different situations
  • Tool-driven: Use integrations and workflows as needed
  • Conversational: Interactive back-and-forth discussions
  • Context-aware: Consider your instructions and conversation history
Agents vs. Workflows: Agents are like quarterbacks who read the situation and call the right plays (workflows). Workflows are the plays themselves: reliable, repeatable sequences that execute consistently.

​
Creating Your First Agent

1

Add Tools

Select integrations and workflows your agent needs.Start Simple: Begin with 2-3 tools and add more as needed. Too many tools can overwhelm the agent and make behavior less predictable.
If you’re using workflows as tools, use descriptive names like “Get User Activity and Salesforce Status” instead of “User Workflow” so agents understand when to use them.
2

Write Instructions

Create clear, specific instructions:
You're a support operations assistant helping evaluate discount eligibility.

When given a Zendesk ticket number:
1. Retrieve ticket details and display them
2. Ask for confirmation before proceeding
3. Run "Get User Profile" workflow
4. Read discount criteria from Notion page [URL]
5. Evaluate eligibility with clear reasoning

Always respond professionally. If uncertain, ask for clarification.
Your agent is brilliant but new to your business. Be explicit about your preferences and expectations.
3

Test Thoroughly

Use the built-in chat interface to test:
  • Start Simple: Test basic functionality with straightforward requests
  • Find Edge Cases: Try unexpected inputs and ambiguous requests
  • Refine Instructions: When mistakes occur, ask the agent: “What could I add to your instructions to help you handle this correctly next time?”
  • Document Patterns: Keep notes on successful approaches

​
How Agents Work

Agents operate through a framework of Tools, Instructions, Skills and Reasoning.
Agent tools including integrations and workflows

​
Tools (What Agents Can Use)

Agents are equipped with tools to accomplish tasks:
Agent Tools
Direct connections to external services:
  • Gmail: Read, search, and send emails
  • Salesforce: Query records and update data
  • Notion: Search documentation and databases
  • Zendesk: Retrieve and manage support tickets
  • Google Calendar: Check availability and schedule meetings
  • And many more
Agents use the personal default credentials of whoever is running them (unless team credentials are configured). You’ll be prompted to authenticate if needed.
Your workflows become powerful tools for agents:
  • Agents see the workflow name and description
  • Understand expected inputs and outputs
  • Call workflows when appropriate
  • Process results to inform next steps
Example: A workflow that queries BigQuery, pulls Salesforce data, and combines them becomes a single “Get User Profile” tool for your agent.
Connect your own MCP server for services not available natively:
  • Internal company APIs
  • Custom data sources
  • Specialized tools
Learn more in the MCP documentation.
The Code Sandbox is natively enabled on all agents. Your agent can execute code in a secure, isolated environment:
  • Run Python code for data analysis, visualizations, and computations
  • Execute shell commands for file operations and package installation
  • Read/write files in the sandbox filesystem
  • Upload/download files between Gumloop storage and the sandbox
The sandbox comes with 80+ pre-installed Python packages including pandas, numpy, matplotlib, scikit-learn, and more. See the Code Sandbox section below for details.
This toggle controls whether your agent can create and edit skills on its own during conversations. It’s found in the Tools section of your agent configuration and is enabled by default.
Skill Editing & Creation toggle in agent tools configuration
Enabled (default, recommended): Your agent can create new skills, update existing ones, and fix its own mistakes. This is the preferred option because it allows the agent to be iterative and continuously improve its playbooks over time.Disabled: Your agent can still read and use the skills you’ve already attached, but it cannot create new skills or edit existing ones on the fly. Use this if you want tighter control over your skill library.
Keep this enabled to get the most value from skills. An agent that can refine its own playbooks gets better with every conversation.

​
Instructions (How Agents Behave)

The system prompt defines your agent’s personality, behavior, and decision-making:
Agent system prompt example

Define a Role

Good: “You’re an executive assistant for a CFO of a Fortune 500 company.”Bad: “You help with tasks.”A specific role sets tone, expertise level, and communication style automatically.

Set Tool Usage Rules

Explain when and how to use specific tools:
When the user provides a ticket number:
1. Retrieve ticket details and ask for confirmation
2. Once confirmed, run the "Get User Profile" workflow
3. Read the discount policy from Notion
4. Assess eligibility and explain your reasoning

Establish Confirmation Rules

Define when the agent should ask before acting:“Always ask for confirmation before:
  • Sending emails
  • Deleting data
  • Making changes to external systems”

Specify Response Style

Control tone, length, and format:“Always respond professionally. Keep responses under 100 words. Use bullet points for lists.”

​
Self-Improve Instructions

Your agent can update its own system prompt during any conversation. If something goes wrong, you don’t need to leave the chat and manually edit the instructions. Just tell the agent to fix it, right there in the conversation. Self-Improve Instructions toggle enabled in Agent Preferences, located below the system prompt editor Toggle this on in Agent Preferences, right below the system prompt editor. Enabled by default for new agents. Changes take effect immediately and persist across all future conversations.

You tell the agent

“Update your system prompt to never do X again” or “Add a rule that all emails should be under 100 words.” The agent modifies its instructions on the spot.

The agent learns on its own

You correct the agent (“don’t use that tone,” “always check Salesforce first”) and it proactively updates its instructions so the same mistake doesn’t happen again.
The agent has access to a file containing its current system prompt in its sandbox. When it modifies that file, changes are automatically detected, saved, and applied to the very next step in the conversation. Every future conversation uses the updated version.Safety guards: The agent cannot delete its own instructions (empty content is rejected), and there is no version history. If the agent makes an unwanted change, you can manually revert by editing the system prompt.
This works hand-in-hand with skills. Skills teach the agent how to do specific tasks; Self-Improve Instructions lets the agent refine its overall personality, tone, and decision-making rules. Together, they create an agent that gets better with every conversation.

​
Reasoning (How Agents Think)

When you assign a task, the agent: Chat with Agent
  1. Analyzes the request and available tools
  2. Decides which tools to use and in what order
  3. Executes tool calls and adapts based on results
  4. Asks for confirmation when needed (based on instructions)
  5. Explains its reasoning step-by-step

​
Triggers

Agents can run autonomously without manual interaction. Set up scheduled tasks to run on a recurring schedule or as a one-time task, or create event-based triggers to fire your agent when something happens in an external service.

Scheduled Tasks

Run your agent on a recurring schedule (e.g. every weekday at 9 AM) or as a one-time task (e.g. in 30 minutes). Your agent can even create and manage its own schedules during a conversation.

Event-Based Triggers

Fire your agent when a new email arrives, a Slack message is posted, a database record changes, and more. Supports Gmail, Slack, Teams, Google Sheets, Notion, Airtable, Zendesk, and other integrations.
Task type selector showing Scheduled Task and Trigger Based Task options

Agent Triggers Guide

Learn how to set up scheduled tasks, event-based triggers, prompt templates, and manage active triggers.

​
Skills

Your system prompt defines who the agent is. Tools give it the ability to act. But without skills, your agent improvises every time. It might send a decent email, but it won’t follow your outreach sequence, use your templates, or log things the way you want. Skills fill that gap. They’re reusable knowledge packs that teach your agent how to do specific work your way:
  • Encode multi-step processes the agent should follow every time (outreach sequences, triage checklists, reporting workflows)
  • Store templates and domain knowledge too detailed for the system prompt
  • Load only when relevant, saving tokens compared to stuffing everything into the system prompt
  • Improve over time as the agent learns from your feedback and even creates new skills on its own
Skills section in agent configuration showing attached skills

Agent Skills Guide

Learn how to create skills, attach them to agents, and build a knowledge base that improves over time.

​
Embedding Agents in Workflows

Creating an agent is the 0 to 1. Embedding that agent in a workflow is the 1 to 100.
The Agent node lets you run any of your pre-configured agents directly within your workflows. With Triggers, agents can already run on a schedule or respond to external events on their own. Embedding them in workflows unlocks additional capabilities: webhook triggers, chaining with other nodes, and batch processing.
CapabilityStandalone AgentAgent in Workflow
Manual Chat✅ Yes✅ Yes
Scheduled Runs✅ Yes✅ Yes
Event-Based Triggers✅ Yes✅ Yes
Webhook Triggers❌ No✅ Yes
Chain with Other Nodes❌ No✅ Yes
Batch Processing❌ No✅ Yes

Before Agents

You are the orchestrator:
  • Monitor conditions manually
  • Decide when to run workflows
  • String workflows together yourself
  • Handle exceptions and edge cases

With Agents

Agent orchestrates automatically:
  • Monitors and responds to requests
  • Decides which workflows to use
  • Chains workflows intelligently
  • Adapts to results and conditions

​
Using Workflows as Agent Tools

The section above covers putting an agent inside a workflow, where the workflow triggers and orchestrates the agent. This is the reverse: giving your agent workflows it can call as tools. When a workflow is attached as a tool, the agent decides when to use it, fills in the inputs, kicks it off, and reads the outputs. The agent is the orchestrator; the workflow just does its job and returns the result. Tips for building workflows your agent will call:
Critical: Agents identify workflow parameters through Input and Output nodes.
Input Node: "company_name" (text)
Input Node: "date_range" (text)
[Your workflow logic here]
Output Node: "enriched_data" (object)
Output Node: "success" (boolean)
Without clear inputs/outputs, the agent won’t know how to use the workflow properly.
Workflow names should clearly indicate their purpose:✅ Good: “Get User Activity and Salesforce Status”, “Enrich Lead from LinkedIn Profile”❌ Bad: “User Workflow”, “Workflow 1”, “Data Thing”
Write descriptions that help agents understand:
  • What the workflow does
  • When it should be used
  • What inputs it expects
  • What outputs it provides
Example: “Takes a LinkedIn profile URL and returns enriched company data including size, industry, recent funding, and key contacts. Use when researching new leads or companies.”
Each workflow should do one thing well:
  • ✅ “Enrich Contact from Email”
  • ✅ “Send Slack Notification”
  • ❌ “Enrich Contact and Send Notification and Update CRM”
Let the agent orchestrate multiple focused workflows rather than building mega-workflows.
Learn more about the Agent node in the Agent Node documentation.

​
Code Sandbox

The Code Sandbox gives your agent the ability to execute Python code and shell commands in a secure, isolated environment. It’s natively enabled on all agents, so there’s nothing to configure. What the sandbox can do:
  • Run Python code for data analysis, visualizations, and computations
  • Execute shell commands for file operations and package installation
  • Read and write files in the sandbox filesystem
  • Upload and download files between Gumloop storage and the sandbox
The sandbox comes pre-loaded with 80+ Python packages including pandas, numpy, matplotlib, scikit-learn, and more. If you need something that isn’t installed, your agent can install it with pip install during the conversation.
The sandbox environment persists across tool calls within the same conversation, allowing your agent to build on previous work and maintain state throughout the interaction.
Data Science & Analysis: pandas, numpy, scipy, scikit-learn, statsmodelsVisualization: matplotlib, seaborn, plotly, bokehAI & Machine Learning: openai, anthropic, google-generativeai, mistralai, llama-index-core, gensimWeb & APIs: requests, aiohttp, beautifulsoup4, scrapy, selenium, playwrightFile Processing: openpyxl, PyMuPDF, python-docx, Pillow, opencv-python, imageioMedia Processing: moviepy, librosa, ffmpeg-python, yt-dlp, soundfileNatural Language Processing: nltk, spacy, textblobDatabase & Cloud: psycopg2-binary, pymongo, PyMySQL, pyodbc, boto3, google-cloud-storage
If you need a package that isn’t pre-installed, your agent can install it using pip install package-name via the shell command tool. However, installed packages only persist for the current conversation.
  • Execution Timeouts: Python scripts: 120 seconds max. Shell commands: 60 seconds default. Search operations: 30 seconds.
  • File Size Limits: Can ingest files which are at max 300MB
  • Session Persistence: The sandbox persists within a single conversation. Starting a new conversation creates a fresh sandbox.
  • Network Access: The sandbox has internet access for pip installs and API calls, but cannot access your local network.
  • No GUI Support: The sandbox runs headless. Visualizations must be saved to files (e.g., plt.savefig()).
  • Resource Constraints: Suitable for data analysis and scripting, not for training large ML models.

​
AI Advanced Settings

Fine-tune how your agent’s AI model behaves, manages long conversations, and handles failures. Access these settings by clicking the AI Advanced Settings button in your agent configuration.
AI Advanced Settings panel
Defaults are optimized. All settings are pre-configured for the best balance of performance, cost, and reliability. Only adjust these if you have a specific need.
Customize AI model behavior. Available parameters vary by provider (OpenAI, Anthropic, Google). Settings are stored per-provider, so switching models preserves your preferences for each.
Model configuration options
ParameterRangeDefaultDescription
Reasoning Effortlow, medium, highmediumControls computational effort before responding. Higher = more thorough reasoning but slower and more tokens. Only for o-series and GPT-5 models.
Temperature0–21Controls output randomness. 0 = deterministic, 2 = highly creative.
Max Output Tokens1+AutoUpper bound for generated tokens (includes reasoning tokens). If unset, uses model default.
Max Tool Calls1+AutoLimits total tool calls per response. Useful for cost control.
Top P0–11Nucleus sampling. Model considers only tokens in the top P probability mass. Only for GPT-4o, GPT-4.1, GPT-5.1, GPT-5.2, o3, o4.
Parallel Tool Callson/offonWhen on, model can execute multiple tools simultaneously. Disable if tools depend on each other’s results.
Adjust either Temperature or Top P, not both. Using both produces unpredictable results.
ParameterRangeDefaultDescription
Extended Thinkingenabled, disabledenabledShows Claude’s reasoning process before the final answer. When enabled, temperature is forced to 1.0.
Budget Tokens1,024+10,000Token budget for thinking. Higher = more thorough reasoning but slower. Only shown when thinking is enabled. Must be less than Max Tokens.
Temperature0–11Controls output randomness. Note: forced to 1.0 when Extended Thinking is enabled.
Max Tokens1+AutoMaximum tokens to generate. Defaults: 64,000 (Claude 4.5), 8,192 (older models).
Top P0–11Nucleus sampling threshold.
Top K1+AutoLimits sampling to top K most likely tokens. Lower values (10–40) produce more focused outputs by removing long-tail responses.
Disable Parallel Tool Useon/offoffWhen on, model outputs at most one tool call per response. Enable for strict sequential execution.
ParameterRangeDefaultDescription
Thinking LevelLOW, HIGHHIGHControls depth of internal reasoning. LOW = faster responses, HIGH = deeper analysis. Only for Gemini 2.5 and 3 models.
Temperature0–21Controls output randomness.
Top P0–10.95Nucleus sampling. Note: Google’s default (0.95) is lower than other providers.
Top K1+AutoMaximum tokens considered at each generation step.
Max Output Tokens1+AutoMaximum tokens to generate.
Temperature vs Reasoning: Temperature controls randomness in word selection. Reasoning effort/thinking controls how much the model deliberates before responding. For complex analysis, increase reasoning, not temperature.

​
Understanding Credit Costs

Agents consume credits based on AI model usage, workflow executions, and integration operations.
Credits are charged per AI interaction. Cost depends on message length, model selected, conversation history (each message includes previous context), and number of tools available.

​
Model Pricing Overview

Best for simple tasks and high-volume usage
Model~Cost per MessageBest For
GPT-4.1 Mini2-3 creditsSimple tasks, quick responses
GPT-5 Mini2-3 creditsGeneral queries
Claude Haiku 4.52-4 creditsFast interactions
Credit costs are approximate per message. Actual costs vary based on message length, conversation history, tools available, and whether the agent executes workflows. Agents also support Kimi K2.5 and Qwen 3.5 via OpenRouter (exclusive to agents, not available in workflow nodes).

​
Workflow and Integration Costs

When agents call workflows or integrations, additional costs apply:
Node TypeCredit CostExamples
Free Nodes0 creditsInput/Output, Filter, Router, Most integrations
Low Cost2-3 creditsAsk AI (simple), Run Code, Custom Operators
Medium Cost10-30 creditsAI with large prompts, AI Vision
High Cost10-60+ creditsData enrichment, Premium APIs
Integration Costs:
  • Free: Google Workspace, Slack, Airtable, Notion, Salesforce, HubSpot, 150+ more
  • Paid: Data enrichment services (eg. Hunter.io ~10 credits, ZoomInfo ~60 credits)

​
Optimizing Credit Usage

Choose Appropriate Models

Use budget models for simple tasks. Reserve expert models for complex analysis that truly requires advanced reasoning.

Keep Conversations Focused

Start new conversations for different topics. Long threads accumulate context costs with each message.

Write Clear Prompts

Specific prompts get better results faster, reducing back-and-forth messages and total credit consumption.

Limit Tool Count

Start with 2-3 essential tools. Each additional tool increases the system prompt size and base cost.
Message Length: Longer inputs and outputs consume more tokens. Short message (~50 words): ~500 tokens. Medium (~200 words): ~2,000 tokens. Long (~500 words): ~5,000 tokens.Conversation History: Each message includes previous context. 1st message: Base cost. 5th message: ~20% higher. 10th message: ~40% higher. Start new conversations for unrelated topics.Tool Availability: More tools = larger system prompt. 2-3 tools: Base cost. 5-10 tools: +10-20%. 15+ tools: +30-40%.Multi-Step Operations: Workflow calls trigger multiple AI steps. Example: Decide to call workflow (~5 credits) + Process results (~5 credits) + Generate response (~5 credits) = ~15 credits + workflow cost.

​
Tracking Credit Usage

Agent credit cost
  • Real-time Display: Credits shown next to each agent response as it streams
  • Conversation History: View total credits per conversation thread
  • History Page: See credit costs for agent chats and Agent node executions (when run via workflows)
  • Account Dashboard: Track total credits used across all agents and timeframes
For full details, see the Credits documentation.

​
Credentials & Authentication

When an agent uses integrations and workflows, it needs credentials to access external services.
Key principle: Agents always use the credentials of the person running the agent, not the agent creator’s credentials. If you run the agent, it uses your credentials. If a teammate runs it, it uses their credentials.
Team agents are created in teams and have two key differences from personal agents:1. Access Control: Only members of the team can use the agent. Non-members will receive an “access denied” message.2. Credential Behavior: If an MCP integration or workflow is set to use “team default” credentials, those team credentials are used instead of personal credentials. Otherwise, the personal default credentials of whoever is running the agent are used.Best for: Team collaboration requiring shared credentials, controlled access to specific team membersLearn more about teams in the Organizations and Teams documentation.
Before using an agent with integrations:
  1. Visit your credentials page
  2. Authenticate with required services (Gmail, Salesforce, etc.)
  3. Set credentials as your personal default
What happens if credentials are missing:
  • The agent will notify you about missing authentication
  • You’ll receive a link to the credentials page
  • After authenticating, return and retry your request
Agents will automatically detect missing credentials and guide you through the authentication process.

Your Data Stays Private

With personal agents and personal credentials, only your authenticated accounts are accessed. Other users cannot see your data through the agent.

Controlled Access

Admin security controls and user roles apply to agents just like workflows. You can only access what you’re authorized to access.
For full details, see the Credentials documentation.

​
Best Practices & Troubleshooting

Begin with 2-3 tools and straightforward instructions. Test thoroughly before adding more capabilities.Anti-pattern: Creating an agent with 15 tools and a 2000-word system prompt immediately.Better approach: Start with core functionality, observe how the agent behaves, then incrementally add tools and refine instructions based on real usage.
Agents improve over time as you refine instructions based on real interactions:
  • Review conversation history regularly for patterns
  • When agents make mistakes, ask: “What could I add to your instructions to prevent this?”
  • Document edge cases and add explicit handling rules
  • Celebrate successful patterns and codify them in instructions
When creating workflows that agents will call:
  • Always use Input and Output nodes so agents understand parameters
  • Keep workflows focused on single responsibilities
  • Use descriptive names that indicate purpose
  • Write clear descriptions explaining when to use the workflow
  • Test workflows independently before giving them to agents
Define what agents should NOT do to prevent unintended actions:
Never:
- Delete customer data or records
- Send emails without explicit user approval
- Make purchases or financial commitments
- Override manual decisions by team members
- Modify production data without confirmation
Be explicit about destructive actions requiring human oversight.
Track metrics to understand agent effectiveness:
  • Time saved: Hours saved per week through automation
  • Success rate: Tasks completed successfully vs requiring intervention
  • Tool usage: Which workflows/integrations are used most frequently
  • Credit efficiency: Cost per completed task or interaction

​
Next Steps

Agent Triggers

Set up scheduled tasks and event-based triggers to run agents automatically

Agent Skills

Create reusable knowledge packs that teach your agents how to do specific work

Agent Node

Embed agents in workflows for webhooks, chaining, and batch processing

Using Agents in Slack

Deploy agents to Slack channels for team-wide access