Agent Tool - PLai Framework Documentation

Under the hood, invoking an agent works like calling a function: the target agent runs independently with its own instructions and tools, then its output is returned to the calling agent. You can target either an agent from your current project or a system-wide core agent.

This tool has Default status, meaning it’s production-ready and available on all subscription plans.

Overview

The Agent Tool creates a powerful multi-agent architecture where agents can:

Agent Orchestration

Coordinate multiple specialized agents for complex tasks

Task Delegation

Delegate specific subtasks to expert agents

Knowledge Sharing

Share context and information between agents

Workflow Automation

Build sophisticated multi-step agent workflows

Configuration Parameters

select

required

The agent to invoke when this tool is used
Options:

Project agents - Agents created in your current project
Core agents - System-wide specialized agents
Note: The target agent must be active and configured properly

Setup Instructions

Create Target Agent

First, ensure you have created and configured the agent you want to invoke

Navigate to Tools

Go to the Tools section in your project dashboard

Create Agent Tool

Click Create Tool and select Agent Tool

Configure Tool Details

Provide a descriptive name and description for the tool

Select Target Agent

Choose the agent you want to invoke from the dropdown list

Test Agent Tool

Use the test button to verify the agent invocation works correctly

Add to Parent Agent

Assign this tool to the orchestrator or parent agent that will use it

Agent Types

Project Agents

Custom agents created within your project:

Characteristics
Best For
Examples

Custom Configuration: Tailored to your specific needs
Project-Scoped: Available only within the current project
Full Control: Complete control over prompts and settings
Flexible: Can be modified and optimized as needed

Core Agents

System-wide specialized agents available across projects:

Characteristics
Best For
Examples

Pre-Configured: Ready to use with optimal settings
System-Wide: Available across all projects
Maintained: Regularly updated and improved
Specialized: Designed for specific common tasks

Configuration Examples

Customer Support Escalation

{
  "name": "Escalate to Specialist",
  "description": "Escalates complex technical issues to the specialized technical support agent",
  "target_agent_id": "tech_support_specialist_agent_id"
}

Use Case: A general support agent can escalate technical questions to a specialized technical support agent with deep product knowledge.

Multi-Language Support

{
  "name": "Spanish Translation Agent",
  "description": "Translates responses to Spanish for Spanish-speaking customers",
  "target_agent_id": "spanish_translation_agent_id"
}

Use Case: An English-speaking agent can invoke a translation agent to provide responses in Spanish.

Data Analysis Pipeline

{
  "name": "Financial Analysis Agent",
  "description": "Performs detailed financial analysis on the provided data",
  "target_agent_id": "financial_analyst_agent_id"
}

Use Case: A general business intelligence agent can delegate financial analysis to a specialized financial analyst agent.

Content Generation Workflow

{
  "name": "SEO Content Optimizer",
  "description": "Optimizes content for SEO best practices",
  "target_agent_id": "seo_optimizer_agent_id"
}

Use Case: A content creation agent can invoke an SEO specialist to optimize generated content.

Multi-Agent Architectures

Hierarchical Architecture

Orchestrator Agent delegates to:
- Research Agent — uses the Web Search Tool and the Database Tool
- Analysis Agent — uses the Data Processing Tool and the Analytics Tool
- Writing Agent — uses Content Templates and Style Guidelines

Pattern: Single orchestrator delegates to specialized agents Benefits: Clear responsibility, easy to maintain Use Cases: Customer service workflows, content creation pipelines

Collaborative Architecture

Agent 1: Intake
Agent 2: Processing
Agent 3: Quality Check
Agent 4: Delivery

There are two feedback loops on top of this sequence: Quality Check can send work back to Processing (feedback), and Delivery can send work back to Quality Check (review). Pattern: Agents pass work sequentially with feedback loops Benefits: Quality control, iterative improvement Use Cases: Document processing, data validation workflows

Specialist Pool Architecture

Router Agent routes to:
- Technical Agent — handles Issue Resolution
- Sales Agent — handles Opportunity Mgmt
- Billing Agent — handles Payment Processing
- General Agent — handles General Inquiries

Pattern: Router agent directs to appropriate specialist Benefits: Efficient routing, specialized expertise Use Cases: Customer support, ticketing systems

Use Cases & Applications

Customer Support Tiers

Architecture: Hierarchical escalation system
Agents:
  Tier 1: General Support Agent
    Tools:
      - Knowledge base search
      - FAQ lookup
      - Escalate to Tier 2 (Agent Tool)
  
  Tier 2: Technical Support Agent
    Tools:
      - System diagnostics
      - Advanced troubleshooting
      - Escalate to Tier 3 (Agent Tool)
  
  Tier 3: Engineering Support Agent
    Tools:
      - Code analysis
      - System access
      - Bug tracking integration

Benefits:
  - Appropriate expertise level
  - Efficient resource usage
  - Better resolution rates
  - Customer satisfaction

Content Creation Pipeline

Architecture: Sequential workflow with quality gates
Agents:
  1. Research Agent:
     - Gathers information from multiple sources
     - Compiles research summary
     - Passes to Content Agent
  
  2. Content Creation Agent:
     - Writes draft content
     - Applies brand guidelines
     - Passes to SEO Agent
  
  3. SEO Optimization Agent:
     - Optimizes keywords
     - Checks readability
     - Passes to Review Agent
  
  4. Quality Review Agent:
     - Fact-checks content
     - Ensures quality standards
     - Approves or sends back for revision

Benefits:
  - Specialized expertise at each stage
  - Quality assurance built-in
  - Scalable content production
  - Consistent output quality

Sales Qualification Workflow

Architecture: Decision-tree routing
Agents:
  Initial Contact Agent:
    - Collects basic information
    - Assesses prospect fit
    - Routes to appropriate specialist
    
  SMB Sales Agent (for small businesses):
    - Self-service product demos
    - Quick pricing quotes
    - Automated onboarding
  
  Enterprise Sales Agent (for large companies):
    - Custom solution design
    - Executive presentations
    - Contract negotiation support
  
  Partner Sales Agent (for resellers):
    - Partner program information
    - Margin calculations
    - Channel support

Benefits:
  - Appropriate sales approach
  - Better conversion rates
  - Efficient use of sales resources
  - Improved customer experience

Data Processing Pipeline

Architecture: Parallel processing with aggregation
Agents:
  Orchestrator Agent:
    - Receives data processing request
    - Splits work across specialist agents
    - Aggregates results
  
  Data Validation Agent:
    - Validates data format
    - Checks data quality
    - Flags anomalies
  
  Data Transformation Agent:
    - Cleanses data
    - Normalizes formats
    - Enriches data
  
  Data Analysis Agent:
    - Performs statistical analysis
    - Generates insights
    - Creates visualizations
  
  Reporting Agent:
    - Compiles final report
    - Formats output
    - Delivers results

Benefits:
  - Parallel processing for speed
  - Specialized data handling
  - Quality assurance
  - Comprehensive reporting

Context Passing & Data Flow

Input Context

When an agent invokes another agent through the Agent Tool:

{
  "input": "User's question or task",
  "context": {
    "conversation_history": "Previous messages in the thread",
    "user_information": "Relevant user data",
    "session_data": "Current session context",
    "parent_agent_findings": "Results from parent agent"
  },
  "metadata": {
    "originating_agent": "parent_agent_id",
    "conversation_id": "thread_id",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Response Format

The invoked agent returns:

{
  "output": "Agent's response or result",
  "confidence": 0.92,
  "sources": [
    {"type": "knowledge_base", "id": "doc_123"},
    {"type": "tool_execution", "tool": "database_query"}
  ],
  "suggested_actions": [
    "follow_up_question",
    "escalate_to_human"
  ],
  "execution_metadata": {
    "duration_ms": 1250,
    "tokens_used": 450,
    "tools_invoked": ["database", "api_request"]
  }
}

Best Practices

Agent Design

Single Responsibility: Design each agent with a specific, well-defined purpose for better reliability and maintainability.

Clear Objectives: Define precise goals for each agent
Focused Expertise: Limit each agent’s scope to specific tasks
Consistent Interfaces: Standardize how agents communicate
Error Handling: Implement robust error handling and fallbacks
Testing: Thoroughly test agent interactions

Context Management

Do's:
  ✅ Pass relevant context to invoked agents
  ✅ Filter unnecessary information
  ✅ Maintain conversation history
  ✅ Track agent invocation chain
  ✅ Preserve user preferences

Don'ts:
  ❌ Pass all context indiscriminately
  ❌ Lose important conversation context
  ❌ Create circular agent invocations
  ❌ Ignore context size limits
  ❌ Forget to handle context overflow

Performance Optimization

Minimize Agent Hops

Issue: Multiple agent invocations increase latency Solution: Design direct paths to specialist agents Example: Instead of A→B→C, allow A to directly invoke C when appropriate

Parallel Processing

Issue: Sequential agent calls are slow Solution: Invoke independent agents in parallel Example: Run data validation and enrichment agents simultaneously

Caching Strategies

Issue: Redundant agent invocations waste resources Solution: Cache agent responses for common queries Example: Cache translation results, frequently used analyses

Agent Selection Logic

Issue: Poor routing leads to multiple handoffs Solution: Implement smart routing based on query analysis Example: Analyze query intent before selecting specialist agent

Security Considerations

Access Control: Ensure agents only invoke other agents they have permission to access. Prevent unauthorized agent chains.

Permission Boundaries: Define clear permission boundaries
Audit Logging: Log all agent invocations for security audits
Data Privacy: Ensure sensitive data is handled appropriately
Rate Limiting: Prevent agent invocation abuse IN PROGRESS
Monitoring: Monitor for unusual agent invocation patterns

Monitoring & Analytics

Key Metrics

Track important multi-agent performance indicators:

Performance Metrics:
  - Agent invocation frequency
  - Average response time per agent
  - Success rate of agent handoffs
  - Context preservation accuracy
  - End-to-end workflow duration

Quality Metrics:
  - Task completion rate
  - Escalation rate
  - User satisfaction scores
  - Error rates per agent
  - Retry and fallback frequency

Efficiency Metrics:
  - Agent utilization rates
  - Average handoff count
  - Resource consumption per workflow
  - Cost per completed task
  - Parallelization opportunities

Workflow Visualization

Monitor agent interaction patterns:

User Query arrives at the Router Agent
Router Agent distributes queries to:
- General Agent — 40% of queries
- Technical Agent — 35% of queries
  - Escalates 20% of its queries to Engineering Escalation
- Billing Agent — 15% of queries
  - Escalates 5% of its queries to Manager Approval
- Sales Agent — 10% of queries

Troubleshooting

Common Issues

Agent Not Found

Symptoms: Target agent cannot be invoked Solutions:

Verify target agent ID is correct
Ensure target agent is active
Check agent permissions
Confirm agent exists in project or core agents

Context Loss

Symptoms: Invoked agent lacks necessary context Solutions:

Verify context is being passed correctly
Check context size limits
Ensure conversation history is maintained
Review agent input configuration

Circular Invocations

Symptoms: Agents invoking each other in loops Solutions:

Implement invocation depth limits
Add circular reference detection
Review agent tool configuration
Redesign agent workflow to prevent loops

Performance Issues

Symptoms: Slow multi-agent workflows Solutions:

Optimize agent invocation paths
Implement parallel processing
Cache frequent agent responses
Reduce unnecessary agent hops

Advanced Patterns

Consensus Building

Multiple agents collaborate to reach consensus:

Pattern: Ensemble Decision Making
Process:
  1. Orchestrator presents problem to multiple specialist agents
  2. Each agent provides independent analysis
  3. Orchestrator aggregates responses
  4. Final decision based on consensus or weighted voting

Benefits:
  - Reduced bias
  - Higher accuracy
  - Multiple perspectives
  - Quality assurance

Example Use Cases:
  - Content moderation
  - Risk assessment
  - Medical diagnosis support
  - Investment decisions

Dynamic Agent Selection

Smart routing based on query analysis:

Pattern: Intelligent Router
Process:
  1. Analyze incoming query/request
  2. Extract key attributes (complexity, domain, urgency)
  3. Score available agents against attributes
  4. Select optimal agent dynamically
  5. Monitor performance and adjust routing

Benefits:
  - Optimal resource allocation
  - Better first-contact resolution
  - Adaptive system
  - Load balancing

Example Use Cases:
  - Customer support routing
  - Task assignment
  - Dynamic pricing quotes
  - Workload distribution

Agent Specialization Layers

Progressively specialized agents:

Pattern: Expertise Pyramid
Layers:
  Layer 1 - Generalist:
    - Handles 70% of queries
    - Routes complex cases upward
    
  Layer 2 - Domain Specialists:
    - Handles 25% of queries
    - Deep domain knowledge
    
  Layer 3 - Expert Consultants:
    - Handles 5% of queries
    - Highest expertise level
    - May involve human experts

Benefits:
  - Efficient triage
  - Cost optimization
  - Quality assurance
  - Scalability

Example Use Cases:
  - Medical consultation
  - Legal advice
  - Technical support
  - Financial planning

Next Steps

Create Your First Agent Tool

Set up agent-to-agent communication

Multi-Agent Patterns

Learn advanced multi-agent architectures

Other Tools

Explore other available tools

API Reference

View the tools API documentation

​Overview

Agent Orchestration

Task Delegation

Knowledge Sharing

Workflow Automation

​Configuration Parameters

​Setup Instructions

​Agent Types

​Project Agents

​Core Agents

​Configuration Examples

​Customer Support Escalation

​Multi-Language Support

​Data Analysis Pipeline

​Content Generation Workflow

​Multi-Agent Architectures

​Hierarchical Architecture

​Collaborative Architecture

​Specialist Pool Architecture

​Use Cases & Applications

​Customer Support Tiers

​Content Creation Pipeline

​Sales Qualification Workflow

​Data Processing Pipeline

​Context Passing & Data Flow

​Input Context

​Response Format

​Best Practices

​Agent Design

​Context Management

​Performance Optimization

​Security Considerations

​Monitoring & Analytics

​Key Metrics

​Workflow Visualization

​Troubleshooting

​Common Issues

​Advanced Patterns

​Consensus Building

​Dynamic Agent Selection

​Agent Specialization Layers

​Next Steps

Create Your First Agent Tool

Multi-Agent Patterns

Other Tools

API Reference

Overview

Configuration Parameters

Setup Instructions

Agent Types

Project Agents

Core Agents

Configuration Examples

Customer Support Escalation

Multi-Language Support

Data Analysis Pipeline

Content Generation Workflow

Multi-Agent Architectures

Hierarchical Architecture

Collaborative Architecture

Specialist Pool Architecture

Use Cases & Applications

Customer Support Tiers

Content Creation Pipeline

Sales Qualification Workflow

Data Processing Pipeline

Context Passing & Data Flow

Input Context

Response Format

Best Practices

Agent Design

Context Management

Performance Optimization

Security Considerations

Monitoring & Analytics

Key Metrics

Workflow Visualization

Troubleshooting

Common Issues

Advanced Patterns

Consensus Building

Dynamic Agent Selection

Agent Specialization Layers

Next Steps