# Build an augment

Canonical: https://auggy.dev/docs/build-augment
Status: Published
Package: auggy 0.5.0

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 capability**

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

> **Note: 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 augment**

```bash
auggy augment create support
```

## Where it lives

**Recommended file tree**

```
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.

> **Note: 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.ts**

```ts
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.ts**

```ts
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 run**

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

1. Open `/console/chat` and ask: Find the case about changing my delivery address.
2. Expand the `search_cases` tool call and confirm its query was validated.
3. Confirm the result includes `case_1042` and the final response does not invent another case.
4. Run 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](https://auggy.dev/docs/add-skills/markdown) |
| Peer-scoped history across turns | [Memory and knowledge](https://auggy.dev/docs/memory-and-knowledge/markdown) |
| Tools from an existing MCP server | [MCP](https://auggy.dev/docs/mcp/markdown) |
| A direct frontend or webhook entry point | [Advanced preview routes](https://auggy.dev/docs/add-http-routes/markdown) |

> **Warning: 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.

## Related

- [Add tools](https://auggy.dev/docs/add-tools/markdown)
- [Skills](https://auggy.dev/docs/add-skills/markdown)
- [Architecture](https://auggy.dev/docs/architecture/markdown)