Skip to main content

​
Agent components overview

Every agent block in Flowgen Studio consists of four essential components that work together to create intelligent, context-aware automation. Understanding how these components interact is crucial for building effective workflows.

Agent Prompt

Define the agent’s personality, behavior, and decision-making logic with structured prompts.

RAG (Knowledge Base)

Ground responses with enterprise data from connected sources and collections.

Tools Integration

Enable external actions through API calls, database queries, and third-party integrations.

Variables (Input & Capture)

Manage data flow with input variables and capture outputs for downstream processing.

​
Component interaction flow

​
Access control considerations

Agent configuration requires “Developer” role or higher. Users with “Tester” or “Viewer” roles can only view agent settings but cannot modify them.

​
Role-based restrictions

  • SuperAdmin/Admin: Full access to all agent components and debugging tools
  • Developer: Can configure prompts, RAG, tools, and variables; cannot publish to production
  • Tester: Read-only access for testing purposes; can view execution logs
  • Viewer: Limited to viewing published agent configurations only

​
Debugging agent issues

​
Common problems and solutions

Symptoms: Agent gives irrelevant or incorrect responsesDebugging steps:
  1. Check prompt clarity and specificity in the Agent Prompt tab
  2. Verify RAG sources are properly attached and contain relevant information
  3. Review execution logs in the Observability section
  4. Test with sample inputs to isolate the issue
Sample debugging code:
// Check agent response quality
const testPrompt = "Analyze this customer query: 'I need help with my order'";
const expectedResponse = "The agent should identify this as a customer service request";
Resolution: Refine the prompt with more specific instructions and examples
Symptoms: Agent ignores attached knowledge sourcesDebugging steps:
  1. Verify data sources are properly connected in RAG Management
  2. Check if collections contain relevant information for the query
  3. Review agent’s RAG configuration in the Inspector panel
  4. Test with queries that should trigger knowledge retrieval
Sample debugging code:
// Test RAG retrieval
const testQuery = "What is our company's refund policy?";
// Should retrieve policy document from RAG sources
Resolution: Ensure RAG sources are relevant and properly indexed
Symptoms: External API calls failing or returning errorsDebugging steps:
  1. Check tool authentication and API keys in DevStudio
  2. Verify tool parameters and input mapping
  3. Review error logs in the execution timeline
  4. Test tools independently outside the workflow
Sample debugging code:
// Test tool integration
const toolTest = {
  toolId: "email-sender",
  parameters: {
    to: "[email protected]",
    subject: "Test email",
    body: "This is a test"
  }
};
Resolution: Fix authentication, parameter mapping, or API endpoint issues
Symptoms: Expected data not being captured or passed to next stepsDebugging steps:
  1. Verify variable names match between capture and usage points
  2. Check data types and formats are consistent
  3. Review variable scope and availability
  4. Test with known input values
Sample debugging code:
// Test variable capture
const inputData = {
  customerEmail: "[email protected]",
  orderId: "12345"
};
// Verify these are captured and available downstream
Resolution: Fix variable naming, data types, or scope issues

​
Best practices

​
Prompt engineering

  • Be specific: Clearly define the agent’s role, context, and expected outputs
  • Provide examples: Include sample inputs and desired responses
  • Set boundaries: Define what the agent should and shouldn’t do
  • Test iteratively: Refine prompts based on actual performance

​
RAG optimization

  • Curate sources: Only attach relevant, high-quality knowledge sources
  • Organize collections: Group related documents for better retrieval
  • Monitor usage: Track which sources are actually being used
  • Update regularly: Keep knowledge sources current and accurate

​
Tool management

  • Error handling: Implement robust error handling for external calls
  • Rate limiting: Respect API rate limits and implement backoff strategies
  • Security: Use secure authentication methods and protect sensitive data
  • Monitoring: Track tool performance and success rates

​
Variable design

  • Consistent naming: Use clear, descriptive variable names
  • Type safety: Ensure data types are consistent across the workflow
  • Documentation: Document variable purposes and expected formats
  • Validation: Implement validation for critical variables

​
Integration with other Phinite components

​
Assistant integration

​
Tool ecosystem

​
Observability and monitoring

​
Next steps

  1. Configure your first agent: Start with prompt design
  2. Add knowledge sources: Connect relevant data
  3. Integrate tools: Enable external capabilities
  4. Set up variables: Manage data flow
  5. Test and debug: Monitor performance and resolve issues