PublishedDocs / Start

Build an augment

Build one project-specific typed tool inside a custom augment.

What you will build

A support augment with one search_cases tool. During conversation, the agent uses it when a customer describes a problem without knowing the exact case ID or database query.

One focused capabilitytext

Customer message
  -> kernel -> model -> search_cases
  -> validated query -> support system
  -> structured result -> model response

Keep the first augment small

The model handles vague intent. Typed project code performs the lookup. You do not need an HTTP route, generated client, or delegated app authorization to build a useful Auggy agent.

Create the augment

Run this inside the agent project created in the previous guide.

Scaffold a custom augmentbash

auggy augment create support

Where it lives

Recommended file treetext

my-agent/
  augments/
    support/
      augment.yaml
      index.ts
      cases.ts
      support.test.ts

The generated index.ts can hold a small capability. Move support-system access into cases.ts so it remains easy to test without a model turn.

Add a skill when the description is not enough

A single-purpose tool usually needs only a clear description. When the model also needs sequencing, examples, or recovery guidance, add skills/support/SKILL.md.

Write the integration

augments/support/cases.tsTypeScript

export interface SupportCase {
  id: string;
  summary: string;
  status: "open" | "closed";
}

export async function searchCases(query: string): Promise<SupportCase[]> {
  // Replace with your existing support API or database adapter.
  return [
    {
      id: "case_1042",
      summary: `Delivery address correction matching: ${query}`,
      status: "open",
    },
  ];
}

Keep the boundary explicit

Layer	Responsibility
Tool description	Tells the model when the lookup is useful.
Zod input	Rejects missing or malformed model-provided arguments.
Integration function	Calls the support system and returns exact data.
Runtime policy	Controls which callers may see or invoke the tool.

Add a tool

The tool lets the model turn a customer's description into one validated support lookup. Its description is enough for this straightforward operation, so the augment does not need a skill yet.

augments/support/index.tsTypeScript

import { defineAugment, defineTool } from "auggy";
import { z } from "zod";
import { searchCases } from "./cases";

const SearchCases = z.object({
  query: z.string().trim().min(1),
});

export default function supportAugment() {
  return defineAugment({
    name: "support",
    type: "custom",
    tools: [
      defineTool({
        name: "search_cases",
        description: "Find support cases relevant to a vague customer request.",
        category: "support",
        input: SearchCases,
        execute: async ({ query }) =>
          JSON.stringify({ cases: await searchCases(query) }),
      }),
    ],
  });
}

Install and verify the tool

Test, install, and runbash

auggy augment test ./augments/support
auggy augment install my-agent ./augments/support
auggy doctor
auggy run

1Open /console/chat and ask: Find the case about changing my delivery address.
2Expand the search_cases tool call and confirm its query was validated.
3Confirm the result includes case_1042 and the final response does not invent another case.
4Run the augment test again after replacing the example integration with your support-system adapter.

Before you add more

If the capability needs	Add
Non-obvious sequencing, examples, or recovery	A skill
Peer-scoped history across turns	Memory and knowledge
Tools from an existing MCP server	MCP
A direct frontend or webhook entry point	Advanced preview routes

A tool is not automatically safe

Use trust policy, authorization, narrow schemas, and integration-level checks before exposing customer records or consequential actions. Model instructions are not an enforcement boundary.

Add toolsExpose typed actions the model can select during a turn and your code executes.SkillsTeach the model when and how to use an augment without loading every instruction into context on every turn.ArchitectureHow Auggy's small turn kernel and composable augments form a self-hosted agent runtime.