Agent

The Agent class is the primary building block in the Loom framework. It represents an AI assistant with a specific purpose, capable of using tools and generating responses.

Creating an Agent

import { Agent } from "loom-agents";

const agent = new Agent({
  name: "Researcher",
  purpose: "Find and summarize information",
  model: "gpt-4o",
  tools: [
    // Tool definitions
  ],
  web_search: {
    enabled: true,
    config: {
      search_context_size: "medium",
    },
  },
});

Agent Configuration

The AgentConfig interface defines the available configuration options:

interface AgentConfig {
  name: string; // Required: Unique name for the agent
  purpose: string; // Required: Defines the agent's objective
  sub_agents?: Agent[]; // Optional: Sub-agents that can be called
  tools?: ToolCall[]; // Optional: Tools the agent can use
  model?: string; // Optional: Default is 'gpt-4o'
  mcp_servers?: (MCPServerSSE | MCPServerStdio)[];
  web_search?: WebSearchConfig; // Optional: Web search configuration
  timeout_ms?: number; // Optional: Default is 60000ms (1 minute)
  client_config?: ClientOptions; // Optional: A custom OpenAI ClientOptions object for this Agent
  api?: "completions" | "responses"; // Optional: Force this client to use a different API than the Loom global config
}

Agent Request and Response

When running an agent, you can use a simple string or a request object:

// AgentRequest interface
interface AgentRequest {
  context: T[]; // Conversation context
}

// AgentResponse interface
interface AgentResponse {
  status: string; // "completed", "error", etc.
  final_message: string; // The final output message
  context: T[]; // The updated conversation context
}

Running an Agent

Agents can process string inputs or more complex request objects:

// Simple string input
const result = await agent.run("Find information about quantum computing");

// Context-aware request
const result = await agent.run(
  {
    context: [
      {
        role: "user",
        content: "What can you tell me about quantum computing?",
      },
      {
        role: "assistant",
        content:
          "Quantum computing is a type of computing that uses quantum phenomena...",
      },
      { role: "user", content: "How does it compare to classical computing?" },
    ],
  },
  optionalTraceObject // Optional: For observability
);

Working with MCP Servers

Loom supports integrating with external tools using the Model Context Protocol (MCP), a standard that allows third-party applications and services to provide context and capabilities to LLMs.

You can use two types of MCP connections:

• MCPServerSSE – Connects to an MCP tool server over Server-Sent Events
• MCPServerStdio – Connects to a local MCP tool server via stdio

Example: Connecting to MCP Servers

import { Agent, MCPServerSSE, MCPServerStdio } from "loom-agents";

const researchAgent = new Agent({
  name: "MCP Tool Runner",
  purpose: "Run a connected MCP tool!",
  mcp_servers: [
    new MCPServerSSE(new URL("http://localhost:3001/sse")),
    new MCPServerStdio("bun", ["stdio.ts"]),
  ],
});

With this configuration, your agent can call tools exposed by the connected MCP servers seamlessly.

Defining Tools

Tools allow agents to interact with external systems or perform specialized tasks:

const tools = [
  {
    name: "fetchWeather",
    description: "Get current weather for a location",
    parameters: {
      location: {
        type: "string",
        description: "City name or coordinates",
      },
    },
    callback: async ({ location }) => {
      // Implementation to fetch weather data
      return { temperature: 72, conditions: "sunny" };
    },
  },
];

Agents as Tools

Sub agents are great, but sometimes we need to leverage the power of an Agent, while not fully influencing the context of our whole orchestration, that’s where using Agents as Tools comes in.

const translationAgent = new Agent({
  name: "Translation Agent",
  purpose:
    "I translate text into different languages, just let me know the language you want to translate to.",
});

const greetingAgent = new Agent({
  name: "Greeting Agent",
  purpose: "Generate a greeting",
  tools: [
    translationAgent.asTool({
      request: {
        type: "string",
        description: `The text to translate`,
      },
      language: {
        type: "string",
        description: `The language to translate to`,
      },
    }),
  ],
});

Advanced Agent Model Configuration

Some model providers make models that are better for certain tasks, so we need a way to Loom configurations to work with these providers.

const deepseekAgent = new Agent({
  name: "DeekSeek",
  purpose: "Are you deepseek or chatgpt? You tell me!",
  model: "deepseek-chat",
  api: "completions", // we need to override this specific model to use the completions api since deekseek doesn't support responses.
  client_config: { // this will create a deepseekAgent specific OpenAI client.
    baseURL: "https://api.deepseek.com",
    apiKey: "sk-",
  },
});

Using Web Search

Agents can perform web searches when configured:

const agent = new Agent({
  // ... other config
  web_search: {
    enabled: true,
    config: {
      search_context_size: "high", // 'high', 'medium', or 'low'
      user_location: {
        type: "approximate",
        country: "US",
        city: "San Francisco",
        region: "CA",
      },
    },
  },
});

Composing with Sub-agents

Agents can delegate tasks to specialized sub-agents:

const mathAgent = new Agent({
  name: "MathExpert",
  purpose: "Solve complex math problems",
  // ... other config
});

const researchAgent = new Agent({
  name: "Researcher",
  purpose: "Find and summarize information",
  sub_agents: [mathAgent],
  // ... other config
});

// The researchAgent can now call mathAgent for math problems

Related

• Runner: Orchestrates agent execution with enhanced context management
• Trace: Provides structured observability for agent operations
• Loom: Global configuration for OpenAI settings and API preferences