Getting Started

This page walks you through installing Auwgent, writing your first agent, and wiring it into your application. By the end you will have a running agent that accepts text input and streams structured output into your codebase.

Prerequisites

For TypeScript, Auwgent requires Node.js 18 or later.

For Python, Auwgent requires Python 3.8 or later. Install the SDK with pip install auwgent-sdk.

No other runtime dependencies are needed.

Installation

Auwgent ships as two separate packages — a CLI for compiling your agent definitions, and an SDK that your application imports at runtime.

Install the CLI globally:

npm install -g @snrraptopack/auwgent-cli

Install the SDK in your project:

TypeScript
Python

npm install @snrraptopack/auwgent-sdk

pip install auwgent-sdk

Project configuration

In the root of your project, create an auwgent.yml file. This tells the compiler where your agent definitions live, where to write the generated output, and what language to compile to.

TypeScript
Python

source: "main.agent"
output: "generated"
targets:
  - ts

source: "main.agent"
output: "generated"
targets:
  - py

source points to either a single .agent file or a folder. If you point to a folder, the compiler will pick up every .agent file inside it.

output is the folder the compiler writes generated files into.

targets is the list of languages to compile to. Currently ts (TypeScript) and py (Python) are supported.

If you prefer a folder-based source layout:

TypeScript
Python

source: "auwgent_src"
output: "generated"
targets:
  - ts

source: "auwgent_src"
output: "generated"
targets:
  - py

Your first agent

Create the file you pointed source to — in this case main.agent — and add the following:

agent Main {
    default config {
        model: gemini("gemini-2.5-flash")
        prompt: "You are a helpful assistant. Be polite."
    }
}

This is the minimal agent definition. It declares an agent named Main, assigns it a model, and gives it a system prompt. With just this, the agent accepts plain text input and returns plain text output.

Generate

Run the compiler:

auwgent generate

During development you can run it in watch mode, which recompiles automatically whenever you save changes to your .agent files:

auwgent generate --watch

After a successful compile, your generated folder will contain two files:

TypeScript
Python

generated/
  main.agent.json         ← compiled IR, describes your agent's intents and structure
  main.agent.types.ts     ← generated TypeScript types, ready to import

generated/
  main.agent.json         ← compiled IR, describes your agent's intents and structure
  main_types.py           ← generated Python types, ready to import

You will only ever work with the generated types file. The JSON file is an internal artifact — it is already embedded in the types file. You do not need to read or reference it directly.

Wiring it up

Open the generated types file and look at what was generated. You will find a named export at the bottom — auwgent — which is a factory function pre-wired to your agent definition. It is all you need to create and run your agent.

AuwgentConfig is a type that describes exactly what your agent needs to run — including which API key fields are required for the model you declared. TypeScript users will get intellisense; Python users will get full type hints. You do not need to look them up.

In your application:

TypeScript
Python

import { auwgent, AuwgentConfig } from "./generated/main.agent.types"

const config: AuwgentConfig = {
    apiKeys: {
        geminiApiKey: "YOUR_API_KEY"
    }
}

const agent = auwgent(config)

from generated.main_types import (auwgent,AuwgentBaseIntentHandler)

agent = auwgent({
    "apiKeys": {
        "geminiApiKey": "YOUR_API_KEY"
    }
})

Handling output

Auwgent uses an intent architecture. Instead of returning a single response value, the agent emits named intents as it runs. You register handlers to receive them.

For deeper details on intent contracts and payload shapes, see Intents (coming soon).

Use these as two separate handlers:

onIntent (or on_intent) for final intents.
onIntentPartial (or on_intent_partial) for streaming partial updates.

TypeScript
Python

// 1) Final intents
agent.onIntent((name, value, agent) => {
    if (name === "response_text") {
        console.log(value.text)
    }

    if (name === "error") {
        console.error(value)
    }
})

// 2) Streaming partial updates (independent of onIntent)
// You can register this with or without onIntent.
agent.onIntentPartial((name, value, agentName) => {
    if (name === "response_text") {
        process.stdout.write(value.delta ?? "")
    }
})

# 1) Final intents
class HandleIntent(AuwgentBaseIntentHandler):
    async def response_text(self, intent, agent_name):
        print(intent.get('text'))

    async def error(self, intent, agent_name: str):
        print("Error",intent)

agent.on_intent(HandleIntent)

# 2) Streaming partial updates (independent of on_intent)
# Partial handlers are class methods by intent name.
# Each method receives (value, agent_name).
class HandlePartialIntent(AuwgentBasePartialIntentHandler):
    async def response_text(self, intent, agent_name):
        print(intent.get("delta", ""), end="")

agent.on_intent_partial(HandlePartialIntent)

For this basic agent, two intents are emitted:

Intent	When it fires
`response_text`	The model has produced a text response
`error`	Something went wrong during execution

As your agent grows — custom intents, tools, workflows — new intent names will appear in this handler. The generated types will keep them typed and discoverable.

await agent.run("hello")

await agent.run("hello")

That’s it. Your agent sends the input to the model, partial text can stream through onIntentPartial, and the final message arrives via onIntent with a response_text intent. They are separate handler paths.

Next steps

The agent you built here is intentionally minimal. From here you can explore:

Tools — declare capabilities the model can invoke, and implement them as plain functions in your application
Workflows — define multi-step sequences with compile-time verified state transitions
Custom intents — shape exactly what structured output the model emits
Middleware — intercept and transform the agent’s execution pipeline