Agents

An Agent is a tenant-owned configuration record. It is not a person, running process, Session or Turn; create one when you need reusable behavior and capability selections for execution.

What an Agent controls

An Agent stores its name, model string, Provider selection, instructions, selected Skills and Tool groups, MCP Connection attachments, optional Sandbox, automatic Memory injection setting, Attribution fields, and avatar. Its current Version number and lifecycle status report configuration history and whether new Turns can begin.

How configuration is resolved

For each execution, Blazing Agents resolves the latest Agent configuration or an explicit Version Pin, then loads the selected Provider credential, current Skill content, current MCP Connection state, and visible Memories. The Agent stores resource IDs and selections; it does not copy those resources into itself.

A Version can record a historical sandboxId, but execution always uses the Agent's current Sandbox. The model loop runs in the platform dispatcher, and Provider credentials never enter the Sandbox.

Create an Agent

This smallest useful Agent leaves optional attachments at their defaults:

import { BlazingAgents } from "@blazing-agents/sdk";

const client = new BlazingAgents({
  apiKey: process.env.BLAZING_AGENTS_API_KEY!,
});

const agent = await client.agents.create({
  name: "Support writer",
  model: "deepseek/deepseek-v4-flash",
  instructions: "Answer clearly and briefly.",
});

if (!agent.id.startsWith("ag_")) throw new Error("Unexpected Agent ID");
console.log(agent.id);

The returned Agent has Version 1, status active, and the omitted fields use the defaults shown below.

Fields, defaults, and updates

Tenant-managed Agent updates are partial merges: omitted fields remain unchanged. Every accepted ordinary update creates a new Version, including a same-value update. Avatar upload and removal, and enable and disable, are separate operations rather than update fields. Avatar uploads accept PNG, JPEG, or WebP files up to 512 KiB and do not create a Version.

The Admin Agent is platform-managed. Tenants can read it, list and get its platform-written Versions, and create Sessions with a Version Pin. They cannot update or restore it, disable or enable it, delete it, change its avatar or MCP attachments, or assign it to a Task; rejected mutations return ADMIN_AGENT_MANAGED.

Attach other capabilities

Attachment IDs must resolve within the Agent's Tenant, except curated platform Skills. Selecting file_operation_sandbox requires an attached Sandbox; selecting no file Tool group requires none. The memory Tool group lets the Agent manage Memory, while memoryInjectionEnabled independently adds visible Memories to execution context.

Ownership, security, and deletion

An API credential can access only its Tenant's Agent records, and Provider, Skill, MCP Connection, and Sandbox attachments are validated against the same Tenant boundary. Provider API keys are write-only. Avatar bytes stay in private storage; responses contain only a short-lived signed avatarUrl, never the object key.

Deleting a tenant-managed Agent permanently removes its Agent-owned Versions, Sessions, Tasks, Artifacts, Memories, and attachments, and reclaims its avatar bytes. It does not delete an attached Provider, Skill, MCP Connection, or Sandbox. Historical Usage survives deletion: per-Turn usage logs and daily rollups retain the deleted agentId without an Agent foreign key.

For the Attribution model, see Tenancy and end-user attribution.

Related guides

Follow Bring your own Provider to attach Tenant-managed model credentials.

Reference

See the Agents TypeScript SDK Reference and Agents REST API Reference for exact operations and error contracts. Return to Configure your Agent for the configuration topic index.