Agentic App Design on Eve Horizon

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

Load eve-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.

The progression:

1. eve-agent-native-design — Principles (parity, granularity, composability, emergent capability)
2. eve-fullstack-app-design — PaaS foundation (manifest, services, DB, pipelines, deploys)
3. This skill — Agentic layer (agents, teams, memory, events, chat, coordination)

Each layer assumes the previous. Skip none.

Agent Architecture

Defining Agents

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.

version: 1
agents:
  coder:
    slug: coder
    description: "Implements features and fixes bugs"
    skill: eve-orchestration
    harness_profile: primary-coder
    access:
      envs: [staging]
      services: [api, worker]
    policies:
      permission_policy: auto_edit
      git:
        commit: auto
        push: on_success
    gateway:
      policy: routable

Design decisions for each agent:

Decision	Options	Guidance
Slug	Lowercase, alphanumeric + dashes	Org-unique. Used for chat routing: @eve coder fix the login bug
Skill	Any installed skill name	The agent's core competency. One skill per agent.
Harness profile	Named profile from manifest	Decouples agent from specific models. Use profiles, never hardcode harnesses.
Gateway policy	none, discoverable, routable	Default to none. Make routable only for agents that should receive direct chat.
Permission policy	default, auto_edit, never, yolo	Start with auto_edit for worker agents. Use default for agents that need human approval.
Git policies	commit, push	auto commit + on_success push for coding agents. never for read-only agents.

Designing Teams

Teams are defined in teams.yaml. A team groups agents under a lead with a dispatch strategy.

version: 1
teams:
  review-council:
    lead: mission-control
    members: [code-reviewer, security-auditor]
    dispatch:
      mode: council
      merge_strategy: majority
  deploy-ops:
    lead: ops-lead
    members: [deploy-agent, monitor-agent]
    dispatch:
      mode: relay

Choose the right dispatch mode:

Mode	When to Use	How It Works
fanout	Independent parallel work	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.

What Goes Where

Information Type	Storage Primitive	Why
Scratch notes during a job	Workspace files (.eve/)	Ephemeral, dies with the job
Job outputs passed to parent	Job attachments	Survives job completion, addressable by job ID
Rolling conversation context	Threads	Continuity across sessions, summarizable
Curated knowledge	Org Document Store	Versioned, searchable, shared across projects
File trees and assets	Org Filesystem (sync)	Bidirectional sync, local editing
Structured queries	Managed database	SQL, relationships, RLS
Reusable workflows	Skills	Highest-fidelity long-term memory

Namespace Conventions

Organize org docs by agent and purpose:

/agents/{agent-slug}/learnings/      — discoveries and patterns
/agents/{agent-slug}/decisions/      — decision records
/agents/{agent-slug}/runbooks/       — operational procedures
/agents/shared/                      — cross-agent shared knowledge
/projects/{project-slug}/            — project-scoped knowledge

Lifecycle Strategy

Memory without expiry becomes noise. For every storage location, decide:

1. Who writes? Which agents create and update this knowledge.
2. Who reads? Which agents query it and when (job start? on demand?).
3. When does it expire? Tag with creation dates. Build periodic cleanup jobs.
4. 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:

Provider	Transport	Best For
Slack	Webhook	Team collaboration, existing Slack workspaces
Nostr	Subscription	Decentralized, privacy-focused, censorship-resistant
WebChat	WebSocket	Browser-native, embedded in your app

Routing Design

Define routes in chat.yaml to map inbound messages to agents or teams:

version: 1
default_route: route_default
routes:
  - id: deploy-route
    match: "deploy|release|ship"
    target: agent:deploy-agent
  - id: review-route
    match: "review|PR|pull request"
    target: team:review-council
  - id: route_default
    match: ".*"
    target: agent:mission-control

Route targets can be agent:<key>, team:<key>, workflow:<name>, or pipeline:<name>.

Gateway vs Backend-Proxied Chat

Approach	When to Use
Gateway provider (WebSocket to Eve)	Simple chat widgets, admin consoles, no backend needed
Backend-proxied (POST /internal/orgs/:id/chat/route)	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 vi