Back to Details

eve-agent-native-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent-Native Design for Eve Horizon

面向Eve Horizon的原生Agent应用设计

Build applications where agents are first-class citizens — not afterthoughts.
构建以Agent为一等公民的应用——而非事后补充的角色。

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
在以下场景中加载此skill：
  • 在Eve上设计新应用或API
  • 评估现有应用是否对Agent友好
  • 添加Agent应能使用的功能
  • 决定将逻辑放在代码中还是提示词中
  • 选择如何处理Agent间通信

The Four Principles

四大核心原则

1. Parity — Agents Can Do Everything Users Can

1. 对等性——Agent可执行用户能做的所有操作

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:
CheckHow
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.
每个用户操作都必须有对应的Agent可执行路径。
在Eve上：CLI就是对等层。如果用户能通过
eve ...
完成操作，Agent也能做到。在构建应用时，请遵循相同原则：
检查项实现方式
Agent能否对所有实体执行创建/读取/更新/删除操作？将UI操作映射为CLI/API等效操作
是否存在仅UI可用的工作流？将其暴露为API端点或CLI命令
Agent能否发现可用资源？为每种实体类型提供
list
操作
CRUD完整性：针对应用中的每个实体，验证Agent是否具备创建、读取、更新和删除路径。缺失任何一项都会破坏对等性。

2. Granularity — Atomic Primitives, Not Bundled Logic

2. 粒度化——原子原语，而非捆绑逻辑

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.
功能从Agent循环中涌现，而非来自单体工具。
错误示例：
deploy_and_monitor(app)
——将判断逻辑捆绑到代码中 错误示例：
classify_and_organize_files(files)
——分类决策应由Agent做出 正确示例：
eve build create
, 
eve build run
, 
eve env deploy
, 
eve job follow
——由Agent决定执行顺序
在Eve上：清单定义要做什么（服务、流水线），由Agent决定如何以及何时组合它们。
设计测试：若要更改行为，你需要编辑文本（提示词/skill）还是重构代码？如果是代码——说明你的工具不够原子化。

3. Composability — New Features = New Prompts

3. 可组合性——新增功能=新增提示词

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.
当工具具备原子性且满足对等性时，你只需编写提示词而非代码即可添加功能。
Eve示例：
eve-pipelines-workflows
skill添加了流水线组合功能。无需新增CLI命令——该skill教会Agent组合现有的
eve pipeline
和
eve workflow
命令。
你的应用：如果添加功能需要新增API端点，你可能在捆绑逻辑。请考虑现有原语是否可以通过不同方式组合实现。

4. Emergent Capability — Agents Surprise You

4. 涌现能力——Agent会带来惊喜

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.
构建原子化工具。Agent会组合出意想不到的解决方案。你观察模式，优化常见模式，重复此过程。
Eve示例：Agent组合
eve job create --parent
+ 
eve job dep add
+ 深度传播来构建任意工作层级。平台并未规定这种方式——Agent从原子原语中自主发现了该方法。

Platform Capabilities for Agentic Apps

面向Agent应用的平台能力

Beyond the four principles, Eve provides (or is building) specific primitives that make agentic apps dramatically simpler:
除四大原则外，Eve还提供（或正在开发）特定原语，可大幅简化Agent应用的开发：

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.
无需复杂的文件操作即可在Agent间传递计划、报告和洞察。将文本文档（markdown、JSON、YAML）附加到作业中。下游Agent可从父作业中读取附件。这解决了80%的「Agent间传递结构化上下文」问题。

Service Account Auth — Backend-to-API Communication

服务账号认证——后端与API通信

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.
使用
eve auth mint
（当前版本）或服务账号（即将推出）对应用后端进行认证。每个带后端的应用都需要非用户令牌来调用API。范围权限遵循最小权限原则。

Org Document Store — Persistent Agent Knowledge

组织文档存储——Agent持久化知识

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.
Agent积累的知识可超越单个作业的生命周期：架构报告、风险评估、约定规范。基于数据库构建，支持全文搜索，以及通过PATCH操作实现原生Agent的搜索/替换编辑。

Web Chat — Two Mechanisms

Web聊天——两种机制

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.
根据需求选择：
  • 网关提供商（机制A）：WebSocket连接到Eve网关。无需后端。最适合简单聊天组件和管理控制台。
  • 后端代理（机制B）：应用后端调用
    POST /internal/orgs/:id/chat/route
    。可完全控制消息增强、存储和路由。最适合生产级SaaS。
决策依据：如果你的应用需要拦截、增强或存储对话 → 使用机制B。否则 → 使用机制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.
组合视图、仪表板以及任何跨多个项目的工具。组织级端点消除了N+1次API调用。
查看
references/eve-horizon-primitives.md
获取完整的原语目录，包含API schema和优先级排序。

Eve-Specific Design Patterns

Eve专属设计模式

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
  • Agent熟悉
    cat
    , 
    grep
    , 
    mv
    , 
    mkdir
    命令
  • 使用
    .eve/manifest.yaml
    作为单一事实来源——Agent可读取和编辑它
  • Agent配置存储在仓库文件中（
    agents.yaml
    , 
    teams.yaml
    ）——而非隐藏在数据库中
  • 目录结构=信息架构：
    {entity_type}/{entity_id}/content
  • 按用途命名文件：
    {entity}.json
    , 
    {type}.md
    , 
    agent_log.md

Context Injection (Three Layers)

上下文注入（三层）

System prompts should include:
  1. Available resources — what exists, with counts: "12 notes in /notes, 3 projects"
  2. Capabilities — what agents can do: "Create, edit, tag, delete notes"
  3. 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.
系统提示词应包含：
  1. 可用资源——已存在的资源及数量："/notes目录下有12条笔记，3个项目"
  2. 能力范围——Agent可执行的操作："创建、编辑、标记、删除笔记"
  3. 近期活动——已发生的操作："用户2小时前创建了'项目启动'"
Eve会将
EVE_API_URL
, 
EVE_PROJECT_ID
, 
EVE_ORG_ID
, 
EVE_ENV_NAME
注入到每个环境中。Skill提供领域词汇。

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
  • 作业返回带
    eve.status
    （"success", "failed", "waiting"）的
    json-result
  • 无启发式完成检测——始终使用明确信号
  • 通过阶段转换在任务级别跟踪进度
  • 为多步骤操作支持
    shouldContinue
  • 检查点状态，以便中断后恢复

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
  • eve job list
    发现可用工作
  • eve agents list
    发现可用Agent
  • Skill系统在安装时自动发现能力
  • 网关按slug将消息路由到Agent——新Agent可立即被寻址
  • 优先使用运行时发现（
    list_available_types()
    ）而非静态的工具-端点映射

Agent-to-UI Communication

Agent与UI通信

  • 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
  • 事件类型：
    thinking
    , 
    toolCall
    , 
    toolResult
    , 
    textResponse
    , 
    statusChange
  • 无静默操作——变更立即可见
  • 执行过程中显示进度，而非仅展示结果
  • 考虑为嘈杂的内部操作使用
    ephemeralToolCalls

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)
架构：
  • 每个UI操作都有对应的CLI/API等效操作（对等性）
  • 每个实体都具备完整CRUD能力（完整性）
  • 工具仅完成单一功能；由Agent决定组合方式（粒度化）
  • 添加能力=添加skill/提示词，而非代码（可组合性）
  • Agent可处理你未明确设计的请求（涌现能力）
实现：
  • 清单和配置文件是事实来源（文件作为接口）
  • 系统提示词包含资源、能力范围和近期活动（上下文注入）
  • 完成状态明确，非启发式判断（带eve.status的json-result）
  • Agent操作立即在UI中反映（可见性）
  • 动态发现可支持新能力（可扩展性）
若构建带后端的应用：
  • 已配置服务账号认证用于API访问
  • 已选择Web聊天机制（网关 vs 代理）
  • 已使用作业附件实现Agent间结构化上下文传递
  • 已使用组织文档存储持久化知识（当可用时）

Anti-Patterns

反模式

Anti-PatternFix
Agent as router onlyLet agents act, not just route
Workflow-shaped tools (
analyze_and_deploy
)		Break into atomic primitives
UI-only actionsMaintain parity — add CLI/API paths
Context starvationInject resources via skills and env vars
Gates without reasonDefault to open; keep primitives available
Heuristic completionUse explicit completion signals
Static API mappingUse dynamic capability discovery
Stuffing context in job descriptionsUse job attachments for structured docs
Per-user tokens for backendsUse service accounts / eve auth mint
Polling for eventsUse webhooks when available (emerging)
反模式修复方案
Agent仅作为路由器让Agent执行操作，而非仅路由
工作流形状的工具（
analyze_and_deploy
）		拆分为原子原语
仅UI可用的操作保持对等性——添加CLI/API路径
上下文缺失通过skill和环境变量注入资源
无意义的权限限制默认开放；保持原语可用
启发式完成检测使用明确的完成信号
静态API映射使用动态能力发现
将上下文塞进作业描述使用作业附件存储结构化文档
后端使用每个用户的令牌使用服务账号 / eve auth mint
轮询事件可用时使用webhooks（即将推出）

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
查看
references/eve-horizon-primitives.md
获取完整的平台原语目录，包含API schema、数据库设计和实现优先级排序。
核心理念来源：
../eve-horizon/docs/ideas/agent-native-design.md
平台原语分析：
../eve-horizon/docs/ideas/platform-primitives-for-agentic-apps.md