Agent Node Anatomy

Agent components overview

Every agent node in Graph 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 PromptDefine 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 IntegrationEnable 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.

Registry agents (A2A)Attach Agent Registry agents in Browse or Discovery mode on a master agent node.

Registry agent nodes (A2A)

In multi-agent graphs, a registry agent node connects a master agent to agents published in the Agent Registry over the A2A protocol:

• Browse mode — call one specific registered agent (fixed build, tools, and hosted URL).
• Discovery mode — master agent auto-selects registry agents that match saved filters (visibility, deployment status, MIME modes, tags).

Expose agent graphs first via Expose as External Agent, then attach them from the canvas browse panel. Only one Discovery node is allowed per master agent node.

See Registry agent nodes (Browse & Discovery) for step-by-step configuration.

Component interaction flow

graph TD
    A[Input Variables] --> B[Agent Prompt]
    C[RAG Knowledge] --> B
    D[Tool Calls] --> B
    B --> E[LLM Processing]
    E --> F[Capture Variables]
    E --> G[Decision Variables]
    F --> H[Next Workflow Step]
    G --> I[Conditional Routing]

Access control considerations

Caution

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

Agent not responding as expected

Symptoms: Agent gives irrelevant or incorrect responses

Debugging 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

RAG knowledge not being used

Symptoms: Agent ignores attached knowledge sources

Debugging 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

Tool integration failures

Symptoms: External API calls failing or returning errors

Debugging 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: "test@example.com",
    subject: "Test email",
    body: "This is a test"
  }
};

Resolution: Fix authentication, parameter mapping, or API endpoint issues

Variable capture issues

Symptoms: Expected data not being captured or passed to next steps

Debugging 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: "user@example.com",
  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

• Conversational Assistants: Agents power chat and voice interactions
• Email Assistants: Agents process and respond to email communications
• Autonomous Assistants: Agents execute background automation tasks

Tool ecosystem

• Custom Tools: Build specialized tools for specific use cases
• Pre-built Integrations: Leverage existing integrations with popular services
• Tool Versioning: Manage tool updates and compatibility

Observability and monitoring

• Execution Logs: Monitor agent performance and debug issues
• Usage Metrics: Track token usage and performance metrics
• Error Tracking: Identify and resolve common issues

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. Expose to Agent Registry: Publish as an A2A agent when external discovery is required
6. Test and debug: Monitor performance and resolve issues