Basic Agents

Basic Agents Guide

Fundamentals Core Concepts

Learn the essential concepts and patterns for creating effective AI agents with AgentForce ADK.

Agent Anatomy

Every AgentForce agent consists of four core components:

Configuration

Basic agent metadata like name and type for identification and logging.

Provider & Model

The AI service and specific model that powers the agent’s intelligence.

System Prompt

Instructions that define the agent’s role, behavior, and capabilities.

User Prompt

The specific input or task the agent needs to process.

The Minimal Agent

Every agent starts with a minimal configuration that includes its name and the user prompt. All other components are optional and can be added as needed. Default model and system prompt are set inside the Agent class.

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

const output = await new AgentForceAgent({ name: "MinimalisticAgent"})
  .prompt("Hello, how can you help me?")   // the only required method
  .getResponse();

console.log(output);

Basic Agent Pattern

Here’s the fundamental structure of every AgentForce agent:

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

// 1. Configuration
const config: AgentConfig = {
  name: "MyAgent"
};

// 2. Create and configure agent
const agent = new AgentForceAgent(config)
  .useLLM("ollama", "gemma3:4b")                // Provider & Model
  .systemPrompt("You are a helpful assistant")  // System Instructions
  .prompt("Hello, what is your name?");         // User Input

// 3. Execute and get response
const response = await agent.getResponse();

// 4. Process the response
console.log(response);

Agent Configuration

Minimal Configuration

Descriptive Names

// ✅ Good - Clear purpose
const agent = new AgentForceAgent({
  name: "CustomerSupportAgent"
});

Avoid Generic Names

// ❌ Avoid - Too generic
const agent = new AgentForceAgent({
  name: "Agent1"
});

Environment Prefixes

// ✅ Good - Environment aware
const agent = new AgentForceAgent({
  name: `${process.env.NODE_ENV}-ChatAgent`
});

Provider and Model Selection

Local Models (Ollama)

// Fast, lightweight models
.useLLM("ollama", "phi4-mini:latest")    // 3.8B params
.useLLM("ollama", "gemma3:4b")           // 4B params

// Balanced performance
.useLLM("ollama", "gemma3:12b")          // 12B params (recommended)
.useLLM("ollama", "llama3.2:7b")         // 7B params

// High capability
.useLLM("ollama", "llama3.1:70b")        // 70B params
.useLLM("ollama", "mixtral:8x7b")        // Mixture of experts

Cloud Models (OpenRouter)

// Free models for development
.useLLM("openrouter", "moonshotai/kimi-k2:free")
.useLLM("openrouter", "google/gemma-2-9b-it:free")

// Premium models for production
.useLLM("openrouter", "openai/gpt-4")
.useLLM("openrouter", "anthropic/claude-3-sonnet")
.useLLM("openrouter", "meta-llama/llama-3.1-8b-instruct")

Dynamic Model Selection

function createAgent(useProduction = false) {
  const config = { name: "AdaptiveAgent" };

  return new AgentForceAgent(config)
    .useLLM(
      useProduction ? "openrouter" : "ollama",
      useProduction ? "openai/gpt-4" : "gemma3:12b"
    );
}

// Development
const devAgent = createAgent(false);

// Production
const prodAgent = createAgent(true);

System Prompts

System prompts define your agent’s personality, expertise, and behavior.

Effective System Prompt Patterns

Role Definition

.systemPrompt(`
  You are a senior software engineer with expertise in TypeScript and Node.js.
  You provide clear, practical solutions and follow best practices.
  Always include code examples in your responses.
`)

Behavioral Guidelines

.systemPrompt(`
  You are a helpful customer support agent.

  Guidelines:
  - Be empathetic and understanding
  - Ask clarifying questions when needed
  - Provide step-by-step solutions
  - Always maintain a positive tone
  - Escalate complex issues when appropriate
`)

Output Format Specification

.systemPrompt(`
  You are a data analyst. Always respond in JSON format with these fields:
  - "analysis": Your findings
  - "recommendations": Actionable suggestions
  - "confidence": Confidence level (1-10)
  - "next_steps": What to do next
`)

Domain Expertise

.systemPrompt(`
  You are a medical information assistant specializing in general health.

  Important:
  - Provide educational information only
  - Always recommend consulting healthcare professionals
  - Never provide specific medical diagnoses
  - Include reliable sources when possible
  - Use clear, accessible language
`)

System Prompt Best Practices

Be Specific

Do: “You are a Python code reviewer focusing on performance optimization”

Don’t: “You are a helpful assistant”

Set Boundaries

Do: Define what the agent should and shouldn’t do

Example: “Only provide factual information. If unsure, say so.”

Include Examples

Do: Show desired output format

Example: “Format responses like: Problem: … Solution: …”

Define Personality

Do: Set tone and communication style

Example: “Use a friendly, professional tone with technical accuracy”

User Prompts

User prompts are the specific inputs or tasks you want the agent to process.

Prompt Engineering Techniques

Clear Instructions

// ✅ Good - Specific and clear
.prompt(`
  Review this TypeScript function for performance issues:

  function processData(items: any[]) {
    return items.map(item => {
      return items.filter(x => x.id === item.id)[0];
    });
  }

  Provide specific optimization suggestions.
`)

Context Provision

// ✅ Good - Includes context
.prompt(`
  I'm building an e-commerce API with Node.js and PostgreSQL.
  I need to implement user authentication with JWT tokens.

  Requirements:
  - Secure password hashing
  - Token expiration handling
  - Role-based access control

  Please provide a complete implementation.
`)

Output Format Request

// ✅ Good - Specifies desired format
.prompt(`
  Analyze this customer feedback and provide insights in markdown format:

  "${customerFeedback}"

  Please structure your response with:
  ## Sentiment Analysis
  ## Key Themes
  ## Recommendations
  ## Action Items
`)

Dynamic Prompts

function createAnalysisAgent(data: any[], analysisType: string) {
  return new AgentForceAgent({
    name: "DataAnalyzer"
  })
    .useLLM("ollama", "gemma3:12b")
    .systemPrompt(`You are a data analyst specializing in ${analysisType} analysis.`)
    .prompt(`
      Analyze this dataset and provide insights:

      Data: ${JSON.stringify(data, null, 2)}
      Analysis Type: ${analysisType}

      Please provide:
      1. Key findings
      2. Patterns or trends
      3. Recommendations
      4. Next steps
    `);
}

// Usage
const salesAgent = createAnalysisAgent(salesData, "sales performance");
const userAgent = createAnalysisAgent(userData, "user behavior");

Agent Execution

Basic Execution Pattern

const agent = new AgentForceAgent(config)
  .useLLM("ollama", "gemma3:12b")
  .systemPrompt("You are a helpful assistant")
  .prompt("Explain quantum computing");

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

Error Handling

async function executeAgent(prompt: string) {
  try {
    const agent = new AgentForceAgent({
      name: "SafeAgent"
    })
      .useLLM("ollama", "gemma3:12b")
      .systemPrompt("You are a helpful assistant")
      .prompt(prompt)
      .debug();

    const response = await agent.output("text");

    return {
      success: true,
      response,
      timestamp: new Date().toISOString()
    };

  } catch (error) {
    console.error("Agent execution failed:", error);

    return {
      success: false,
      error: error.message,
      timestamp: new Date().toISOString()
    };
  }
}

Response Processing

async function processAgentResponse(agent: AgentForceAgent) {

  // Get different output formats
  const textResponse = await agent.output("text");
  const jsonResponse = await agent.output("json");
  const markdownResponse = await agent.output("md");

  return {
    text: textResponse,
    json: jsonResponse,
    markdown: markdownResponse
  };
}

Common Agent Patterns

Question-Answer Agent

function createQAAgent(context: string) {
  return new AgentForceAgent({
    name: "QAAgent"
  })
    .useLLM("ollama", "gemma3:12b")
    .systemPrompt(`
      You are a knowledgeable assistant with access to this context:

      ${context}

      Answer questions based on this information. If you don't know
      something from the context, say so clearly.
    `);
}

// Usage
const docAgent = createQAAgent(documentationText);
docAgent.prompt("How do I configure authentication?");

Code Review Agent

function createCodeReviewAgent(language: string) {
  return new AgentForceAgent({
    name: "CodeReviewer"
  })
    .useLLM("openrouter", "openai/gpt-4")
    .systemPrompt(`
      You are an expert ${language} code reviewer.

      For each code review, provide:
      1. Overall assessment
      2. Specific issues found
      3. Performance considerations
      4. Security concerns
      5. Best practice recommendations

      Use a constructive, educational tone.
    `);
}

// Usage
const tsReviewer = createCodeReviewAgent("TypeScript");
tsReviewer.prompt(`Review this function: ${codeSnippet}`);

Content Generation Agent

function createContentAgent(contentType: string, audience: string) {
  return new AgentForceAgent({
    name: "ContentGenerator"
  })
    .useLLM("ollama", "gemma3:12b")
    .systemPrompt(`
      You are a skilled content creator specializing in ${contentType}.
      Your target audience is ${audience}.

      Create engaging, informative content that:
      - Matches the audience's knowledge level
      - Uses appropriate tone and style
      - Includes relevant examples
      - Has clear structure and flow
    `);
}

// Usage
const blogAgent = createContentAgent("technical blog posts", "software developers");
const docsAgent = createContentAgent("API documentation", "integration developers");

Advanced Configuration

Conditional System Prompts

function createAdaptiveAgent(userLevel: 'beginner' | 'intermediate' | 'expert') {
  const systemPrompts = {
    beginner: "Explain concepts in simple terms with basic examples",
    intermediate: "Provide detailed explanations with practical examples",
    expert: "Give technical details, edge cases, and advanced considerations"
  };

  return new AgentForceAgent({
    name: "AdaptiveAgent"
  })
    .useLLM("ollama", "gemma3:12b")
    .systemPrompt(systemPrompts[userLevel]);
}

Multi-Step Agents

async function multiStepAnalysis(data: any) {
  // Step 1: Data validation
  const validationAgent = new AgentForceAgent({
    name: "DataValidator"
  })
    .useLLM("ollama", "gemma3:12b")
    .systemPrompt("Validate data quality and structure")
    .prompt(`Validate this data: ${JSON.stringify(data)}`);

  await validationAgent.run();
  const validation = await validationAgent.output("json");

  // Step 2: Analysis (only if validation passes)
  if (validation.includes('"valid": true')) {
    const analysisAgent = new AgentForceAgent({
      name: "DataAnalyzer"
    })
      .useLLM("ollama", "gemma3:12b")
      .systemPrompt("Perform comprehensive data analysis")
      .prompt(`Analyze this validated data: ${JSON.stringify(data)}`);

    await analysisAgent.run();
    return await analysisAgent.output("md");
  }

  return "Data validation failed. Cannot proceed with analysis.";
}

Debugging and Development

Debug Mode

const agent = new AgentForceAgent(config)
  .useLLM("ollama", "gemma3:12b")
  .systemPrompt("You are a helpful assistant")
  .prompt("Test prompt")
  .debug();  // Enables detailed logging

await agent.run();

Development Helpers

function createTestAgent(testName: string) {
  return new AgentForceAgent({
    name: `Test-${testName}`
  })
    .useLLM("ollama", "phi4-mini:latest")  // Fast model for testing
    .debug();
}

// Quick test
const testAgent = createTestAgent("prompt-engineering")
  .systemPrompt("Test system prompt")
  .prompt("Test user prompt");

console.log(await testAgent.output("text"));

Next Steps

API Reference

Explore the complete compatibility API reference → API Reference

Multiple Providers

Learn advanced provider usage and switching strategies → Provider Guide

You now have a solid foundation in AgentForce ADK agent fundamentals. These patterns will serve as building blocks for more complex agent workflows and applications!