> ## Documentation Index > Fetch the complete documentation index at: https://developers.datagrid.com/llms.txt > Use this file to discover all available pages before exploring further. # Create agent > Create a new agent ## OpenAPI ````yaml post /agents openapi: 3.0.3 info: version: 0.1.1 title: Datagrid API description: Datagrid API servers: - url: https://api.datagrid.com/v1 security: - BearerAuth: [] paths: /agents: post: tags: - Agents summary: Create agent description: Create a new agent operationId: CreateAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' responses: '201': description: Created agent content: application/json: schema: $ref: '#/components/schemas/Agent' x-codeSamples: - lang: JavaScript source: |- import Datagrid from 'datagrid-ai'; const client = new Datagrid({ apiKey: process.env['DATAGRID_API_KEY'], // This is the default and can be omitted }); const agent = await client.agents.create(); console.log(agent.id); - lang: Python source: |- 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.create() print(agent.id) components: schemas: CreateAgentRequest: allOf: - $ref: '#/components/schemas/InputAgentConfig' - type: object properties: name: type: string description: The name of the agent maxLength: 255 nullable: true description: type: string description: The description of the agent maxLength: 1000 nullable: true Agent: allOf: - type: object required: - object - id - name - emoji - description - created_at - agent_model - llm_model - knowledge_ids - corpus - tools - mcp_servers - system_prompt - custom_prompt - planning_prompt properties: object: type: string enum: - agent description: The object type, always 'agent' id: type: string description: Unique identifier for the agent name: type: string description: The name of the agent emoji: type: string description: The emoji of the agent nullable: true description: type: string description: The description of the agent nullable: true created_at: type: string format: date-time description: The ISO string for when the agent was created nullable: false - $ref: '#/components/schemas/AgentConfig' InputAgentConfig: allOf: - $ref: '#/components/schemas/AgentInputConfigCommon' - type: object properties: mcp_servers: type: array items: $ref: '#/components/schemas/AgentMcpServerConfig' description: Registered MCP servers to enable for this agent. nullable: true AgentConfig: allOf: - $ref: '#/components/schemas/AgentConfigShared' - type: object properties: agent_model: $ref: '#/components/schemas/AgentModel' nullable: false llm_model: $ref: '#/components/schemas/LlmModel' nullable: false tools: type: array items: $ref: '#/components/schemas/Tool' description: Tools that this agent can use. nullable: false mcp_servers: type: array items: $ref: '#/components/schemas/AgentMcpServer' description: Registered MCP servers enabled for this agent. nullable: false AgentInputConfigCommon: allOf: - $ref: '#/components/schemas/AgentConfigShared' - type: object properties: tools: $ref: '#/components/schemas/AgentTools' nullable: true disabled_tools: $ref: '#/components/schemas/AgentTools' description: >- 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. nullable: true llm_model: $ref: '#/components/schemas/LlmModel' nullable: true temperature: type: number description: >- Sampling temperature for model output. Lower values are more deterministic; higher values are more diverse. minimum: 0 maximum: 1 nullable: true agent_model: $ref: '#/components/schemas/AgentModel' nullable: true AgentMcpServerConfig: type: object required: - server_id properties: server_id: type: string credential_id: type: string nullable: true AgentConfigShared: type: object properties: knowledge_ids: type: array nullable: true deprecated: true description: >- Deprecated, use corpus instead. Array of Knowledge IDs the agent should use during the converse. When omitted, all knowledge is used. items: type: string corpus: type: array nullable: true description: >- Array of corpus items the agent should use during the converse. When omitted, all knowledge is used. items: oneOf: - $ref: '#/components/schemas/CorpusKnowledgeItem' - $ref: '#/components/schemas/CorpusPageItem' system_prompt: type: string description: Directs your AI Agent's operational behavior. nullable: true custom_prompt: type: string description: >- Use custom prompt to instruct the style and formatting of the agent's response nullable: true planning_prompt: type: string description: >- Define the planning strategy your AI Agent should use when breaking down tasks and solving problems nullable: true AgentModel: anyOf: - $ref: '#/components/schemas/AgentModelEnum' - type: string type: string enum: - magpie-1.1 - magpie-1.1-flash - magpie-2.0 - magpie-2.5 - magpie-2.5-flash - llm-only default: magpie-2.0 description: > 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. nullable: true LlmModel: anyOf: - $ref: '#/components/schemas/LlmModelEnum' - type: string default: gemini-2.5-flash description: >- The LLM used to generate responses. Deprecated Gemini 2.0 Flash ids are accepted for backward compatibility and automatically run as gemini-3.1-flash-lite. Tool: type: object required: - name properties: name: $ref: '#/components/schemas/ToolName' connection_id: type: string description: The ID of the connection to use for the tool. nullable: true AgentMcpServer: type: object required: - object - server_id - name - base_url - status - credential_id properties: object: type: string enum: - agent_mcp_server server_id: type: string name: type: string base_url: type: string format: uri status: type: string tool_count: type: integer last_synced_at: type: string format: date-time credential_id: type: string nullable: true AgentTools: description: > 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 - charts: Agents render charts inline in the conversation (bar, line, area, combo, pie, funnel, gauge, treemap, scorecard). 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 type: array nullable: true items: oneOf: - $ref: '#/components/schemas/ToolName' - $ref: '#/components/schemas/Tool' CorpusKnowledgeItem: type: object required: - type - knowledge_id properties: type: type: string enum: - knowledge description: The type of the corpus item. Always 'knowledge' for knowledge items. x-stainless-const: true knowledge_id: type: string description: The ID of the knowledge to include in the corpus. CorpusPageItem: type: object required: - type - page_id properties: type: type: string enum: - page description: The type of the corpus item. Always 'page' for page items. x-stainless-const: true page_id: type: string description: The ID of the page to include in the corpus. AgentModelEnum: type: string enum: - magpie-1.1 - magpie-1.1-flash - magpie-2.0 - magpie-2.5 - magpie-2.5-flash - llm-only description: Predefined agent model versions LlmModelEnum: type: string description: >- The LLM used to generate responses. Deprecated Gemini 2.0 Flash ids are accepted for backward compatibility and automatically run as gemini-3.1-flash-lite. enum: - gemini-3.5-flash - gemini-3.1-flash-lite - 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 - claude-haiku-4-5@20251001 - claude-sonnet-4-6@default - claude-opus-4-6@default - claude-opus-4-7 - claude-opus-4-8 - anthropic.claude-haiku-4-5-20251001-v1:0 - anthropic.claude-sonnet-4-6 - anthropic.claude-opus-4-6-v1 - anthropic.claude-opus-4-7 - anthropic.claude-opus-4-8 ToolName: type: string description: The unique identifier for a tool. securitySchemes: BearerAuth: type: http scheme: bearer ````