Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augmentcode.com/llms.txt

Use this file to discover all available pages before exploring further.

​
About

The Auggie TypeScript SDK provides a programmatic interface to Auggie for building custom integrations and agents in Node.js and TypeScript applications. The SDK offers two main interfaces:
  1. Agent Interaction (ACP) - Launch and communicate with a local Auggie agent process
  2. AI SDK Provider - Use Augment as a language model provider with Vercel’s AI SDK (API-only, no local installation required)

​
Installation

npm install @augmentcode/auggie-sdk

​
Agent Interaction (ACP)

⚠️ Requires Local Auggie Installation The Agent Interaction interface allows you to launch Auggie in ACP mode and communicate bidirectionally. This requires a local Auggie installation.

​
Usage

​
Basic Initialization

import { Auggie } from "@augmentcode/auggie-sdk";

// Simple initialization
const client = await Auggie.create({
  model: "sonnet4.5"
});

// Send a prompt
const response = await client.prompt("What files are in the current directory?");
console.log(response);

// Close the connection
await client.close();

​
Full Configuration

import { Auggie } from "@augmentcode/auggie-sdk";

const client = await Auggie.create({
  // Path to Auggie executable (default: "auggie")
  auggiePath: "/path/to/auggie",

  // Working directory for the Auggie process (default: process.cwd())
  workspaceRoot: "/path/to/workspace",

  // Eg: "haiku4.5" | "gpt-5" | "sonnet4.5" | "sonnet4"
  model: "sonnet4.5",

  // Allow codebase indexing (default: true)
  allowIndexing: true,

  // API key for authentication (optional)
  apiKey: "your-api-key",

  // API URL (optional)
  apiUrl: "https://your-tenant.api.augmentcode.com",

  // Custom tools to provide to Auggie (optional)
  tools: {
    // Your custom tools here
  },

  // Rule file paths (optional)
  rules: ["/path/to/rules.md"],

  // Additional CLI arguments to pass to the Auggie process (optional)
  cliArgs: ["--quiet", "--max-turns=10"]
});

// Use the client
const response = await client.prompt("Your question here");
console.log(response);

await client.close();

​
Advanced CLI Arguments

The cliArgs option allows you to pass additional command-line arguments directly to the Auggie CLI process. These arguments are appended after all SDK-generated flags, allowing you to use advanced configurations or experimental flags not exposed through standard SDK options. 
import { Auggie } from "@augmentcode/auggie-sdk";

// Pass custom CLI flags
const client = await Auggie.create({
  model: "sonnet4.5",
  cliArgs: ["--quiet", "--max-turns=10"]
});

// Arguments can use either format:
// 1. Separate flag and value: ["--retry-timeout", "60"]
// 2. Combined with equals: ["--retry-timeout=60"]
const client2 = await Auggie.create({
  model: "sonnet4.5",
  cliArgs: ["--shell=bash", "--allow-indexing"]
});
Note: Since cliArgs are appended after SDK-generated flags, they can override default values when the CLI uses a last-value-wins strategy. Refer to auggie --help for available CLI flags.

​
Output Modes

The TypeScript SDK supports multiple output modes to fit different use cases:

​
String Response (Default)

By default, the SDK returns the complete agent response as a string: 
const client = await Auggie.create({ model: "sonnet4.5" });
const response = await client.prompt("What files are in the current directory?");
console.log(response); // Full response as string

​
Answer-Only Mode

Get only the final answer after all tool calls complete, excluding intermediate reasoning: 
const finalAnswer = await client.prompt(
  "List all TypeScript files in this project",
  { isAnswerOnly: true }
);
// Returns only the final response after tool execution

​
Streaming Mode

Listen to real-time updates as the agent processes your request: 
client.onSessionUpdate((event) => {
  switch (event.update.sessionUpdate) {
    case "agent_message_chunk":
      if (event.update.content.type === "text") {
        process.stdout.write(event.update.content.text);
      }
      break;
    case "tool_call":
      console.log(`\nTool: ${event.update.title}`);
      break;
    case "tool_call_update":
      console.log("Output:", event.update.rawOutput);
      break;
  }
});

const response = await client.prompt("Your question here");

​
Custom Tools

The TypeScript SDK supports ai-sdk compatible tools, allowing you to extend Auggie with custom functionality. You can provide tools that the agent can call during execution.

​
Creating a Custom Tool

Here’s an example of a custom weather tool: 
import { Auggie } from "@augmentcode/auggie-sdk";
import { tool } from "ai";
import { z } from "zod";

// Define a custom tool
const weather_tool = tool({
  name: "get_weather",
  description: "Get the weather in a location",
  inputSchema: z.object({
    location: z.string().describe("The location to get the weather for"),
  }),
  execute: ({ location }) => {
    console.log(`\n Weather tool called for location: ${location}`);
    return `The weather in ${location} is sunny.`;
  },
});

// Initialize Auggie with the custom tool
const client = await Auggie.create({
  model: "sonnet4.5",
  tools: {
    get_weather: weather_tool,
  },
});

// The agent can now use the weather tool
const response = await client.prompt("What's the weather like in San Francisco?");
console.log(response);

await client.close();

​
Key Points

  • ai-sdk Compatible: Tools follow the Vercel AI SDK tool format
  • Zod Schemas: Use Zod for input validation and type safety
  • Automatic Discovery: The agent automatically discovers and uses available tools when relevant
  • Multiple Tools: Pass multiple tools in the tools object

​
Tool Structure

Each tool requires:
  • name - Unique identifier for the tool
  • description - Clear description of what the tool does (helps the agent decide when to use it)
  • inputSchema - Zod schema defining the tool’s input parameters
  • execute - Function that implements the tool’s logic

​
AI SDK Provider (Vercel AI SDK)

✅ No Local Auggie Required - API Only The AI SDK Provider allows you to use Augment as a language model provider with Vercel’s AI SDK. This interface only requires API credentials and works without a local Auggie installation.

​
Features

  • Compatible with generateText, streamText, and other AI SDK functions
  • Full support for tool calling (function calling) with automatic execution
  • Multi-turn conversations with context retention
  • Streaming responses for real-time output
  • Works with API credentials only (no local Auggie installation needed)

​
Quick Start

import { AugmentLanguageModel, resolveAugmentCredentials } from "@augmentcode/auggie-sdk";
import { generateText } from "ai";

// Resolve credentials from environment or ~/.augment/session.json
const credentials = await resolveAugmentCredentials();

// Create the Augment language model
const model = new AugmentLanguageModel("claude-sonnet-4-5", credentials);

// Use with AI SDK functions
const { text } = await generateText({
  model,
  prompt: "Explain TypeScript in one sentence.",
});

console.log(text);

​
Streaming Responses

import { streamText } from "ai";

const { textStream } = await streamText({
  model,
  prompt: "Write a haiku about coding.",
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}

​
Tool Calling

import { generateText, tool, stepCountIs } from "ai";
import { z } from "zod";

const weatherTool = tool({
  description: "Get the weather in a location",
  inputSchema: z.object({
    location: z.string().describe("The location to get the weather for"),
  }),
  execute: async ({ location }) => {
    return `The weather in ${location} is sunny.`;
  },
});

const { text } = await generateText({
  model,
  tools: { weather: weatherTool },
  stopWhen: stepCountIs(5),
  prompt: "What's the weather like in San Francisco?",
});

​
Multi-turn Conversations

const messages = [
  { role: "user" as const, content: "What's 2+2?" },
];

const response1 = await generateText({ model, messages });
messages.push({ role: "assistant" as const, content: response1.text });
messages.push({ role: "user" as const, content: "Multiply that by 3" });

const response2 = await generateText({ model, messages });
console.log(response2.text); // "12"

​
Authentication

The AI SDK Provider uses the same authentication methods as the rest of the SDK:
  1. Session File (Recommended) - Use credentials from ~/.augment/session.json (created by auggie login)
  2. Environment Variable - Set AUGMENT_SESSION_AUTH to the session JSON from auggie token print
  3. Direct Credentials - Pass credentials directly to AugmentLanguageModel
// Option 1: Auto-resolve from session file or environment
const credentials = await resolveAugmentCredentials();
const model = new AugmentLanguageModel("claude-sonnet-4-5", credentials);

// Option 2: Pass credentials directly
const model = new AugmentLanguageModel("claude-sonnet-4-5", {
  apiKey: "your-api-key",
  apiUrl: "https://your-tenant.api.augmentcode.com",
});