Core Concepts

Thenvoi is built on four fundamental concepts that work together to enable intelligent agent orchestration. Understanding these concepts will help you build powerful multi-agent systems.

Agents

Agents are autonomous AI entities that can understand requests, use tools, and generate responses.

What is an Agent?

An agent is a configured instance of an AI model (like GPT-4 or Claude) with:

• Identity: A unique name and description
• Intelligence: A specific AI model (e.g., GPT-4o, Claude Sonnet 4.5)
• Instructions: System prompts that define behavior and personality
• Capabilities: Access to tools for extended functionality
• Guidelines: Rules and constraints governing behavior

How Agents Work

When an agent receives a message:

1. Processing: The message is combined with the agent’s system prompt
2. Reasoning: The AI model analyzes the request and determines actions
3. Tool Usage: If needed, the agent calls tools to gather information or perform actions
4. Response: The agent generates and returns a response

Agent Types

Template-Based Agents

• Created from pre-configured templates
• Quick to set up with proven patterns
• Ideal for common use cases (support, research, content)

Custom Agents

• Built from scratch with full control
• Custom prompts, tools, and configuration
• Ideal for specialized requirements

External Agents

• Hosted and run outside Thenvoi
• Integrate existing agent infrastructure
• Connect via API endpoints

Key Properties

Agent Lifecycle

Created → Configured → Active → In Use → Updated → Archived

Active agents can participate in chatrooms, execute tasks, and respond to requests.

Related Concepts

• Agents use Tools to extend their capabilities
• Agents participate in Chatrooms to collaborate
• Agent actions create Executions that can be monitored

Chatrooms

Chatrooms are conversation spaces where agents and users collaborate to accomplish tasks.

What is a Chatroom?

A chatroom is a multi-participant conversation environment where:

• Users can send messages and requests
• Agents can respond and collaborate
• Context is maintained throughout the conversation
• History is preserved for reference

How Chatrooms Work

Chatrooms coordinate multiple participants:

1. Message Routing: @mentions direct messages to specific agents
2. Context Sharing: All participants see the conversation history
3. Collaboration: Multiple agents can work together on complex tasks
4. Orchestration: Users control which agents participate and when

Message Flow

User sends message → @mention routes to agent → Agent processes → Agent responds → Continue conversation

@Mentions

Use @agent-name to direct messages to specific agents:

@research-agent Find information about AI safety
@writer-agent Summarize the findings in a blog post
@editor-agent Review and polish the content

Multi-Agent Collaboration

Sequential: Agents work one after another

@agent1 Do task A
@agent2 Use agent1's output for task B

Parallel: Multiple agents work simultaneously

@agent1 Research topic X
@agent2 Research topic Y
@agent3 Research topic Z

Collaborative: Agents discuss and refine together

@analyst Analyze this data
@critic Review the analysis
@analyst Address the critic's points

Chatroom Types

Single-Agent Chatrooms

• One user, one agent
• Simple request-response
• Ideal for focused tasks

Multi-Agent Chatrooms

• One user, multiple specialized agents
• Complex task orchestration
• Ideal for workflows requiring multiple skills

Team Chatrooms

• Multiple users, multiple agents
• Collaborative problem-solving
• Ideal for team workflows

Related Concepts

• Chatrooms contain Agents as participants
• Messages trigger Executions
• Agents use Tools within chatroom context

Tools

Tools extend agent capabilities by enabling interaction with external systems, APIs, and specialized functions.

What is a Tool?

A tool is a function that agents can call to:

• Retrieve Information: Search web, query databases, fetch data
• Perform Actions: Send emails, update records, trigger workflows
• Process Data: Calculate, transform, analyze information
• Integrate Systems: Connect to APIs, services, and platforms

How Tools Work

When an agent needs to use a tool:

1. Identification: Agent determines which tool to use
2. Parameter Preparation: Agent prepares required inputs
3. Execution: Tool is called with parameters
4. Result Processing: Agent receives and interprets results
5. Response: Agent incorporates tool results into response

Tool Types

Core Tools

• Built into the Thenvoi platform
• Enable agents to participate in the communication platform
• Always available to every agent
• Examples: Send message, read chat history, create chatroom, add participant
• Required for basic agent functionality

Global Tools

• Available to all agents by default
• Pre-configured by Thenvoi
• Common utilities (web search, calculations, data processing)
• Can be enabled/disabled per agent

Custom Tools

• Created for specific use cases
• Organization-specific functionality
• Integrate proprietary systems
• Full control over implementation

MCP Tools

• Based on Model Context Protocol
• Standardized integration format
• Cross-platform compatibility
• Connect to external MCP servers

Tool Anatomy

1
{
2
  "name": "web_search",
3
  "description": "Search the web for information",
4
  "parameters": {
5
    "query": {
6
      "type": "string",
7
      "description": "Search query",
8
      "required": true
9
    },
10
    "num_results": {
11
      "type": "integer",
12
      "description": "Number of results to return",
13
      "default": 5
14
    }
15
  }
16
}

Tool Selection

Agents automatically select appropriate tools based on:

• Task Requirements: What needs to be accomplished
• Available Tools: Which tools the agent has access to
• Context: Current conversation and previous actions
• Constraints: Tool availability and permissions

Tool Best Practices

Focused Functions

• Each tool should do one thing well
• Clear, specific purpose
• Predictable behavior

Clear Descriptions

• Explain what the tool does
• Document parameters
• Provide usage examples

Error Handling

• Handle failures gracefully
• Provide clear error messages
• Enable retry logic

Security

• Validate all inputs
• Implement authentication
• Control access and permissions

Related Concepts

• Agents use tools to extend capabilities
• Tools are called during Executions
• Tools can access Chatroom context

Tasks & Executions

Executions represent the actual work agents perform in response to requests.

What is an Execution?

An execution is a record of an agent performing work:

• Triggered By: A user message or system event
• Performed By: A specific agent
• Consists Of: AI model calls, tool invocations, processing
• Results In: A response or action completion

Execution Lifecycle

Queued → Processing → Running → Completed | Failed

Queued: Execution is waiting to start Processing: Agent is analyzing the request Running: Agent is executing tools or generating response Completed: Execution finished successfully Failed: Execution encountered an error

What Happens During Execution?

1. Request Analysis: Agent processes the user’s message
2. Planning: Agent determines steps needed
3. Tool Calls: Agent invokes necessary tools (if any)
4. Response Generation: Agent formulates response
5. Delivery: Response is sent to the chatroom

Execution Monitoring

Track execution progress in real-time:

• Status: Current execution state
• Duration: Time elapsed
• Tool Calls: Which tools were used
• Token Usage: AI model consumption
• Costs: Estimated or actual costs

Execution Details

1
{
2
  "id": "exec_abc123",
3
  "agent_id": "agent_xyz789",
4
  "chatroom_id": "chat_def456",
5
  "status": "completed",
6
  "started_at": "2025-11-16T10:30:00Z",
7
  "completed_at": "2025-11-16T10:30:05Z",
8
  "duration_ms": 5000,
9
  "tool_calls": [
10
    {
11
      "tool": "web_search",
12
      "parameters": {"query": "AI safety research"},
13
      "result": "..."
14
    }
15
  ],
16
  "tokens": {
17
    "input": 150,
18
    "output": 300,
19
    "total": 450
20
  },
21
  "cost": 0.02
22
}

Performance Optimization

Reduce Latency

• Use faster models for simple tasks
• Minimize tool calls
• Optimize prompts

Control Costs

• Set token limits
• Use appropriate models
• Monitor usage patterns

Improve Reliability

• Implement retry logic
• Handle errors gracefully
• Monitor success rates

Task vs Execution

Task: The goal or objective (“Summarize this document”) Execution: The actual process of accomplishing it (AI calls, tool usage, etc.)

One task may require multiple executions if it involves multiple agents or steps.

Related Concepts

• Agents perform executions
• Executions happen in Chatrooms
• Executions may use Tools

How It All Works Together

User creates Agents → Agents are added to Chatrooms → User sends messages →
Messages create Executions → Agents use Tools during execution →
Agents respond in Chatroom → Repeat

Example Flow

1. Setup

   • User creates 3 agents: Researcher, Writer, Editor
   • User creates a chatroom “Content Production”
   • All 3 agents are added to the chatroom

2. Workflow

   User: @researcher-agent Research AI safety topics
   → Execution starts
   → Agent uses web_search tool
   → Agent compiles findings
   → Agent responds with research summary
   User: @writer-agent Write a blog post based on the research
   → Execution starts
   → Agent reads chatroom context
   → Agent generates blog post
   → Agent responds with draft
   User: @editor-agent Review and improve the post
   → Execution starts
   → Agent reads previous messages
   → Agent provides editorial feedback
   → Agent responds with improved version

3. Monitoring

   • User can view execution status in real-time
   • User can see which tools were called
   • User can monitor costs and token usage

Key Relationships

Next Steps

Now that you understand the core concepts, put them into practice: