Agents

client.agents creates and configures your agents, keeps a version for every configuration change, and lets you pause an agent or roll it back. To learn what an agent is and how to design one, read Agents.

const agent = await client.agents.create({
  name: "Release writer",
  providerId: "prv_0123456789abcdef",
  model: "openai/gpt-6-luna",
  instructions: "Write concise release notes.",
  tools: ["workspace"],
});

Every method takes one input object and accepts an optional abortSignal. create() and update() save a new numbered version; the other methods do not. See Versions and lifecycle.

Available operations

Methods

create()

Creates an agent and saves its configuration as version 1.

Signature: create(input: CreateAgentBody & ResourceRequestOptions): Promise<Agent>

const agent = await client.agents.create({
  name: "Release writer",
  providerId: "prv_0123456789abcdef",
  model: "openai/gpt-6-luna",
  instructions: "Write concise release notes.",
});

Set providerId and model together, or leave both out to create an agent you configure later. Turns on an agent without a model fail with provider_required. Blazing Agents checks the model against your provider when you save.

Without workspaceId, the agent gets a new workspace of its own named after it. Pass an ID to share an existing workspace. Changing the agent later does not rename its workspace.

An ApprovalPolicy has a default decision and optional overrides for single tools. Decisions are "full", "deny", "manual", or "auto". See tool approvals.

await client.agents.create({
  name: "Careful operator",
  providerId: "prv_0123456789abcdef",
  model: "openai/gpt-6-luna",
  tools: ["workspace"],
  approvalInChat: {
    default: "full",
    overrides: [{ tool: { type: "builtin", name: "bash" }, decision: "manual" }],
  },
  approvalInTasks: { default: "deny" },
});

Returns Agent. Errors: validation_failed, agent_name_conflict, provider_not_found, model_not_found, agent_mcp_connection_not_found, agent_mcp_connections_invalid.

list()

Lists your agents, most recently updated first. The result is not paginated.

Signature: list(input?: AgentsListOptions): Promise<AgentsResponse>

const { agents } = await client.agents.list({ userId: "user_123" });

Returns { agents: Agent[] }. Errors: validation_failed.

get()

Reads an agent's current configuration.

Signature: get(input: { agentId: string } & ResourceRequestOptions): Promise<Agent>

const agent = await client.agents.get({ agentId });

Returns Agent. Errors: validation_failed, not_found.

update()

Changes one or more settings and saves the result as the next version.

Signature: update(input: UpdateAgentBody & { agentId: string } & ResourceRequestOptions): Promise<Agent>

const agent = await client.agents.update({
  agentId,
  instructions: "Write concise release notes and include migration steps.",
});

Takes agentId plus any create() field except userId. Pass at least one field.

• Fields you leave out keep their current value.
• Arrays such as tools and mcpConnectionIds replace the whole list.
• A supplied approval policy replaces the whole policy; leaving out overrides clears them.
• thinkingLevel: null goes back to the provider's default.
• To switch providers, send providerId and model together. To unconfigure the agent, send both as null.
• workspaceId moves the agent to another workspace. It cannot be cleared.

Returns Agent with the new version. Errors: validation_failed, not_found, agent_name_conflict, provider_not_found, model_not_found, agent_mcp_connection_not_found, agent_mcp_connections_invalid, admin_agent_managed.

delete()

Deletes an agent and its history for good. You choose whether its published artifacts go too.

Signature: delete(input: { agentId: string; includeArtifacts: boolean } & ResourceRequestOptions): Promise<void>

await client.agents.delete({ agentId, includeArtifacts: false });

The agent's workspace stays. Delete it with workspaces.delete() if nothing else uses it. Errors: validation_failed, not_found, admin_agent_managed.

disable()

Stops the agent from starting new turns. Turns already running finish.

Signature: disable(input: { agentId: string } & ResourceRequestOptions): Promise<Agent>

const agent = await client.agents.disable({ agentId });

New turns fail with agent_disabled, and scheduled task runs are skipped. You can still read and update a disabled agent. Returns Agent with status: "disabled". Errors: not_found, admin_agent_managed.

enable()

Lets a disabled agent run turns again.

Signature: enable(input: { agentId: string } & ResourceRequestOptions): Promise<Agent>

const agent = await client.agents.enable({ agentId });

Schedule fires skipped while the agent was disabled do not run later. Returns Agent with status: "active". Errors: not_found, admin_agent_managed.

uploadAvatar()

Sets or replaces the agent's avatar image.

Signature: uploadAvatar(input: { agentId: string; file: File } & ResourceRequestOptions): Promise<Agent>

import { readFile } from "node:fs/promises";

const agent = await client.agents.uploadAvatar({
  agentId,
  file: new File([await readFile("avatar.webp")], "avatar.webp", { type: "image/webp" }),
});

file is a PNG, JPEG, or WebP image of at most 512 KiB. Returns Agent with a short-lived avatarUrl; fetch the agent again for a fresh URL. Errors: validation_failed, not_found, admin_agent_managed.

removeAvatar()

Removes the avatar. Calling it on an agent without one succeeds.

Signature: removeAvatar(input: { agentId: string } & ResourceRequestOptions): Promise<Agent>

const agent = await client.agents.removeAvatar({ agentId });

Returns Agent with avatarUrl: null. Errors: validation_failed, not_found, admin_agent_managed.

listVersions()

Lists an agent's saved versions, newest first.

Signature: listVersions(input: { agentId: string } & AgentVersionsListOptions): Promise<AgentVersionsResponse>

const page = await client.agents.listVersions({ agentId, limit: 20 });
const older = page.nextCursor
  ? await client.agents.listVersions({ agentId, cursor: page.nextCursor })
  : null;

Returns AgentVersionsResponse. Errors: validation_failed, invalid_cursor, not_found.

getVersion()

Reads one saved version.

Signature: getVersion(input: { agentId: string; version: number } & ResourceRequestOptions): Promise<AgentVersion>

const first = await client.agents.getVersion({ agentId, version: 1 });

Returns AgentVersion. Errors: validation_failed, not_found.

restoreVersion()

Copies an old version's configuration into a new latest version. History stays as it was.

Signature: restoreVersion(input: { agentId: string; version: number } & ResourceRequestOptions): Promise<Agent>

const agent = await client.agents.restoreVersion({ agentId, version: 1 });

The SDK reads the version with getVersion() and saves its fields with update(). The workspace, userId, status, and avatar are not part of a version, so they stay as they are. Returns the updated Agent. It fails with the errors of either call, for example provider_not_found when the old provider was deleted.

listMcpAttachments()

Shows, for each MCP connection the agent uses, whether it receives the end user's ID and which metadata keys.

Signature: listMcpAttachments(input: { agentId: string } & ResourceRequestOptions): Promise<McpAttachmentsResponse>

const { mcpAttachments } = await client.agents.listMcpAttachments({ agentId });

Returns { mcpAttachments: McpAttachmentResponse[] }. Errors: validation_failed, not_found.

updateMcpAttachment()

Chooses what one MCP connection receives about the end user on each tool call. It does not save a new version.

Signature: updateMcpAttachment(input: UpdateMcpAttachmentBody & { agentId: string; mcpConnectionId: string } & ResourceRequestOptions): Promise<McpAttachmentResponse>

const attachment = await client.agents.updateMcpAttachment({
  agentId,
  mcpConnectionId,
  forwardUserId: true,
  forwardedMetadataKeys: ["locale"],
});

Pass at least one of the two settings. Returns McpAttachmentResponse. Errors: validation_failed, not_found. See MCP tools.

Response types

Agent

AgentsResponse is { agents: Agent[] }. The package exports Agent, ApprovalPolicy, ApprovalDecision, and ToolReference.

AgentVersion

A saved configuration. It has agentId, tenantId, version, createdAt, and the versioned fields: name, providerId, model, thinkingLevel, instructions, tools, mcpConnectionIds, memoryInjectionEnabled, autoCompaction, compactionReserveTokens, approvalInChat, approvalInTasks, and metadata.

AgentVersionsResponse

interface AgentVersionsResponse {
  data: AgentVersion[];
  nextCursor: string | null;
}

nextCursor is null on the last page.

McpAttachmentResponse

Errors

Failures throw BlazingAgentsError. The codes you are most likely to handle:

Next

• Agents
• Versions and lifecycle
• Providers and models