Assistant Tasks

This feature is currently marked as a “Beta” by OpenAI. Make sure to check our their How Assistants Work and Assistants Overview guides.

Assistants

Build assistants that can call models and use tools to perform tasks. Official OpenAI docs

create()

Create an assistant with a model and instructions. Official OpenAI Docs

example.ts

const file = await io.openai.files.createAndWaitForProcessing("upload-file", {
  purpose: "assistants",
  file: fs.createReadStream("./fixtures/mydata.csv"),
});

const assistant = await io.openai.beta.assistants.create("create-assistant", {
  name: "Data visualizer",
  description:
    "You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",
  model: "gpt-4-1106-preview",
  tools: [{ type: "code_interpreter" }],
  file_ids: [file.id],
});

update()

Update an assistant. Official OpenAI Docs

example.ts

const file = await io.openai.files.createAndWaitForProcessing("upload-file", {
  purpose: "assistants",
  file: fs.createReadStream("./fixtures/mydata.csv"),
});

const assistantId = "asst_abc123";

const assistant = await io.openai.beta.assistants.update("update-assistant", assistantId, {
  file_ids: [file.id], // add a file to the assistant
});

list()

List assistants. Official OpenAI Docs

example.ts

const assistants = await io.openai.beta.assistants.list("list");

// with pagination
const assistants = await io.openai.beta.assistants.list("list", {
  limit: 10,
  order: "desc",
  after: "asst_abc123",
});

retrieve()

Retrieve an assistant. Official OpenAI Docs

example.ts

const assistant = await io.openai.beta.assistants.retrieve("get-assistant", "asst_abc123");

del()

Delete an assistant. Official OpenAI Docs

example.ts

const deletedAssistant = await io.openai.beta.assistants.del("delete-assistant", "asst_abc123");

Threads

Create threads that assistants can interact with. Official OpenAI docs

create()

Create a thread. Official OpenAI Docs

example.ts

const thread = await io.openai.beta.threads.create("create-thread", {
  messages: [
    {
      role: "user",
      content: "Create 3 data visualizations based on the trends in this file.",
      file_ids: [fileId],
    },
  ],
});

createAndRun()

Create a thread and run it in one task.

example.ts

const run = await io.openai.beta.threads.createAndRun("create-and-run-thread", {
  assistant_id: "asst_abc123",
  thread: {
    messages: [
      {
        role: "user",
        content: "Create 3 data visualizations based on the trends in this file.",
        file_ids: [fileId],
      },
    ],
  },
});

createAndRunUntilCompletion()

Create a thread and runs it in one task, and only returns when the run is completed by polling in the background using io.backgroundPoll().

example.ts

const run = await io.openai.beta.threads.createAndRunUntilCompletion("create-thread", {
  assistant_id: "asst_abc123",
  thread: {
    messages: [
      {
        role: "user",
        content: "Create 3 data visualizations based on the trends in this file.",
        file_ids: [fileId],
      },
    ],
  },
});

if (run.status !== "completed") {
  throw new Error(`Run finished with status ${run.status}: ${JSON.stringify(run.last_error)}`);
}

// List all messages in the thread
const messages = await io.openai.beta.threads.messages.list("list-messages", run.thread_id);

retrieve()

Retrieves a thread. Official OpenAI Docs

example.ts

const thread = await io.openai.beta.threads.retrieve("get-thread", "thread_abc123");

update()

Modifies a thread. Official OpenAI Docs

example.ts

await io.openai.beta.threads.update("update-thread", "thread_abc123", {
  metadata: {
    foo: "bar",
  },
});

del()

Deletes a thread. Official OpenAI Docs

example.ts

const deletedThread = await io.openai.beta.threads.del("update-thread", "thread_abc123");

Messages

Create messages within threads. Official OpenAI docs

list()

List messages in a thread.

example.ts

const messages = await io.openai.beta.threads.messages.list("list-messages", "thread_abc123");
// with pagination
const messages = await io.openai.beta.threads.messages.list("list-messages", "thread_abc123", {
  limit: 10,
  order: "desc",
  after: "message_abc123",
});

If you want to list all messages in a thread, you can use the listAll() helper:

example.ts

const messages = await io.openai.beta.threads.messages.listAll("list-messages", "thread_abc123");

This will automatically paginate through all messages in the thread and return them as a single array.

create()

Create a message. Official OpenAI Docs

example.ts

const thread = await io.openai.beta.threads.create("get-thread");

const message = await io.openai.beta.threads.messages.create("create-message", thread.id, {
  role: "user",
  content: "Create 3 data visualizations based on the trends in this file.",
  file_ids: [fileId],
});

retrieve()

Retrieve a message. Official OpenAI Docs

example.ts

const message = await io.openai.beta.threads.messages.retrieve(
  "get-message",
  "thread_abc123",
  "message_abc123"
);

update()

Update a message. Official OpenAI Docs

example.ts

await io.openai.beta.threads.messages.update("update-message", thread.id, message.id, {
  metadata: {
    foo: "bar",
  },
});

Runs

Represents an execution run on a thread. Official OpenAI docs

list()

List all runs belonging to a thread.

example.ts

const runs = await io.openai.beta.threads.runs.list("list-runs", "thread_abc123");

create()

Create a run. Official OpenAI Docs

example.ts

const run = await io.openai.beta.threads.runs.create("create-run", "thread_abc123", {
  assistant_id: payload.id,
});

createAndWaitForCompletion()

Create a run and only return when the run is completed by polling in the background using io.backgroundPoll().

example.ts

const run = await io.openai.beta.threads.runs.createAndWaitForCompletion(
  "create-run",
  "thread_abc123",
  {
    assistant_id: payload.id,
  }
);

if (run.status !== "completed") {
  throw new Error(`Run finished with status ${run.status}: ${JSON.stringify(run.last_error)}`);
}

const messages = await io.openai.beta.threads.messages.list("list-messages", run.thread_id);

waitForCompletion()

Wait for a run to complete by polling in the background using io.backgroundPoll().

example.ts

const run = await io.openai.beta.threads.runs.create("create-run", "thread_abc123", {
  assistant_id: payload.id,
});

const completedRun = await io.openai.beta.threads.runs.waitForCompletion(
  "wait-for-completion",
  "thread_abc123",
  run.id
);

if (completedRun.status !== "completed") {
  throw new Error(
    `Run finished with status ${completedRun.status}: ${JSON.stringify(completedRun.last_error)}`
  );
}

const messages = await io.openai.beta.threads.messages.list("list-messages", run.thread_id);

retrieve()

Retrieve a run. Official OpenAI Docs

example.ts

const run = await io.openai.beta.threads.runs.retrieve("get-run", "thread_abc123", "run_abc123");

cancel()

Cancels a run that is in_progress. Official OpenAI Docs

example.ts

const run = await io.openai.beta.threads.runs.cancel("cancel-run", "thread_abc123", "run_abc123");

submitToolOutputs()

When a run has the status: "requires_action" and required_action.type is submit_tool_outputs, this endpoint can be used to submit the outputs from the tool calls once they’re all completed. All outputs must be submitted in a single request. Official OpenAI Docs

example.ts

const run = await io.openai.beta.threads.runs.submitToolOutputs(
  "submit-tool-outputs",
  "thread_abc123",
  "run_abc123",
  {
    tool_outputs: [
      {
        tool_call_id: "tool_run_abc123",
        output: "This is the output of the tool call.",
      },
    ],
  }
);

list()

Returns all runs belonging to a thread. Official OpenAI Docs

example.ts

const runs = await io.openai.beta.threads.runs.list("list-runs", "thread_abc123");