AgentForceAgent

AgentForceAgent

AgentForceAgent Main Class Core API

The AgentForceAgent class is the core component of the AgentForce ADK, providing a fluent API for configuring and executing AI agents with various LLM providers, tools, skills, and MCP (Model Context Protocol) integrations.

AgentConfig

The constructor accepts an AgentConfig object with the following properties:

• name (string): Required - Unique identifier for the agent
• tools? (ToolType[]): Optional array of built-in tools available to the agent
• skills? (string[]): Optional array of skill file paths to auto-load
• mcps? (string[]): Optional array of MCP server names (local and remote)
• mcpConfig? (string): Optional path to agent-specific MCP configuration
• assetPath? (string): Optional base path for agent assets and resources
• logger? (AgentForceLogger): Optional custom logger instance

Configuration Methods

Method

Type

Required

Description

.useLLM()

Chainable

Optional

Configure the LLM provider (ollama, openrouter, google, etc.), model, and parameters

.systemPrompt()

Chainable

Optional

Set system instructions that define the agent's behavior, role, and capabilities

.withTemplate()

Chainable

Optional

Load Handlebars templates with data substitution for dynamic prompts

.debug()

Chainable

Optional

Enable debug logging for configuration, execution, and troubleshooting

MCP Integration Methods

Method

Type

Required

Description

.addMCP()

Chainable

Optional

Add MCP servers at runtime - supports both local command-based and remote SSE servers

Task & Prompt Methods

Method

Type

Required

Description

.prompt()

Chainable

Required

Set the main user prompt - the primary instruction for the agent

.task()

Chainable

Optional

Add sequential tasks for complex multi-step workflows and processes

Execution Methods

Method

Type

Required

Description

.getResponse()

Terminal • Async

Optional

Execute agent and return the raw LLM response as a string

.output()

Terminal • Async

Optional

Execute agent and return formatted output (text, json, md, yaml, html)

.saveToFile()

Terminal • Async

Optional

Execute agent and save the response to a file with automatic format detection

Method Categories

Configuration Methods

Chainable - Configure agent behavior

• .useLLM() - Provider & model
• .systemPrompt() - System instructions
• .withTemplate() - Template loading
• .debug() - Debug logging

Extension Methods

Chainable - Extend capabilities

• .addMCP() - MCP server integration
• Tools & Skills via AgentConfig
• Runtime capability enhancement

Task Methods

Chainable - Define work

• .prompt() - Main user prompt
• .task() - Sequential tasks
• Multi-step workflow support

Execution Methods

Terminal - Get results

• .getResponse() - Raw response
• .output() - Formatted output
• .saveToFile() - File output

Method Types

• Chainable: Returns the agent instance for fluent method chaining
• Terminal: Executes the agent and returns results (ends the chain)
• Async: Returns a Promise and must be awaited

Quick Start Examples

Basic Agent

import { AgentForceAgent } from '@agentforce/adk';

const agent = new AgentForceAgent({ name: "MyAgent" })
  .useLLM("ollama", "phi4-mini:latest")
  .systemPrompt("You are a helpful TypeScript expert")
  .prompt("Explain the key benefits of TypeScript over JavaScript");

const response = await agent.getResponse();
console.log(response);

Agent with MCP Integration

import { AgentForceAgent } from '@agentforce/adk';

const agent = new AgentForceAgent({
  name: "DocsAgent",
  mcps: ["filesystem", "agentforce-adk-docs"] // Local and remote MCP servers
})
  .addMCP({
    name: "custom-docs",
    type: "sse",
    url: "https://gitmcp.io/your-org/your-repo"
  })
  .useLLM("openrouter", "z-ai/glm-4.5v")
  .systemPrompt("You are a documentation expert with access to code and docs")
  .prompt("Analyze the codebase structure and create API documentation");

const documentation = await agent.output("md");

Agent with Tools and Skills

import { AgentForceAgent, type AgentConfig } from '@agentforce/adk';

const config: AgentConfig = {
  name: "FullStackAgent",
  tools: ["fs_read_file", "fs_write_file", "web_fetch"],
  skills: ["full-stack-development", "api-design"],
  assetPath: "./agent-assets"
};

const agent = new AgentForceAgent(config)
  .useLLM("google", "gemini-2.5-pro")
  .systemPrompt("You are a full-stack development expert")
  .withTemplate("./templates/project-setup.hbs", {
    projectName: "MyApp",
    framework: "Next.js"
  });

const projectPlan = await agent.saveToFile("project-plan.md");

Fluent API Pattern

The AgentForceAgent follows a fluent API pattern where most methods return this for chaining:

// All these methods are chainable
const agent = new AgentForceAgent({ name: "ChainedAgent" })
  .useLLM("ollama", "gpt-oss")           // Configure provider
  .addMCP("filesystem")                     // Add MCP capability
  .systemPrompt("You are an expert...")    // Set behavior
  .withTemplate("./template.hbs", data)    // Load template
  .prompt("Analyze this code...")          // Set task
  .debug();                                // Enable debugging

// Terminal methods end the chain and execute
const result = await agent.output("json");  // Execute and get result

Error Handling

All methods include built-in error handling that maintains the fluent API:

try {
  const agent = new AgentForceAgent({ name: "SafeAgent" })
    .useLLM("ollama", "gpt-oss")
    .addMCP("filesystem")
    .systemPrompt("You are a helpful assistant")
    .prompt("Help me with this task")
    .debug();

  const response = await agent.output("text");
  console.log("Success:", response);
} catch (error) {
  console.error("Agent Error:", error.message);
  // Handle provider errors, MCP connection issues, etc.
}