Understanding Fabric Agent Types

Fabric Portal provides three distinct types of AI agents, each designed for different use cases and architectural patterns. This guide will help you understand when to use each type and how to build effective multi-agent systems.

Overview of Agent Types

Fabric supports three categories of agents:

System Agents - Pre-built agents for common patterns (Orchestrator, Composable)
Custom Agents - Build your own specialized agents with various frameworks

Quick Comparison

| Agent Type | Best For | Complexity | Customization | |------------|----------|------------|---------------| | Orchestrator Agent | Multi-step tasks requiring coordination | Low | Limited | | Composable Agent | Hierarchical agent systems | Medium | Medium | | Custom Agent | Specialized domain tasks | High | Full |

1. Fabric Orchestrator Agent 🎯

What is it?

The Orchestrator Agent uses a hub-and-spoke architecture to intelligently route tasks to specialized agents via the A2A (Agent-to-Agent) protocol. It acts as a central coordinator that delegates work to the best agent for each subtask.

Architecture

Loading diagram...

When to Use

✅ Use Orchestrator Agent when:

You have complex multi-step tasks that require different specialized agents
You need dynamic agent selection based on task requirements
You want automatic result consolidation from multiple agents
You're building enterprise-grade multi-agent systems

❌ Don't use when:

You have a simple single-purpose task (use Custom Agent instead)
You need agents to call other agents as tools (use Composable Agent instead)

Example Use Case

Research Report Generation:

User: "Research AI trends and create a comprehensive report"
Orchestrator routes to Research Agent → gathers papers
Orchestrator routes to Document Generator → creates report
Orchestrator routes to Task Planner → creates follow-up tasks
Orchestrator consolidates all results and returns to user

Code Example

// The Orchestrator Agent is a system agent - no code needed!
// Just use it via the UI or API

const result = await orpcClient.agents.execute({
  agentId: "orchestrator",
  message: "Research AI trends and create a comprehensive report",
  userId: session.user.id,
  organizationId: session.user.organizationId,
});

2. Fabric Composable Agent 🔗

What is it?

The Composable Agent uses a hierarchical architecture where agents can call other agents as tools. It dynamically discovers agent capabilities via A2A protocol and composes complex workflows by chaining specialized agents.

Architecture

Loading diagram...

Authentication Flow

The Composable Agent implements secure tenant context propagation for MCP credential lookup:

Loading diagram...

When to Use

✅ Use Composable Agent when:

You need hierarchical agent systems (agents calling agents)
You want dynamic tool discovery from Agent Cards
You need automatic credential lookup for MCP tools
You're building nested agent workflows

❌ Don't use when:

You need simple hub-and-spoke delegation (use Orchestrator instead)
You have a single-purpose task (use Custom Agent instead)

Example Use Case

Automated Research Pipeline:

Composable Agent discovers available agents (Research, DocGen, Linear)
Calls Research Agent as tool → gathers papers
Research Agent calls DocGen as tool → creates report
DocGen calls Notion MCP as tool → fetches template
Results flow back up the hierarchy to user

Code Example

import {
  discoverAgentTools,
  executeAgentTool,
} from "@repo/agent-core";

// Discover tools from an agent
const tools = await discoverAgentTools("http://localhost:8080");

// Execute agent as tool with tenant context
const result = await executeAgentTool(
  tools[0],
  { format: "markdown" },
  {
    userId: session.user.id,
    organizationId: session.user.organizationId,
    executionId: "exec-123",
    variables: {
      research_papers: papers,
      key_findings: findings,
    },
  }
);

Best for: Graph-based workflows, complex state management
Language: Python/TypeScript
Features: Checkpointing, streaming, custom nodes

Microsoft Agent (Semantic Kernel / AutoGen)

Best for: Azure AI integration, Microsoft ecosystem
Language: C#/Python
Features: Azure AI, Microsoft Graph, enterprise features

Pydantic AI Agent

Best for: Type-safe Python workflows, structured outputs
Language: Python
Features: Strong typing, validation, Pydantic models

Fully Custom Agent

Best for: Unique requirements, legacy integration
Language: Any (via A2A protocol)
Features: Complete flexibility, framework-agnostic

When to Use

✅ Use Custom Agent when:

You have specialized domain-specific requirements
You need full control over agent logic and state
You're integrating with specific frameworks or services
You need advanced features like graph-based reasoning

❌ Don't use when:

Standard orchestration patterns work (use Orchestrator)
You need agent-as-tool composition (use Composable)

Example: LangGraph Custom Agent

// Define your custom LangGraph agent
import { StateGraph } from "@langchain/langgraph";

const workflow = new StateGraph({
  channels: {
    messages: { value: (x, y) => x.concat(y) },
    context: { value: (x, y) => ({ ...x, ...y }) },
  },
});

workflow.addNode("research", researchNode);
workflow.addNode("analyze", analyzeNode);
workflow.addNode("report", reportNode);

workflow.addEdge("research", "analyze");
workflow.addEdge("analyze", "report");

const app = workflow.compile();

// Register as Custom Agent in Fabric
await orpcClient.agents.registry.create({
  name: "research-analyst",
  displayName: "Research Analyst",
  description: "Specialized agent for academic research analysis",
  framework: "LANGGRAPH",
  scope: "USER",
  config: {
    graphId: "research-analyst",
    model: "gpt-4o",
    systemPromptKey: "research-analyst-prompt",
  },
});