Skip to main content

Creating Agents

Module: operations:agents | Role: Any member | Licence: Pro+

Any workspace member can create custom agents via Eve using the create_agent tool.

Required Fields​

FieldTypeDescription
agent_idstringUnique identifier (kebab-case, e.g., grid-planning-assistant)
namestringDisplay name
descriptionstringWhat the agent does (shown in agent list)
promptstringSystem prompt — defines personality, expertise, and constraints

Optional Fields​

FieldDefaultDescription
emoji"robot"Display emoji
tool_groups["all"]Which tool groups the agent can access
temperature0.7LLM temperature (0.0-1.0)
modelinherited"sonnet", "opus", "haiku", or null (inherit from parent)
pattern"bespoke"LANES pattern — sets default objective/kr if not provided
objective""What the agent aims to achieve
kr""Key result — how success is measured
visibility"workspace""workspace" (all members) or "restricted"
visible_to[]User IDs (only when visibility is "restricted")
triggers[]Autonomous execution triggers
module_idnullModule to associate with (enables dispatch tool)
mcp_connections[]External MCP server connections — e.g. ["snowflake"] (workspace must have these integrated; call list_agent_tool_groups() to see what's available)

External Integrations (MCP)​

Agents can call external services at dispatch time by declaring mcp_connections. Credentials are resolved from the workspace's connected integrations — the agent never handles secrets directly.

IntegrationScopeWhat it provides
"holistics"Personal onlyQuery analytics and dashboards via Holistics MCP (API key per-person). Cannot be used in mcp_connections — it is user-only and would silently fail for other workspace members and scheduled triggers.
"snowflake"WorkspaceQuery Snowflake data via Cortex Agents MCP.

Use list_agent_tool_groups() to see which integrations are actively connected for the current workspace. Each entry includes a can_be_stored_in_mcp_connections flag — entries where this is false (user-scoped integrations like Holistics) cannot be used in mcp_connections and will be rejected at create/update time. Non-MCP integrations (e.g. Slack) cannot be used as mcp_connections either.

Tool Groups​

Agents declare which tool groups they can access:

GroupToolsDescription
simulationScenario creation, analysis, comparisonEnergy simulation tools
simulation_coreCore simulation without location/hostingSubset for constrained contexts
utilityformat_generic_chart, read_chart_dataData visualization
policyAll policy agent toolsRegulatory intelligence
websearchWeb searchExternal information retrieval
allEverything aboveFull access (default)

Triggers​

Add autonomous execution with optional delivery channels:

{
"triggers": [
{
"type": "cron",
"schedule": "every monday at 06:00 UTC",
"task_prompt": "Generate weekly regulatory digest",
"delivery": ["slack_dm", "email"]
}
]
}

The schedule string is human-readable and always UTC. Accepted forms: daily at HH:MM UTC, every <weekday> at HH:MM UTC, every weekday at HH:MM UTC. Raw crontab notation ("0 6 * * 1") is no longer accepted — it was the source of a day-of-week ambiguity that shifted some agents' fire days by one.

Trigger TypeRequired Fields
cronschedule (human-readable UTC string), optional task_prompt
eventevent (event name)
webhookwebhook_path
manual(none — triggered via Eve)

Delivery Channels​

When a triggered agent completes, its output can be pushed to the user who created the trigger (scheduled_by). Configure via the delivery list on any trigger:

ChannelBehavior
slack_dmSends output as a Slack DM via the workspace's connected Slack bot. Requires the workspace to have an active Slack integration and the user to have a linked Slack account.
emailSends output to the user's registered email address via Mailgun.

Specific targets​

Use colon syntax to send somewhere other than the trigger creator:

TargetBehavior
slack:@handleDM a user by their Slack display name or username (e.g. slack:@nick). Fails if two humans share the same first name and neither has a unique display name.
slack:#channelPost to a channel by name (e.g. slack:#policy). The Eve bot must be invited to private channels.
slack:user@email.comDM a user by their registered email (e.g. slack:nick.woolley@ev.energy). Most reliable option — resolves via Slack's users.lookupByEmail endpoint and survives handle collisions. Bot needs the users:read.email scope.
email:user@example.comSend an email to any address.

Targets can be combined with commas: slack:@nick,#policy.

Both top-level channels can be used together. If a channel fails (e.g., no Slack integration), the other channels still deliver. If no delivery is specified, agent output is logged but not pushed — the user would need to ask Eve for results.

Agent Lifecycle​

  1. Create — Agent registered in workspace, dispatch tool auto-generated if module_id set
  2. Use — Eve dispatches to agent via auto-generated tool (e.g., ask_grid_planning_assistant)
  3. Update — Modify prompt, tools, triggers, visibility (workspace agents only)
  4. Delete — Remove agent, dispatch tool, and team memberships

Permissions​

OperationWho Can Do It
CreateAny workspace member
Read/ListAny member (respecting visibility)
UpdateCreator only (for workspace agents)
DeleteCreator only (for workspace agents)
Modify builtinNobody (immutable)
Promote/DemotePlatform admin only