Frequently Asked Questions

General

What is the Agents App?

The Agents App is an application within FlowState for managing and orchestrating AI agents. It provides capabilities for:

• Creating and assigning tasks to AI agents
• Monitoring agent execution in real-time
• Reviewing and approving agent outputs through human-in-the-loop workflows
• Tracking agent performance metrics and logs
• Managing codebases where agents perform work

Who should use this app?

The Agents App is designed for:

What is an "agent" in this context?

An agent is an autonomous AI worker that can execute tasks within your codebases. Agents can:

• Execute code-related tasks (refactoring, bug fixes, documentation)
• Follow spec-driven development workflows
• Request human feedback when needed
• Generate outputs for approval

Tasks

How do I create a new task?

To create a task:

1. Click New Task from the Dashboard or Tasks page
2. Enter a descriptive title
3. Provide detailed instructions in the description
4. Click Create

The task enters the queue and will be picked up by an available agent.

What do the different task statuses mean?

Why is my task stuck in "In Progress"?

Common reasons include:

1. Agent query pending: The agent has a question. Check the Conversation tab.
2. Agent crashed: Review the Logs page for errors.
3. Long-running task: Some complex tasks take time. Check recent log activity.
4. Network issues: Verify the worker is still active.

See Troubleshooting for detailed solutions.

Can I edit a task after creating it?

Yes. Navigate to the task detail page and update the task information. Note that editing a task while an agent is working on it may cause conflicts.

Approvals

What is the approval workflow?

When an agent completes certain tasks, it may create an approval request. This implements a "human-in-the-loop" pattern where:

1. Agent completes work
2. Approval request is created
3. Human reviews the output
4. Human approves, rejects, or requests revision
5. Workflow continues based on decision

How do I approve agent work?

1. Navigate to Approvals in the sidebar
2. Click on a pending approval to open the review dialog
3. Review the agent's output
4. Choose an action:
   • Approve: Accept the work
   • Reject: Decline the work
   • Request Revision: Ask for changes with feedback
5. Optionally add comments
6. Submit your decision

What happens when I request a revision?

When you request a revision:

1. The approval status changes to "Needs Revision"
2. Your feedback is recorded
3. The associated task may be re-queued for the agent
4. The agent will attempt to address your feedback

Workers

What is a worker?

A worker represents an AI agent instance capable of processing tasks. Workers:

• Pick up tasks from the queue
• Execute work autonomously
• Report status and metrics
• Generate logs for monitoring

How can I tell if a worker is healthy?

On the Workers page, each worker shows:

Also check:

• Success rate percentage
• Completed vs failed task counts
• Last activity timestamp

Why are there no active workers?

If no workers appear:

1. The agent service may not be running
2. Network connectivity issues between agents and FlowState
3. Workers may not be configured for your workspace

Contact your administrator to verify worker configuration.

Codebases

What is a codebase?

A codebase represents a repository or project where agents perform work. Codebases help:

• Organize tasks by repository
• Provide context for agent work
• Group related work together

How do I add a new codebase?

1. Navigate to Codebases in the sidebar
2. Click New Codebase
3. Fill in the details:
   • Name
   • Description
   • Path (repository path or URL)
4. Click Save

Can agents work across multiple codebases?

Yes. Tasks can be associated with specific codebases, and agents can work on tasks in any codebase they have access to.

Logs

How do I view execution logs?

1. Navigate to Logs in the sidebar
2. Use filters to narrow results:
   • Level (debug, info, warn, error, critical)
   • Category
   • Search text
3. Click on log entries to expand and see metadata

What information is in log entries?

Log entries include:

• Timestamp: When the event occurred
• Level: Severity (debug, info, warn, error, critical)
• Category: Classification of the log
• Message: Description of the event
• Metadata (expandable):
  • Command executed
  • Exit code
  • Duration
  • Error details

Can I export logs?

Log export functionality is not currently available. You can copy individual log entries for reporting purposes.

Access & Permissions

How do I get access to the Agents App?

Contact your organization administrator to request access. They will need to:

1. Add you to the appropriate workspace
2. Grant you the required permissions

What permissions do I need?

The Agents App requires these permissions:

• database: For reading and writing data
• notifications: For receiving alerts about approvals and task updates

Additional permissions may be required for administrative functions.

Technical

Which browsers are supported?

The Agents App supports the latest versions of:

• Chrome (recommended)
• Firefox
• Safari
• Microsoft Edge

Does the app work offline?

The Agents App uses a local-first architecture with RxDB. This means:

• You can view cached data while offline
• Changes made offline will sync when connectivity is restored
• Some features require active connectivity (e.g., creating new tasks)

Is my data secure?

Yes. Security measures include:

• All data encrypted in transit (HTTPS)
• Organization and workspace isolation
• Authentication required for access
• Role-based access controls

See the FlowState security documentation for comprehensive details.

Troubleshooting

The app is running slowly. What can I do?

Try these steps:

1. Apply filters to reduce data being loaded
2. Clear browser cache
3. Check network connectivity
4. Close other resource-intensive tabs
5. Try a different browser

See Troubleshooting for more solutions.

Something isn't working. Where do I report it?

1. Check Troubleshooting for common solutions
2. Search existing support documentation
3. Contact support with:
   • Issue description
   • Steps to reproduce
   • Screenshots
   • Browser/device info

Still Have Questions?

If your question isn't answered here:

• Check the Features documentation for detailed capabilities
• Review Getting Started for setup guidance
• See Troubleshooting for common issues
• Contact support for additional help