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:

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.

每个用户操作都必须有对应的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:

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.

系统提示词应包含：

可用资源——已存在的资源及数量："/notes目录下有12条笔记，3个项目"
能力范围——Agent可执行的操作："创建、编辑、标记、删除笔记"
近期活动——已发生的操作："用户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

成功检查清单

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)

反模式	修复方案
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