Transform a full-stack app into one where agents are primary actors — reasoning, coordinating, remembering, and communicating alongside humans.
When to Use
Load this skill when:
Designing an app where agents are primary users alongside (or instead of) humans
Adding agent capabilities to an existing Eve app
Choosing between human-first and agent-first architecture
Deciding how agents should coordinate, remember, and communicate
Prerequisite: Start with the Foundation
Loadeve-fullstack-app-design first. The agentic layer builds on a solid PaaS foundation. Without a well-designed manifest, service topology, database, pipeline, and deployment strategy, agentic capabilities collapse into chaos.
# Child stores findings
eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'
# Parent reads on resume
eve job attachment $CHILD_JOB_ID findings.json --out ./child-findings.json
用于文档挂载的资源引用
将特定的组织文档版本固定为作业输入：
eve job create \
--description "Review the approved plan" \
--resource-refs='[{"uri":"org_docs:/pm/features/FEAT-123.md@v3","label":"Plan","mount_path":"pm/plan.md"}]'
文档被加载到工作区中的挂载路径。事件会跟踪加载成功或失败。
协调线程
当团队分发工作时，一个协调线程（coord:job:{parent_job_id}）会链接父作业和子作业。子作业读取 .eve/coordination-inbox.md 以获取兄弟作业的上下文。通过 eve thread post 发布更新。负责人智能体可以 eve supervise 来监控作业树。
访问与安全
服务账户
后端服务需要非用户令牌来进行 API 调用。使用 eve auth mint 创建范围受限的令牌：
eve auth mint --email app-bot@example.com --project proj_xxx --role admin
Agents are defined in agents.yaml (path set via x-eve.agents.config_path in the manifest). Each agent is a persona with a skill, access scope, and policies.
Root job + parallel child per member. Best for decomposable tasks.
council
Collective judgment
All agents respond, results merged by strategy (majority, unanimous, lead-decides). Best for reviews, audits.
relay
Sequential handoff
Lead delegates to first member, output passes to next. Best for staged workflows.
Design principle : Most work is fanout. Use council only when multiple perspectives genuinely improve the outcome. Use relay only when each stage's output is the next stage's input.
Harness Profiles
Define named profiles in the manifest. Agents reference profiles, never specific harnesses.
x-eve:
agents:
profiles:
primary-coder:
- harness: claude
model: opus-4.5
reasoning_effort: high
- harness: codex
model: gpt-5.2-codex
reasoning_effort: high
fast-reviewer:
- harness: mclaude
model: sonnet-4.5
reasoning_effort: medium
Profile entries are a fallback chain: if the first harness is unavailable, the next is tried. Design profiles around capability needs, not provider loyalty.
Model Selection Guidance
Task Type
Profile Strategy
Complex coding, architecture
High-reasoning model (opus, gpt-5.2-codex)
Code review, documentation
Medium-reasoning model (sonnet, gemini)
Triage, routing, classification
Fast model (haiku-equivalent, low reasoning)
Specialized domains
Choose the model with strongest domain performance
Memory Design
Load eve-agent-memory for the full storage primitive catalog. This section focuses on architectural decisions.
Memory without expiry becomes noise. For every storage location, decide:
Who writes? Which agents create and update this knowledge.
Who reads? Which agents query it and when (job start? on demand?).
When does it expire? Tag with creation dates. Build periodic cleanup jobs.
How does it stay current? Search before writing. Update beats create.
Event-Driven Coordination
The Event Spine
Events are the nervous system of an agentic app. Use them for reactive automation — things that should happen in response to other things.
Trigger Patterns
Trigger
Event
Response
Code pushed to main
github.push
Run CI pipeline
PR opened
github.pull_request
Run review council
Deploy pipeline failed
system.pipeline.failed
Run self-healing workflow
Job failed
system.job.failed
Run diagnostic agent
Org doc created
system.doc.created
Notify subscribers, update indexes
Scheduled maintenance
cron.tick
Run audit, cleanup, reporting
Custom app event
app.*
Application-specific automation
Self-Healing Pattern
Wire system failure events to recovery pipelines:
pipelines:
self-heal:
trigger:
system:
event: job.failed
pipeline: deploy
steps:
- name: diagnose
agent:
prompt: "Diagnose the failed deploy and suggest a fix"
Custom App Events
Emit application-specific events from your services:
eve event emit --type app.invoice.created --source app --payload '{"invoice_id":"inv_123"}'
Wire these to workflows or pipelines in the manifest. Design your app's event vocabulary intentionally — events are the API between your app logic and your agent automation.
Chat and Human-Agent Interface
Gateway Architecture
Eve supports multiple chat providers through a unified gateway:
Production SaaS, when you need to intercept, enrich, or store conversations
If your app needs to add context, filter messages, or maintain its own chat history — proxy through your backend.
Thread Continuity
Chat threads maintain context across messages. Thread keys are scoped to the integration account. Design your chat UX to preserve thread context — agents are dramatically more effective when they can reference conversation history.
Jobs as Coordination Primitive
Parent-Child Orchestration
Jobs are the fundamental unit of agent work. Design complex workflows as job trees:
Parent (orchestrator)
├── Child A (research)
├── Child B (implementation)
└── Child C (testing)
The parent dispatches, waits, resumes, synthesizes. Children execute independently. Use waits_for relations to express dependencies. See eve-orchestration for full patterns.
Structured Context via Attachments
Pass structured data between agents using job attachments, not giant description strings:
# Child stores findings
eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'
# Parent reads on resume
eve job attachment $CHILD_JOB_ID findings.json --out ./child-findings.json
Resource Refs for Document Mounting
Pin specific org document versions as job inputs:
eve job create \
--description "Review the approved plan" \
--resource-refs='[{"uri":"org_docs:/pm/features/FEAT-123.md@v3","label":"Plan","mount_path":"pm/plan.md"}]'
The document is hydrated into the workspace at the mount path. Events track hydration success or failure.
Coordination Threads
When teams dispatch work, a coordination thread (coord:job:{parent_job_id}) links parent and children. Children read .eve/coordination-inbox.md for sibling context. Post updates via eve thread post. The lead agent can eve supervise to monitor the job tree.
Access and Security
Service Accounts
Backend services need non-user tokens for API calls. Use eve auth mint to create scoped tokens:
eve auth mint --email app-bot@example.com --project proj_xxx --role admin
Design each service account with minimal necessary scope.
Access Groups
Segment data-plane access using groups. Groups control who can read/write org docs, org filesystem paths, and database schemas:
Sync with eve access sync --file .eve/access.yaml --org org_xxx.
Agent Permission Policies
Policy
Use Case
default
Interactive agents that need human approval for risky actions
auto_edit
Worker agents that edit code and files autonomously
never
Read-only agents (auditors, reviewers)
yolo
Fully autonomous agents in controlled environments (use carefully)
Policy-as-Code
Declare all access in .eve/access.yaml and sync declaratively. This ensures access is version-controlled, reviewable, and reproducible. See eve-auth-and-secrets for the full v2 policy schema.
The Agentic Checklist
Agent Architecture:
Agents defined in agents.yaml with clear slug, skill, and profile
Teams defined in teams.yaml with appropriate dispatch modes
Gateway policies set intentionally (not everything routable)
Chat routes defined for inbound message handling
Harness Profiles:
Harness profiles defined in manifest (agents reference profiles, not harnesses)
Fallback chains in profiles for resilience
Model choice matches task complexity
Memory:
Storage primitive chosen for each information type (see table above)
Namespace conventions established for org docs
Lifecycle and expiry strategy defined
Agents search before writing (update beats create)
Events:
Trigger patterns wired for key events (push, PR, failures)
Self-healing pipeline exists for deploy and job failures
Custom app events defined for domain-specific automation
Chat:
Gateway provider chosen (Slack, Nostr, WebChat, or multiple)
Chat routing configured (chat.yaml)
Gateway vs backend-proxied decision made
Thread continuity preserved in UX
Coordination:
Complex work decomposed as job trees (parent-child)
Attachments used for structured context passing
Coordination threads used for team communication
Resource refs used for document mounting
Security:
Service accounts created for backend services
Access groups defined for data-plane segmentation
Agent permission policies appropriate to each agent's role
Access policy declared as code (.eve/access.yaml)
The Real Test — Is This App Truly Agent-Native?
Agents can do everything users can (parity)
Adding capability means writing prompts, not code (composability)
Agents coordinate through platform primitives, not custom glue (granularity)
Agents have surprised you with unexpected solutions (emergent capability)
