AWEtoAgent

https://github.com/stpdevteam/awetoagent-kit
Admin
AWEtoAgent is a TypeScript framework for building, deploying, and monetizing autonomous AI agents...
Tokens:85,760
Snippets:630
Trust Score:6.7
License:MIT
Update:8 months ago
Show doc for...
Tokens:
Raw
### Start AWEtoAgent and Test Endpoints

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/README.md

Commands to install dependencies, start the AWEtoAgent in development mode, and test its functionality using curl. This includes checking the agent manifest, listing entrypoints, and invoking an example entrypoint.

```bash
cd my-agent
bun install
bun run dev
```

```bash
# View agent manifest
curl http://localhost:3000/.well-known/agent.json

# List entrypoints
curl http://localhost:3000/entrypoints

# Invoke an entrypoint (example for echo template)
curl -X POST http://localhost:3000/entrypoints/echo/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Hello, AWEtoAgent!"}}'
```

--------------------------------

### Entrypoint Examples

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/blank/AGENTS.md

Examples demonstrating how to implement different types of entrypoint handlers.

```APIDOC
## Entrypoint Examples

### Error Handling in Entrypoints

This example shows how to implement error handling within an entrypoint handler. The framework automatically handles errors thrown by the handler.

```typescript
handler: async ({ input }) => {
  try {
    // Your logic here
    const result = await someOperation(input.data);
    return {
      output: { result },
    };
  } catch (error) {
    // Errors are automatically handled by the framework
    // and returned as JSON with error.code and message
    throw error;
  }
};
```

### Async Operations

This example demonstrates fetching data from an external API within an entrypoint handler.

```typescript
handler: async ({ input }) => {
  // Fetch from external API
  const response = await fetch(`https://api.example.com/data/${input.id}`);
  const data = await response.json();

  return {
    output: { data },
  };
};
```

### Using Multiple Entrypoints

This example shows how to define and register multiple entrypoints using the `addEntrypoint` function.

```typescript
// In src/agent.ts

addEntrypoint({
  key: "entrypoint1",
  description: "First capability",
  handler: async () => ({ output: { result: "one" } }),
});

addEntrypoint({
  key: "entrypoint2",
  description: "Second capability",
  handler: async () => ({ output: { result: "two" } }),
});

// Each becomes available at:
// POST /entrypoints/entrypoint1/invoke
// POST /entrypoints/entrypoint2/invoke
```
```

--------------------------------

### Clone and Install AWEtoAgent-Kit

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/README.md

Clones the AWEtoAgent-Kit repository from GitHub and installs its dependencies using Bun. This is the initial setup step for working with the project.

```bash
git clone https://github.com/STPDevteam/AWEtoAgent-Kit.git
cd AWEtoAgent-Kit
bun install
```

--------------------------------

### Install and Run Agent (Shell)

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm/README.md

Installs project dependencies using Bun and starts the agent in development watch mode. This command is essential for local development and testing.

```shell
bun install
bun run dev
```

--------------------------------

### Testing create-agent-kit Template Generation

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Outlines the steps for testing the agent template generation process using the `create-agent-kit` CLI. This involves creating a temporary directory, running the CLI to generate a test agent, installing dependencies, and starting the development server.

```bash
# Test template generation
cd /tmp
bunx /path/to/AWEtoAgent-Kit/packages/create-agent-kit/dist/index.js test-agent --template=blank
cd test-agent
bun install
bun run dev
```

--------------------------------

### Run AWEtoAgent CLI in Interactive Mode

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/README.md

Initiates the AWEtoAgent Kit CLI in interactive mode to guide the user through the agent setup process. This involves navigating to the project directory and executing the CLI script using Node.js.

```bash
cd /path/to/AWEtoAgent-Kit
node ./packages/cli/dist/index.js
```

--------------------------------

### Start Development Server with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm-flow/AGENTS.md

Starts the Bun HTTP server in development mode, enabling watch mode for automatic restarts on file changes. This is useful during active development.

```bash
bun run dev
```

--------------------------------

### Run Agent Kit Example with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/CONTRIBUTING.md

Executes an example TypeScript file from the 'agent-kit' package using Bun. This demonstrates the usage of the core agent runtime.

```bash
cd packages/agent-kit
bun run examples/full-agent.ts
```

--------------------------------

### Full-Featured Agent Example (TypeScript)

Source: https://context7.com/stpdevteam/awetoagent-kit/llms.txt

Demonstrates a complete AI agent setup using AWEtoAgent-Kit, including identity creation, LLM integration, payment configuration, and a paid streaming entrypoint for chat functionality. It utilizes Zod for input validation and streams responses from an LLM.

```typescript
import { z } from 'zod';
import { createAgentApp } from '@aweto-agent/hono';
import { createAgentIdentity, getTrustConfig } from '@aweto-agent/identity';
import { createAxLLMClient } from '@aweto-agent/core';

// 1. Create on-chain identity
const identity = await createAgentIdentity({
  domain: 'ai-assistant.example.com',
  autoRegister: true,
});

// 2. Initialize LLM client
const llm = createAxLLMClient({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
});

// 3. Create agent with full configuration
const { app, addEntrypoint } = createAgentApp(
  {
    name: 'ai-assistant',
    version: '1.0.0',
    description: 'AI assistant with on-chain reputation',
    image: 'https://ai-assistant.example.com/og-image.png',
  },
  {
    config: {
      payments: {
        payTo: process.env.PAYMENTS_RECEIVABLE_ADDRESS!,
        network: 'base-sepolia',
        facilitatorUrl: 'https://facilitator.world.fun/',
      },
    },
    trust: getTrustConfig(identity),
  }
);

// 4. Add paid streaming entrypoint
addEntrypoint({
  key: 'chat',
  description: 'Chat with AI assistant',
  input: z.object({
    message: z.string(),
    history: z.array(z.object({
      role: z.enum(['user', 'assistant']),
      content: z.string(),
    })).optional(),
  }),
  output: z.object({ completed: z.boolean() }),
  streaming: true,
  price: { stream: '5000' },
  async stream(ctx, emit) {
    const messages = [
      ...(ctx.input.history || []),
      { role: 'user' as const, content: ctx.input.message },
    ];

    if (!llm.ax) {
      await emit({ kind: 'delta', delta: 'LLM not configured', mime: 'text/plain' });
      return { output: { completed: false } };
    }

    const stream = await llm.ax.chat.stream({ messages });
    for await (const chunk of stream) {
      await emit({ kind: 'delta', delta: chunk.delta, mime: 'text/plain' });
    }

    return {
      output: { completed: true },
      usage: { total_tokens: stream.usage?.total_tokens },
    };
  },
});

// Start server
const port = Number(process.env.PORT ?? 3000);
Bun.serve({ port, fetch: app.fetch });
console.log(`AI Assistant running at http://localhost:${port}`);

```

--------------------------------

### Full-Stack Agent Example

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/core/examples/README.md

A comprehensive, end-to-end example showcasing `@aweto-agent/hono` features, including agent server creation, streaming entrypoints, x402 monetization, ERC-8004 identity registration, and AgentCard generation.

```APIDOC
## Full-Stack Agent Example

### Description
This example demonstrates building a full-stack agent using `@aweto-agent/hono`, including monetisation, identity registration, and AgentCard generation. It is designed to be self-contained and uses viem-style clients.

### Method
N/A (This is a script to run)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```bash
bun run examples/full-agent.ts
```

### Environment Variables
- **FACILITATOR_URL**: x402 facilitator endpoint (defaults to `https://facilitator.world.fun/`).
- **PAYMENTS_RECEIVABLE_ADDRESS**: Receivable address for payments (EVM or Solana).
- **NETWORK**: x402 network name (e.g., `base-sepolia`).
- **IDENTITY_REGISTRY_ADDRESS**: ERC-8004 registry contract (defaults to `0x7177a6867296406881E20d6647232314736Dd09A`).
- **CHAIN_ID**: Numeric chain ID (e.g., `84532` for Base Sepolia).
- **RPC_URL**: HTTPS RPC endpoint for the chosen chain.
- **AGENT_DOMAIN**: Domain for the agent's well-known files.
- **PRIVATE_KEY**: Wallet private key for ERC-8004 registration and payments (required for registration).
- **AGENT_REF**: Agent reference for the Lucid wallet API.
- **API_BASE_URL**: Base URL for the Lucid agent API (defaults to `https://localhost:8787`).
- **AGENT_ORIGIN**: Override for the agent server origin (defaults to `https://localhost:PORT`).
- **LUCID_AGENT_BASE_URL**: Auth server base URL for challenge/exchange (falls back to `API_BASE_URL`).
- **LUCID_AGENT_AGENT_REF**: Agent ref to authenticate (falls back to `AGENT_REF`).
- **LUCID_AGENT_CREDENTIAL_ID**: Credential ID for signing challenges.
- **LUCID_AGENT_REFRESH_TOKEN**: Optional refresh token for the runtime cache.
- **LUCID_AGENT_SCOPES**: Optional scopes (JSON array or comma-separated string).
- **AGENT_AUTH_PRIVATE_KEY**: Hex private key for signing challenges (falls back to `PRIVATE_KEY`).
```

--------------------------------

### Agent Runtime Auth Loop Example

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/core/examples/README.md

This example, `runtime-auth.ts`, sets up two local servers: a minimal agent with an 'echo' entrypoint and a mock Lucid auth/API surface. It then demonstrates the AgentRuntime authentication and refresh loop.

```APIDOC
## Agent Runtime Auth Loop

### Description
This example spins up a local agent server and a mock Lucid auth server to demonstrate the `AgentRuntime.load` authentication and refresh loop, including token exchange and wrapped fetch requests.

### Method
N/A (This is a script to run)

### Endpoint
N/A

### Parameters
N/A

### Request Example
```bash
AGENT_REF=demo-agent CREDENTIAL_ID=cred-demo bun run examples/runtime-auth.ts
```

### Environment Variables
- **AGENT_PORT**: Port for the demo agent (default `8789`).
- **AUTH_PORT**: Port for the mock auth API (default `8790`).
- **SCOPES**: Comma-separated scopes for the runtime (default `agents.read`).

### Response
N/A (This example demonstrates a client-side authentication flow.)
```

--------------------------------

### Get Agent Manifest with cURL

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/blank/AGENTS.md

Starts the agent and then uses cURL to retrieve the agent's manifest file, which describes its capabilities and configuration.

```bash
# Start the agent
bun run dev

# Get the agent manifest
curl http://localhost:3000/.well-known/agent.json
```

--------------------------------

### Create TanStack Runtime for Agent

Source: https://context7.com/stpdevteam/awetoagent-kit/llms.txt

This snippet demonstrates how to create an agent runtime for the TanStack Start framework. It supports both UI and headless modes and allows defining entrypoints with input/output schemas using Zod. The example shows adding an 'analyze' entrypoint.

```typescript
import { z } from 'zod';
import { createTanStackRuntime } from '@aweto-agent/tanstack';

const { runtime, handlers } = createTanStackRuntime({
  name: 'tanstack-agent',
  version: '1.0.0',
  description: 'Full-stack agent with TanStack',
});

runtime.entrypoints.add({
  key: 'analyze',
  description: 'Analyze text content',
  input: z.object({ text: z.string() }),
  output: z.object({ sentiment: z.string(), wordCount: z.number() }),
  async handler({ input }) {
    const words = input.text.split(/\s+/).length;
    return {
      output: {
        sentiment: 'positive',
        wordCount: words,
      },
    };
  },
});

const { agent } = runtime;
export { agent, handlers, runtime };
```

--------------------------------

### Testing Unit Tests with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Provides an example of how to write and run unit tests using Bun's built-in testing framework. It demonstrates basic test structure with `describe`, `expect`, and `test` from `bun:test`.

```typescript
import { describe, expect, test } from 'bun:test';

describe('MyModule', () => {
  test('should do something', () => {
    expect(something()).toBe(expected);
  });
});
```

```bash
# Run tests
bun test                    # All tests
bun test src/__tests__/specific.test.ts  # Specific test
```

--------------------------------

### Test Echo Entrypoint with cURL

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/blank/AGENTS.md

Starts the agent and then uses cURL to send a POST request to the 'echo' entrypoint with JSON input.

```bash
# Start the agent
bun run dev

# Test the echo entrypoint
curl -X POST http://localhost:3000/entrypoints/echo/invoke \
  -H "Content-Type: application/json" \
  -d '{"input": {"text": "Hello World"}}'
```

--------------------------------

### Scaffold New Agent Project with CLI

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/README.md

Initiates the creation of a new agent project using the aweto-agent CLI. It guides the user through template selection and configuration via an interactive wizard. Dependencies can be automatically installed.

```bash
bunx @aweto-agent/cli@latest my-agent
```

--------------------------------

### Implement Streaming Entrypoints with SSE

Source: https://context7.com/stpdevteam/awetoagent-kit/llms.txt

This example shows how to create agent entrypoints that stream responses using Server-Sent Events (SSE). By setting `streaming: true` and defining a `stream` handler, you can emit incremental chunks of data to clients in real-time. The example demonstrates streaming content character by character.

```typescript
import { z } from 'zod';
import { createAgentApp } from '@aweto-agent/hono';

const { app, addEntrypoint } = createAgentApp({
  name: 'streaming-agent',
  version: '1.0.0',
});

addEntrypoint({
  key: 'generate',
  description: 'Stream generated content character by character',
  input: z.object({ prompt: z.string() }),
  output: z.object({ done: z.boolean() }),
  streaming: true,
  price: { stream: '2500' }, // Different price for streaming
  async stream({ input }, emit) {
    // Emit deltas (incremental chunks)
    for (const char of input.prompt) {
      await emit({ kind: 'delta', delta: char, mime: 'text/plain' });
    }

    // Emit final text message
    await emit({
      kind: 'text',
      text: `Completed streaming: ${input.prompt}`,
      mime: 'text/plain',
    });

    return {
      output: { done: true },
      usage: { total_tokens: input.prompt.length },
    };
  },
});

// Client-side consumption via SSE
// POST /entrypoints/generate/stream with EventSource or fetch
```

--------------------------------

### Full-Featured Agent Example

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/README.md

Demonstrates the creation of a full-featured agent integrating identity, LLM, and payments. It includes setting up on-chain identity, initializing an LLM, and defining a paid, streaming entrypoint for chat.

```typescript
import { z } from 'zod';
import { createAgentApp } from '@AWEtoAgent/hono';
import { createAgentIdentity, getTrustConfig } from '@AWEtoAgent/identity';
import { AI } from '@ax-llm/ax';

// 1. Create on-chain identity
const identity = await createAgentIdentity({
  domain: 'my-agent.example.com',
  autoRegister: true,
});

// 2. Initialize LLM
const ai = new AI({
  provider: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
});

// 3. Create agent with payments and identity
const { app, addEntrypoint } = createAgentApp(
  {
    name: 'ai-assistant',
    version: '1.0.0',
    description: 'AI assistant with on-chain reputation',
    image: 'https://my-agent.example.com/og-image.png',
  },
  {
    config: {
      payments: {
        payTo: process.env.PAYMENTS_RECEIVABLE_ADDRESS!,
        network: 'base-sepolia',
        facilitatorUrl: 'https://facilitator.world.fun/',
        defaultPrice: '5000', // 0.005 USDC per request
      },
    },
    useConfigPayments: true,
    trust: getTrustConfig(identity),
  }
);

// 4. Add paid entrypoint with streaming
addEntrypoint({
  key: 'chat',
  description: 'Chat with AI assistant',
  input: z.object({
    message: z.string(),
    history: z
      .array(
        z.object({
          role: z.enum(['user', 'assistant']),
          content: z.string(),
        })
      )
      .optional(),
  }),
  streaming: true,
  async stream(ctx, emit) {
    const messages = [
      ...(ctx.input.history || []),
      { role: 'user' as const, content: ctx.input.message },
    ];

    const stream = await ai.chat.stream({ messages });

    for await (const chunk of stream) {
      await emit({
        kind: 'delta',
        delta: chunk.delta,
        mime: 'text/plain',
      });
    }

    return {
      output: { completed: true },
      usage: { total_tokens: stream.usage.total_tokens },
    };
  },
});

const port = Number(process.env.PORT ?? 3000);
app.listen(port, () => {
  console.log(`agent listening on http://localhost:${port}`);
});
```

--------------------------------

### Run Agent Kit Identity Example with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/CONTRIBUTING.md

Executes an example TypeScript file from the 'agent-kit-identity' package using Bun. This showcases the ERC-8004 identity toolkit.

```bash
cd packages/agent-kit-identity
bun run examples/quick-start.ts
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/TESTING_PLAYBOOK.md

Installs external dependencies for the test project using the `bun install` command. This command is executed after updating the `package.json` to ensure all necessary packages, including local `@aweto-agent/*` packages, are correctly installed and linked.

```bash
cd /tmp/test-agent
bun install
```

--------------------------------

### Integrate Real Data with Fetch - TypeScript

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/trading-data-agent/AGENTS.md

Provides an example of replacing mock data generation with actual API calls within an entrypoint handler. It demonstrates fetching real market data based on input parameters.

```typescript
handler: async ctx => {
  const data = await fetchRealMarketData(ctx.input.symbol);
  return { output: data };
},
```

--------------------------------

### AxFlow + createAxLLMClient Example

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/core/examples/README.md

Demonstrates how to instantiate an Ax LLM client with payments enabled and run an AxFlow pipeline within an agent entrypoint. It also provides a fallback for missing Ax credentials.

```APIDOC
## GET /entrypoints/brainstorm/invoke

### Description
This endpoint accepts a `topic` string and responds with a summary and follow-up ideas, powered by AxFlow and an Ax LLM client.

### Method
GET

### Endpoint
/entrypoints/brainstorm/invoke

### Parameters
#### Query Parameters
- **topic** (string) - Required - The topic for which to generate a summary and ideas.

### Request Example
```bash
bun run examples/ax-flow.ts
```

### Response
#### Success Response (200)
- **summary** (string) - A summary of the provided topic.
- **followUpIdeas** (array<string>) - A list of follow-up ideas related to the topic.

#### Response Example
```json
{
  "summary": "This is a summary of the topic.",
  "followUpIdeas": [
    "Idea 1",
    "Idea 2"
  ]
}
```

### Environment Variables
- **OPENAI_API_KEY**: API key forwarded to `@ax-llm/ax`.
- **PRIVATE_KEY**: Wallet key used by x402 to sign requests.
- **PORT**: Optional; defaults to 3000.
```

--------------------------------

### CLI Options for Agent Scaffolding

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/README.md

Lists the available command-line options for the @aweto-agent/cli tool, including template selection, adapter configuration, installation control, and non-interactive mode.

```bash
bunx @aweto-agent/cli <app-name> [options]

Options:
  -t, --template <id>   Select template (blank, axllm, axllm-flow, identity)
  -a, --adapter <id>    Select runtime adapter (hono, express, tanstack-ui, tanstack-headless, next)
  -i, --install         Run bun install after scaffolding
  --no-install          Skip bun install (default)
  --wizard=no           Skip wizard, use template defaults
  --non-interactive     Same as --wizard=no
  --network=<network>   Set payment network (base-sepolia, base, solana-devnet, solana)
  --KEY=value           Pass template argument (use with --non-interactive)
  -h, --help            Show this help
```

--------------------------------

### GET /entrypoints

Source: https://context7.com/stpdevteam/awetoagent-kit/llms.txt

Lists all available entrypoints exposed by the agent.

```APIDOC
## GET /entrypoints

### Description

Lists all available entrypoints exposed by the agent, including their keys and descriptions.

### Method

GET

### Endpoint

`/entrypoints`

### Response

#### Success Response (200)

- **items** (array) - An array of entrypoint objects.
  - **key** (string) - The unique identifier for the entrypoint.
  - **description** (string) - A brief description of the entrypoint's functionality.
  - **streaming** (boolean) - Indicates if the entrypoint supports streaming.

#### Response Example

```json
{
  "items": [
    {
      "key": "echo",
      "description": "Echoes the input text.",
      "streaming": false
    }
  ]
}
```
```

--------------------------------

### Install Dependencies with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/CONTRIBUTING.md

Installs all project dependencies for the monorepo and its individual packages using Bun. This command should be run after cloning the repository.

```bash
bun install
```

--------------------------------

### Run Package in Development Mode with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/CONTRIBUTING.md

Starts a specific package in watch mode using Bun. This allows for live reloading and faster development cycles as changes are automatically reflected.

```bash
cd packages/agent-kit
bun run dev
```

--------------------------------

### Example Agent App Test Structure

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/CONTRIBUTING.md

A basic example of a unit test written in TypeScript for the 'createAgentApp' function. It demonstrates the use of Bun's testing utilities and assertions.

```typescript
import { describe, test, expect } from "bun:test";
import { createAgentApp } from "../src/app";

describe("createAgentApp", () => {
  test("creates app with metadata", () => {
    const { app, config } = createAgentApp({
      name: "test-agent",
      version: "1.0.0",
    });

    expect(app).toBeDefined();
    expect(config).toBeDefined();
  });
});
```

--------------------------------

### Add Entrypoint with Multiple Fields

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/blank/AGENTS.md

Shows how to add an entrypoint that handles multiple fields, including an enum for operation type and performing basic arithmetic calculations.

```typescript
addEntrypoint({
  key: "calculate",
  description: "Perform basic arithmetic",
  input: z.object({
    operation: z.enum(["add", "subtract", "multiply", "divide"]),
    a: z.number(),
    b: z.number(),
  }),
  output: z.object({
    result: z.number(),
  }),
  handler: async ({ input }) => {
    let result: number;
    switch (input.operation) {
      case "add":
        result = input.a + input.b;
        break;
      case "subtract":
        result = input.a - input.b;
        break;
      case "multiply":
        result = input.a * input.b;
        break;
      case "divide":
        result = input.a / input.b;
        break;
    }
    return {
      output: { result },
    };
  },
});
```

--------------------------------

### Version Packages for Release with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Prepares packages for a new release by managing versioning. This involves using the 'changeset' command to record changes.

```bash
bun run changeset
bun run release:version
```

--------------------------------

### Available Routes

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/blank/AGENTS.md

List of available API routes for interacting with the AwetoAgent.

```APIDOC
## Available Routes

### Health Check

- **Method**: GET
- **Endpoint**: `/health`
- **Description**: Checks the health status of the agent.

### List Entrypoints

- **Method**: GET
- **Endpoint**: `/entrypoints`
- **Description**: Retrieves a list of all available entrypoints.

### Agent Manifest

- **Method**: GET
- **Endpoint**: `/.well-known/agent.json`
- **Description**: Fetches the full agent manifest in A2A format.

### Invoke Entrypoint

- **Method**: POST
- **Endpoint**: `/entrypoints/:key/invoke`
- **Description**: Invokes a specific entrypoint with the provided input.
- **Path Parameters**
  - `key` (string) - Required - The unique key of the entrypoint to invoke.

### Stream Entrypoint

- **Method**: POST
- **Endpoint**: `/entrypoints/:key/stream`
- **Description**: Streams the output of a specific entrypoint (if streaming is enabled).
- **Path Parameters**
  - `key` (string) - Required - The unique key of the entrypoint to stream.
```

--------------------------------

### Core Runtime Setup with Entrypoint - TypeScript

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/README.md

Demonstrates how to set up the core runtime for an agent and add a simple 'greet' entrypoint. This requires the '@AWEtoAgent/core' package and 'zod' for input/output schema validation. The handler function processes the input and returns a greeting message.

```typescript
import { createRuntime } from '@AWEtoAgent/core';
import { z } from 'zod';

const runtime = createRuntime({
  name: 'my-agent',
  version: '1.0.0',
  description: 'My first agent',
});

runtime.addEntrypoint({
  key: 'greet',
  input: z.object({ name: z.string() }),
  async handler({ input }) {
    return { output: { message: `Hello, ${input.name}!` } };
  },
});
```

--------------------------------

### Test Agent Health Endpoint with cURL

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/blank/AGENTS.md

Starts the agent in development mode and then uses cURL to send a GET request to the agent's health check endpoint.

```bash
# Start the agent
bun run dev

# Test the health endpoint
curl http://localhost:3000/health
```

--------------------------------

### Quick Start for Recommendation Agent (Shell)

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/trading-recommendation-agent/README.md

Provides the command-line instructions to create and run the trading recommendation agent. It requires setting environment variables for the private key and data agent URL.

```sh
bunx @aweto-agent/create-agent-kit recommendation-agent --template=trading-recommendation-agent --adapter=hono
cd recommendation-agent
# Set PRIVATE_KEY and DATA_AGENT_URL in .env
bun run dev
```

--------------------------------

### TypeScript Type Definition Example - Single Source of Truth

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Demonstrates the principle of having a single type definition for a concept to avoid redundancy. This 'Good' example consolidates related properties into one type, unlike the 'Bad' example which uses separate internal and public types.

```typescript
type PaymentsRuntime = {
  config: PaymentsConfig;
  isActive: boolean;
  requirements: any;
  activate: any;
};
```

--------------------------------

### TypeScript Encapsulation Example - Owning Package Complexity

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Illustrates proper encapsulation where domain complexity resides within the owning package. The 'Good' example shows the payments package exporting a complete runtime, which the core runtime uses directly, avoiding transformation layers.

```typescript
export function createPaymentsRuntime(...): PaymentsRuntime | undefined {
  return {
    config,
    isActive,
    requirements(...) { /* ... */ },
    activate(...) { /* ... */ }
  };
}

// In core runtime - use directly
const payments = createPaymentsRuntime(...);
return { payments };
```

--------------------------------

### Hono Adapter for HTTP Server - TypeScript

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/README.md

Illustrates the setup of an HTTP server using the Hono adapter. This involves creating an agent application with `createAgentApp` from '@AWEtoAgent/hono', allowing for the addition of entrypoints and exporting the Hono app instance for serving.

```typescript
import { createAgentApp } from '@AWEtoAgent/hono';

const { app, addEntrypoint } = createAgentApp({
  name: 'my-agent',
  version: '1.0.0',
});

// Add entrypoints...

export default app; // Bun.serve or Hono serve
```

--------------------------------

### TypeScript Package Interaction Example

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Demonstrates how the `agent-kit` package imports and utilizes types from the `agent-kit-identity` package. It shows type imports and how these types are used in function arguments.

```typescript
// agent-kit imports identity types
import type { TrustConfig } from '@AWEtoAgent/agent-kit-identity';

// agent-kit accepts trust config
createAgentApp(meta, {
  trust: trustConfig, // From agent-kit-identity
});
```

--------------------------------

### Complete AWEtoAgent Onboarding (Skipped Registration)

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/README.md

Steps to complete the AWEtoAgent registration process if the wallet was auto-generated without sufficient ETH for initial gas fees. This involves retrieving the wallet address, funding it using a faucet, and running the onboarding script.

```bash
# 1. Get your wallet address from the generated project
cat my-agent/.agent-wallet.json

# 2. Fund the wallet using a faucet (Base Sepolia)
#    - https://www.alchemy.com/faucets/base-sepolia
#    - https://faucets.chain.link/base-sepolia

# 3. Run onboarding to complete ERC-8004 registration
cd my-agent
bun run agent:onboard
```

--------------------------------

### Zod Schema Definition and Inference

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Provides an example of defining a data schema using Zod in TypeScript. It includes defining required and optional fields and inferring the TypeScript type from the schema.

```typescript
import { z } from 'zod';

const schema = z.object({
  field: z.string().min(1),
  optional: z.number().optional(),
});

type Parsed = z.infer<typeof schema>;
```

--------------------------------

### TypeScript ESM Import Example

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Demonstrates the use of ES Module (ESM) syntax for importing and exporting in TypeScript. This adheres to the project's requirement of using `import`/`export` over `require()`.

```typescript
// index.ts
export { mainFunction } from './feature1';
export { helperFunction } from './utils/helpers';
export type { MyType } from './types';
```

--------------------------------

### Configure Agent Kit with Runtime Overrides

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/core/README.md

Shows how to configure the Aweto Agent Kit at runtime using `configureAgentKit`. This example sets payment and wallet configurations, then demonstrates retrieving these resolved values using `getAgentKitConfig` and `paymentsFromEnv`.

```typescript
import {
  configureAgentKit,
  getAgentKitConfig,
  paymentsFromEnv,
} from '@aweto-agent/core';

configureAgentKit({
  payments: {
    facilitatorUrl: 'https://facilitator.example',
    payTo: '0x...',
    network: 'base-sepolia',
  },
  wallets: {
    agent: {
      type: 'local',
      privateKey: '0xabc...',
    },
  },
});

const config = getAgentKitConfig();
console.log(config.payments?.facilitatorUrl); // resolved facilitator
console.log(config.wallets?.agent?.type); // 'local'
console.log(paymentsFromEnv()); // reuse inside handlers
```

--------------------------------

### Configure Agent Wallet in TypeScript

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/trading-recommendation-agent/AGENTS.md

Provides an example of wallet configuration for an agent. It specifies a private key type for the agent's wallet, essential for authorizing payments and transactions.

```typescript
config: {
  wallets: {
    agent: {
      type: 'private-key',
      privateKey: process.env.PRIVATE_KEY,
    },
  },
}
```

--------------------------------

### POST /entrypoints/quickSignal/invoke

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/trading-recommendation-agent/README.md

Generates a quick trading signal using only price data, which is a cheaper option.

```APIDOC
## POST /entrypoints/quickSignal/invoke

### Description
Generates a quick trading signal using only price data. This is a more cost-effective option compared to `generateSignal`.

### Method
POST

### Endpoint
/entrypoints/quickSignal/invoke

### Parameters
#### Query Parameters
- **symbol** (string) - Required - The trading symbol (e.g., 'BTC/USD').

### Request Body
```json
{
  "input": {
    "symbol": "string"
  }
}
```

### Request Example
```json
{
  "input": {
    "symbol": "ETH/USD"
  }
}
```

### Response
#### Success Response (200)
- **signal** (string) - The generated trading signal (BUY/SELL/HOLD).
- **price** (number) - The current price of the asset.

#### Response Example
```json
{
  "signal": "HOLD",
  "price": 3500.50
}
```
```

--------------------------------

### TypeScript Template Package Imports

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Illustrates how generated agent code within templates imports core functionalities from `agent-kit` and `agent-kit-identity`. This shows the typical setup for a new agent application.

```typescript
// In generated agent.ts
import { createAgentApp } from '@AWEtoAgent/agent-kit';
import { createAgentIdentity } from '@AWEtoAgent/agent-kit-identity';
```

--------------------------------

### Test Entrypoint with TypeScript Fetch API

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/blank/AGENTS.md

Demonstrates how to test an agent's entrypoint programmatically using the TypeScript `fetch` API. It sends a POST request with JSON data and logs the result.

```typescript
const response = await fetch("http://localhost:3000/entrypoints/echo/invoke", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    input: { text: "test" },
  }),
});

const result = await response.json();
console.log(result.output);
```

--------------------------------

### Configure AxLLM Client

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm/AGENTS.md

Initializes the AxLLM client using `createAxLLMClient` from `@aweto-agent/core`. It includes basic logger configuration and a check for LLM provider setup via environment variables.

```typescript
import { createAxLLMClient } from "@aweto-agent/core";

const axClient = createAxLLMClient({
  logger: {
    warn(message, error) {
      if (error) {
        console.warn(`[agent] ${message}`, error);
      } else {
        console.warn(`[agent] ${message}`);
      }
    },
  },
});

// Check if LLM provider is configured
if (!axClient.isConfigured()) {
  console.warn("LLM provider not configured - add API keys to .env");
}
```

--------------------------------

### Run Test Project with Bun

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/TESTING_PLAYBOOK.md

Starts the development server for the test project using the `bun run dev` command. This command is typically executed after installing dependencies to run the application locally.

```bash
cd /tmp/test-agent
bun run dev
```

--------------------------------

### Run ESLint Linting Commands (Bun)

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/eslint-config/README.md

Demonstrates how to execute ESLint linting checks and apply auto-fixes using Bun. It also shows how to use the 'just' command-line tool for linting specific packages.

```bash
# Check for issues
bun run lint

# Auto-fix issues
bun run lint:fix

# Using just
just lint-check <package-name>
just lint-fix <package-name>
```

--------------------------------

### Generate Projects with Different Adapters

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/TESTING_PLAYBOOK.md

Demonstrates how to generate new Aweto Agent Kit projects using different adapter flags. This allows testing of various integrations like Hono, Express, TanStack UI, and TanStack Headless. After generation, the standard setup and testing process should be followed.

```bash
# Hono
bunx @aweto-agent/create-agent-kit test-hono --adapter=hono --template=identity

# Express
bunx @aweto-agent/create-agent-kit test-express --adapter=express --template=identity

# TanStack UI
bunx @aweto-agent/create-agent-kit test-tanstack-ui --adapter=tanstack-ui --template=identity

# TanStack Headless
bunx @aweto-agent/create-agent-kit test-tanstack-headless --adapter=tanstack-headless --template=identity
```

--------------------------------

### Configure LLM Provider (Bash)

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm/AGENTS.md

Example of how to configure an LLM provider by setting the necessary API key in a `.env` file. This is a prerequisite for the AxLLM client to function correctly, especially when using services like OpenAI.

```bash
# Add your API key to the .env file
OPENAI_API_KEY=sk-your-openai-api-key-here

# Or for Anthropic:
# ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here
```

--------------------------------

### Avoid Unnecessary Getters and Wrappers in TypeScript

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/AGENTS.md

Contrasts an example of an unnecessary wrapper object with getters to access runtime properties against the preferred approach of directly using the runtime object's methods. This adheres to the principle of simplicity over indirection.

```typescript
// Bad: Unnecessary wrapper
const paymentsRuntime = {
  get config() { return payments.config!; },
  get isActive() { return payments.isActive; },
  requirements(...) { return evaluate(...); }
};

```

```typescript
// Good: Direct use
payments.requirements(...);

```

--------------------------------

### Test Agent API Endpoints with cURL

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm-flow/AGENTS.md

Provides examples of how to test agent API endpoints using cURL. It demonstrates testing a multi-step workflow and a streaming workflow by sending POST requests with JSON payloads.

```bash
# Test multi-step workflow
curl -X POST http://localhost:3000/entrypoints/analyze-and-summarize/invoke \
  -H "Content-Type: application/json" \
  -d '{ "input": { "text": "Your text here..." } }'

# Test streaming workflow
curl -X POST http://localhost:3000/entrypoints/stream-workflow/stream \
  -H "Content-Type: application/json" \
  -d '{ "input": { "topic": "quantum computing" } }'
```

--------------------------------

### Configure Payments for Agent Entrypoints (TypeScript)

Source: https://context7.com/stpdevteam/awetoagent-kit/llms.txt

This snippet demonstrates how to configure the x402 payment protocol for monetizing agent entrypoints. It supports manual configuration for EVM and Solana networks, as well as environment-based configuration. Dependencies include '@aweto-agent/hono' and '@aweto-agent/payments'.

```typescript
import { createAgentApp } from '@aweto-agent/hono';
import { paymentsFromEnv } from '@aweto-agent/payments';
import { z } from 'zod';

// Manual configuration
const { app, addEntrypoint } = createAgentApp(
  { name: 'paid-agent', version: '1.0.0' },
  {
    config: {
      payments: {
        payTo: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb0', // EVM address
        network: 'base-sepolia',
        facilitatorUrl: 'https://facilitator.world.fun/',
      },
    },
  }
);

// Or with Solana
const solanaConfig = {
  payTo: '9yPGxVrYi7C5JLMGjEZhK8qQ4tn7SzMWwQHvz3vGJCKz', // Solana Base58 address
  network: 'solana-devnet',
  facilitatorUrl: 'https://facilitator.world.fun/',
};

// Add paid entrypoint with different prices for invoke vs stream
addEntrypoint({
  key: 'premium',
  description: 'Premium paid service',
  input: z.object({ query: z.string() }),
  output: z.object({ answer: z.string() }),
  price: { invoke: '5000', stream: '7500' }, // 0.005 / 0.0075 USDC
  streaming: true,
  async handler({ input }) {
    return { output: { answer: `Premium answer for: ${input.query}` } };
  },
  async stream({ input }, emit) {
    await emit({ kind: 'delta', delta: 'Premium ', mime: 'text/plain' });
    await emit({ kind: 'delta', delta: 'streaming ', mime: 'text/plain' });
    await emit({ kind: 'delta', delta: 'response', mime: 'text/plain' });
    return { output: { answer: 'Premium streaming complete' } };
  },
});

// Environment-based configuration (reads PAYMENTS_* env vars)
const payments = paymentsFromEnv();
console.log(`Payments configured: ${payments?.network}`);

```

--------------------------------

### Manage Wallets with Wallet SDK (TypeScript)

Source: https://context7.com/stpdevteam/awetoagent-kit/llms.txt

This snippet shows how to use the Wallet SDK to create and manage agent and developer wallets. It covers creating a local wallet from a private key, signing messages, and signing typed data (EIP-712). It also demonstrates how to load wallets configured via environment variables.

```typescript
import { createAgentWallet, walletsFromEnv } from '@aweto-agent/wallet';

// Create local wallet from private key
const agentWallet = await createAgentWallet({
  type: 'local',
  privateKey: process.env.AGENT_WALLET_PRIVATE_KEY,
});

console.log(`Agent address: ${agentWallet.address}`);

// Sign a message
const signature = await agentWallet.signMessage('Hello, World!');

// Sign typed data (EIP-712)
const typedSignature = await agentWallet.signTypedData({
  primaryType: 'Mail',
  typedData: {
    domain: { name: 'My Agent', version: '1' },
    types: { Mail: [{ name: 'contents', type: 'string' }] },
    message: { contents: 'Hello!' },
  },
});

// Or use environment-based configuration
// Reads AGENT_WALLET_PRIVATE_KEY, DEVELOPER_WALLET_PRIVATE_KEY
const wallets = walletsFromEnv();
console.log(`Agent wallet type: ${wallets?.agent?.type}`);

```

--------------------------------

### Utilize Different LLM Models (TypeScript)

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm/AGENTS.md

Demonstrates how to use different language models for varying needs, such as speed, cost, or capability. The examples show calls to `axClient.gen` using 'gpt-3.5-turbo' for quick responses, 'gpt-4' for more capable generation, and 'claude-3-5-sonnet-20241022' from Anthropic.

```typescript
// Fast and cheap
const quickResult = await axClient.gen({
  prompt: input.text,
  model: "gpt-3.5-turbo",
});

// More capable
const smartResult = await axClient.gen({
  prompt: input.text,
  model: "gpt-4",
});

// Anthropic
const claudeResult = await axClient.gen({
  prompt: input.text,
  model: "claude-3-5-sonnet-20241022",
});

```

--------------------------------

### Basic AxLLM Flow Agent Entrypoint

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm-flow/AGENTS.md

Defines a basic agent entrypoint using AxLLM Flow in TypeScript. This example demonstrates a two-step process: analyzing text for sentiment and then generating a summary based on that analysis. It uses `axClient.gen` for LLM calls and `zod` for input/output schema validation.

```typescript
import { flow } from "@ax-llm/ax";

addEntrypoint({
  key: "analyze-and-summarize",
  description: "Analyze text and create a summary",
  input: z.object({
    text: z.string(),
  }),
  output: z.object({
    analysis: z.string(),
    summary: z.string(),
  }),
  handler: async ({ input }) => {
    // Step 1: Analyze the text
    const analysisResult = await axClient.gen({
      prompt: `Analyze this text for key themes and sentiment: ${input.text}`,
      model: "gpt-4",
    });

    // Step 2: Create summary based on analysis
    const summaryResult = await axClient.gen({
      prompt: `Based on this analysis, create a concise summary:

Analysis: ${analysisResult.text}
Original text: ${input.text}`,
      model: "gpt-4",
    });

    return {
      output: {
        analysis: analysisResult.text,
        summary: summaryResult.text,
      },
      usage: {
        prompt_tokens:
          (analysisResult.usage?.promptTokens || 0) +
          (summaryResult.usage?.promptTokens || 0),
        completion_tokens:
          (analysisResult.usage?.completionTokens || 0) +
          (summaryResult.usage?.completionTokens || 0),
        total_tokens:
          (analysisResult.usage?.totalTokens || 0) +
          (summaryResult.usage?.totalTokens || 0),
      },
    };
  },
});
```

--------------------------------

### Advanced AxLLM Flow API Usage

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/cli/templates/axllm-flow/AGENTS.md

Demonstrates a more advanced use of the AxLLM Flow API in TypeScript for a multi-step research workflow. This example chains multiple LLM calls using the `flow().step()` pattern to first generate a research outline and then expand on each point. It showcases context passing between steps.

```typescript
import { flow } from "@ax-llm/ax";

addEntrypoint({
  key: "research-workflow",
  description: "Multi-step research workflow",
  input: z.object({
    topic: z.string(),
  }),
  output: z.object({
    outline: z.array(z.string()),
    details: z.string(),
  }),
  handler: async ({ input }) => {
    const result = await flow()
      // Step 1: Generate outline
      .step("outline", async () => {
        return await axClient.gen({
          prompt: `Create a research outline for: ${input.topic}`,
          schema: z.object({
            points: z.array(z.string()),
          }),
          model: "gpt-4",
        });
      })
      // Step 2: Expand each point
      .step("details", async (ctx) => {
        const outline = ctx.outline.data.points;
        const expanded = await Promise.all(
          outline.map((point) =>
            axClient.gen({
              prompt: `Expand on this research point: ${point}`,
              model: "gpt-4",
            })
          )
        );
        return expanded.map((r) => r.text).join("\n\n");
      })
      .run();

    return {
      output: {
        outline: result.outline.data.points,
        details: result.details,
      },
    };
  },
});
```

--------------------------------

### Install ESLint Config Package (Bun)

Source: https://github.com/stpdevteam/awetoagent-kit/blob/master/packages/eslint-config/README.md

Installs the @aweto-agent/eslint-config package as a development dependency using the Bun package manager.

```bash
# In your package directory
bun add -D @aweto-agent/eslint-config
```
Tokens:
Raw