The agent.json
specification La especificación
agent.json

"voice": {
  "tone": ["clear", "direct", "expert without being distant"],
  "personality": "An engineer who communicates like a teacher",
  "formality": "professional-relaxed",
  "avoid": ["corporate jargon", "techno-optimism clichés"],
  "pronouns": "second-person singular (you)",
  "adaptation_rules": {
    "with_experts": "use technical language freely",
    "with_non_technical": "use analogies, avoid acronyms"
  }
}

"products": [
  {
    "id": "dashboard-basic",
    "name": "Econecta Basic",
    "description": "Real-time energy monitoring for businesses under 50 employees",
    "price_from": 49,
    "currency": "EUR",
    "audience": ["SME", "first-time buyer"],
    "key_benefit": "Visible cost savings in the first month",
    "cta_url": "/start"
  }
]

"intents": [
  {
    "type": "explore",
    "description": "Visitor doesn't know us. Needs to understand what we do and why it matters.",
    "priority_content": ["hero", "key_benefits", "social_proof"]
  },
  {
    "type": "buy",
    "description": "Visitor is ready to purchase or sign up. Reduce friction.",
    "priority_content": ["pricing", "cta", "trust_signals"]
  },
  {
    "type": "support",
    "description": "Existing customer needs help.",
    "priority_content": ["documentation", "contact"]
  }
]

"agent": {
  "enabled": true,
  "version": "1.0",
  "capabilities": [
    "generate_personalised_experience",
    "answer_product_questions",
    "route_to_support"
  ],
  "limitations": [
    "cannot process payments",
    "cannot access account data"
  ],
  "handoff_url": "/contact"
}

"brand": {
  "logo_url": "https://yourdomain.com/logo.svg",
  "logo_dark_url": "https://yourdomain.com/logo-dark.svg",
  "colors": {
    "primary": "#1A6B3C",
    "secondary": "#F0F7F4",
    "accent": "#E8B84B"
  },
  "fonts": {
    "headline": "Syne",
    "body": "EB Garamond"
  }
}

"contact": {
  "email": "hello@yourdomain.com",
  "phone": "+34 900 000 000",
  "address": "Calle Mayor 1, Madrid, Spain",
  "support_url": "/help",
  "social": {
    "linkedin": "https://linkedin.com/company/yourco",
    "twitter": "https://twitter.com/yourco"
  }
}

"styles": {
  "aesthetic": "clean, data-driven, trustworthy",
  "layout_preference": "editorial grid, generous whitespace",
  "imagery_style": "real photography, no stock illustrations",
  "dark_mode": true,
  "animation_level": "subtle"
}

"mission": {
  "statement": "Make energy intelligence accessible to every business, not just enterprises.",
  "problem_solved": "SMEs pay up to 30% more for energy because they lack the data to negotiate and optimise.",
  "impact": "Every customer reduces their carbon footprint as a direct consequence of reducing waste."
}

"goals": {
  "primary": "free trial signup",
  "secondary": ["demo request", "newsletter subscription"],
  "kpis": ["trial_signup_rate", "demo_completion_rate"],
  "avoid": ["high bounce without interaction", "support overload"]
}

"narrative": {
  "origin": "Founded after discovering that a mid-sized factory was paying triple per kWh versus its large competitors — simply because it lacked data.",
  "key_messages": [
    "Energy data should be democratised",
    "The best sustainability is the one you can measure",
    "Small businesses deserve enterprise-grade tools"
  ],
  "approved_metaphors": ["energy as a language", "the meter as a compass"],
  "forbidden_metaphors": ["revolution", "disruptive", "game-changer"]
}

"segments": [
  {
    "id": "ops-manager",
    "description": "Operations or facilities manager. Practical. Responsible for costs. Sceptical of tech that adds complexity.",
    "priority_message": "Save time and money with zero technical overhead.",
    "avoid": ["API references", "technical architecture"]
  },
  {
    "id": "cto",
    "description": "Technical decision-maker. Evaluates integration complexity, data reliability, security.",
    "priority_message": "REST API, GDPR compliant, ISO 27001 certified.",
    "avoid": ["vague claims", "marketing language"]
  }
]

"legal": {
  "jurisdiction": "Spain / EU",
  "certifications": ["GDPR compliant", "ISO 27001"],
  "disclaimers_required": ["energy savings may vary by installation"],
  "prohibited_claims": [
    "guaranteed ROI",
    "government subsidies without verification"
  ],
  "data_processing": "EU servers only. No data sold to third parties."
}

"content_governance": {
  "can_generate": [
    "product descriptions",
    "explainer copy",
    "CTAs",
    "FAQs"
  ],
  "cannot_generate": [
    "pricing without approval",
    "competitor comparisons",
    "testimonials not in source data"
  ],
  "human_review_required": ["legal pages", "press releases"],
  "update_frequency": "monthly"
}