Reflections give your agent the ability to learn from its own history. Instead of relying solely on your feedback, the agent periodically reviews its recent conversations, identifies patterns (repeated mistakes, inefficient tool usage, missing knowledge), and proposes concrete improvements to its skills and instructions. Think of it as a built-in performance review that runs on autopilot.Documentation Index
Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt
Use this file to discover all available pages before exploring further.
Why Reflections?
Without Reflections, your agent improves only when you explicitly correct it or manually update its instructions. That works for one-off fixes, but it doesn’t scale. With Reflections enabled, your agent:- Detects recurring problems across multiple conversations, not just the one you noticed
- Proposes targeted fixes like new skills, instruction updates, or tool configuration changes
- Backs every suggestion with evidence from actual conversation transcripts
- Gets better over time without requiring constant hands-on management from you
Without Reflections
You notice the agent keeps making the same mistake. You manually update the instructions or skill. Repeat for every issue you catch.
With Reflections
The agent reviews its own work on a schedule. It finds the mistake pattern across 8 conversations, proposes a skill fix, and you approve it with one click.
Reflections works best when paired with Skills and Self-Improve Instructions. Skills give the agent structured playbooks to update. Self-Improve Instructions lets the agent tweak its own system prompt. Reflections is the engine that identifies what to change.
How Reflections Work
Here’s what happens behind the scenes when a reflection runs:Gather Recent Activity
The agent collects all operations (tool calls, conversations, errors) since its last reflection run. These are the raw data it will analyze.
Mine for Patterns
Automated analysis identifies candidates: repeated request types, recurring errors, inefficient tool sequences, frequently re-fetched data. Each pattern gets a confidence score and support count (how many interactions showed it).
Validate with Transcripts
This is the critical step. The agent reads actual conversation transcripts for each candidate pattern. It checks whether the pattern is real, consistent across interactions, and worth fixing. Patterns that are one-off, already handled, or inherent to the task get rejected.
Check Existing Knowledge
The agent reads its current instructions and skills to make sure it’s not proposing a change that’s already covered. It also checks previous reflections to see if a pattern is persistent (keeps coming up) or resolved (a past fix worked).
Types of Improvements
Reflections can propose several types of changes:| Type | When It’s Used | Example |
|---|---|---|
| New Skill | A repeating multi-step workflow (3+ tool calls in a consistent sequence) | “Search Jira by status, filter results, format as table” recurs across 8 interactions |
| Skill Fix | An existing skill covers the case but misses an edge case | The outreach skill works but doesn’t handle out-of-office replies |
| Instruction Update | A behavioral rule or domain fact, not a workflow | ”Always use UTC for timestamps” or “User X prefers CSV over JSON” |
| Tool Access | The agent is working around a missing integration | The agent uses sandbox curl instead of the proper API tool |
Setting Up Reflections
Enabling Reflections
- Open your agent’s configuration
- Find Reflections under the Abilities section in the sidebar
- Toggle Enable Reflections on
- Click Save
Apply Behavior
This controls what happens when the agent proposes an improvement.
Review Queue (default)
Review Queue (default)
Every suggestion goes into a queue for you to review. Nothing changes until you explicitly approve it. This is the safest option and the default for all agents.Best for: Production agents, customer-facing workflows, or any agent where you want full control over changes.
Auto-Apply Eligible Reflections
Auto-Apply Eligible Reflections
Low-risk suggestions with strong evidence get applied automatically. The agent still creates the suggestion, but it fires the improvement run immediately without waiting for your approval.Best for: Internal agents, personal assistants, or agents where you trust the improvement process and want faster iteration.
Reflection Schedule
Set how often reflections run using a cron schedule. The default is daily at 10:00 PM UTC. You can change this to match your needs. Use the schedule picker to set a custom frequency, like every 2 days, weekly, or at a specific time that works for your team.Extra Reflection Instructions
Optionally guide what your agent pays attention to during reflections. This is a free-text field where you can steer the reflection focus. Examples:- “Focus on repeated tasks, missed tools, and recurring user requests.”
- “Pay special attention to error patterns in Salesforce queries.”
- “Prioritize improvements that reduce the number of tool calls per interaction.”
- “Look for cases where the agent asked for clarification but shouldn’t have needed to.”
Reviewing Reflections
When your agent completes a reflection run, the proposed improvements appear on the Reflections page. Navigate there from the agent’s sidebar.The Reflections Page
Each reflection shows up as a card with:- Title: A short description of the proposed improvement
- Rationale: Why the agent thinks this change is needed
- Status: Current state of the reflection
- Date: When the reflection was created
Reflection Detail
| Field | Description |
|---|---|
| Status | Current lifecycle state (Pending, Completed, etc.) |
| Created | When this reflection was proposed |
| Evidence | Number of operations the agent analyzed to reach this conclusion |
| Prompt | The exact instructions the agent will follow if you apply this reflection. This includes file paths, content changes, and the evidence rationale. |
Applying a Reflection
To apply a pending reflection:- Click the reflection card to open the detail view
- Review the prompt to understand what will change
- Click Apply
Only users with Owner or Editor access to the agent can apply reflections.
How Reflections Differ from Other Self-Improvement Features
Gumloop agents have several ways to learn and improve. Here’s how they fit together:| Feature | What It Does | When It Runs |
|---|---|---|
| Self-Improve Instructions | Agent updates its own system prompt during a conversation based on your feedback | In real-time, during any chat |
| Skill Editing | Agent creates or updates skills when you ask it to, or when it learns something new | In real-time, during any chat |
| Reflections | Agent reviews past work on a schedule, identifies patterns across many conversations, and proposes batch improvements | On a schedule (e.g., daily, every 2 days) |
Best Practices
Start with Review Queue. When first enabling Reflections, use the Review Queue mode so you can see what kinds of improvements the agent proposes. Once you’re comfortable with the quality, you can switch to Auto-Apply. Write specific extra instructions. Generic instructions like “improve everything” are less useful than targeted ones like “focus on reducing errors in our Salesforce integration” or “look for opportunities to create skills for repeated reporting tasks.” Check reflections regularly. Pending reflections don’t expire, but they become less relevant over time. Review and apply (or dismiss) them within a few days of creation. Let the agent build momentum. The first few reflections may be modest. As the agent accumulates more conversation history and applies improvements, subsequent reflections become more insightful because they can compare against previous ones. Combine with Search Past Conversations. Enable Search Past Conversations so the reflection agent can look up full conversation transcripts. This makes reflection validation much more accurate.FAQ
Does my agent run reflections if there's no new activity?
Does my agent run reflections if there's no new activity?
No. If there are no new operations since the last reflection, the scheduled run will skip automatically. No credits are consumed.
How many credits do reflections cost?
How many credits do reflections cost?
Reflections use credits like any other agent interaction. The cost depends on how many operations need to be analyzed and how many conversation transcripts the agent reads for validation. Typically, a reflection run costs roughly the same as a moderate agent conversation.
Can I manually trigger a reflection?
Can I manually trigger a reflection?
Reflections run on their configured schedule. To get an immediate reflection, you can adjust the schedule to run soon, or use the agent’s chat to ask it to review its recent work (which uses Self-Improve Instructions rather than the formal Reflections system).
What happens if I never apply pending reflections?
What happens if I never apply pending reflections?
Nothing breaks. Pending reflections stay in the queue indefinitely. Future reflection runs may propose newer, better versions of the same improvement (which supersede the older ones). But stale reflections lose relevance over time, so it’s best to review them periodically.
Can auto-apply make a bad change?
Can auto-apply make a bad change?
Auto-apply is conservative by design. It only fires suggestions the system classifies as low-risk with enough supporting evidence. High-risk or ambiguous suggestions still go to the Review Queue. That said, if you want full control, stick with Review Queue mode.
Who can apply reflections?
Who can apply reflections?
Only users with Owner or Editor access to the agent can apply reflections. Viewers can see the reflections page but cannot apply or dismiss suggestions.
Can I see what changed after a reflection is applied?
Can I see what changed after a reflection is applied?
Yes. When you apply a reflection, it creates a new interaction in the agent’s chat history. You can open that interaction to see exactly what the agent did: which files it edited, which skills it created or updated, and the reasoning behind each change.