.saveToFile()

.saveToFile()

AgentForceAgent Execution Method Asynchronous

Execute the agent and save the response to a file with the format automatically determined by the file extension. This is a execution method that triggers agent execution and returns the file path where the content was saved - not the agent instance for chaining.

Signature

saveToFile(fileName: string): Promise<string>

Parameters

Parameter

Type

Default

Description

fileName

string

undefined

The filename to save to. Extension determines format: .txt (text), .json (JSON), .md (markdown)

Returns

Returns a Promise<string> containing the full file path where the content was saved.

Note

This is an execution method - it executes the agent and saves the response to a file, ending the method chain. The file format is determined by the file extension.

Examples:

Basic Usage

Text File (.txt)

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

const agent = new AgentForceAgent({
  name: "QuestionAgent"
})
  .useLLM("ollama", "gemma3:4b")
  .systemPrompt("You are a helpful assistant")
  .prompt("What is the capital of France?");

const filePath = await agent.saveToFile("answer.txt");
console.log(`Response saved to: ${filePath}`);

// File content format:
// === Agent QuestionAgent Output (Text Format) ===
// System: You are a helpful assistant
// User: What is the capital of France?
// Response: Paris is the capital of France.

JSON File (.json)

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

const agent = new AgentForceAgent({
  name: "CodeGenerator"
})
  .systemPrompt("You are a TypeScript expert")
  .useLLM("google", "gemini-1.5-flash")
  .prompt("Create a function to validate email addresses");

const filePath = await agent.saveToFile("code-response.json");
console.log(`Structured data saved to: ${filePath}`);

// File content format:
// {
//   "agent": "CodeGenerator",
//   "provider": "google",
//   "model": "gemini-1.5-flash",
//   "systemPrompt": "You are a TypeScript expert",
//   "userPrompt": "Create a function to validate email addresses",
//   "response": "function validateEmail(email: string): boolean { ... }",
//   "timestamp": "2024-03-15T10:30:00.000Z"
// }

Markdown File (.md)

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

const agent = new AgentForceAgent({
  name: "DocumentationAgent"
})
  .systemPrompt("You are a technical writer. Format responses as clean markdown")
  .useLLM("openrouter", "mistralai/mistral-small")
  .prompt("Write a guide on REST API best practices");

const filePath = await agent.saveToFile("api-guide.md");
console.log(`Documentation saved to: ${filePath}`);

// File content format: Clean markdown response only
// # REST API Best Practices
//
// ## 1. Use HTTP Status Codes Correctly
// ...

Real-World Examples

Code Generation with Save

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

const agent = new AgentForceAgent({
  name: "ComponentGenerator",
  tools: ["fs_read_file"]
})
  .systemPrompt("You are a React expert. Generate production-ready TypeScript components")
  .useLLM("google", "gemini-1.5-pro")
  .prompt("Read the design system file and create a Button component with all variants");

// Save as markdown for documentation
const docPath = await agent.saveToFile("components/Button.md");
console.log(`Component documentation: ${docPath}`);

// Save as JSON for metadata
const metaPath = await agent.saveToFile("components/Button-meta.json");
console.log(`Component metadata: ${metaPath}`);

Data Analysis Pipeline

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

const agent = new AgentForceAgent({
  name: "DataAnalyst",
  tools: ["fs_read_file"]
})
  .systemPrompt("You are a data analyst. Provide detailed insights with charts and recommendations")
  .useLLM("ollama", "qwen3-coder-tool", {
    appendToolResults: true,
    maxToolRounds: 3
  })
  .prompt("Read 'data/sales-q4.csv' and generate a comprehensive analysis report");

// Save analysis as markdown report
const reportPath = await agent.saveToFile("reports/q4-analysis.md");
console.log(`Analysis report: ${reportPath}`);

// Save raw data as JSON for further processing
const dataPath = await agent.saveToFile("reports/q4-data.json");
console.log(`Raw analysis data: ${dataPath}`);

Batch Processing

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

class BatchProcessor {
  static async processPrompts(prompts: string[], baseFileName: string) {
    const results: string[] = [];

    for (let i = 0; i < prompts.length; i++) {
      const agent = new AgentForceAgent({
        name: `BatchAgent${i + 1}`
      })
        .useLLM("ollama", "gemma3:4b")
        .systemPrompt("You are a helpful assistant")
        .prompt(prompts[i]);

      const fileName = `${baseFileName}-${i + 1}.txt`;
      const filePath = await agent.saveToFile(fileName);
      results.push(filePath);

      console.log(`Processed prompt ${i + 1}/${prompts.length} → ${filePath}`);
    }

    return results;
  }
}

// Usage
const prompts = [
  "Explain machine learning",
  "Describe blockchain technology",
  "What is quantum computing?"
];

const savedFiles = await BatchProcessor.processPrompts(prompts, "batch-response");
console.log("All files saved:", savedFiles);

File Format Processing

// Automatically choose format based on use case
async function saveAgentResponse(agent: AgentForceAgent, purpose: string) {
  const timestamp = new Date().toISOString().split('T')[0];

  switch (purpose) {
    case 'documentation':
      return await agent.saveToFile(`docs/${timestamp}-guide.md`);

    case 'data':
      return await agent.saveToFile(`data/${timestamp}-analysis.json`);

    case 'log':
      return await agent.saveToFile(`logs/${timestamp}-output.txt`);

    default:
      return await agent.saveToFile(`output/${timestamp}-response.txt`);
  }
}

// Usage
const docAgent = new AgentForceAgent({ name: "DocAgent" })
  .prompt("Create API documentation");

const filePath = await saveAgentResponse(docAgent, 'documentation');
console.log(`Saved to: ${filePath}`);

File Format Details

Parameter

Type

Default

Description

.txt

Text Format

Structured

Includes agent metadata, system prompt, user prompt, and response in readable format

.json

JSON Format

Complete

Full structured data with all agent configuration, prompts, response, and timestamp

.md

Markdown Format

Response Only

Clean markdown containing only the agent's response content

Use Cases

Documentation Generation

Format: .md files

Best for: API docs, guides, tutorials, technical writing

Example: Generate clean markdown documentation from code analysis

Data Export

Format: .json files

Best for: Structured data, analysis results, API responses

Example: Save analysis results with full metadata for processing

Log & Debug

Format: .txt files

Best for: Debugging, audit trails, complete interaction logs

Example: Save full agent interactions for troubleshooting

Batch Processing

Format: Multiple formats

Best for: Automated workflows, report generation, bulk operations

Example: Process multiple prompts and save results systematically

Best Practices

✅ Good Practices

// Use descriptive filenames with timestamps
const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
const filePath = await agent.saveToFile(`analysis-${timestamp}.json`);

// Choose appropriate format for content type
const documentationAgent = agent.saveToFile("guide.md");     // For readable content
const dataAgent = agent.saveToFile("results.json");         // For structured data
const debugAgent = agent.saveToFile("debug.txt");           // For debugging info

// Organize files in directories
await agent.saveToFile("reports/quarterly-analysis.md");
await agent.saveToFile("data/processed-results.json");
await agent.saveToFile("logs/execution-log.txt");

// Handle file paths properly
const fullPath = await agent.saveToFile("output.json");
console.log(`File saved at: ${fullPath}`);

❌ Common Issues

// ❌ Trying to chain after saveToFile()
const result = await agent
  .prompt("Hello")
  .saveToFile("output.txt")
  .prompt("Follow up"); // Error: saveToFile() is terminal

// ❌ Unsupported file extensions
await agent.saveToFile("output.csv"); // Error: Only .txt, .json, .md supported

// ❌ Empty or invalid filename
await agent.saveToFile(""); // Error: Filename must be non-empty string
await agent.saveToFile(123); // Error: Filename must be string

// ❌ Not handling async properly
const path = agent.saveToFile("output.txt"); // Missing await
console.log(path); // Logs Promise object

Error Handling

Caution

The method handles errors gracefully and includes comprehensive validation.

try {
  const agent = new AgentForceAgent({
    name: "FileAgent",
    tools: ["fs_read_file"]
  })
    .systemPrompt("You are a file processor")
    .prompt("Process the configuration file");

  const filePath = await agent.saveToFile("results.json");
  console.log(`Successfully saved to: ${filePath}`);

} catch (error) {
  if (error.message.includes("Unsupported file extension")) {
    console.error("Use .txt, .json, or .md extensions");
  } else if (error.message.includes("Failed to write file")) {
    console.error("File system error:", error.message);
  } else if (error.message.includes("Filename must be")) {
    console.error("Invalid filename provided");
  } else {
    console.error("Unexpected error:", error.message);
  }
}

Common Error Messages:

• Filename must be a non-empty string - Invalid filename parameter
• Unsupported file extension. Use .txt, .json, or .md - Wrong file extension
• Failed to write file: [reason] - File system write errors

Related Methods

• .getResponse() - Execute and return raw response string
• .output() - Execute and return structured output with format control
• .run() - Execute multi-step task workflows
• .prompt() - Set the main user prompt

See Also

• Execution Methods Guide - Choosing the right execution method
• File Handling Guide - Working with file outputs
• Batch Processing Examples - Processing multiple agents
• Error Handling Guide - Handling file and execution errors