Augment ADK

A lightweight TypeScript SDK for building multi-agent workflows over the Responses API via LlamaStack. Inspired by the OpenAI Agents JS SDK, zero external runtime dependencies.

Core concepts

1. Agents: LLMs configured with instructions, tools, guardrails, and handoffs
2. Handoffs: Delegating to other agents via typed agent graphs with validation
3. Tools: Function tools, MCP tool integration, and hosted tool factories
4. Guardrails: Configurable safety checks for input and output validation
5. Human in the loop: Built-in approval store with MCP approval flow
6. Sessions: Conversation history management across agent runs
7. Tracing: Built-in tracking of agent runs for debugging and optimization
8. Streaming: SSE normalization for real-time token streaming

Explore the examples/ directory to see the SDK in action.

Get started

Supported environments

• Node.js 18 or later
• Any TypeScript runtime (Deno, Bun)

Installation

npm install @augment-adk/augment-adk

Run your first agent

import { run, LlamaStackModel } from '@augment-adk/augment-adk';

const model = new LlamaStackModel({
  clientConfig: { baseUrl: 'http://localhost:8321' },
});

const result = await run('What is the capital of France?', {
  model,
  agents: {
    assistant: {
      name: 'Assistant',
      instructions: 'You are a helpful assistant.',
    },
  },
  defaultAgent: 'assistant',
  config: {
    model: 'meta-llama/Llama-3.1-8B-Instruct',
    baseUrl: 'http://localhost:8321',
    systemPrompt: 'You are a helpful assistant.',
    enableWebSearch: false,
    enableCodeInterpreter: false,
    vectorStoreIds: [],
    vectorStoreName: '',
    embeddingModel: '',
    embeddingDimension: 384,
    chunkingStrategy: 'auto',
    maxChunkSizeTokens: 800,
    chunkOverlapTokens: 400,
    skipTlsVerify: true,
    zdrMode: false,
    verboseStreamLogging: false,
  },
});

console.log(result.content);

Optional: Chat Completions for local development

For local testing with Ollama, vLLM, or other Chat Completions providers, install the optional adapter:

npm install @augment-adk/adk-chat-completions

import { run } from '@augment-adk/augment-adk';
import { ChatCompletionsModel } from '@augment-adk/adk-chat-completions';

const model = new ChatCompletionsModel({
  clientConfig: {
    baseUrl: 'http://localhost:11434',
    token: process.env.API_KEY,
  },
});

See the chat-completions example for a complete walkthrough.

Examples

| Example | Description | |---------|-------------| | basic | Single-agent question answering | | chat-completions | Chat Completions backend via optional @augment-adk/adk-chat-completions | | multi-agent | Router + specialist agent graph with handoffs | | mcp-tools | Function tools and hosted MCP tool integration | | human-in-the-loop | Approval workflows for destructive operations | | backstage-plugin | Integrating ADK into a Backstage backend plugin |

Packages

The SDK is organized as a monorepo with focused packages:

| Package | Description | |---------|-------------| | @augment-adk/augment-adk | Batteries-included entry point (core + LlamaStack) | | @augment-adk/adk-core | Provider-agnostic core: agents, runner, tools, guardrails, approval, streaming, tracing | | @augment-adk/adk-llamastack | LlamaStack Responses API model provider | | @augment-adk/adk-chat-completions | Chat Completions adapter (optional, separate install) |

Most users should install @augment-adk/augment-adk. Advanced consumers can import individual packages for lighter bundles:

import { run, Agent } from '@augment-adk/adk-core';
import { LlamaStackModel } from '@augment-adk/adk-llamastack';

Architecture

See ARCHITECTURE.md for design decisions, extension points, and how the run loop works. Start there if you want to add a new model provider, integrate with a different framework, or understand how the codebase is structured.

Development

# Install dependencies
pnpm install

# Build all packages (in dependency order)
pnpm -r build

# Run all tests
pnpm -r test

# Type-check all packages
pnpm -r typecheck

# Lint
pnpm -r lint

Acknowledgements

We'd like to acknowledge the excellent work of the open-source community, especially:

• OpenAI Agents JS SDK (architectural inspiration)
• LlamaStack (Responses API backend)
• zod (optional schema validation)
• vitest and tsup
• pnpm

License

Apache-2.0 — see LICENSE.