Retrieve agent

Get details of a specific agent

GET /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.retrieve(
    "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 retrieve

Response

200

application/json

Agent details

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