Getting Started

Agents

Understand what an agent is, what it bundles together, and how it scopes prompts, tool access, origins, and budgets for one agent surface.

6 sections

An agent is the runtime boundary for an agent in Emcy.

For Embed, agents are required.

It is more than a chat room and more than a single MCP server.

An agent bundles the things that define how one agent surface should behave:

  • which MCP servers it can use
  • which tools are exposed through those servers
  • the system prompt and model settings
  • allowed origins for embeds
  • widget configuration and playground behavior
  • budgets and usage tracking

When you pass an agentId into the Agent SDK, that id usually points at an agent.

Why agents exist#

Without an agent boundary, every agent surface would need to hand-assemble:

  • prompt rules
  • server access
  • embed rules
  • observability settings
  • usage controls

Agents make those decisions explicit and reusable.

That is what lets the same managed agent surface run in:

  • the Emcy agent UI
  • your embedded app
  • internal testing flows such as playground

What should go in one agent#

A good agent groups tools that belong to one product surface or one job to be done.

Examples:

  • a support agent agent
  • an operations agent
  • a finance workflow agent
  • a customer-facing in-app assistant for one SaaS module

Avoid packing unrelated servers into the same agent just because they are technically available.

The tighter the agent, the better:

  • tool selection
  • auditability
  • prompt quality
  • operator control

How agents affect embedded agents#

For embeds, the agent is the contract between the dashboard and the host app.

The agent decides:

  • which tools the embed can ever call
  • which domains are allowed through Allowed Origins
  • which prompt rules the embedded agent follows
  • which Gateway-backed MCP infrastructure the widget talks to

The host app can still add local clientTools, but it is adding them on top of the agent, not replacing it.

How identity works in a shared agent#

Multiple people can use the same agent without collapsing into one shared permission model.

That is the important distinction.

The agent is shared, but downstream auth can still stay user-scoped:

  • Sarah connects her account
  • Marco connects his account
  • both use the same agent
  • each action still runs under the user who owns the downstream grant

That is why agents are compatible with same-user auth and team collaboration at the same time.

What to configure first#

For a new agent, do these in order:

  1. attach the right MCP servers
  2. write the system prompt
  3. set model behavior and allowed origins
  4. test in playground
  5. embed it in your app or share it with the right team