Core Concepts

Agents

Agents are the core building blocks of Meebly AI. Each agent combines a role, a type, system instructions, tools, and optional memory and intelligence settings. Once created in the dashboard, you interact with your agent via API using its unique agent ID.

Agent Types

Every agent is either Conversational or Functional. This determines what endpoint you call and what the agent returns.

Conversational

Chat-based agent that streams natural language responses via SSE. Uses the /v1/chat endpoint.

• Customer support & virtual assistants
• Shopping assistants and product discovery
• Internal knowledge base Q&A
• Any agent that needs to take business actions

Functional

Task-based agent that returns structured JSON matching a predefined output schema. Uses the /v1/execute endpoint.

• Data extraction and transformation
• Semantic search and ranking
• Report generation
• Automated order or workflow processing

Agent Roles

In addition to a type, every agent has a role that controls how it fits into your system.

Assistantdefault

Handles tasks directly using its own tools and instructions. Most agents are Assistant agents. Supports both Conversational and Functional types.

Orchestration

Coordinates a network of sub-agents rather than calling tools directly. It receives the user's request, delegates sub-tasks to specialist agents, and synthesises their results into a final reply. Orchestration agents are always Conversational. See Agent Networks for the full guide.

Creating Agents

Open the Meebly dashboard, navigate to the Agents page within your environment, and click "New Agent". The creation form has three steps.

1Identity & Instructions

Name — the agent's display name (required)
Role — Assistant or Orchestration
Type — Conversational or Functional
Output Schema — required for Functional agents; defines the JSON structure the agent must return
AI Model — use the Meebly default or supply your own API key for OpenAI, Anthropic, Google, or any OpenAI-compatible endpoint
System Instructions — plain text or Markdown that defines the agent's behaviour, personality, and tool usage

2Memory & Behavior

Customer Memory — persist facts about each customer across conversations (see Customer Memory)
Semantic Recall — surface relevant past conversation snippets automatically
Customer Webhook — map an incoming customer ID to your own system's customer ID on each message (see Customer Webhook)
Agent Intelligence — add pre- and post-processors to improve reasoning, planning, and response quality (see Processors)

3Tools & Actions

Actions — connect your backend API endpoints so the agent can fetch data or trigger operations (see Actions)
MCP Servers — attach external tool servers via the Model Context Protocol (see MCP Servers)
Sub-Agents — for Orchestration agents, assign which specialist agents this orchestrator can delegate to

After creating your agent, use the Sandbox page to test it interactively before wiring it into your application.

AI Model

By default, agents use the Meebly-managed model. To use your own model, select Custom in the AI Model section and provide your credentials.

Provider	Available for	Notes
OpenAI	Conversational & Functional	GPT-4o, GPT-4.1, GPT-5, and more
Anthropic	Conversational & Functional	Claude Opus 4, Claude Sonnet 4, and more
Google	Conversational only	Gemini 2.5 Pro, Gemini 2.5 Flash, and more
Custom	Conversational & Functional	Any OpenAI-compatible endpoint (e.g. local Llama)

System Instructions

System instructions define your agent's behaviour, personality, and how it uses its tools. Write them as plain text or Markdown. The dashboard ships with ready-made templates for common patterns (customer support, e-commerce, research, etc.) that you can apply with one click and then customise.

Example Instructions

Conversational Agent — Customer Support:

### TASK You are a customer support agent for an e-commerce store. Help customers with orders, shipping, returns, and product questions. ### CONSTRAINTS - Always verify the customer's email before accessing or modifying an order. - Use the getOrderStatus tool to look up live order data — never guess. - If you can't resolve an issue, offer to escalate to a human agent. ### TONE Friendly, empathetic, and concise.

Functional Agent — Data Extraction:

### TASK Extract structured order data from the user's message and return it as JSON matching the output schema. ### PROCESS 1. Identify all products mentioned (name, quantity, price if stated). 2. Extract shipping address components. 3. Determine requested delivery method (standard / express / same-day). 4. Return JSON — all required fields must be populated. Use null for missing optional fields. ### ERROR HANDLING If required fields cannot be determined from the message, return an error object with a descriptive message field.

Best Practices for System Instructions:

• Be specific about the agent's role and responsibilities
• Describe which tools to call and when
• Define tone and communication style
• Include constraints and error-handling expectations
• For Functional agents, describe the expected output format and what to do when data is missing

Using Agents via API

Once your agent is created you'll find its agent ID in the dashboard. Pass this ID on every API request.

javascript

// Conversational agent — streams responses via SSE
const response = await fetch('https://api.meebly.ai/v1/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    agentId: 'agent_abc123',       // From dashboard
    environmentId: 'env_xyz789',
    messages: [{ content: 'Hello!' }]
  })
});

// Functional agent — returns structured JSON
const result = await fetch('https://api.meebly.ai/v1/execute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  },
  body: JSON.stringify({
    agentId: 'agent_abc123',
    environmentId: 'env_xyz789',
    userContext: 'Extract order details',
    inputParameters: {
      message: 'I want 2x blue widgets shipped to 123 Main St'
    }
  })
});

Each agent is scoped to an environment. Swap the environmentId to target your development, staging, or production environment. See Environments for details.

PreviousAuthentication NextAgent Networks

Last updated: March 2026Report an issue