Build applications where agents are first-class citizens — not afterthoughts.
When to Use
Load this skill when:
Designing a new application or API on Eve
Evaluating whether an existing app is agent-friendly
Adding features that agents should be able to use
Deciding between putting logic in code vs. in prompts
Choosing how to handle inter-agent communication
The Four Principles
1. Parity — Agents Can Do Everything Users Can
Every user action must have an agent-equivalent path.
On Eve
The CLI IS the parity layer. If a user can do it through
eve ...
, an agent can too. When building your app, apply the same principle:
Check
How
Can agents create/read/update/delete every entity?
Map UI actions to CLI/API equivalents
Are there UI-only workflows?
Expose them as API endpoints or CLI commands
Can agents discover what's available?
Provide
list
operations for every entity type
CRUD Completeness
For every entity in your app, verify agents have Create, Read, Update, and Delete paths. Missing any one breaks parity.
2. Granularity — Atomic Primitives, Not Bundled Logic
Features emerge from agent loops, not monolithic tools.
Wrong
:
deploy_and_monitor(app)
— bundles judgment into code
Wrong
:
classify_and_organize_files(files)
— agent should decide classification
Right
:
eve build create
,
eve build run
,
eve env deploy
,
eve job follow
— agent decides the sequence
On Eve
The manifest defines WHAT (services, pipelines), the agent decides HOW and WHEN to compose them.
Design test
To change behavior, do you edit prose (prompts/skills) or refactor code? If code — your tools aren't atomic enough.
3. Composability — New Features = New Prompts
When tools are atomic and parity exists, you add capabilities by writing prompts, not code.
Eve example
The
eve-pipelines-workflows
skill adds pipeline composition capability. No new CLI commands needed — the skill teaches agents to compose existing
eve pipeline
and
eve workflow
commands.
Your app
If adding a feature requires new API endpoints, you may be bundling logic. Consider whether existing primitives can be composed differently.
4. Emergent Capability — Agents Surprise You
Build atomic tools. Agents compose unexpected solutions. You observe patterns. Optimize common patterns. Repeat.
Eve example
Agents compose
eve job create --parent
+
eve job dep add
+ depth propagation to build arbitrary work hierarchies. The platform didn't prescribe this — agents discovered it from atomic primitives.
Platform Capabilities for Agentic Apps
Beyond the four principles, Eve provides (or is building) specific primitives that make agentic apps dramatically simpler:
Job Attachments — Structured Context Passing
Pass plans, reports, and insights between agents without file gymnastics. Attach text documents (markdown, JSON, YAML) to jobs. Downstream agents read attachments from parent jobs. This solves 80% of the "agents passing structured context" problem.
Service Account Auth — Backend-to-API Communication
Use
eve auth mint
(today) or service accounts (emerging) to authenticate app backends. Every app with a backend needs a non-user token for API calls. Scoped permissions enforce least privilege.
Org Document Store — Persistent Agent Knowledge
Agents accumulate knowledge that outlives individual jobs: architecture reports, risk assessments, conventions. DB-backed with full-text search and agent-native search/replace editing via PATCH operations.
Web Chat — Two Mechanisms
Choose based on your needs:
Gateway Provider
(Mechanism A): WebSocket to Eve gateway. Zero backend. Best for simple chat widgets and admin consoles.
Backend-Proxied
(Mechanism B): App backend calls
POST /internal/orgs/:id/chat/route
. Full control over enrichment, storage, routing. Best for production SaaS.
Decision
If your app intercepts, enriches, or stores conversations → use B. Otherwise → use A.
Cross-Project Queries — Org-Level Intelligence
Portfolio views, dashboards, and any tool spanning multiple projects. Org-level endpoints eliminate N+1 API calls.
See
references/eve-horizon-primitives.md
for the full catalog with API schemas and priority ranking.
Eve-Specific Design Patterns
Files as Universal Interface
Agents know
cat
,
grep
,
mv
,
mkdir
Use
.eve/manifest.yaml
as single source of truth — agents read and edit it
Agent configs live in repo files (
agents.yaml
,
teams.yaml
) — not hidden in databases
Directory structure = information architecture:
{entity_type}/{entity_id}/content
Name files by purpose:
{entity}.json
,
{type}.md
,
agent_log.md
Context Injection (Three Layers)
System prompts should include:
Available resources
— what exists, with counts: "12 notes in /notes, 3 projects"
Capabilities
— what agents can do: "Create, edit, tag, delete notes"
Recent activity
— what happened: "User created 'Project kickoff' 2 hours ago"
Eve injects
EVE_API_URL
,
EVE_PROJECT_ID
,
EVE_ORG_ID
,
EVE_ENV_NAME
into every environment. Skills provide domain vocabulary.
Explicit Completion Signals
Jobs return
json-result
with
eve.status
("success", "failed", "waiting")
No heuristic completion detection — explicit signals always
Track progress at task level with phase transitions
Support
shouldContinue
for multi-step operations
Checkpoint state for resume on interruption
Dynamic Capability Discovery
eve job list
discovers available work
eve agents list
discovers available agents
Skills system auto-discovers capabilities at install time
Gateway routes messages to agents by slug — new agents are instantly addressable
Prefer runtime discovery (
list_available_types()
) over static tool-per-endpoint mapping
Agent-to-UI Communication
Event types:
thinking
,
toolCall
,
toolResult
,
textResponse
,
statusChange
No silent actions — changes visible immediately
Show progress during execution, not just results
Consider
ephemeralToolCalls
for noisy internal operations
The Success Checklist
Architecture:
Every UI action has a CLI/API equivalent (parity)
Every entity has full CRUD (completeness)
Tools do one thing; agent decides composition (granularity)
Adding capability = adding a skill/prompt, not code (composability)
Agent can handle requests you didn't explicitly design for (emergent)
Implementation:
Manifest and config files are the source of truth (files as interface)
System prompt includes resources, capabilities, and recent activity (context injection)
Completion is explicit, not heuristic (json-result with eve.status)
Agent actions reflect immediately in UI (visibility)
Dynamic discovery works for new capabilities (extensibility)
If building an app with a backend:
Service account auth configured for API access
Web chat mechanism chosen (gateway vs. proxied)
Job attachments used for structured inter-agent context
Org document store for persistent knowledge (when available)
Anti-Patterns
Anti-Pattern
Fix
Agent as router only
Let agents act, not just route
Workflow-shaped tools (
analyze_and_deploy
)
Break into atomic primitives
UI-only actions
Maintain parity — add CLI/API paths
Context starvation
Inject resources via skills and env vars
Gates without reason
Default to open; keep primitives available
Heuristic completion
Use explicit completion signals
Static API mapping
Use dynamic capability discovery
Stuffing context in job descriptions
Use job attachments for structured docs
Per-user tokens for backends
Use service accounts / eve auth mint
Polling for events
Use webhooks when available (emerging)
Reference
See
references/eve-horizon-primitives.md
for the full platform primitives catalog with API schemas, DB designs, and implementation priority ranking.
For the source philosophy:
../eve-horizon/docs/ideas/agent-native-design.md
For platform primitives analysis:
../eve-horizon/docs/ideas/platform-primitives-for-agentic-apps.md