Update agent

Update an agent configuration

PATCH /agents/{agent_id}

Python

Python

import os
from datagrid_ai import Datagrid

client = Datagrid(
    api_key=os.environ.get("DATAGRID_API_KEY"),  # This is the default and can be omitted
)
agent = client.agents.update(
    agent_id="agent_id",
)
print(agent.id)

200

{
  "id": "<string>",
  "name": "<string>",
  "emoji": "<string>",
  "description": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "knowledge_ids": [
    "<string>"
  ],
  "corpus": [
    {
      "knowledge_id": "<string>"
    }
  ],
  "system_prompt": "<string>",
  "custom_prompt": "<string>",
  "planning_prompt": "<string>",
  "agent_model": "magpie-2.0",
  "llm_model": "gemini-2.5-flash",
  "tools": [
    {
      "name": "<string>",
      "connection_id": "<string>"
    }
  ],
  "mcp_servers": [
    {
      "server_id": "<string>",
      "name": "<string>",
      "base_url": "<string>",
      "status": "<string>",
      "credential_id": "<string>",
      "tool_count": 123,
      "last_synced_at": "2023-11-07T05:31:56Z"
    }
  ]
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

agent_id · string · required

The ID of the agent to update

Body

application/json

knowledge_ids · string[] | null · deprecated

Deprecated, use corpus instead. Array of Knowledge IDs the agent should use during the converse. When omitted, all knowledge is used.

corpus · object[] | null

Array of corpus items the agent should use during the converse. When omitted, all knowledge is used.

Option 1

Option 2

Show child attributes

system_prompt · string | null

Directs your AI Agent's operational behavior.

custom_prompt · string | null

Use custom prompt to instruct the style and formatting of the agent's response

planning_prompt · string | null

Define the planning strategy your AI Agent should use when breaking down tasks and solving problems

tools · (string | object)[] | null

Array of the agent tools to enable. If not provided, or null is provided - default tools of the agent are used. If empty list provided - none of the tools are used. When connection_id is set for a tool, it will use that specific connection instead of the default one.

Structured outputs (Converse): All agent_model values support JSON Schema constrained responses via text.format on the Converse request.

Tool availability by agent model (aligned with in-app Execute / Extended / direct LLM; see Converse chat_mode for Ask vs agent_model):

• Execute (magpie-2.0, magpie-2.5, magpie-1.1): All tools below are available.
• Extended (magpie-1.1-flash): Only semantic_search is supported. Requests specifying other tools will be rejected with a 400 error.
• Direct LLM (llm-only): No tools are executed. Requests specifying tools will be rejected with a 400 error.

Knowledge management tools:

• data_analysis: Answer statistical or analytical questions like "Show my quarterly revenue growth"
• semantic_search: Search knowledge through natural language queries.
• agent_memory: Agents can remember experiences, conversations and user preferences.
• schema_info: Helps the Agent understand column names and dataset purpose. Avoid disabling
• table_info: Allow the AI Agent to get information about datasets and schemas
• create_dataset: Agents respond with data tables

Actions:

• calendar: Allow the Agent to access and make changes to your Google Calendar
• schedule_recurring_message_tool: Eliminate busywork such as: "Send a summary of today's meetings at 5pm on workdays"

Data processing tools:

• data_classification: Agents handle queries like "Label these emails as high, medium, or low priority"
• data_extraction: Helps the agent understand data from other tools. Avoid disabling
• image_detection: Extract information from images using AI
• pdf_extraction: Extraction of information from PDFs using AI

Enhanced response tools:

• connect_data: Agents provide buttons to import data in response to queries like "Connect Hubspot"
• download_data: Agents handle queries like "download the table as CSV"

Web tools:

• web_search: Agents search the internet, and provide links to their sources
• fetch_url: Fetch URL content
• company_prospect_researcher: Agents provide information about companies
• people_prospect_researcher: Agents provide information about people

The unique identifier for a tool.

disabled_tools · (string | object)[] | null

Array of the agent tools to disable. Disabling is performed after the 'agent_tools' rules are applied. For example, agent_tools: null and disabled_tools: [data_analysis] will enable everything but the data_analysis tool. If nothing or [] is provided, nothing is disabled and therefore only the agent_tools setting is relevant.

The unique identifier for a tool.

llm_model · enum<string> string · default: gemini-2.5-flash

The LLM used to generate responses.

Available options: gemini-3-pro-preview, gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-2.5-pro-preview-05-06, gemini-2.5-flash, gemini-2.5-flash-preview-04-17, gemini-2.5-flash-native-audio-preview-12-2025, gemini-2.5-flash-lite, gpt-5, gpt-5.1, gemini-2.0-flash-001, gemini-2.0-flash, gemini-1.5-pro-001, gemini-1.5-pro-002, gemini-1.5-flash-002, gemini-1.5-flash-001, chatgpt-4o-latest, gpt-4o, gpt-4, gpt-4-turbo, gpt-4o-mini

temperature · number | null

Sampling temperature for model output. Lower values are more deterministic; higher values are more diverse.

Required range: 0 <= x <= 1

agent_model · Option 1 · enum<string> Option 2 · enum<string> · default: magpie-2.0

The agent model determines the processing mode for Converse requests. The Datagrid web app exposes Ask, Extended, and Execute as Converse chat_mode (llm_router, light_agent, full_agent). The values below set config.agent_model (model tier and tool limits)—use both fields when mirroring in-app behavior.

Execute (full tool use, planning, and multi-step reasoning; aligns with Execute in the web app / full_agent):

• magpie-2.0 — Default. Full agent model with proactive planning and reasoning.
• magpie-2.5 — Beta. Latest full-agent model — faster, more adaptable, and built to handle a broader range of real-world tasks.
• magpie-1.1 — Previous-generation full agent model.

Extended (search-focused; aligns with Extended in the web app / light_agent; not Ask):

• magpie-1.1-flash — Fast model optimized for RAG use cases. Only supports the semantic_search tool. A 400 error will be returned if other tools are specified.

Direct LLM (no tool execution; agent_model only—Ask in the web app is chat_mode: llm_router, not magpie-1.1-flash):

• llm-only — Runs a direct LLM conversation with no planning or tool calls. A 400 error will be returned if tools are specified.

Can also accept any custom string value for future model versions.

Available options: magpie-1.1, magpie-1.1-flash, magpie-2.0, magpie-2.5, magpie-2.5-flash, llm-only

mcp_servers · object[] | null

Registered MCP servers to enable for this agent.

Show child attributes

name · string | null

The name of the agent

Maximum string length: 255

emoji · string | null

The emoji of the agent

Maximum string length: 255

description · string | null

The description of the agent

Maximum string length: 1000

Response

200

application/json

Updated agent

object · enum<string> · required

The object type, always 'agent'

Available options: agent

id · string · required

Unique identifier for the agent

name · string · required

The name of the agent

emoji · string | null · required

The emoji of the agent

description · string | null · required

The description of the agent

created_at · string<date-time> · required

The ISO string for when the agent was created

knowledge_ids · string[] | null · required · deprecated

Deprecated, use corpus instead. Array of Knowledge IDs the agent should use during the converse. When omitted, all knowledge is used.

corpus · object[] | null · required

Array of corpus items the agent should use during the converse. When omitted, all knowledge is used.

Option 1

Option 2

Show child attributes

system_prompt · string | null · required

Directs your AI Agent's operational behavior.

custom_prompt · string | null · required

Use custom prompt to instruct the style and formatting of the agent's response

planning_prompt · string | null · required

Define the planning strategy your AI Agent should use when breaking down tasks and solving problems

agent_model · Option 1 · enum<string> Option 2 · enum<string> · default: magpie-2.0 · required

The agent model determines the processing mode for Converse requests. The Datagrid web app exposes Ask, Extended, and Execute as Converse chat_mode (llm_router, light_agent, full_agent). The values below set config.agent_model (model tier and tool limits)—use both fields when mirroring in-app behavior.

Execute (full tool use, planning, and multi-step reasoning; aligns with Execute in the web app / full_agent):

• magpie-2.0 — Default. Full agent model with proactive planning and reasoning.
• magpie-2.5 — Beta. Latest full-agent model — faster, more adaptable, and built to handle a broader range of real-world tasks.
• magpie-1.1 — Previous-generation full agent model.

Extended (search-focused; aligns with Extended in the web app / light_agent; not Ask):

• magpie-1.1-flash — Fast model optimized for RAG use cases. Only supports the semantic_search tool. A 400 error will be returned if other tools are specified.

Direct LLM (no tool execution; agent_model only—Ask in the web app is chat_mode: llm_router, not magpie-1.1-flash):

• llm-only — Runs a direct LLM conversation with no planning or tool calls. A 400 error will be returned if tools are specified.

Can also accept any custom string value for future model versions.

Available options: magpie-1.1, magpie-1.1-flash, magpie-2.0, magpie-2.5, magpie-2.5-flash, llm-only

llm_model · enum<string> string · default: gemini-2.5-flash · required

The LLM used to generate responses.

Available options: gemini-3-pro-preview, gemini-3.1-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-2.5-pro-preview-05-06, gemini-2.5-flash, gemini-2.5-flash-preview-04-17, gemini-2.5-flash-native-audio-preview-12-2025, gemini-2.5-flash-lite, gpt-5, gpt-5.1, gemini-2.0-flash-001, gemini-2.0-flash, gemini-1.5-pro-001, gemini-1.5-pro-002, gemini-1.5-flash-002, gemini-1.5-flash-001, chatgpt-4o-latest, gpt-4o, gpt-4, gpt-4-turbo, gpt-4o-mini

tools · object[] · required

Tools that this agent can use.

Show child attributes

mcp_servers · object[] · required

Registered MCP servers enabled for this agent.

Show child attributes