Agents

client.agents creates and configures your agents. Every configuration change saves a numbered version you can inspect or restore, and you can pause an agent without losing its setup.

Examples assume client = BlazingAgents() and reuse objects such as provider and agent from earlier examples. Every method also accepts extra_headers and timeout. On AsyncBlazingAgents, await the same method names and use async for with iter_versions().

import os

from blazing_agents import BlazingAgents

client = BlazingAgents()
provider = client.providers.create(
    name="OpenRouter",
    provider_type="openrouter",
    api_key=os.environ["OPENROUTER_API_KEY"],
)
agent = client.agents.create(
    name="Release writer",
    provider_id=provider.id,
    model="openai/gpt-6-luna",
    instructions="Write concise release notes.",
)
print(agent.id, agent.version)

Available operations

Methods

create()

Creates an agent and saves its configuration as version 1.

agent = client.agents.create(
    name="Support agent",
    provider_id=provider.id,
    model="openai/gpt-6-luna",
    tools=["workspace", "memory"],
    user_id="customer_123",
    metadata={"team": "support"},
)

Signature: create(*, name, model=..., provider_id=..., thinking_level=..., workspace_id=..., tools=..., instructions=..., memory_injection_enabled=..., auto_compaction=..., compaction_reserve_tokens=..., approval_in_chat=..., approval_in_tasks=..., user_id=..., metadata=..., mcp_connection_ids=...) -> Agent

Without provider_id and model, the agent is saved unconfigured. Passing only one of them raises ValueError before any request. A workspace created for the agent stays independent afterwards: renaming the agent does not rename it.

An approval policy is a dictionary with a required default decision and an optional list of per-tool overrides. Decisions are "full", "deny", "manual", or "auto". See tool approvals for what each decision does.

Returns Agent. Raises APIStatusError with validation_failed, agent_name_conflict, provider_not_found, model_not_found, model_validation_unavailable, agent_mcp_connection_not_found, or agent_mcp_connections_invalid.

list()

Lists your agents, most recently updated first.

tenant_level = client.agents.list(user_id="").agents

Signature: list(*, user_id=..., workspace_id=...) -> Agents

Returns Agents, whose agents field is list[Agent]. The list is not paginated. Raises validation_failed for invalid filters.

get()

Gets an agent's current configuration.

agent = client.agents.get(agent.id)

Signature: get(agent_id: str) -> Agent

Returns Agent. Raises validation_failed for a malformed ID or not_found.

update()

Changes an agent's configuration and saves the result as the next version, even when the values are unchanged.

agent = client.agents.update(
    agent.id,
    instructions="Write concise release notes and include migration steps.",
)

Signature: update(agent_id: str, *, name=..., model=..., provider_id=..., thinking_level=..., workspace_id=..., tools=..., instructions=..., memory_injection_enabled=..., auto_compaction=..., compaction_reserve_tokens=..., approval_in_chat=..., approval_in_tasks=..., metadata=..., mcp_connection_ids=...) -> Agent

Accepts every create() parameter except user_id, which never changes. Omitted parameters keep their current value. Supplied values replace the old ones completely: tools, mcp_connection_ids, metadata, and each approval policy are full replacements, not patches.

• To change the model on the current provider, pass model alone. To switch providers, pass provider_id and model together; provider_id alone raises ValueError.
• To unconfigure the agent, pass provider_id=None and model=None. Clearing only one raises ValueError.
• thinking_level=None resets to the provider default.
• workspace_id moves the agent to another workspace. It cannot be cleared.

Calling update() with no parameters raises ValueError before any request. Returns Agent with the new version. Raises validation_failed, not_found, agent_name_conflict, provider_not_found, model_not_found, agent_mcp_connection_not_found, or agent_mcp_connections_invalid.

delete()

Permanently deletes an agent with its versions, sessions, tasks, and memories. Its workspace, providers, and MCP connections are kept.

client.agents.delete(agent.id, include_artifacts=False)

Signature: delete(agent_id: str, *, include_artifacts: bool) -> None

include_artifacts is required: True also deletes the agent's published artifacts, and False keeps them. Raises validation_failed or not_found.

disable()

Stops an agent from starting new turns. Turns already running finish normally.

agent = client.agents.disable(agent.id)

Signature: disable(agent_id: str) -> Agent

Returns Agent with status == "disabled". Calling it again is harmless. A disabled agent stays readable and editable, and new turns fail with agent_disabled. Raises not_found.

enable()

Lets a disabled agent start turns again.

agent = client.agents.enable(agent.id)

Signature: enable(agent_id: str) -> Agent

Returns Agent with status == "active". Calling it again is harmless. Scheduled task runs skipped while the agent was disabled do not run afterwards. Raises not_found.

upload_avatar()

Sets or replaces the agent's avatar. This does not create a version.

from pathlib import Path

agent = client.agents.upload_avatar(agent.id, Path("avatar.webp"))

Signature: upload_avatar(agent_id: str, file: UploadFile, *, filename: str | None = None, content_type: str | None = None) -> Agent

file is a PNG, JPEG, or WebP image of at most 512 KiB, given as bytes, a file path, or an open binary file. The SDK opens and closes paths itself and never closes a file object you pass. Bytes need filename; paths and named file objects supply their own. content_type overrides the type guessed from the filename.

Returns Agent whose avatar_url is a short-lived signed URL. A missing filename raises ValueError. Raises validation_failed for a missing, oversized, or unsupported file, or not_found.

remove_avatar()

Removes the avatar. This does not create a version, and calling it again is harmless.

agent = client.agents.remove_avatar(agent.id)

Signature: remove_avatar(agent_id: str) -> Agent

Returns Agent with avatar_url is None. Raises validation_failed or not_found.

list_versions()

Gets one page of the agent's saved versions, newest first.

page = client.agents.list_versions(agent.id, limit=20)

Signature: list_versions(agent_id: str, *, cursor=..., limit=...) -> AgentVersionsPage

limit is 1 to 200 and defaults to 50. Pass the previous page's next_cursor as cursor to get the next page. Returns AgentVersionsPage with data: list[AgentVersion] and next_cursor: str | None. Raises validation_failed, invalid_cursor, or not_found.

iter_versions()

Iterates every version, fetching pages as you go.

for version in client.agents.iter_versions(agent.id, limit=20):
    print(version.version, version.model)

Signature: iter_versions(agent_id: str, *, cursor=..., limit=...) -> Iterator[AgentVersion]

No request is sent until you start iterating. On the async client, use async for directly on iter_versions(...); do not await it. Each page request can raise the same errors as list_versions().

get_version()

Gets one saved version by number.

first = client.agents.get_version(agent.id, 1)

Signature: get_version(agent_id: str, version: int) -> AgentVersion

Returns AgentVersion. Raises validation_failed or not_found.

restore_version()

Copies an old version's configuration into a new latest version. History is never rewritten.

agent = client.agents.restore_version(agent.id, 1)

Signature: restore_version(agent_id: str, version: int) -> Agent

The SDK reads the version with get_version(), then saves its fields through update(). That copies the name, provider and model, thinking level, compaction settings, memory injection, tools, approval policies, instructions, metadata, and MCP connections. The workspace, user_id, status, and avatar stay as they are, because versions do not store them.

Returns the updated Agent. It can raise any error from either call, for example provider_not_found when the old provider was deleted.

list_mcp_attachments()

Lists how the agent forwards end-user details to each of its MCP connections.

attachments = client.agents.list_mcp_attachments(agent.id).mcp_attachments

Signature: list_mcp_attachments(agent_id: str) -> McpAttachments

Returns McpAttachments, whose mcp_attachments field is list[McpAttachment], one per connection in the agent's mcp_connection_ids. Raises validation_failed or not_found.

update_mcp_attachment()

Chooses whether the agent sends the end user's ID and selected metadata keys to one MCP connection. This does not create a version.

attachment = client.agents.update_mcp_attachment(
    agent.id,
    "mcp_0123456789abcdef",
    forward_user_id=True,
    forwarded_metadata_keys=["locale"],
)

Signature: update_mcp_attachment(agent_id: str, mcp_connection_id: str, *, forward_user_id=..., forwarded_metadata_keys=...) -> McpAttachment

Pass at least one; omitting both raises ValueError. Returns McpAttachment. Raises validation_failed or not_found.

Response models

Agent

AgentVersion

A saved configuration. It has agent_id, tenant_id, version, created_at, and the same configuration fields as Agent: name, provider_id, model, thinking_level, tools, instructions, memory_injection_enabled, auto_compaction, compaction_reserve_tokens, approval_in_chat, approval_in_tasks, metadata, and mcp_connection_ids. It has no workspace_id, user_id, avatar, status, or updated_at.

McpAttachment

Next

• Agents guide
• Versions and lifecycle
• Providers