npm i assistan-ts
A lightweight framework for building and running code first, type-safe "Agents".
This library aims to make it easy to create & run assistants, without introducing heavy abstractions or departing too far from the official openai
library.
Key Features:
- Define Assistants using
typebox
schemas - Sync changes with OpenAI
- Parse & validate arguments to tool calls
- Automatically poll
runs
for completion
Warning
Both this library & openai's assistants api are still in early development and is subject to change.
import { Type, definition, assistant } from 'assistan-ts';
const def = definition({
key: "Schedul-O-Bot-3000", // 'unique' key added to metadata for linking
model: "gpt-4",
name: "Schedul-O-Bot-3000",
instructions: "You help schedule meetings for E-Corp.",
codeInterpreter: true,
functionTools: {
employee_directory: {
description: "List all employees with contact and role information",
parameters: Type.Void(),
},
schedule_meeting: {
description: "Schedule a meeting with an employee",
parameters: Type.Object({
employee: Type.Number({
description: "The Employee Id to schedule the meeting with",
}),
date: Type.String({
description: "The date to schedule the meeting on",
format: "date-time",
}),
duration: Type.Number({
description: "The duration of the meeting in minutes",
minimum: 15,
maximum: 60 * 3,
}),
}),
},
},
});
Note
Not all typebox
types are supported by OpenAI at this time
You can sync files by setting the files.resolve
property of the definition. This allows you to sync files from the filesystem or a remote location.
import { toFile } from "openai/uploads";
import { readFile, readdir } from "fs/promises";
const def = definition({
//...
retrieval: true,
files: {
resolve: async () => {
const fileName = 'time-off-policy.md';
const content = await readFile(path.join('docs', fileName));
return [ toFile(content, filename) ];
},
},
});
Files will be compared for equality using the filename by default, but you can overrides this by setting files.keyFn
.
const linked = await def.link(openai);
This will create the assistant if it doesn't exist, and update it to match the schema if there is any drift.
Warning
By default, this will update the assistant to match the schema. If you want to disable this behavior, pass { updateMode: "skip" }
to the link
function.
For any tools you defined, you must provide an implementation with a matching signature.
const scheduleBot = assistant({
definition: linked,
tools: {
employee_directory: async () => {
return [
{
id: 1000,
name: "John Chen",
email: "ariachen@example.com",
department: "Marketing",
role: "Marketing Manager",
},
//...
];
},
schedule_meeting: async ({ employee, date, duration }) => {
return {
status: "success",
meeting_id: "123",
};
},
},
toolOptions: {
// override defaults
}
});
const thread = await openai.beta.threads.create({
messages: [
{
role: "user",
content: "Schedule a 45m meeting with Alana on Tuesday at 3pm",
},
],
});
const { run, complete } = await scheduleBot.run.create({
threadId: thread.id,
});
await complete({ interval: 1500 });
const messages = await openai.beta.threads.messages.list(thread.id);
Alternately, you can use toolsRequired
to better control the execution of the tools:
const { toolsRequired } = await scheduleBot.run.create({
threadId: thread.id,
});
let toolActions = await toolsRequired();
while (toolActions) {
//let user confirm
if(confirm(`Continue with ${JSON.stringify(toolActions.toolCalls, null, 2)}?`)){
toolActions = await toolActions.execute( /* you may provide overrides outputs here */ );
}
}
pg-bot
connected to coffee roasting db
This project contains a number of examples
to demonstrate the use of the library.
schedulo-bot-3000
: simple demo, not actually connected to anythingbash-bot
: Agent with full control to execute in your terminal and upload files to for the code interpreterpg-bot
: Agent connected to a postgres database. Can explore schema and execute queries.
To run an example:
cd examples
npm i
- Set the
OAI_KEY
environment variable to your OpenAI API key (export OAI_KEY=<your key>
) - use
bun
to run the index file:
npx bun <example name>/index.ts
Note
Checkout the agentCli.ts to see a simple demo of how to manage the agent lifecycle.
Property | Type | Description | Default Value |
---|---|---|---|
assistantId | string | Pass a OpenAI id to retrieve by id instead of metadata-->__key__ search |
- |
allowCreate | boolean | Will create assistant if not found | true |
afterCreate | (assistant: Assistant) => void | Run after creating assistant | - |
updateMode | "update" | "throw" | "skip" | What to do if drift is detected | "update" |
beforeUpdate | (diff: string[], local: AssistantCreateParams, remote: Assistant) => boolean | Runs before updating an assistant. Return false to skip update | - |
afterUpdate | (assistant: Assistant) => void | Runs after updating an assistant | - |
fileMode | "update" | "throw" | "skip" | What to do if file drift is detected | "update" |
pruneFiles | boolean | Deletes files from OpenAI when they are removed from the Assistant | false |
Property | Type | Description | Default Value |
---|---|---|---|
validateArguments | boolean | Run JSONSchema validation before calling tool | true |
jsonParser | (args: string, ctx: ToolContext) => unknown | Argument Parser | - |
validator | (args: unknown, ctx: ToolContext) => void | Argument Validator | - |
formatToolError | (error: unknown, ctx: ToolContext) => string | Chance to remap errors or throw a fatal 'fatal'. By Default only AssistantVisibleError will be passed along |
- |
formatValidationError | (errors: ErrorObject<string, Record<string, any>, unknown>[], ctx: ToolContext) => string | Custom error messages on argument validation | - |
formatOutput | (output: Output, ctx: ToolContext) => string | Output Formatter | - |
Property | Type | Description | Default Value |
---|---|---|---|
interval | number | MS wait between polling for run completion | 1000 |
abortSignal | AbortSignal | Abort controller to abort the run | - |
onStatusChange | (run: Run, previous: Run["status"]) => void | Executes anytime the status changes (within the execution of this function) | - |