Using Azad ¶

This guide explains how to install, configure, and use Azad for development tasks.

Installation ¶

There are two main ways to install and run Azad:

Method 1: Using Poetry (Recommended for Development/All Platforms)¶

This method requires Python (>=3.13, <3.14) and Poetry.

Clone the repository:

git clone <repository-url>
cd azad

Install dependencies:
```
poetry install
```
This sets up a virtual environment with all necessary packages. You can then run Azad using poetry run azad ... (see Usage section).

Method 2: Pre-built Linux Executable (from GitHub Releases)¶

For Linux users who prefer not to install Python/Poetry or clone the repository, a pre-built executable is automatically created for tagged releases.

Go to the Releases page of the Azad repository on GitHub.
Find the desired release tag (e.g., v1.0.4).
Download the azad-linux-x64.zip file from the assets.
Unzip the file: unzip azad-linux-x64.zip
Navigate into the created azad directory: cd azad
Make the binary executable: chmod +x azad
Run the executable directly: ./azad --help, ./azad start, etc.

Note: This executable is built on Ubuntu and should work on most modern Linux distributions. It bundles necessary dependencies but might have specific system library requirements.

Configuration ¶

Azad can be configured via a configuration file, environment variables, and command-line arguments.

Configuration File (`config.ini`)¶

Default Location: ~/.config/azad/config.ini
Custom Location: Specify using the --config argument with azad start.

Example config.ini:

[daemon]
interface = 127.0.0.1
port = 8765
protocol = ws

[logging]
level = INFO
directory = ~/.local/share/azad/logs

[defaults]
model_api_key = your_default_api_key_here
model_name = claude-3-5-sonnet-latest
# model_endpoint_url = (Optional: For custom endpoints)
dialect_name = xml
# dialect_options = {"use_cdata": true} # Example for XML

Environment Variables ¶

ANTHROPIC_API_KEY: Can be used to set the default API key (overridden by --api-key and [defaults] model_api_key). Other provider keys might be supported via LiteLLM's environment variable handling.

Command-Line Arguments ¶

Arguments passed to azad start (like --port, --api-key, --log-level) override settings from environment variables and configuration files.

Command-Line Interface ¶

The primary way to interact with Azad is through its command-line interface.

Starting the Agent Daemon ¶

The agent runs as a background daemon process, listening for connections (e.g., from a VS Code extension or other client).

poetry run azad start [options]

Common Options:

--config <path>: Specify a custom configuration file path.
--interface <ip>: Network interface to bind to (default: all interfaces).
--port <number>: Port to listen on (default: 8765).
--log-level <LEVEL>: Set logging level (e.g., DEBUG, INFO, PROD).
--api-key <key>: Set the default AI model API key (overrides config/env).

The daemon will run until stopped. It manages its process ID in logs/azad.pid.

Stopping the Agent Daemon ¶

poetry run azad stop

This command reads the PID from logs/azad.pid and sends signals to gracefully stop the running daemon process.

Generating TypeScript Client (Introspection)¶

Generate a TypeScript client library based on the agent's current capabilities:

poetry run azad introspect [options]

Common Options:

--output <dir>: Directory to output the generated client (default: azad-ts-client).
--verbose or -v: Enable detailed output during generation.
--methods <list>: Comma-separated list of specific agent methods to include.

Getting Help ¶

poetry run azad --help
poetry run azad start --help
poetry run azad introspect --help

Azad is designed to be used with client applications that connect to the agent daemon. The most common client is the VS Code extension, but you can also create your own clients using the generated TypeScript client library.

VS Code Extension ¶

The VS Code extension provides a graphical interface for interacting with Azad. It allows you to:

Start and stop the agent daemon
Send tasks to the agent
View the agent's responses
Approve or reject tool calls
View the agent's progress

Custom Clients ¶

You can create your own clients using the generated TypeScript client library. The library provides a type-safe interface for communicating with the agent daemon.

To generate the client library:

poetry run azad introspect --output my-client

Then, in your TypeScript/JavaScript project:

import { AzadClient } from './my-client';

const client = new AzadClient('ws://localhost:8765');

// Connect to the agent
await client.connect();

// Send a task
const task = await client.createTask({
  description: 'Create a simple React component',
  config: {
    model_name: 'claude-3-5-sonnet-latest',
    dialect_name: 'xml',
  },
});

// Listen for events
client.on('message', (message) => {
  console.log('Received message:', message);
});

// Approve a tool call
client.approveTool(toolCallId);

// Close the connection
client.close();

Development Workflow ¶

Here's a typical workflow for using Azad in your development process:

Start the agent daemon:

poetry run azad start

Connect with a client (VS Code extension or custom client)
Send a task to the agent, such as:
Creating a new component
Fixing a bug
Refactoring code
Adding tests
Review and approve tool calls as the agent works on the task
Provide feedback if needed
Review the final result when the agent completes the task
Stop the agent daemon when you're done:
```
poetry run azad stop
```

Best Practices ¶

Be specific in your task descriptions to help the agent understand what you want.
Review tool calls carefully before approving them, especially those that modify your codebase.
Provide feedback when the agent makes mistakes to help it learn and improve.
Use the appropriate model for your task - larger models may be better for complex tasks, while smaller models may be faster for simple tasks.
Configure the agent to match your development environment and preferences.