Concevent AI Agent SDK

https://www.npmjs.com/package/concevent-ai-agent-sdk
Admin
A framework-agnostic AI Agent SDK for building intelligent conversational agents with tool calling,...
Tokens:119,433
Snippets:825
Trust Score:9.6
Update:8 months ago
Show doc for...
Tokens:
Raw
### Quick Start: Create an AI Agent with Tool Calling

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

A quick start guide demonstrating how to create an AI agent using the SDK. It includes defining custom tools with Zod schemas for parameter validation and executing a chat with the agent. This example showcases basic agent creation and interaction.

```typescript
import { createAgent } from "concevent-ai-agent-sdk";
import type {
  ToolDefinition,
  ToolExecutorContext,
} from "concevent-ai-agent-sdk";
import { z } from "zod";
import { zodToJsonSchema } from "zod-to-json-schema";

// Define your tools
const tools: ToolDefinition[] = [
  {
    declaration: {
      name: "getWeather",
      description: "Get current weather for a city",
      parametersJsonSchema: zodToJsonSchema(
        z.object({
          city: z.string().describe("City name"),
        })
      ),
    },
    executor: async (args) => {
      const city = args.city as string;
      // Your weather API logic here
      return { city, temperature: 22, condition: "sunny" };
    },
  },
];

// Create the agent
const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  systemPrompts: ["You are a helpful weather assistant."],
  tools,
});

// Chat with the agent
const result = await agent.chat("What's the weather in Tokyo?", {
  appContext: { userId: "user-123", timezone: "Asia/Tokyo" },
});

console.log(result.message);
// "The weather in Tokyo is currently sunny with a temperature of 22°C."
```

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

### Example with Full Configuration

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=code

An example demonstrating how to create an agent with a comprehensive configuration.

```APIDOC
#### Example with Full Configuration
```
const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  baseURL: "https://openrouter.ai/api/v1",
  temperature: 0.7,
  reasoning: { effort: "high" },  // Or just "high" as shorthand, or false to disable
  maxIterations: 10,
  systemPrompts: [
    "You are a helpful assistant.",
    "Always be concise and accurate.",
  ],
  tools: myTools,
  summarization: {
    enabled: true,
    contextLimitTokens: 50000,
    prompt: "Summarize the key points of this conversation...",
  },
  errorMessages: {
    maxIterations: "Too many steps required. Please simplify your request.",
    genericError: "Something went wrong. Please try again.",
  },
});
```
```

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

### Example Agent Creation

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=versions

An example demonstrating how to create an agent instance with various configuration options.

```APIDOC
#### Example with Full Configuration
```javascript
const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  baseURL: "https://openrouter.ai/api/v1",
  temperature: 0.7,
  reasoning: { effort: "high" },  // Or just "high" as shorthand, or false to disable
  maxIterations: 10,
  systemPrompts: [
    "You are a helpful assistant.",
    "Always be concise and accurate.",
  ],
  tools: myTools,
  summarization: {
    enabled: true,
    contextLimitTokens: 50000,
    prompt: "Summarize the key points of this conversation...",
  },
  errorMessages: {
    maxIterations: "Too many steps required. Please simplify your request.",
    genericError: "Something went wrong. Please try again.",
  },
});
```
```

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

### Complete Streaming Example

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=dependencies

An example demonstrating how to use various streaming callbacks for a chat interaction.

```APIDOC
## Complete Streaming Example

```javascript
import { createAgent } from "concevent-ai-agent-sdk";

const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  systemPrompts: ["You are a helpful assistant."],
  tools: myTools,
  stream: true, // Enabled by default
});

let messageBuffer = "";
let reasoningBuffer = "";

const result = await agent.chat(
  "Explain quantum computing",
  { appContext: { userId: "user-123", timezone: "UTC" } },
  {
    // Real-time message chunks
    onMessageDelta: (delta) => {
      messageBuffer += delta;
      updateUI(messageBuffer); // Update your UI with partial content
    },

    // Real-time reasoning chunks (for reasoning models)
    onReasoningDelta: (detail) => {
      if (detail.text) {
        reasoningBuffer += detail.text;
        updateReasoningUI(reasoningBuffer);
      }
    },

    // Tool execution still works with streaming
    onToolCallStart: (calls) => {
      showToolIndicator(calls.map((c) => c.name));
    },

    onToolResult: (result) => {
      hideToolIndicator(result.functionName);
    },

    // Final complete message
    onMessage: (message, reasoning) => {
      console.log("Complete message received");
    },
  }
);
```
```

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

### Tool Selection Examples

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=code

Examples demonstrating how to create built-in tools with different configurations, including read-only tools, file tools, and shell tools.

```APIDOC
## Tool Selection Examples

### Description
Examples of initializing built-in tools with specific sets of functionalities.

### Request Example
```typescript
import { createBuiltInTools } from 'concevent-ai-agent-sdk';

// Read-only tools for safe analysis
const { tools: readOnlyTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Read', 'Glob', 'Grep'],
});

// File tools only (no shell access)
const { tools: fileTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Read', 'Write', 'Edit', 'Glob', 'Grep'],
});

// Shell tools only
const { tools: shellTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Bash', 'BashOutput', 'KillBash'],
});
```
```

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

### Tool Selection Examples

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

Examples demonstrating how to create built-in tools with different configurations, including read-only tools, file tools, and shell tools.

```APIDOC
## Tool Selection Examples

### Description
Examples of initializing `createBuiltInTools` with different sets of tools and configurations.

### Request Example
```typescript
import { createBuiltInTools } from 'concevent-ai-agent-sdk';

// Read-only tools for safe analysis
const { tools: readOnlyTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Read', 'Glob', 'Grep'],
});

// File tools only (no shell access)
const { tools: fileTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Read', 'Write', 'Edit', 'Glob', 'Grep'],
});

// Shell tools only
const { tools: shellTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Bash', 'BashOutput', 'KillBash'],
});
```
```

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

### Built-in Tools Configuration Examples

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=dependencies

Examples demonstrating how to create built-in tools with different configurations, including read-only tools, file tools, and shell tools.

```APIDOC
## Read-only Tools Example

```typescript
import { createBuiltInTools } from 'concevent-ai-agent-sdk';

const { tools: readOnlyTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Read', 'Glob', 'Grep'],
});
```

## File Tools Only Example

```typescript
import { createBuiltInTools } from 'concevent-ai-agent-sdk';

const { tools: fileTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Read', 'Write', 'Edit', 'Glob', 'Grep'],
});
```

## Shell Tools Only Example

```typescript
import { createBuiltInTools } from 'concevent-ai-agent-sdk';

const { tools: shellTools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Bash', 'BashOutput', 'KillBash'],
});
```
```

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

### Complete Streaming Example with Callbacks

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

A comprehensive example demonstrating how to configure an agent for streaming and utilize various callbacks like `onMessageDelta`, `onReasoningDelta`, `onToolCallStart`, and `onToolResult` for real-time updates and feedback during chat interactions.

```javascript
import { createAgent } from "concevent-ai-agent-sdk";

const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  systemPrompts: ["You are a helpful assistant."],
  tools: myTools,
  stream: true, // Enabled by default
});

let messageBuffer = "";
let reasoningBuffer = "";

const result = await agent.chat(
  "Explain quantum computing",
  { appContext: { userId: "user-123", timezone: "UTC" } },
  {
    // Real-time message chunks
    onMessageDelta: (delta) => {
      messageBuffer += delta;
      updateUI(messageBuffer); // Update your UI with partial content
    },

    // Real-time reasoning chunks (for reasoning models)
    onReasoningDelta: (detail) => {
      if (detail.text) {
        reasoningBuffer += detail.text;
        updateReasoningUI(reasoningBuffer);
      }
    },

    // Tool execution still works with streaming
    onToolCallStart: (calls) => {
      showToolIndicator(calls.map((c) => c.name));
    },

    onToolResult: (result) => {
      hideToolIndicator(result.functionName);
    },

    // Final complete message
    onMessage: (message, reasoning) => {
      console.log("Complete message received");
    },
  }
);
```

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

### Complete Streaming Example

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=versions

A comprehensive example demonstrating the use of various streaming callbacks within a chat interaction.

```APIDOC
## Complete Streaming Example

```javascript
import { createAgent } from "concevent-ai-agent-sdk";

const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  systemPrompts: ["You are a helpful assistant."],
  tools: myTools,
  stream: true, // Enabled by default
});

let messageBuffer = "";
let reasoningBuffer = "";

const result = await agent.chat(
  "Explain quantum computing",
  { appContext: { userId: "user-123", timezone: "UTC" } },
  {
    // Real-time message chunks
    onMessageDelta: (delta) => {
      messageBuffer += delta;
      updateUI(messageBuffer); // Update your UI with partial content
    },

    // Real-time reasoning chunks (for reasoning models)
    onReasoningDelta: (detail) => {
      if (detail.text) {
        reasoningBuffer += detail.text;
        updateReasoningUI(reasoningBuffer);
      }
    },

    // Tool execution still works with streaming
    onToolCallStart: (calls) => {
      showToolIndicator(calls.map((c) => c.name));
    },

    onToolResult: (result) => {
      hideToolIndicator(result.functionName);
    },

    // Final complete message
    onMessage: (message, reasoning) => {
      console.log("Complete message received");
    },
  }
);
```

### Method
POST

### Endpoint
/chat

### Parameters
#### Query Parameters
- **stream** (boolean) - Optional - Whether to enable streaming. Defaults to true.

#### Request Body
- **message** (string) - Required - The user's message.
- **context** (object) - Optional - Context for the chat.
- **callbacks** (object) - Optional - Callbacks for handling streaming events:
  - **onMessageDelta** (function) - Callback for message content chunks.
  - **onMessage** (function) - Callback for the complete verified message.
  - **onReasoningDelta** (function) - Callback for reasoning content chunks.
  - **onThinking** (function) - Callback when reasoning is complete.
  - **onToolCallStart** (function) - Callback when tool calls start.
  - **onToolResult** (function) - Callback when a tool returns a result.
```

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

### Complete Streaming Example

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

A comprehensive example demonstrating the integration of various streaming callbacks for a chat interaction.

```APIDOC
## Complete Streaming Example

### Description
This example illustrates a full streaming interaction, including handling message deltas, reasoning deltas, tool calls, and final message delivery.

### Request Example
```javascript
import { createAgent } from "concevent-ai-agent-sdk";

const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  systemPrompts: ["You are a helpful assistant."],
  tools: myTools,
  stream: true, // Enabled by default
});

let messageBuffer = "";
let reasoningBuffer = "";

const result = await agent.chat(
  "Explain quantum computing",
  { appContext: { userId: "user-123", timezone: "UTC" } },
  {
    // Real-time message chunks
    onMessageDelta: (delta) => {
      messageBuffer += delta;
      updateUI(messageBuffer); // Update your UI with partial content
    },

    // Real-time reasoning chunks (for reasoning models)
    onReasoningDelta: (detail) => {
      if (detail.text) {
        reasoningBuffer += detail.text;
        updateReasoningUI(reasoningBuffer);
      }
    },

    // Tool execution still works with streaming
    onToolCallStart: (calls) => {
      showToolIndicator(calls.map((c) => c.name));
    },

    onToolResult: (result) => {
      hideToolIndicator(result.functionName);
    },

    // Final complete message
    onMessage: (message, reasoning) => {
      console.log("Complete message received");
    },
  }
);
```
```

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

### Complete Streaming Example

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=dependents

A comprehensive example demonstrating the use of various streaming callbacks for messages, reasoning, and tool calls within a single agent chat interaction.

```APIDOC
## Complete Streaming Example

### Description
This example illustrates a full streaming interaction with the AI agent, including handling message deltas, reasoning deltas, tool call indicators, and final message delivery.

### Method
`agent.chat(message, context, callbacks)`

### Parameters
#### Request Body (for `agent.chat`)
- **message** (string) - The user's message.
- **context** (object) - Contextual information for the chat.
- **callbacks** (object) - An object containing various streaming callbacks.
  - **onMessageDelta** (function) - Handles chunks of the message content.
  - **onReasoningDelta** (function) - Handles chunks of the model's reasoning process.
  - **onToolCallStart** (function) - Indicates the start of tool execution.
  - **onToolResult** (function) - Indicates the result of a tool execution.
  - **onMessage** (function) - Called with the complete verified message and reasoning.

### Request Example
```javascript
import { createAgent } from "concevent-ai-agent-sdk";

const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  systemPrompts: ["You are a helpful assistant."],
  tools: myTools,
  stream: true, // Enabled by default
});

let messageBuffer = "";
let reasoningBuffer = "";

const result = await agent.chat(
  "Explain quantum computing",
  { appContext: { userId: "user-123", timezone: "UTC" } },
  {
    // Real-time message chunks
    onMessageDelta: (delta) => {
      messageBuffer += delta;
      updateUI(messageBuffer); // Update your UI with partial content
    },

    // Real-time reasoning chunks (for reasoning models)
    onReasoningDelta: (detail) => {
      if (detail.text) {
        reasoningBuffer += detail.text;
        updateReasoningUI(reasoningBuffer);
      }
    },

    // Tool execution still works with streaming
    onToolCallStart: (calls) => {
      showToolIndicator(calls.map((c) => c.name));
    },

    onToolResult: (result) => {
      hideToolIndicator(result.functionName);
    },

    // Final complete message
    onMessage: (message, reasoning) => {
      console.log("Complete message received");
    },
  }
);
```
```

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

### Install concevent-ai-agent-sdk using npm, yarn, or pnpm

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Instructions for installing the concevent-ai-agent-sdk package using different package managers. This is the first step to integrating the SDK into your project.

```bash
npm install concevent-ai-agent-sdk
# or
yarn add concevent-ai-agent-sdk
# or
pnpm add concevent-ai-agent-sdk
```

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

### Creating Middleware

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=versions

Examples of how to create different types of middleware, including logging, input sanitization, rate limiting, and output filtering.

```APIDOC
## Creating Middleware

### Description
This section provides code examples for creating custom middleware functions. You can implement various functionalities such as logging, sanitizing input, rate limiting, and filtering output.

### Example: Logging Middleware
```javascript
import { createAgent } from "concevent-ai-agent-sdk";
import type { Middleware } from "concevent-ai-agent-sdk";

const loggingMiddleware: Middleware = {
  name: "logging",
  beforeChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat started:`, ctx.message);
    return ctx.message;
  },
  afterChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat completed:`, ctx.result.message);
    return ctx.result;
  },
  beforeToolCall: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Tool call:`, ctx.toolCall.name);
    return ctx.toolCall;
  },
  onError: async (ctx) => {
    console.error(`[${new Date().toISOString()}] Error:`, ctx.error.code, ctx.error.message);
  },
};
```

### Example: Input Sanitization Middleware
```javascript
const sanitizationMiddleware: Middleware = {
  name: "sanitization",
  beforeChat: async (ctx) => {
    // Remove potentially harmful content from user input
    const sanitized = ctx.message.replace(/<script[^>]*>.*?<\/script>/gi, "");
    return sanitized;
  },
};
```

### Example: Rate Limiting Middleware with Typed Context
```javascript
interface MyAppContext {
  userId: string;
  timezone: string;
}

const rateLimitMiddleware: Middleware<MyAppContext> = {
  name: "rate-limit",
  beforeChat: async (ctx) => {
    const userId = ctx.toolContext.appContext.userId;
    if (await isRateLimited(userId)) {
      throw new Error("Rate limit exceeded. Please try again later.");
    }
    return ctx.message;
  },
};
```

### Example: Output Filtering Middleware
```javascript
const outputFilterMiddleware: Middleware = {
  name: "output-filter",
  afterChat: async (ctx) => {
    // Remove sensitive data from responses
    const filteredMessage = ctx.result.message.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[REDACTED]");
    return { ...ctx.result, message: filteredMessage };
  },
  afterToolCall: async (ctx) => {
    // Filter sensitive data from tool results
    if (typeof ctx.result.result === "object" && ctx.result.result !== null) {
      const filtered = JSON.parse(
        JSON.stringify(ctx.result.result).replace(/"password":\s*"[^ vital]*"/g, '"password": "[REDACTED]"')
      );
      return { ...ctx.result, result: filtered };
    }
    return ctx.result;
  },
};
```
```

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

### Creating Middleware

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=dependents

Examples of creating different types of middleware, including logging, sanitization, rate limiting, and output filtering.

```APIDOC
## Creating Middleware

Middleware is implemented as objects with specific hook functions. Here are some examples:

### Logging Middleware

```javascript
import { createAgent } from "concevent-ai-agent-sdk";
import type { Middleware } from "concevent-ai-agent-sdk";

const loggingMiddleware: Middleware = {
  name: "logging",
  beforeChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat started:`, ctx.message);
    return ctx.message;
  },
  afterChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat completed:`, ctx.result.message);
    return ctx.result;
  },
  beforeToolCall: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Tool call:`, ctx.toolCall.name);
    return ctx.toolCall;
  },
  onError: async (ctx) => {
    console.error(`[${new Date().toISOString()}] Error:`, ctx.error.code, ctx.error.message);
  },
};
```

### Input Sanitization Middleware

```javascript
const sanitizationMiddleware: Middleware = {
  name: "sanitization",
  beforeChat: async (ctx) => {
    // Remove potentially harmful content from user input
    const sanitized = ctx.message.replace(/<script[^>]*>.*?<\/script>/gi, "");
    return sanitized;
  },
};
```

### Rate Limiting Middleware (with typed context)

```javascript
interface MyAppContext {
  userId: string;
  timezone: string;
}

const rateLimitMiddleware: Middleware<MyAppContext> = {
  name: "rate-limit",
  beforeChat: async (ctx) => {
    const userId = ctx.toolContext.appContext.userId;
    if (await isRateLimited(userId)) {
      throw new Error("Rate limit exceeded. Please try again later.");
    }
    return ctx.message;
  },
};
```

### Output Filtering Middleware

```javascript
const outputFilterMiddleware: Middleware = {
  name: "output-filter",
  afterChat: async (ctx) => {
    // Remove sensitive data from responses
    const filteredMessage = ctx.result.message.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[REDACTED]");
    return { ...ctx.result, message: filteredMessage };
  },
  afterToolCall: async (ctx) => {
    // Filter sensitive data from tool results
    if (typeof ctx.result.result === "object" && ctx.result.result !== null) {
      const filtered = JSON.parse(
        JSON.stringify(ctx.result.result).replace(/"password":\s*"[^"]*"/g, '"password": "[REDACTED]"')
      );
      return { ...ctx.result, result: filtered };
    }
    return ctx.result;
  },
};
```
```

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

### Creating Middleware

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

Examples of creating different types of middleware, including logging, sanitization, rate limiting, and output filtering.

```APIDOC
## Creating Middleware

Middleware is implemented as objects with specific hook functions.

### Logging Middleware Example

```javascript
import { createAgent } from "concevent-ai-agent-sdk";
import type { Middleware } from "concevent-ai-agent-sdk";

const loggingMiddleware: Middleware = {
  name: "logging",
  beforeChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat started:`, ctx.message);
    return ctx.message;
  },
  afterChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat completed:`, ctx.result.message);
    return ctx.result;
  },
  beforeToolCall: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Tool call:`, ctx.toolCall.name);
    return ctx.toolCall;
  },
  onError: async (ctx) => {
    console.error(`[${new Date().toISOString()}] Error:`, ctx.error.code, ctx.error.message);
  },
};
```

### Input Sanitization Middleware Example

```javascript
const sanitizationMiddleware: Middleware = {
  name: "sanitization",
  beforeChat: async (ctx) => {
    // Remove potentially harmful content from user input
    const sanitized = ctx.message.replace(/<script[^>]*>.*?<\/script>/gi, "");
    return sanitized;
  },
};
```

### Rate Limiting Middleware Example (with typed context)

```javascript
interface MyAppContext {
  userId: string;
  timezone: string;
}

const rateLimitMiddleware: Middleware<MyAppContext> = {
  name: "rate-limit",
  beforeChat: async (ctx) => {
    const userId = ctx.toolContext.appContext.userId;
    if (await isRateLimited(userId)) {
      throw new Error("Rate limit exceeded. Please try again later.");
    }
    return ctx.message;
  },
};
```

### Output Filtering Middleware Example

```javascript
const outputFilterMiddleware: Middleware = {
  name: "output-filter",
  afterChat: async (ctx) => {
    // Remove sensitive data from responses
    const filteredMessage = ctx.result.message.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[REDACTED]");
    return { ...ctx.result, message: filteredMessage };
  },
  afterToolCall: async (ctx) => {
    // Filter sensitive data from tool results
    if (typeof ctx.result.result === "object" && ctx.result.result !== null) {
      const filtered = JSON.parse(
        JSON.stringify(ctx.result.result).replace(/"password":\s*"[^"]*"/g, '"password": "[REDACTED]"')
      );
      return { ...ctx.result, result: filtered };
    }
    return ctx.result;
  },
};
```
```

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

### Integrate Built-in Tools with Concevent AI Agent SDK

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

This example illustrates how to initialize an agent with a selection of built-in tools provided by the concevent-ai-agent-sdk. It shows the process of creating built-in tools, specifying the desired tool names, and setting up the agent with these tools.

```typescript
import { createAgent, createBuiltInTools } from 'concevent-ai-agent-sdk';

// Explicitly specify which tools you need
const { tools, cleanup } = createBuiltInTools({
  workingDirectory: '/path/to/project',
  tools: ['Read', 'Write', 'Edit', 'Glob', 'Grep'],
});

const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: 'anthropic/claude-3.5-sonnet',
  systemPrompts: ['You are a helpful coding assistant.'],
  tools: [...tools],
});

// Don't forget to cleanup background processes when done
process.on('exit', () => cleanup());
```

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

### Install Concevent AI Agent SDK using npm

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

This command shows how to install the concevent-ai-agent-sdk package using npm. It is a prerequisite for using the SDK in your project.

```bash
npm i concevent-ai-agent-sdk
```

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

### Agent Chat Method Usage Example (JavaScript)

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Provides a practical example of calling the `agent.chat` method with a user message, execution context, and optional callbacks for tool execution and message events. This illustrates how to interact with the agent and handle its responses.

```javascript
const result = await agent.chat(
  "Calculate 25 * 4 and tell me the weather in Paris",
  { appContext: { userId: "user-123", timezone: "Europe/Paris" } },
  {
    onToolCallStart: (calls) => {
      console.log(
        "Executing tools:",
        calls.map((c) => c.name)
      );
    },
    onMessage: (message) => {
      console.log("Response:", message);
    },
  }
);
```

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

### Creating Middleware

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Examples of creating different types of middleware, including logging, input sanitization, rate limiting with custom context, and output filtering.

```APIDOC
## Creating Middleware

### Description
Demonstrates how to implement custom middleware functions for the Concevent AI Agent SDK. Includes examples for logging, sanitization, rate limiting with typed application context, and output filtering.

### Example: Logging Middleware
```javascript
import { createAgent } from "concevent-ai-agent-sdk";
import type { Middleware } from "concevent-ai-agent-sdk";

const loggingMiddleware: Middleware = {
  name: "logging",
  beforeChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat started:`, ctx.message);
    return ctx.message;
  },
  afterChat: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Chat completed:`, ctx.result.message);
    return ctx.result;
  },
  beforeToolCall: async (ctx) => {
    console.log(`[${new Date().toISOString()}] Tool call:`, ctx.toolCall.name);
    return ctx.toolCall;
  },
  onError: async (ctx) => {
    console.error(`[${new Date().toISOString()}] Error:`, ctx.error.code, ctx.error.message);
  },
};
```

### Example: Input Sanitization Middleware
```javascript
// Input sanitization middleware
const sanitizationMiddleware: Middleware = {
  name: "sanitization",
  beforeChat: async (ctx) => {
    // Remove potentially harmful content from user input
    const sanitized = ctx.message.replace(/<script[^>]*>.*?<\/script>/gi, "");
    return sanitized;
  },
};
```

### Example: Rate Limiting Middleware with Custom Context
```javascript
// Rate limiting middleware (with typed context)
interface MyAppContext {
  userId: string;
  timezone: string;
}

const rateLimitMiddleware: Middleware<MyAppContext> = {
  name: "rate-limit",
  beforeChat: async (ctx) => {
    const userId = ctx.toolContext.appContext.userId;
    if (await isRateLimited(userId)) {
      throw new Error("Rate limit exceeded. Please try again later.");
    }
    return ctx.message;
  },
};
```

### Example: Output Filtering Middleware
```javascript
// Output filtering middleware
const outputFilterMiddleware: Middleware = {
  name: "output-filter",
  afterChat: async (ctx) => {
    // Remove sensitive data from responses
    const filteredMessage = ctx.result.message.replace(/\b\d{3}-\d{2}-\d{4}\b/g, "[REDACTED]");
    return { ...ctx.result, message: filteredMessage };
  },
  afterToolCall: async (ctx) => {
    // Filter sensitive data from tool results
    if (typeof ctx.result.result === "object" && ctx.result.result !== null) {
      const filtered = JSON.parse(
        JSON.stringify(ctx.result.result).replace(/"password":\s*"[^"]*"/g, '"password": "[REDACTED]"')
      );
      return { ...ctx.result, result: filtered };
    }
    return ctx.result;
  },
};
```
```

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

### Create Agent with Full Configuration Example (JavaScript)

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Demonstrates how to create an AI agent instance with a comprehensive set of configurations. This includes API keys, model selection, base URL, temperature, reasoning settings, iteration limits, system prompts, tools, summarization options, and custom error messages.

```javascript
const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  baseURL: "https://openrouter.ai/api/v1",
  temperature: 0.7,
  reasoning: { effort: "high" },  // Or just "high" as shorthand, or false to disable
  maxIterations: 10,
  systemPrompts: [
    "You are a helpful assistant.",
    "Always be concise and accurate.",
  ],
  tools: myTools,
  summarization: {
    enabled: true,
    contextLimitTokens: 50000,
    prompt: "Summarize the key points of this conversation...",
  },
  errorMessages: {
    maxIterations: "Too many steps required. Please simplify your request.",
    genericError: "Something went wrong. Please try again.",
  },
});
```

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

### Initialize Concevent AI Agent with Built-in Tools (JavaScript)

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

Shows how to initialize an agent with a selection of built-in tools provided by the SDK. This example demonstrates explicitly specifying the required tools (e.g., 'Read', 'Write') and setting a working directory. It also includes essential cleanup logic for background processes.

```javascript
import { createAgent, createBuiltInTools } from 'concevent-ai-agent-sdk';

// Explicitly specify which tools you need
const { tools, cleanup } = createBuiltInTools({
  workingDirectory: '/path/to/project',
  tools: ['Read', 'Write', 'Edit', 'Glob', 'Grep'],
});

const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: 'anthropic/claude-3.5-sonnet',
  systemPrompts: ['You are a helpful coding assistant.'],
  tools: [...tools],
});

// Don't forget to cleanup background processes when done
process.on('exit', () => cleanup());

```

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

### Individual Tool Creation

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

Demonstrates how to create individual tools like Read and Bash using their specific creator functions or the generic `createBuiltInTool` factory.

```APIDOC
## Individual Tool Creation

### Description
Examples of creating specific tools using their dedicated creator functions or the generic factory.

### Request Example
```typescript
import {
  createReadTool,
  createBashTool,
  createBuiltInTool,
} from 'concevent-ai-agent-sdk';

// Create a specific tool using its creator function
const readTool = createReadTool({ workingDirectory: '/project' });

// Or use the generic factory with tool name (strongly typed)
const bashTool = createBuiltInTool('Bash', {
  workingDirectory: '/project',
  defaultTimeout: 60000,
});
```
```

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

### Streaming Event Types

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=versions

Provides examples of creating typed streaming events using the `createEvent` utility.

```APIDOC
## Streaming Event Types

The SDK exports event types for building event-driven streaming systems:

```typescript
import { createEvent } from "concevent-ai-agent-sdk";
import type {
  MessageDeltaEventData,
  ReasoningDeltaEventData,
} from "concevent-ai-agent-sdk";

// Create typed streaming events
const messageDeltaEvent = createEvent("message_delta", {
  delta: "Hello, ",
});

const reasoningDeltaEvent = createEvent("reasoning_delta", {
  detail: {
    type: "reasoning.text",
    text: "Let me think about this...",
    format: "text",
    index: 0,
  },
});
```

### Method
N/A (Utility function)

### Endpoint
N/A

### Parameters
#### Request Body
- **type** (string) - Required - The type of the event.
- **payload** (object) - Required - The data associated with the event.
```

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

### Task Tool with Agent Factory

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=dependents

Explains the requirement of an agent factory for the Task tool and provides an example of its implementation.

```APIDOC
## Task Tool with Agent Factory

### Description
The `Task` tool requires an `agentFactory` function to be provided during configuration. This factory is responsible for creating and managing sub-agents that execute specific tasks.

### Method
N/A (Configuration Example)

### Endpoint
N/A (Configuration Example)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tools** (array of ToolName) - Must include 'Task'.
- **agentFactory** (function) - A function that accepts a `TaskAgentConfig` and returns a promise resolving to an object with a `message` property. This function is used to instantiate sub-agents.
  - `TaskAgentConfig` includes `description`, `allowedTools`, and `prompt`.

### Request Example
```typescript
import { createAgent, createBuiltInTools } from 'concevent-ai-agent-sdk';

const { tools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Task'],
  agentFactory: async (config) => {
    // Create a sub-agent for the task
    const subAgent = createAgent({
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: 'anthropic/claude-3.5-sonnet',
      systemPrompts: [config.description],
      tools: [], // Configure tools based on config.allowedTools
    });
    
    const result = await subAgent.chat(config.prompt, {
      appContext: { userId: 'task-agent', timezone: 'UTC' },
    });
    
    return { message: result.message };
  },
});
```

### Response
N/A (Configuration Example)
```

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

### Task Tool with Agent Factory

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=code

Explains the requirement of an `agentFactory` for the Task tool to launch sub-agents and provides an example implementation.

```APIDOC
## Task Tool with Agent Factory

### Description
Configuration for the Task tool, which requires an `agentFactory` to create and manage sub-agents for complex tasks.

### Request Example
```typescript
import { createAgent, createBuiltInTools } from 'concevent-ai-agent-sdk';

const { tools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Task'],
  agentFactory: async (config) => {
    // Create a sub-agent for the task
    const subAgent = createAgent({
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: 'anthropic/claude-3.5-sonnet',
      systemPrompts: [config.description],
      tools: [], // Configure tools based on config.allowedTools
    });

    const result = await subAgent.chat(config.prompt, {
      appContext: { userId: 'task-agent', timezone: 'UTC' },
    });

    return { message: result.message };
  },
});
```
```

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

### Create Individual Tools Using Creator Functions or Generic Factory (TypeScript)

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

Shows how to create specific tools like 'Read' or 'Bash' using their dedicated creator functions (e.g., `createReadTool`) or by using the generic `createBuiltInTool` factory function with the tool name and configuration. This allows for more granular control over tool instantiation.

```typescript
import {
  createReadTool,
  createBashTool,
  createBuiltInTool,
} from 'concevent-ai-agent-sdk';

// Create a specific tool using its creator function
const readTool = createReadTool({ workingDirectory: '/project' });

// Or use the generic factory with tool name (strongly typed)
const bashTool = createBuiltInTool('Bash', {
  workingDirectory: '/project',
  defaultTimeout: 60000,
});
```

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

### Agent ClearHistory Method Call (JavaScript)

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Demonstrates the usage of the `agent.clearHistory()` method to remove all messages from the current conversation history. This effectively starts a new conversation.

```javascript
agent.clearHistory();
```

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

### Individual Tool Creation

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=code

Demonstrates how to create individual tools using specific creator functions or the generic factory.

```APIDOC
## Individual Tool Creation

### Description
Examples of creating specific tools using their dedicated creator functions or the generic `createBuiltInTool` factory.

### Request Example
```typescript
import {
  createReadTool,
  createBashTool,
  createBuiltInTool,
} from 'concevent-ai-agent-sdk';

// Create a specific tool using its creator function
const readTool = createReadTool({ workingDirectory: '/project' });

// Or use the generic factory with tool name (strongly typed)
const bashTool = createBuiltInTool('Bash', {
  workingDirectory: '/project',
  defaultTimeout: 60000,
});
```
```

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

### Task Tool with Agent Factory

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

Explains the requirement of an `agentFactory` for the Task tool and provides an example of how to implement it to launch sub-agents for complex tasks.

```APIDOC
## Task Tool with Agent Factory

### Description
Details the necessity of an `agentFactory` for the Task tool to enable sub-agent creation and provides an implementation example.

### Request Example
```typescript
import { createAgent, createBuiltInTools } from 'concevent-ai-agent-sdk';

const { tools } = createBuiltInTools({
  workingDirectory: '/project',
  tools: ['Task'],
  agentFactory: async (config) => {
    // Create a sub-agent for the task
    const subAgent = createAgent({
      apiKey: process.env.OPENROUTER_API_KEY!,
      model: 'anthropic/claude-3.5-sonnet',
      systemPrompts: [config.description],
      tools: [], // Configure tools based on config.allowedTools
    });

    const result = await subAgent.chat(config.prompt, {
      appContext: { userId: 'task-agent', timezone: 'UTC' },
    });

    return { message: result.message };
  },
});
```
```

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

### Registering Middleware

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index

Demonstrates how to register multiple middleware instances with the agent configuration.

```APIDOC
## Registering Middleware

Middleware is registered via the `middleware` property in `AgentConfig`. Middleware executes in registration order.

```javascript
const agent = createAgent({
  apiKey: process.env.API_KEY!,
  model: "anthropic/claude-3.5-sonnet",
  systemPrompts: ["You are a helpful assistant."],
  tools: myTools,
  middleware: [
    loggingMiddleware,
    sanitizationMiddleware,
    rateLimitMiddleware,
    outputFilterMiddleware,
  ],
});
```
```

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

### Create Individual Tools

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Shows how to create specific tools using dedicated creator functions or the generic `createBuiltInTool` factory. This provides more granular control over tool configuration, such as setting timeouts.

```typescript
import { 
  createReadTool, 
  createBashTool,
  createBuiltInTool,
} from 'concevent-ai-agent-sdk';

// Create a specific tool using its creator function
const readTool = createReadTool({ workingDirectory: '/project' });

// Or use the generic factory with tool name (strongly typed)
const bashTool = createBuiltInTool('Bash', { 
  workingDirectory: '/project',
  defaultTimeout: 60000,
});
```

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

### Save Orchestration Diagram to File

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Shows an example of saving the generated Mermaid sequence diagram to a Markdown file. This is useful for debugging and offline analysis of the agent's execution flow.

```javascript
// Example: Save diagram to file for debugging
import { writeFile } from "fs/promises";

const result = await orchestrator.chat("Complex multi-agent task", context);
await writeFile("orchestration-flow.md", ````mermaid\n${result.diagram}\n```);
```

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

### Initialize Agent with Vision-Capable Model (JavaScript)

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=readme

Initializes the Concevent AI agent using a vision-capable multimodal model, such as 'openai/gpt-4o'. This setup is necessary for the agent to process and understand image inputs.

```javascript
const agent = createAgent({
  apiKey: process.env.OPENROUTER_API_KEY!,
  model: "openai/gpt-4o", // Vision-capable model
  systemPrompts: ["You are a helpful visual assistant."],
  tools: [],
});
```

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

### Handle Reasoning Deltas and Full Reasoning

Source: https://www.npmjs.com/package/concevent-ai-agent-sdk/index_activeTab=code

Illustrates how to use the onReasoningDelta callback to receive real-time chunks of model reasoning and the onThinking callback for the complete reasoning output. This is useful for models that provide step-by-step thinking processes.

```javascript
await agent.chat("Solve this problem step by step", context, {
  onReasoningDelta: (detail) => {
    if (detail.type === "reasoning.text" && detail.text) {
      // Stream the reasoning/thinking output
      process.stdout.write(detail.text);
    }
  },
  onThinking: (fullThinking, details) => {
    // Called when reasoning is complete
    console.log("\n\nFull reasoning:", fullThinking);
  },
});
```
Tokens:
Raw