Custom agents

Agent architecture

Emergent uses a hierarchical agent system to break down complex application-building tasks into manageable units of work. At the top level, a main agent orchestrates the overall build process, while sub-agents handle specialized tasks like testing, published app, or integration work.

Each agent is a language model instance equipped with:

Context - the current state of your app (files, preview database schema, dependencies)
Tools - callable functions to read/write code, run commands, query the database, publish, etc.
Instructions - system prompts that define the agent's role and constraints
Memory - conversation history and state from prior turns

Agents collaborate by spawning sub-agents when a task requires focused expertise (for example, a sub-agent might handle writing unit tests while the main agent continues with feature development). This division of labor keeps each agent's context window focused and improves both speed and quality.

Note

You can inspect agent logs, tool calls, and sub-agent activity in real time as your app builds.

Main agents

The main agent is the primary autonomous worker that interprets your chat messages and drives the build-test-publish cycle. When you describe a feature, fix, or new app in chat, the main agent:

Plans the work by breaking your request into implementation steps
Executes those steps using its tools (editing files, running commands, querying docs)
Validates the result (spawning test sub-agents, checking build output)
Reports back in chat with a summary, diff preview, or follow-up questions

The main agent has access to the full workspace: your app's source tree, environment variables, database, and publish config. It decides when to delegate work to sub-agents and when to proceed autonomously.

Stop reasons determine when a main agent pauses and returns control to you. Common stop reasons include:

Successful completion of your request
A question or clarification needed
An error that requires human input (e.g., missing API key)
Credit budget exhausted

For a detailed walk-through of the agent workflow, see How the agent runs.

Sub-agents

Sub-agents are ephemeral, specialized agents spawned by the main agent to handle discrete tasks. They inherit relevant context from the main agent but operate with a narrower scope and tailored instructions.

Common sub-agent roles:

Test agents - write and run unit/integration tests, validate outputs
Published app agents - handle build steps, environment provisioning, and publish commands
Integration agents - configure third-party services (Stripe, Twilio, MCP servers)
Refactor agents - clean up code, apply linting, optimize performance

Sub-agents execute in parallel when possible, report results back to the main agent, and terminate once their task completes. They do not persist across turns or interact directly with you in chat.

Tip

Sub-agent logs appear nested under the main agent's activity. You can expand them to see tool calls and outputs.

Custom tools

You can extend agent capabilities by providing custom tools via MCP (Model Context Protocol) servers. Custom tools are useful for:

Calling proprietary or internal APIs not covered by built-in integrations
Performing domain-specific calculations or transformations
Interfacing with hardware, legacy systems, or non-standard data sources

Registering a custom tool (MCP server)

Custom tools are MCP servers registered through the platform UI. There is no

tools/

directory, tools are not auto-discovered from files.

Open Manage Agents

Go to Account Settings → Manage Agents → MCP tab.

Configure the MCP server

The modal has separate Name and Description form fields (above the JSON box) - these are their own inputs, not JSON keys. Fill those in, then enter your MCP server configuration as JSON in the

mcpServers

format.

Each server entry takes

command

args

, and

env

- this launches a local process (for example

npx

). There is no

url

field anywhere in this modal.

JSON

{
  "mcpServers": {
    "your-tool": {
      "command": "npx",
      "args": ["-y", "@your-org/mcp-server"],
      "env": {
        "API_KEY": "your-api-key-here"
      }
    }
  }
}

Verify and Save

Click Verify and Save to validate the configuration and register the MCP server with your agents.

Inspect tool calls

Check the agent activity log to see arguments passed and results returned.

Tool execution security

Custom tools run as MCP servers accessible to your agents. Avoid executing untrusted input or performing destructive operations without validation.

Tool best practices

Keep tools focused - one tool per discrete operation. Agents compose multiple tool calls for complex workflows.
Provide clear descriptions - agents rely on natural-language descriptions to decide when to use a tool.
Return structured data - JSON objects are easier for agents to parse than free-form strings.
Handle errors gracefully - return
```
{ error: "message" }
```
rather than throwing, so agents can retry or adjust strategy.

For integrating external platforms via the Model Context Protocol (MCP), see Custom & MCP integrations.