# Client Usage

This guide covers how to integrate with the Agent Smith server from client applications, using both the `@agent-smith/wscli` package for WebSocket communication and standard HTTP clients for REST API access.

## Using `@agent-smith/wscli`

The `@agent-smith/wscli` package provides a high-level WebSocket client with auto-reconnect and full callback support.

### Installation

```bash
npm install @agent-smith/wscli
```

### Basic Usage

```typescript
import { useWsServer } from "@agent-smith/wscli";

const ws = useWsServer({
    url: "ws://localhost:5184/ws",
    onToken: (token, from) => process.stdout.write(token),
    onThinkingToken: (token, from) => console.log(`\x1b[2m${token}\x1b[0m`),
});

// Execute an agent
ws.executeAgent("my-agent", { prompt: "Write a haiku about code" });

// Execute a workflow
ws.executeWorkflow("my-workflow", { input: "data" });

// Cancel current execution
await ws.cancel();
```

### Full Callback Example

```typescript
import { useWsServer } from "@agent-smith/wscli";
import type { ToolCallSpec } from "@agent-smith/types";

const ws = useWsServer({
    url: "ws://localhost:5184/ws",
    onToken: (token, from) => process.stdout.write(token),
    onThinkingToken: (token, from) => console.log(`\x1b[2m${token}\x1b[0m`),
    onToolCall: (tc, type, from) => {
        console.log(`\n⚒️ Tool: ${tc.name}`);
    },
    onToolCallEnd: (tc, content, type, from) => {
        console.log(`  Result: ${content?.slice(0, 100)}`);
    },
    onConfirmToolUsage: async (tool: ToolCallSpec) => {
        // Return true to allow, false to deny
        return true;
    },
    onEndEmit: (result, from) => {
        console.log(`\nInference complete. Tokens: ${result.stats?.totalTokens}`);
    },
    onError: (msg, from) => {
        console.error(`[${from}] ${msg}`);
    },
});

ws.executeAgent("code-review", { prompt: "Review this function" });
```

### Using `useClientFeatures`

For a higher-level service that combines REST API queries with WebSocket execution:

```typescript
import { useClientFeatures } from "@agent-smith/wscli";
import type { ServerParams } from "@agent-smith/types";

const params: ServerParams = {
    onToken: (token, from) => process.stdout.write(token),
    defaultInferenceParams: {
        temperature: 0.7,
        max_tokens: 2048,
    },
};

const features = useClientFeatures(params);

// Load agent metadata and variables
await features.load("my-agent");
console.log(features.agentSpec.value);
console.log(features.variables.required);

// Execute with resolved variables
await features.executeAgent("Process the data", {
    variables: { input: "file.txt" },
});

// Cancel execution
await features.cancel();

// Query backends and models
const backends = await features.loadBackends();
const models = await features.loadModels("openai");
```

## Using HTTP Client

The REST API at `/api/*` can be accessed with any HTTP client.

### Using `fetch`

```typescript
// List all agents
const agentsRes = await fetch("http://localhost:5184/api/agents");
const agents = await agentsRes.json();

// Get a specific agent
const agentRes = await fetch("http://localhost:5184/api/agent/my-agent");
const agent = await agentRes.json();

// Update agent settings
const settingsRes = await fetch("http://localhost:5184/api/agentSettings", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ model: "gpt-4", temperature: 0.5 }),
});

// List backends
const backendsRes = await fetch("http://localhost:5184/api/backends");
const backends = await backendsRes.json();
```

## Authentication

The server does not enforce API key authentication by default. All endpoints are accessible to any client that can reach the server. For production deployments, place the server behind a reverse proxy (e.g., Nginx) with TLS and access controls.

## Example: Execute Command and Receive Streaming Response

```typescript
import { useWsServer } from "@agent-smith/wscli";

const tokenStream: string[] = [];

const ws = useWsServer({
    url: "ws://localhost:5184/ws",
    onToken: (token) => tokenStream.push(token),
    onEndEmit: (result) => {
        const fullText = tokenStream.join("");
        console.log("Full response:", fullText);
        console.log("Stats:", result.stats);
    },
});

ws.executeAgent("summarize", { prompt: "Summarize the key points of quantum computing" });
```

<a href="javascript:openLink('/server/deployment')">Next: Deployment</a>