Agents

client.agents manages tenant-owned Agent configuration, lifecycle, immutable Versions, avatars, and MCP Attachments. Every ordinary update creates the next Version; disable, enable, and avatar changes do not.

Overview

Create requires name; the exact default model is deepseek/deepseek-v4-flash. Other omitted fields default to null Provider and Sandbox, disabled Memory injection, and empty arrays, instructions, Attribution, metadata, and MCP Connection IDs. Updates require at least one mutable field; userId is immutable and nullable fields are cleared with null.

Methods

create()

create(body: CreateAgentBody): Promise<Agent> — POST /v1/agents. Arrays set the complete selection. See create Agent.

list()

list(userId?: string): Promise<AgentsResponse> — GET /v1/agents. The list is unpaginated; omit userId for all or pass "" for tenant-level Agents. See list Agents.

get()

get(agentId: string): Promise<Agent> — GET /v1/agents/:agentId. See get Agent.

update()

update(agentId: string, body: UpdateAgentBody): Promise<Agent> — PUT /v1/agents/:agentId. Omitted fields stay unchanged; providerId and sandboxId accept null. See update Agent.

delete()

delete(agentId: string): Promise<void> — DELETE /v1/agents/:agentId. This permanently removes the Agent and its history. See delete Agent.

disable()

disable(agentId: string): Promise<Agent> — POST /v1/agents/:agentId/disable. New Turns fail with AGENT_DISABLED; in-flight Turns finish. See disable Agent.

enable()

enable(agentId: string): Promise<Agent> — POST /v1/agents/:agentId/enable. See enable Agent.

uploadAvatar()

uploadAvatar(agentId: string, file: File): Promise<Agent> — multipart POST /v1/agents/:agentId/avatar. The response contains a short-lived signed avatarUrl. See upload avatar.

removeAvatar()

removeAvatar(agentId: string): Promise<Agent> — DELETE /v1/agents/:agentId/avatar; it is idempotent. See delete avatar.

listVersions()

listVersions(agentId: string, options?: AgentVersionsListOptions): Promise<AgentVersionsResponse> — GET /v1/agents/:agentId/versions. cursor is opaque; limit defaults to 50 and accepts 1–200. See list Versions.

getVersion()

getVersion(agentId: string, version: number): Promise<AgentVersion> — GET /v1/agents/:agentId/versions/:version. See get Version.

restoreVersion()

restoreVersion(agentId: string, version: number): Promise<Agent> is SDK-only composition. It calls getVersion(), copies all versioned fields through update(), and therefore creates a new latest Version rather than rewriting history.

listMcpAttachments()

listMcpAttachments(agentId: string): Promise<McpAttachmentsResponse> — GET /v1/agents/:agentId/mcp-attachments. See list MCP Attachments.

updateMcpAttachment()

updateMcpAttachment(agentId: string, mcpConnectionId: string, body: UpdateMcpAttachmentBody): Promise<McpAttachmentResponse> — PATCH /v1/agents/:agentId/mcp-attachments/:mcpConnectionId. Set at least one of forwardUserId or forwardedMetadataKeys. See update MCP Attachment.

Types

Canonical shapes are in objects and schemas.

Errors

Expect invalid_request for invalid configuration and not_found for inaccessible resources. AGENT_VERSION_NOT_FOUND identifies a missing numbered Version. ADMIN_AGENT_MANAGED rejects update, lifecycle, avatar, deletion, or Task-assignment operations forbidden for the Admin Agent. Sandbox attachment conflicts use the Sandbox-specific codes. A disabled Agent remains readable and configurable, but later Turns fail with AGENT_DISABLED. All methods can raise SDK errors.

Example

import { BlazingAgents } from "@blazing-agents/sdk";
const client = new BlazingAgents({ apiKey: process.env.BLAZING_AGENTS_API_KEY! });

const connection = await client.mcpConnections.create({
  name: "Release tools",
  url: "https://mcp.example.com/",
  authType: "none",
});
const agent = await client.agents.create({
  name: "Release writer",
  mcpConnectionIds: [connection.id],
});
await client.agents.list();
await client.agents.get(agent.id);
await client.agents.update(agent.id, { instructions: "Write concise notes." });
await client.agents.disable(agent.id);
await client.agents.enable(agent.id);
const png = Buffer.from(
  "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mP8/x8AAusB9Y9ZQmcAAAAASUVORK5CYII=",
  "base64",
);
await client.agents.uploadAvatar(
  agent.id,
  new File([png], "avatar.png", { type: "image/png" }),
);
await client.agents.removeAvatar(agent.id);
await client.agents.listVersions(agent.id, { limit: 50 });
await client.agents.getVersion(agent.id, 1);
const restored = await client.agents.restoreVersion(agent.id, 1);
const { mcpAttachments } = await client.agents.listMcpAttachments(agent.id);
await client.agents.updateMcpAttachment(
  agent.id,
  mcpAttachments[0].mcpConnectionId,
  { forwardUserId: true },
);
console.log(restored.version);
await client.agents.delete(agent.id);
await client.mcpConnections.delete(connection.id);

Related

• Agents
• Versions and lifecycle
• Create and attach a Skill
• MCP connections
• REST Agents