> ## Documentation Index
> Fetch the complete documentation index at: https://docs.phinite.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Node Anatomy
> Master the four core components of AI agents: prompts, RAG knowledge, tool integrations, and variable management.
## 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.
Define the agent's personality, behavior, and decision-making logic with structured prompts.
Ground responses with enterprise data from connected sources and collections.
Enable external actions through API calls, database queries, and third-party integrations.
Manage data flow with input variables and capture outputs for downstream processing.
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](/agent-registry/overview)** 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](/agent-registry/expose-your-flow)**, then attach them from the canvas browse panel. Only **one Discovery node** is allowed per master agent node.
See **[Registry agent nodes (Browse & Discovery)](/agent-registry/registry-agent-nodes)** for step-by-step configuration.
## Component interaction flow
```mermaid theme={null}
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
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 responses
**Debugging steps**:
1. Check prompt clarity and specificity in the [Agent Prompt](/graph-studio/agent-node/prompt) tab
2. Verify RAG sources are properly attached and contain relevant information
3. Review execution logs in the [Observability](/observability/logs) section
4. Test with sample inputs to isolate the issue
**Sample debugging code**:
```javascript theme={null}
// 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 sources
**Debugging steps**:
1. Verify data sources are properly connected in [RAG Management](/graph-studio/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**:
```javascript theme={null}
// 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 errors
**Debugging steps**:
1. Check tool authentication and API keys in [DevStudio](/devstudio/overview)
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**:
```javascript theme={null}
// 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
**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**:
```javascript theme={null}
// 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](/assistants/conversational)**: Agents power chat and voice interactions
* **[Email Assistants](/assistants/email)**: Agents process and respond to email communications
* **[Autonomous Assistants](/assistants/autonomous)**: Agents execute background automation tasks
### Tool ecosystem
* **[Custom Tools](/devstudio/custom-tools)**: Build specialized tools for specific use cases
* **[Pre-built Integrations](/devstudio/prebuilt-tools)**: Leverage existing integrations with popular services
* **[Tool Versioning](/devstudio/versioning)**: Manage tool updates and compatibility
### Observability and monitoring
* **[Execution Logs](/observability/logs)**: Monitor agent performance and debug issues
* **[Usage Metrics](/observability/usage-metrics)**: Track token usage and performance metrics
* **[Error Tracking](/support/error-codes)**: Identify and resolve common issues
## Next steps
1. **[Configure your first agent](/graph-studio/agent-node/prompt)**: Start with prompt design
2. **[Add knowledge sources](/graph-studio/agent-node/rag)**: Connect relevant data
3. **[Integrate tools](/graph-studio/agent-node/tools)**: Enable external capabilities
4. **[Set up variables](/graph-studio/agent-node/variables)**: Manage data flow
5. **[Expose to Agent Registry](/agent-registry/expose-your-flow)**: Publish as an A2A agent when external discovery is required
6. **[Test and debug](/observability/logs)**: Monitor performance and resolve issues