Management API

Create Agent

POST/v1/agent

Programmatically create a new Agent in a Meebly environment. Agents can be conversational (chat-based) or functional (task-based) and are linked to actions that define their capabilities.

Definition

Headers

bash

X-API-Key: YOUR_API_KEY

Body Parameters

Parameter	Type	Required	Description
`environmentId`	string	Yes	The ID of the environment to create the agent in
`name`	string	Yes	Display name for the agent
`instructions`	string	Yes	System instructions defining the agent's behavior, persona, and responsibilities
`toolIds`	string[]	Yes	Array of action IDs to attach to this agent. Pass an empty array for no actions.
`mcpToolIds`	string[]	Yes	Array of MCP tool IDs to attach to this agent. Pass an empty array for none.
`agentType`	string	No	`conversational` or `functional`. Defaults to `conversational`.
`roleName`	string	No	Controls the agent's role. `assistant` (default) handles tasks directly using tools. `orchestration` coordinates a network of sub-agents instead of calling tools directly.
`displayName`	string	No	Optional alternate display name shown in the chat UI, separate from the internal agent name.
`subAgentIds`	string[]	Yes	Array of agent IDs this orchestration agent can delegate to. Pass an empty array for non-orchestration agents.
`temperature`	number	No	Model temperature between `0` and `1`. Lower values produce more deterministic responses.
`models`	object[]	No	Custom model configurations. Each entry has `name`, `provider`, `apiKey`, and optional `baseUrl`.
`outputSchema`	object	No	JSON Schema defining the structured output for functional agents
`quickActions`	object[]	No	Pre-defined prompt shortcuts shown to users in the chat UI. Each has `label` and `text`.
`enableToolSearch`	boolean	No	Enable semantic search to dynamically select relevant tools from a large action set
`enableCustomerMemory`Premium	boolean	No	Enable persistent customer memory — the agent remembers facts about each customer across conversations.
`enableSemanticRecall`Premium	boolean	No	Enable semantic recall — the agent automatically surfaces relevant snippets from past conversations as hidden context.
`enableHumanHandoff`Premium	boolean	No	Enable human handoff — allows this agent to transfer conversations to a human agent via the Handoffs inbox.
`agenticConfig`Premium	object	No	Agent Intelligence processor pipeline. Contains a `processors` array where each entry has `id`, `name`, `type` (`pre` or `post`), `mode` (`system-prompt` or `llm-node`), `enabled`, and `instructions`. Post-processors may also include a `loop` object with `continueSignal` and `maxIterations` (1–3). See Processors for details.
`profilePictureUrl`Premium	string	No	URL of the agent's avatar shown in the chat UI

Response

Returns 201 Created with the newly created agent object on success.

json

{
  "id": "agent_xyz456",
  "name": "Support Assistant",
  "agentType": "conversational",
  "roleName": "assistant",
  "environmentId": "env_xyz789",
  "toolIds": ["action_abc123"],
  "mcpToolIds": [],
  "subAgentIds": [],
  "temperature": 0.3,
  "quickActions": [
    { "label": "Track my order", "text": "I want to check the status of my order" },
    { "label": "Return policy", "text": "What is your return policy?" }
  ],
  "createdAt": "2025-01-15T12:00:00Z"
}

Store the id returned in the response — you will need it to reference this agent in conversational and functional API calls.

Sample Request

bash

curl -X POST "https://api.meebly.ai/v1/agent" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "environmentId": "env_xyz789",
    "name": "Support Assistant",
    "instructions": "You are a helpful customer support agent. Use the available actions to look up orders and resolve customer issues.",
    "agentType": "conversational",
    "roleName": "assistant",
    "toolIds": ["action_abc123"],
    "mcpToolIds": [],
    "subAgentIds": [],
    "temperature": 0.3,
    "quickActions": [
      { "label": "Track my order", "text": "I want to check the status of my order" },
      { "label": "Return policy", "text": "What is your return policy?" }
    ]
  }'

PreviousCreate Action NextEdit App

Last updated: March 2026Report an issue