From 644ad94dc9f0532a8b96382e55f162e53c1aef4b Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Tue, 18 Aug 2026 11:56:27 -0700 Subject: [PATCH 1/5] integrate leftover faq content --- packages/core/docs/content/cloneable-saas.mdx | 2 +- packages/core/docs/content/deployment.mdx | 11 +- .../docs/content/environment-variables.mdx | 7 + packages/core/docs/content/faq.mdx | 257 ------------------ packages/core/docs/content/key-concepts.mdx | 2 + .../core/docs/content/locales/ar-SA/faq.mdx | 232 ---------------- .../core/docs/content/locales/de-DE/faq.mdx | 232 ---------------- .../core/docs/content/locales/es-ES/faq.mdx | 232 ---------------- .../core/docs/content/locales/fr-FR/faq.mdx | 232 ---------------- .../core/docs/content/locales/hi-IN/faq.mdx | 230 ---------------- .../core/docs/content/locales/ja-JP/faq.mdx | 232 ---------------- .../core/docs/content/locales/ko-KR/faq.mdx | 230 ---------------- .../core/docs/content/locales/pt-BR/faq.mdx | 232 ---------------- .../core/docs/content/locales/zh-CN/faq.mdx | 230 ---------------- .../core/docs/content/locales/zh-TW/faq.mdx | 230 ---------------- .../docs/content/syncing-template-changes.mdx | 4 +- .../content/writing-agent-instructions.mdx | 8 + .../app/components/docs-slug-redirects.ts | 5 + packages/docs/app/components/docsNavItems.ts | 1 - 19 files changed, 36 insertions(+), 2573 deletions(-) delete mode 100644 packages/core/docs/content/faq.mdx delete mode 100644 packages/core/docs/content/locales/ar-SA/faq.mdx delete mode 100644 packages/core/docs/content/locales/de-DE/faq.mdx delete mode 100644 packages/core/docs/content/locales/es-ES/faq.mdx delete mode 100644 packages/core/docs/content/locales/fr-FR/faq.mdx delete mode 100644 packages/core/docs/content/locales/hi-IN/faq.mdx delete mode 100644 packages/core/docs/content/locales/ja-JP/faq.mdx delete mode 100644 packages/core/docs/content/locales/ko-KR/faq.mdx delete mode 100644 packages/core/docs/content/locales/pt-BR/faq.mdx delete mode 100644 packages/core/docs/content/locales/zh-CN/faq.mdx delete mode 100644 packages/core/docs/content/locales/zh-TW/faq.mdx diff --git a/packages/core/docs/content/cloneable-saas.mdx b/packages/core/docs/content/cloneable-saas.mdx index a97e105dea..08fc2087e5 100644 --- a/packages/core/docs/content/cloneable-saas.mdx +++ b/packages/core/docs/content/cloneable-saas.mdx @@ -214,7 +214,7 @@ Four steps take you from template to deployed app: 1. **Pick an app.** Use the CLI picker, or browse the docs. 2. **Brand it.** Change the name, colors, logo, and copy. Most example apps expose this in a single config file. -3. **Customize it.** Make source changes in your own repository and development workflow. An agent can help when its frame is intentionally granted workspace and write tooling; otherwise the embedded agent operates the resulting app through its actions, data, and configured integrations. +3. **Customize it.** Make source changes in your own repository and development workflow: "add a priority field to forms," "connect to our Salesforce instance," "change the color scheme to match our brand." An agent can help when its frame is intentionally granted workspace and write tooling; otherwise the embedded agent operates the resulting app through its actions, data, and configured integrations. 4. **Ship it.** Run the deploy command. You now have a production app at your own domain. Steps 2–4 typically take a few days. Step 3 has no fixed end point — the app is yours to evolve, while the embedded agent remains available to operate the deployed product and can assist with source changes when code access is explicitly enabled. diff --git a/packages/core/docs/content/deployment.mdx b/packages/core/docs/content/deployment.mdx index d6b22aabaf..f968cfd1f0 100644 --- a/packages/core/docs/content/deployment.mdx +++ b/packages/core/docs/content/deployment.mdx @@ -5,7 +5,16 @@ description: "Deploy agent-native apps to any platform with Nitro presets — No # Deployment -Agent-native apps use [Nitro](https://nitro.build) under the hood, which means you can deploy to any platform with zero config changes — just set a preset. +Agent-native apps use [Nitro](https://nitro.build) under the hood, which means you can deploy to any platform with zero config changes — just set a preset. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS Lambda, Deno Deploy, or your own server — paired with any Drizzle-compatible SQL database (Postgres, SQLite, Turso, D1). Nothing here requires Builder.io or any particular cloud; self-hosting the whole stack is a first-class path, not a workaround. + +## Cost {#cost} + +The framework itself is free — no license fee, and no markup on top of your model provider. In practice you'll see two costs: + +- **AI usage.** You bring your own API key (Anthropic, OpenAI, etc.) and pay the model provider directly. +- **Hosting.** Whatever your host charges. Most templates run fine on free tiers (Netlify, Vercel, Cloudflare) for small workloads. + +If you'd rather not manage either, the hosted version at `agent-native.com` (operated by Builder.io) bundles inference and hosting into a per-seat plan. ## Fast path: self-host a Chat app locally {#self-host-quickstart} diff --git a/packages/core/docs/content/environment-variables.mdx b/packages/core/docs/content/environment-variables.mdx index d7b6d89a8f..e4deecc549 100644 --- a/packages/core/docs/content/environment-variables.mdx +++ b/packages/core/docs/content/environment-variables.mdx @@ -127,6 +127,13 @@ multi-user apps should prefer the scoped credential and connection store. Every provider key below selects its engine on its own: dropping one in is enough, and `AGENT_ENGINE` is only needed to pick between several. +Supported models span Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, +and any provider that speaks the OpenAI API shape via `OPENAI_BASE_URL` — +including OpenAI-compatible gateways like LiteLLM. The model is chosen in +Settings, so switching providers is a configuration change, not a code +rewrite. Claude is the framework's most heavily tested path and the default +recommendation. + | Variable | What it controls | Supported values or format | | ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------- | | `ANTHROPIC_API_KEY` | Claude model fallback for the built-in AI engine. | An Anthropic API key. | diff --git a/packages/core/docs/content/faq.mdx b/packages/core/docs/content/faq.mdx deleted file mode 100644 index a667577f23..0000000000 --- a/packages/core/docs/content/faq.mdx +++ /dev/null @@ -1,257 +0,0 @@ ---- -title: "FAQ" -description: "Common questions about Agent-Native — what it is, who it's for, what you can build, and how it works." ---- - -# FAQ - -Common questions about Agent-Native, organized from "I'm just looking" to "I'm wiring up auth right now." - -## The basics {#general} - -### What is Agent-Native? {#what-is-agent-native} - -Agent-Native is a framework for building apps where the AI agent and the product surface around it are equal partners. The usual path starts with chat, adds typed actions, renders structured results inline, and grows into durable pages around the same SQL state. The invariant is that agents and humans share the same actions, database, and state. See [What is Agent-Native?](/docs/what-is-agent-native) for the full explanation. - -### Who is this for? {#who-is-this-for} - -Agent-Native is for people who want a real app and an AI agent to work from the same data and actions. The common paths are: - -- **Use a hosted app** if you want Mail, Calendar, Forms, Plan, or another finished template with no setup — start at the [template gallery](/templates). -- **Start with Chat** if you want the default from-scratch path: users can talk to the agent immediately, then you extend with actions, native results, and screens — start with [Getting Started](/docs/getting-started) or [Chat](/docs/template-chat). -- **Start automation-first** if you are building scheduled jobs, queues, scripts, integration workers, or external-agent workflows with no browser UI yet — start with [Automation-First Apps](/docs/pure-agent-apps). -- **Start from a template and customize it** if you want your own SaaS product with auth, database, UI, and agent actions already wired — see [Templates](/docs/cloneable-saas). -- **Build from scratch** if you want the framework primitives for a new agent-driven product — start with [Getting Started](/docs/getting-started). -- **Connect another agent or code tool** if you want Claude, ChatGPT, Codex, Cursor, or GitHub Copilot / VS Code to use an Agent-Native app — see [External Agents](/docs/external-agents) and [Skills Guide](/docs/skills-guide). - -### How is this different from adding AI to an existing app? {#how-is-this-different} - -Most apps bolt AI on as an afterthought that can't actually _do_ things in the app. In an Agent-Native app the agent is a first-class citizen that shares the same actions, database, and state as the UI, so it can do anything the buttons can. See [Why build apps this way](/docs/what-is-agent-native#why-build-apps-this-way). - - - -```html -
-
- Bolted-on AI -
Chat sidebar
- -
- separate AI world
can't touch the app -
-
App UI & data
-
- -
- Agent-Native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### Is it open source? {#is-this-open-source} - -Yes. The framework and all templates are open source. You can run everything locally, self-host, or use Builder.io's cloud for managed hosting, collaboration, and team features. - -### How much does it cost? {#how-much} - -The framework itself is free. The two costs you'll see in practice: - -- **AI usage.** You bring your own API key (Anthropic, OpenAI, etc.) and pay the model provider directly. There's no markup from us. -- **Hosting.** Whatever your host charges. Most templates run fine on free tiers (Netlify, Vercel, Cloudflare) for small workloads. - -If you'd rather not manage any of this, the hosted version on `agent-native.com` (operated by Builder.io) bundles inference and hosting into a per-seat plan. - -### Can I host this myself? {#can-i-self-host} - -Yes. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS, Deno Deploy, your own server — and any SQL database (Postgres, SQLite, Turso, D1). The framework is built to be portable. Start with the [local Docker quickstart](/docs/deployment#self-host-quickstart), then use [Deployment](/docs/deployment) for production. - -### What AI models does it support? {#what-models} - -Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, and any provider that speaks the OpenAI API shape. For OpenAI-compatible gateways like LiteLLM, choose OpenAI in Settings and add the gateway URL under Advanced. You configure the model in settings; switching is a config change, not a code rewrite. The framework's heaviest tested path is Claude, so that's the default recommendation. - -### Do I need to know AI/ML? {#do-i-need-to-know-ai} - -No. You don't train models, fine-tune, or deal with embeddings. You build a regular web app — and on the hosted version, you barely build anything at all. The framework handles the agent integration: routing messages, running actions, syncing state. - -### Can I migrate an existing app to Agent-Native? {#can-i-use-existing-code} - -You can, but Agent-Native works best when built from the ground up. The architecture — shared database, polling sync, actions, application state — needs to be integrated throughout. Starting from an app and customizing it is the recommended path. Think of it like the shift from desktop-first to mobile-first: you _can_ retrofit, but building native is better. - -## Templates and what you can build {#templates} - -### What templates are available? {#what-templates-are-available} - -The framework ships with production-ready templates including [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (visual plans and PR recaps), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), and more. Each is a complete app with UI, agent actions, database schema, and AI instructions ready to go. See [Templates](/docs/cloneable-saas) for the full catalog. - -### Can I customize templates? {#can-i-customize-templates} - -That's the whole point. Start from a template and customize it in your own repository and development workflow. "Add a priority field to forms." "Connect to our Salesforce instance." "Change the color scheme to match our brand." An agent can edit the source when its frame is intentionally granted workspace and write tooling; otherwise the embedded agent operates the resulting app through its actions and data surface. - -### Can I build something the templates don't cover? {#build-from-scratch} - -Yes. If you want a basic agentic app, run `npx @agent-native/core@latest create my-chat-app --template chat`; you get durable chat threads, actions, auth, SQL-backed runtime state, native inline result rendering, and room to add your own screens. If you are building a no-browser automation, run `npx @agent-native/core@latest create my-agent --headless`. See [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps), and [Chat](/docs/template-chat). - -### Can I try it without starting from a template? {#try-with-a-skill} - -Yes — install a skill into a coding agent you already use with one command and no scaffold required. See the [Skills Guide](/docs/skills-guide#app-backed-skills) for the walkthrough. - -## Agent capabilities {#agent-capabilities} - -### Does the embedded agent edit the app's source code? {#can-the-agent-modify-code} - -Not by default. The embedded agent normally works through actions, SQL-backed state, and configured integrations. It can edit components, routes, styles, or actions only when its frame is intentionally granted repository workspace and write tooling. Otherwise use your normal development workflow or a separate code-capable development/Builder frame. For runtime customization without source changes, use [Extensions](/docs/extensions). - -### Can users talk to the agent from outside the app? {#external-channels} - -Yes. The same agent runs in your web UI, in Slack, in Telegram, over email, and from other agents (via [A2A](/docs/a2a-protocol)). It's the same agent with the same memory and the same actions, just reached through different channels. See [Messaging the agent](/docs/messaging). - -### Can agents talk to each other? {#can-agents-talk-to-each-other} - -Yes, via the [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Every Agent-Native app automatically gets an A2A endpoint. From the mail app, you can tag the analytics agent to query data. An agent discovers what other agents are available, calls them over the protocol, and shows results in the UI. No configuration needed — the agent card is auto-generated from your template's actions. - -### What can the agent see in the app? {#what-can-the-agent-see} - -The agent always knows what the user is currently viewing. The UI writes navigation state to the database on every route change — which view is open, which item is selected. The agent reads this before taking action. If an email is open, the agent knows which email. If a slide is selected, the agent knows which slide. See [Context Awareness](/docs/context-awareness). - -## Development questions {#development} - -### Which AI coding tools work with Agent-Native? {#which-ai-tools-work} - -Any AI coding tool that reads project instructions. The framework uses AGENTS.md as the universal standard: - -- **Claude Code** — reads CLAUDE.md (symlinked from AGENTS.md by the CLI setup) -- **Cursor** — reads AGENTS.md directly, or `.cursorrules` (Cursor's legacy location) if present in your project -- **Windsurf** — reads AGENTS.md directly, or `.windsurfrules` (Windsurf's legacy location) if present in your project -- **Codex, Gemini, and others** — work via the embedded agent panel -- **Builder.io** — cloud-hosted agent with visual editing and collaboration - -### Can I use my own database? {#can-i-use-my-own-database} - -Yes. Set `DATABASE_URL` and the framework auto-detects it. Supported databases include SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL), and Cloudflare D1. All SQL is dialect-agnostic via Drizzle ORM — the same code works everywhere. - -### Where can I deploy? {#where-can-i-deploy} - -Anywhere. The server runs on Nitro, which compiles to any deployment target: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda, and Bun. You can also use Builder.io's hosting for managed deployments. See the [Deployment guide](/docs/deployment). - -## Architecture {#architecture} - -### Why SSE plus polling instead of WebSockets? {#why-polling-not-websockets} - -SSE gives same-process writes an immediate path to the browser, and a lightweight version-counter poll remains the fallback because it works in every deployment environment — including serverless and edge, where persistent sockets may not be available. See [Key Concepts — Live sync](/docs/key-concepts#polling-sync). - - - -```html -
-
DB write
- -
-
- SSE
/_agent-native/events · instant -
-
- Poll
/_agent-native/poll · universal fallback -
-
- -
Browser refetch
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### Why can't the UI call an LLM directly? {#why-no-inline-llm-calls} - -AI is non-deterministic, so you need conversation flow to give feedback and iterate — not one-shot buttons — and the agent already has your codebase, instructions, skills, and history that an inline call lacks. Routing everything through the agent is also what lets the app be driven from Slack, Telegram, or another agent. See [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge). - -### How do I upgrade an older Agent-Native app? {#upgrade-older-app} - -Run the supported upgrade path from the app or workspace root: - -```bash -npx @agent-native/core@latest upgrade -``` - -That bumps `@agent-native/*` dependencies to `latest`, installs, refreshes -scaffold skills (`skills update scaffold --project`), and runs typecheck when -available. Use `upgrade check` first if you want a doctor-only report of -framework overrides/patches and pending bumps. - -Do **not** fix a broken upgrade with `pnpm.overrides`, `patchedDependencies`, -or edits under `node_modules/@agent-native/*` (especially core/dispatch). If -upgrade or typecheck fails, fix app-level code or ask — then re-run upgrade. - -### Why is this a framework and not a library? {#why-framework-not-library} - -The shared database, live sync, actions system, and application state only work because they're wired together from the ground up — the UI reacts to agent changes instantly, agents communicate, and the agent understands what the user is looking at. A library gives you pieces; this is an architecture. See [Key Concepts](/docs/key-concepts). - -## What's next - -- [**Getting Started**](/docs/getting-started) — build your first action and render it inline in chat -- [**What is Agent-Native?**](/docs/what-is-agent-native) — the full explanation behind the answers above -- [**Templates**](/docs/cloneable-saas) — start from a complete SaaS product instead of starting from scratch -- [**Key Concepts**](/docs/key-concepts) — the architecture: SQL, actions, polling sync, and portability -- [**Deployment**](/docs/deployment) — host on your own domain or any Nitro-compatible provider diff --git a/packages/core/docs/content/key-concepts.mdx b/packages/core/docs/content/key-concepts.mdx index 62a91f6df1..0b36222f71 100644 --- a/packages/core/docs/content/key-concepts.mdx +++ b/packages/core/docs/content/key-concepts.mdx @@ -370,6 +370,8 @@ Every consumer calls the same underlying function, so there is only one implemen When the agent changes data, the UI needs to reflect that without a manual refresh. `useDbSync()` is what makes that automatic. Same-process writes stream over `/_agent-native/events`; `/_agent-native/poll` remains the cross-process and serverless fallback. When the agent writes to the database (application state, settings, or domain data), a version counter increments and the client invalidates the relevant React Query caches. +SSE covers the common case instead of WebSockets because it gives same-process writes an immediate path to the browser with plain HTTP, while the version-counter poll stays as a fallback that works in every deployment environment — including serverless and edge, where persistent sockets may not be available. + ```ts // Client: subscribe to agent/UI data changes once near the app shell import { useDbSync } from "@agent-native/core/client/hooks"; diff --git a/packages/core/docs/content/locales/ar-SA/faq.mdx b/packages/core/docs/content/locales/ar-SA/faq.mdx deleted file mode 100644 index eff06dbe74..0000000000 --- a/packages/core/docs/content/locales/ar-SA/faq.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: "FAQ" -description: "الأسئلة الشائعة حول Agent-Native - ما هو، ومن هو، وما الذي يمكنك إنشاؤه، وكيف يعمل." ---- - -# FAQ - -الأسئلة الشائعة حول الوكيل الأصلي، منظمة من "أنا أبحث فقط" إلى "أقوم بتوصيل المصادقة الآن." - -## الأساسيات {#general} - -### ما هو الوكيل الأصلي؟ {#what-is-agent-native} - -Agent-native هو framework لبناء التطبيقات حيث يكون AI agent وسطح المنتج المحيط به شريكين متساويين. يبدأ المسار المعتاد بالدردشة، ثم يضيف typed actions، ويعرض نتائج منظمة inline، ثم ينمو إلى صفحات دائمة فوق نفس SQL state. الثابت هو أن agents والبشر يتشاركون نفس actions وقاعدة البيانات والحالة. راجع [What Is Agent-Native?](/docs/what-is-agent-native) للحصول على الشرح الكامل. - -### لمن هذا؟ {#who-is-this-for} - -Agent-native مخصص للأشخاص الذين يريدون تطبيقًا حقيقيًا ووكيل AI للعمل من نفس البيانات وactions. المسارات الشائعة هي: - -- **استخدم تطبيقًا مستضافًا** إذا كنت تريد البريد أو التقويم أو النماذج أو الخطة أو أي قالب نهائي آخر بدون إعداد - ابدأ من [template gallery](/templates). -- **ابدأ بالدردشة** إذا كنت تريد المسار الافتراضي من الصفر: يتحدث المستخدمون مع agent فورًا، ثم توسع التطبيق باستخدام actions ونتائج أصلية وشاشات - ابدأ بـ [Getting Started](/docs/getting-started) أو [Chat](/docs/template-chat). -- **ابدأ بـ automation-first** إذا كنت تبني مهام مجدولة أو queues أو scripts أو integration workers أو workflows لوكلاء خارجيين بدون UI في المتصفح بعد - ابدأ بـ [Automation-First Apps](/docs/pure-agent-apps). -- **تفرع القالب وتخصيصه** إذا كنت تريد توصيل منتج SaaS الخاص بك بالمصادقة وقاعدة البيانات وUI والوكيل actions بالفعل - راجع [Templates](/docs/cloneable-saas). -- **الإنشاء من الصفر** إذا كنت تريد أساسيات إطار العمل لمنتج جديد يستند إلى الوكيل - فابدأ بـ [Getting Started](/docs/getting-started). -- **قم بتوصيل وكيل آخر أو أداة تعليمات برمجية أخرى** إذا كنت تريد أن يستخدم Claude أو ChatGPT أو Codex أو Cursor أو GitHub Copilot / VS Code تطبيقًا أصليًا للوكيل - راجع [External Agents](/docs/external-agents) و[Skills Guide](/docs/skills-guide). - -### كيف يختلف هذا عن إضافة الذكاء الاصطناعي إلى تطبيق موجود؟ {#how-is-this-different} - -تعمل معظم التطبيقات على تشغيل الذكاء الاصطناعي كفكرة لاحقة لا يمكنها في الواقع القيام بأشياء في التطبيق. في تطبيق الوكيل الأصلي، يكون الوكيل مواطنًا من الدرجة الأولى يشترك في نفس actions وقاعدة البيانات والحالة مثل UI، لذا يمكنه فعل أي شيء يمكن أن تفعله الأزرار. انظر [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder). - - - -```html -
-
- ذكاء اصطناعي ملحق -
الشريط الجانبي للدردشة
- -
- عالم AI منفصل
لا يمكنه لمس التطبيق -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### هل هو مفتوح المصدر؟ {#is-this-open-source} - -نعم. الإطار وجميع القوالب مفتوحة المصدر. يمكنك تشغيل كل شيء محليًا، أو الاستضافة الذاتية، أو استخدام سحابة Builder.io للاستضافة المُدارة والتعاون وميزات الفريق. - -### كم تبلغ التكلفة؟ {#how-much} - -إطار العمل نفسه مجاني. التكاليف التي ستراها عمليًا: - -- **استخدام الذكاء الاصطناعي.** يمكنك إحضار مفتاح API الخاص بك (Anthropic، OpenAI، وما إلى ذلك) والدفع لموفر النموذج مباشرة. ليس هناك أي ترميز من جانبنا. -- **الاستضافة.** أيًا كان ما يتقاضاه مضيفك. تعمل معظم القوالب بشكل جيد على المستويات المجانية (Netlify وVercel وCloudflare) لأحمال العمل الصغيرة. - -إذا كنت تفضل عدم إدارة أي من هذا، فإن الإصدار المستضاف على `agent-native.com` (الذي يديره Builder.io) يجمع الاستدلال والاستضافة في خطة لكل مقعد. - -### هل يمكنني استضافة هذا بنفسي؟ {#can-i-self-host} - -نعم. اختر أي مضيف يقوم بتشغيل Node - Netlify، وVercel، وCloudflare، وAWS، وDeno Deploy، والخادم الخاص بك - وأي قاعدة بيانات SQL (Postgres، SQLite، Turso، D1). تم تصميم الإطار ليكون محمولاً. ابدأ بـ [دليل Docker المحلي السريع](https://www.agent-native.com/docs/deployment#self-host-quickstart)، ثم استخدم [Deployment](/docs/deployment) للإنتاج. - -### ما هي نماذج الذكاء الاصطناعي التي يدعمها؟ {#what-models} - -Anthropic Claude وOpenAI (عائلة GPT-5) وGoogle Gemini وأي مزود يتحدث شكل OpenAI API (بما في ذلك النماذج المحلية عبر Ollama). يمكنك تكوين النموذج في الإعدادات؛ التبديل هو تغيير في التكوين، وليس إعادة كتابة التعليمات البرمجية. المسار الأكثر اختبارًا لإطار العمل هو Claude، لذا فهذه هي التوصية الافتراضية. - -### هل أحتاج إلى معرفة الذكاء الاصطناعي/تعلم الآلة؟ {#do-i-need-to-know-ai} - -لا. أنت لا تقوم بتدريب النماذج، أو الضبط الدقيق، أو التعامل مع التضمينات. أنت تنشئ تطبيق ويب عاديًا - وفي الإصدار المستضاف، بالكاد تنشئ أي شيء على الإطلاق. يعالج إطار العمل تكامل الوكيل: توجيه الرسائل، تشغيل actions، حالة المزامنة. - -### هل يمكنني ترحيل تطبيق موجود إلى الوكيل الأصلي؟ {#can-i-use-existing-code} - -يمكنك ذلك، ولكن الوكيل الأصلي يعمل بشكل أفضل عند إنشائه من الألف إلى الياء. يجب أن تكون البنية - قاعدة البيانات المشتركة، ومزامنة الاستقصاء، وactions، وحالة التطبيق - متكاملة طوال الوقت. البدء من تطبيق وتخصيصه هو المسار الموصى به. فكر في الأمر مثل التحول من سطح المكتب أولاً إلى الهاتف المحمول أولاً: يمكنك التعديل التحديثي، ولكن إنشاء المحتوى الأصلي هو الأفضل. - -## النماذج وما يمكنك إنشاؤه {#templates} - -### ما هي النماذج المتاحة؟ {#what-templates-are-available} - -يأتي إطار العمل مع قوالب جاهزة للإنتاج بما في ذلك [Chat](/docs/template-chat)، و[Mail](/docs/template-mail)، و[Calendar](/docs/template-calendar)، و[Forms](/docs/template-forms)، و[Plan](/docs/template-plan) (الخطط المرئية وملخصات العلاقات العامة)، و[Analytics](/docs/template-analytics)، و[Dispatch](/docs/template-dispatch)، والمزيد. كل منها عبارة عن تطبيق كامل مع UI والوكيل actions ومخطط قاعدة البيانات وتعليمات الذكاء الاصطناعي الجاهزة للاستخدام. راجع [Templates](/docs/cloneable-saas) للحصول على الكتالوج الكامل. - -### هل يمكنني تخصيص النماذج؟ {#can-i-customize-templates} - -هذا هو بيت القصيد. ابدأ من قالب وخصّصه في مستودعك ومسار التطوير الخاص بك. ويمكن للوكيل المضمّن بعد ذلك تشغيل التطبيق الناتج من خلال actions والبيانات الخاصة به. - -### هل يمكنني إنشاء شيء لا تغطيه النماذج؟ {#build-from-scratch} - -نعم. إذا كنت تريد agentic app أساسيًا، فقم بتشغيل `npx @agent-native/core@latest create my-chat-app --template chat`؛ تحصل على chat threads متينة وactions ومصادقة وحالة وقت تشغيل مدعومة بـ SQL وعرض native inline ومساحة لإضافة شاشاتك الخاصة. إذا كنت تبني automation بلا متصفح، فقم بتشغيل `npx @agent-native/core@latest create my-agent --headless`. راجع [Getting Started](/docs/getting-started)، و[Automation-First Apps](/docs/pure-agent-apps)، و[Chat](/docs/template-chat). - -### هل يمكنني تجربته بدون تفرع القالب؟ {#try-with-a-skill} - -نعم - قم بتثبيت مهارة في وكيل الترميز الذي تستخدمه بالفعل بأمر واحد دون الحاجة إلى أي دعم. راجع [Skills Guide](/docs/skills-guide#app-backed-skills) للاطلاع على الإرشادات التفصيلية. - -## قدرات الوكيل {#agent-capabilities} - -### هل يعدّل الوكيل المضمّن الكود المصدري للتطبيق؟ {#can-the-agent-modify-code} - -ليس افتراضيًا. يمكنه تعديل المصدر فقط عندما يمنحه المضيف عمدًا أدوات كتابة repository/workspace. بخلاف ذلك، يعمل الوكيل المضمّن من خلال actions والحالة المدعومة بـ SQL والتكاملات المكوّنة. استخدم مسار تطوير مستودعك أو إطار تطوير/Builder منفصلًا قادرًا على التعامل مع الكود لتغيير المكونات أو المسارات أو الأنماط أو actions. - -### هل يمكن للمستخدمين التحدث إلى الوكيل من خارج التطبيق؟ {#external-channels} - -نعم. يعمل نفس الوكيل في UI على الويب الخاص بك، وفي Slack، وفي Telegram، عبر البريد الإلكتروني، ومن وكلاء آخرين (عبر [A2A](/docs/a2a-protocol)). إنه نفس الوكيل بنفس الذاكرة ونفس actions، تم الوصول إليه للتو من خلال قنوات مختلفة. انظر [Messaging the agent](/docs/messaging). - -### هل يمكن للوكلاء التحدث مع بعضهم البعض؟ {#can-agents-talk-to-each-other} - -نعم، عبر [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). يحصل كل تطبيق أصلي للوكيل تلقائيًا على نقطة نهاية A2A. من تطبيق البريد، يمكنك وضع علامة على وكيل التحليلات للاستعلام عن البيانات. يكتشف الوكيل ما هو الوكلاء الآخرون المتاحون، ويستدعيهم عبر البروتوكول، ويعرض النتائج في UI. ليست هناك حاجة إلى تكوين — يتم إنشاء بطاقة الوكيل تلقائيًا من actions الخاص بنموذجك. - -### ما الذي يمكن للوكيل رؤيته في التطبيق؟ {#what-can-the-agent-see} - -يعرف الوكيل دائمًا ما يشاهده المستخدم حاليًا. يكتب UI حالة التنقل إلى قاعدة البيانات عند كل تغيير للمسار - أي طريقة عرض مفتوحة، وأي عنصر محدد. يقرأ الوكيل هذا قبل اتخاذ الإجراء. إذا كان البريد الإلكتروني مفتوحًا، فسيعرف الوكيل أي بريد إلكتروني. إذا تم تحديد شريحة، يعرف الوكيل أي شريحة. انظر [Context Awareness](/docs/context-awareness). - -## أسئلة التطوير {#development} - -### ما هي أدوات ترميز الذكاء الاصطناعي التي تعمل مع الوكيل الأصلي؟ {#which-ai-tools-work} - -أي أداة ترميز تعمل بالذكاء الاصطناعي تقرأ تعليمات المشروع. يستخدم إطار العمل AGENTS.md كمعيار عالمي ويقوم تلقائيًا بإنشاء روابط رمزية لأدوات محددة: - -- **رمز Claude** — يقرأ CLAUDE.md (مرتبط بـ AGENTS.md بواسطة إعداد CLI) -- **المؤشر** — يقرأ AGENTS.md مباشرة، أو `.cursorrules` (الموقع القديم للمؤشر) إذا كان موجودًا في مشروعك -- **Windsurf** — يقرأ .windsurfrules (مرتبط بـ AGENTS.md بواسطة إعداد CLI) -- **Codex وGemini وآخرون** — يعملون عبر لوحة الوكلاء المضمنة -- **Builder.io** — وكيل مستضاف على السحابة مع إمكانية التحرير المرئي والتعاون - -### هل يمكنني استخدام قاعدة البيانات الخاصة بي؟ {#can-i-use-my-own-database} - -نعم. قم بتعيين `DATABASE_URL` وسيكتشفه الإطار تلقائيًا. تتضمن قواعد البيانات المدعومة SQLite، وPostgres (Neon، وSupabase، وplain)، وTurso (libSQL)، وCloudflare D1. كل SQL لا تعرف لهجة من خلال Drizzle ORM — نفس الرمز يعمل في كل مكان. - -### أين يمكنني النشر؟ {#where-can-i-deploy} - -في أي مكان. يعمل الخادم على Nitro، والذي يتم تجميعه لأي هدف نشر: Node.js، وCloudflare Workers/Pages، وNetlify، وVercel، وDeno Deploy، وAWS Lambda، وBun. يمكنك أيضًا استخدام استضافة Builder.io لعمليات النشر المُدارة. انظر [Deployment guide](/docs/deployment). - -## الهندسة المعمارية {#architecture} - -### لماذا SSE بالإضافة إلى الاقتراع بدلاً من WebSockets؟ {#why-polling-not-websockets} - -يوفر SSE نفس العملية لكتابة مسار فوري للمتصفح، ويظل استطلاع عداد الإصدار خفيف الوزن هو البديل لأنه يعمل في كل بيئة نشر - بما في ذلك بيئة بدون خادم وبيئة الحافة، حيث قد لا تكون المقابس الدائمة متاحة. انظر [Key Concepts — مزامنة مباشرة](/docs/key-concepts#polling-sync). - - - -```html -
-
كتابة في قاعدة البيانات
- -
-
- SSE
/_agent-native/events · instant -
-
- استقصاء
/_agent-native/poll · universal fallback -
-
- -
إعادة جلب المتصفح
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### لماذا لا يستطيع UI الاتصال بـ LLM مباشرة؟ {#why-no-inline-llm-calls} - -الذكاء الاصطناعي غير حتمي، لذلك تحتاج إلى تدفق المحادثة لتقديم التعليقات والتكرار - وليس أزرار طلقة واحدة - ويمتلك الوكيل بالفعل قاعدة التعليمات البرمجية والتعليمات وskills والسجل الذي تفتقر إليه المكالمة المضمنة. إن توجيه كل شيء عبر الوكيل هو أيضًا ما يتيح تشغيل التطبيق من Slack أو Telegram أو وكيل آخر. انظر [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge). - -### لماذا هذا إطار عمل وليس مكتبة؟ {#why-framework-not-library} - -تعمل قاعدة البيانات المشتركة والمزامنة المباشرة ونظام actions وحالة التطبيق فقط لأنها متصلة معًا من الألف إلى الياء — يتفاعل UI مع تغييرات الوكيل على الفور، ويتواصل الوكلاء، ويفهم الوكيل ما يبحث عنه المستخدم. مكتبة تمنحك قطعًا؛ هذه هي الهندسة المعمارية. انظر [Key Concepts](/docs/key-concepts). diff --git a/packages/core/docs/content/locales/de-DE/faq.mdx b/packages/core/docs/content/locales/de-DE/faq.mdx deleted file mode 100644 index edb8871d6e..0000000000 --- a/packages/core/docs/content/locales/de-DE/faq.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: "FAQ" -description: "Häufige Fragen zu Agent-Native – was es ist, für wen es ist, was Sie erstellen können und wie es funktioniert." ---- - -# FAQ - -Häufig gestellte Fragen zu Agent-Native, sortiert von „Ich suche nur“ bis „Ich verkabele gerade die Authentifizierung.“ - -## Die Grundlagen {#general} - -### Was ist Agent-nativ? {#what-is-agent-native} - -Agent-native ist ein Framework zum Erstellen von Apps, bei dem der KI-Agent und die ihn umgebende Produktoberfläche gleichberechtigte Partner sind. Der übliche Weg beginnt mit Chat, fügt typisierte actions hinzu, rendert strukturierte Ergebnisse inline und wächst zu dauerhaften Seiten auf demselben SQL-Zustand. Die Invariante besteht darin, dass Agenten und Menschen denselben actions, dieselbe Datenbank und denselben Status teilen. Die vollständige Erklärung finden Sie unter [What Is Agent-Native?](/docs/what-is-agent-native). - -### Für wen ist das? {#who-is-this-for} - -Agent-native ist für Leute gedacht, die möchten, dass eine echte App und ein KI-Agent mit denselben Daten und actions arbeiten. Die allgemeinen Pfade sind: - -- **Verwenden Sie eine gehostete App**, wenn Sie E-Mail, Kalender, Formulare, Pläne oder eine andere fertige Vorlage ohne Einrichtung wünschen – beginnen Sie bei [template gallery](/templates). -- **Beginnen Sie mit Chat**, wenn Sie den Standardpfad von Grund auf möchten: Benutzer sprechen sofort mit dem Agenten, und Sie erweitern mit actions, nativen Ergebnissen und Bildschirmen – beginnen Sie mit [Getting Started](/docs/getting-started) oder [Chat](/docs/template-chat). -- **Beginnen Sie automation-first**, wenn Sie geplante Aufgaben, Queues, Skripte, integration workers oder externe Agenten-Workflows ohne Browser-UI bauen – beginnen Sie mit [Automation-First Apps](/docs/pure-agent-apps). -- **Forken und passen Sie eine Vorlage an**, wenn Sie Ihr eigenes SaaS-Produkt mit Authentifizierung, Datenbank, UI und Agentenaktionen bereits verkabelt haben möchten – siehe [Templates](/docs/cloneable-saas). -- **Erstellen Sie von Grund auf**, wenn Sie die Framework-Grundelemente für ein neues agentengesteuertes Produkt benötigen – beginnen Sie mit [Getting Started](/docs/getting-started). -- **Verbinden Sie einen anderen Agenten oder ein anderes Code-Tool**, wenn Sie möchten, dass Claude, ChatGPT, Codex, Cursor oder GitHub Copilot/VS-Code eine agentennative App verwenden – siehe [External Agents](/docs/external-agents) und [Skills Guide](/docs/skills-guide). - -### Wie unterscheidet sich das vom Hinzufügen von KI zu einer vorhandenen App? {#how-is-this-different} - -Bei den meisten Apps wird die KI nachträglich eingebaut, sodass sie in der App eigentlich keine Aufgaben erledigen kann. In einer agentennativen App ist der Agent ein erstklassiger Bürger, der dasselbe actions, dieselbe Datenbank und denselben Status wie UI verwendet, sodass er alles tun kann, was die Schaltflächen können. Siehe [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder). - - - -```html -
-
- nachträglich angebaute KI -
Chat-Seitenleiste
- -
- separate KI-Welt
kann die App nicht steuern -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### Ist es Open Source? {#is-this-open-source} - -Ja. Das Framework und alle Vorlagen sind Open Source. Sie können alles lokal ausführen, selbst hosten oder die Cloud von Builder.io für verwaltetes Hosting, Zusammenarbeit und Teamfunktionen nutzen. - -### Wie viel kostet es? {#how-much} - -Das Framework selbst ist kostenlos. Die beiden Kosten werden Sie in der Praxis sehen: - -- **KI-Nutzung.** Sie bringen Ihren eigenen API-Schlüssel (Anthropic, OpenAI usw.) mit und bezahlen den Modellanbieter direkt. Es gibt keinen Aufschlag von uns. -- **Hosting.** Was auch immer Ihr Host verlangt. Die meisten Vorlagen laufen problemlos auf kostenlosen Stufen (Netlify, Vercel, Cloudflare) für kleine Arbeitslasten. - -Wenn Sie das alles lieber nicht verwalten möchten, bündelt die gehostete Version auf `agent-native.com` (betrieben von Builder.io) Inferenz und Hosting in einem Plan pro Sitzplatz. - -### Kann ich das selbst hosten? {#can-i-self-host} - -Ja. Wählen Sie einen beliebigen Host aus, auf dem Node ausgeführt wird – Netlify, Vercel, Cloudflare, AWS, Deno Deploy, Ihr eigener Server – und eine beliebige SQL-Datenbank (Postgres, SQLite, Turso, D1). Das Framework ist portabel aufgebaut. Beginnen Sie mit dem [lokalen Docker-Schnellstart](https://www.agent-native.com/docs/deployment#self-host-quickstart), und verwenden Sie anschließend [Deployment](/docs/deployment) für die Produktion. - -### Welche KI-Modelle werden unterstützt? {#what-models} - -Anthropic Claude, OpenAI (GPT-5-Familie), Google Gemini und alle Anbieter, die die Form OpenAI API sprechen (einschließlich lokaler Modelle über Ollama). Sie konfigurieren das Modell in den Einstellungen; Beim Umschalten handelt es sich um eine Konfigurationsänderung, nicht um ein Umschreiben des Codes. Der am häufigsten getestete Pfad des Frameworks ist Claude, daher ist dies die Standardempfehlung. - -### Muss ich mich mit KI/ML auskennen? {#do-i-need-to-know-ai} - -Nein. Sie trainieren keine Modelle, nehmen keine Feinabstimmung vor und befassen sich nicht mit Einbettungen. Sie erstellen eine normale Web-App – und in der gehosteten Version erstellen Sie kaum etwas. Das Framework übernimmt die Agentenintegration: Weiterleiten von Nachrichten, Ausführen von actions, Synchronisieren des Status. - -### Kann ich eine vorhandene App auf Agent-nativ migrieren? {#can-i-use-existing-code} - -Das ist möglich, aber Agent-nativ funktioniert am besten, wenn es von Grund auf neu entwickelt wird. Die Architektur – gemeinsam genutzte Datenbank, Polling-Synchronisierung, actions, Anwendungsstatus – muss durchgehend integriert sein. Der empfohlene Weg besteht darin, von einer App auszugehen und diese anzupassen. Stellen Sie sich das wie den Wechsel von Desktop-First zu Mobile-First vor: Sie _können_ nachrüsten, aber nativ zu bauen ist besser. - -## Vorlagen und was Sie erstellen können {#templates} - -### Welche Vorlagen sind verfügbar? {#what-templates-are-available} - -Das Framework wird mit produktionsbereiten Vorlagen geliefert, darunter [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (visuelle Pläne und PR-Zusammenfassungen), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) und mehr. Bei jeder handelt es sich um eine vollständige App mit UI, Agentenaktionen, Datenbankschema und sofort einsatzbereiten KI-Anweisungen. Den vollständigen Katalog finden Sie unter [Templates](/docs/cloneable-saas). - -### Kann ich Vorlagen anpassen? {#can-i-customize-templates} - -Das ist der springende Punkt. Beginnen Sie mit einer Vorlage und passen Sie sie in Ihrem eigenen Repository und Entwicklungsablauf an. Der eingebettete Agent bedient die daraus entstehende App dann über ihre Actions und Daten. - -### Kann ich etwas erstellen, das die Vorlagen nicht abdecken? {#build-from-scratch} - -Ja. Wenn Sie eine einfache agentic app wünschen, führen Sie `npx @agent-native/core@latest create my-chat-app --template chat` aus. Sie erhalten dauerhafte Chat-Threads, actions, Authentifizierung, SQL-gestützten Laufzeitstatus, natives Inline-Rendering und Platz zum Hinzufügen eigener Bildschirme. Wenn Sie eine Automation ohne Browser bauen, führen Sie `npx @agent-native/core@latest create my-agent --headless` aus. Siehe [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps) und [Chat](/docs/template-chat). - -### Kann ich es ausprobieren, ohne eine Vorlage zu forken? {#try-with-a-skill} - -Ja – installieren Sie einen Skill in einem Codierungsagenten, den Sie bereits verwenden, mit einem Befehl und ohne dass ein Gerüst erforderlich ist. Die exemplarische Vorgehensweise finden Sie im [Skills Guide](/docs/skills-guide#app-backed-skills). - -## Agentenfunktionen {#agent-capabilities} - -### Bearbeitet der eingebettete Agent den Quellcode der App? {#can-the-agent-modify-code} - -Nicht standardmäßig. Er kann Quellcode nur bearbeiten, wenn der Host ihm bewusst Repository-/Workspace-Schreibwerkzeuge bereitstellt. Andernfalls arbeitet der eingebettete Agent über actions, SQL-gestützten Zustand und konfigurierte Integrationen. Verwenden Sie zum Ändern von Komponenten, Routen, Stilen oder actions Ihren Repository-Workflow oder einen separaten codefähigen Entwicklungs-/Builder-Frame. - -### Können Benutzer von außerhalb der App mit dem Agenten sprechen? {#external-channels} - -Ja. Derselbe Agent läuft in Ihrem Web UI, in Slack, in Telegram, per E-Mail und von anderen Agenten (über [A2A](/docs/a2a-protocol)). Es handelt sich um denselben Agenten mit demselben Speicher und demselben actions, der nur über verschiedene Kanäle erreicht wird. Siehe [Messaging the agent](/docs/messaging). - -### Können Agenten miteinander reden? {#can-agents-talk-to-each-other} - -Ja, über [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Jede agentennative App erhält automatisch einen A2A-Endpunkt. In der Mail-App können Sie den Analyseagenten markieren, um Daten abzufragen. Ein Agent erkennt, welche anderen Agenten verfügbar sind, ruft sie über das Protokoll auf und zeigt die Ergebnisse im UI an. Keine Konfiguration erforderlich – die Agentenkarte wird automatisch aus actions Ihrer Vorlage generiert. - -### Was kann der Agent in der App sehen? {#what-can-the-agent-see} - -Der Agent weiß immer, was der Benutzer gerade sieht. Der UI schreibt bei jeder Routenänderung den Navigationsstatus in die Datenbank – welche Ansicht geöffnet ist, welches Element ausgewählt ist. Der Agent liest dies, bevor er Maßnahmen ergreift. Wenn eine E-Mail geöffnet ist, weiß der Agent, um welche E-Mail es sich handelt. Wenn eine Folie ausgewählt ist, weiß der Agent, welche Folie. Siehe [Context Awareness](/docs/context-awareness). - -## Entwicklungsfragen {#development} - -### Welche KI-Codierungstools funktionieren mit Agent-Native? {#which-ai-tools-work} - -Jedes KI-Codierungstool, das Projektanweisungen liest. Das Framework verwendet AGENTS.md als universellen Standard und erstellt automatisch Symlinks für bestimmte Tools: - -- **Claude-Code** – liest CLAUDE.md (durch das CLI-Setup mit AGENTS.md verknüpft) -- **Cursor** – liest AGENTS.md direkt oder `.cursorrules` (der alte Speicherort des Cursors), falls in Ihrem Projekt vorhanden -- **Windsurf** – liest .windsurfrules (durch das CLI-Setup mit AGENTS.md verknüpft) -- **Codex, Gemini und andere** – funktionieren über das eingebettete Agent-Panel -- **Builder.io** – Cloud-gehosteter Agent mit visueller Bearbeitung und Zusammenarbeit - -### Kann ich meine eigene Datenbank verwenden? {#can-i-use-my-own-database} - -Ja. Legen Sie `DATABASE_URL` fest und das Framework erkennt es automatisch. Zu den unterstützten Datenbanken gehören SQLite, Postgres (Neon, Supabase, Plain), Turso (libSQL) und Cloudflare D1. Alle SQL sind dialektunabhängig über Drizzle ORM – der gleiche Code funktioniert überall. - -### Wo kann ich bereitstellen? {#where-can-i-deploy} - -Überall. Der Server läuft auf Nitro, das zu jedem Bereitstellungsziel kompiliert wird: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda und Bun. Sie können das Hosting von Builder.io auch für verwaltete Bereitstellungen nutzen. Siehe [Deployment guide](/docs/deployment). - -## Architektur {#architecture} - -### Warum SSE plus Polling statt WebSockets? {#why-polling-not-websockets} - -SSE gibt Schreibvorgängen im selben Prozess einen sofortigen Pfad zum Browser, und eine einfache Abfrage des Versionszählers bleibt der Fallback, da sie in jeder Bereitstellungsumgebung funktioniert – einschließlich serverloser und Edge-Umgebungen, in denen dauerhafte Sockets möglicherweise nicht verfügbar sind. Siehe [Key Concepts — Live-Synchronisierung](/docs/key-concepts#polling-sync). - - - -```html -
-
DB-Schreibvorgang
- -
-
- SSE
/_agent-native/events · instant -
-
- Polling
/_agent-native/poll · universal fallback -
-
- -
Browser lädt neu
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### Warum kann der UI einen LLM nicht direkt aufrufen? {#why-no-inline-llm-calls} - -KI ist nicht deterministisch, daher benötigen Sie einen Konversationsfluss, um Feedback zu geben und zu iterieren – keine One-Shot-Schaltflächen – und der Agent verfügt bereits über Ihre Codebasis, Anweisungen, skills und den Verlauf, der einem Inline-Anruf fehlt. Durch die Weiterleitung aller Daten über den Agenten kann die App auch von Slack, Telegram oder einem anderen Agenten gesteuert werden. Siehe [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge). - -### Warum ist dies ein Framework und keine Bibliothek? {#why-framework-not-library} - -Die gemeinsame Datenbank, die Live-Synchronisierung, das actions-System und der Anwendungsstatus funktionieren nur, weil sie von Grund auf miteinander verbunden sind – der UI reagiert sofort auf Agentenänderungen, Agenten kommunizieren und der Agent versteht, was der Benutzer sieht. Eine Bibliothek gibt Ihnen Stücke; Das ist eine Architektur. Siehe [Key Concepts](/docs/key-concepts). diff --git a/packages/core/docs/content/locales/es-ES/faq.mdx b/packages/core/docs/content/locales/es-ES/faq.mdx deleted file mode 100644 index 99299357e6..0000000000 --- a/packages/core/docs/content/locales/es-ES/faq.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: "FAQ" -description: "Preguntas comunes sobre el agente nativo: qué es, para quién es, qué se puede crear y cómo funciona." ---- - -# FAQ - -Preguntas comunes sobre el agente nativo, organizadas desde "Solo estoy mirando" hasta "Estoy conectando la autenticación ahora mismo". - -## Conceptos básicos {#general} - -### ¿Qué es el agente nativo? {#what-is-agent-native} - -Agent-native es un marco para crear aplicaciones en las que el agente de IA y la superficie del producto que lo rodea son socios iguales. El camino habitual empieza con chat, añade actions tipadas, renderiza resultados estructurados en línea y crece hacia páginas duraderas sobre el mismo estado SQL. La invariante es que los agentes y los humanos comparten el mismo actions, base de datos y estado. Consulte [What Is Agent-Native?](/docs/what-is-agent-native) para obtener la explicación completa. - -### ¿Para quién es esto? {#who-is-this-for} - -El agente nativo es para personas que desean que una aplicación real y un agente de IA trabajen con los mismos datos y actions. Las rutas comunes son: - -- **Utilice una aplicación alojada** si desea Correo, Calendario, Formularios, Plan u otra plantilla terminada sin configuración; comience en [template gallery](/templates). -- **Comience con Chat** si desea el camino predeterminado desde cero: los usuarios hablan con el agent inmediatamente, y usted amplía con actions, resultados nativos y pantallas; comience con [Getting Started](/docs/getting-started) o [Chat](/docs/template-chat). -- **Comience automation-first** si crea tareas programadas, colas, scripts, integration workers o flujos de agents externos sin UI de navegador todavía; comience con [Automation-First Apps](/docs/pure-agent-apps). -- **Bifurque y personalice una plantilla** si desea su propio producto SaaS con autenticación, base de datos, UI y agente actions ya conectados; consulte [Templates](/docs/cloneable-saas). -- **Compile desde cero** si desea las primitivas del marco para un nuevo producto impulsado por agentes, comience con [Getting Started](/docs/getting-started). -- **Conecte otro agente o herramienta de código** si desea que Claude, ChatGPT, Codex, Cursor o GitHub Copilot/VS Code utilice una aplicación nativa del agente; consulte [External Agents](/docs/external-agents) y [Skills Guide](/docs/skills-guide). - -### ¿En qué se diferencia esto de agregar IA a una aplicación existente? {#how-is-this-different} - -La mayoría de las aplicaciones incorporan IA como una ocurrencia tardía que en realidad no puede _hacer_ cosas en la aplicación. En una aplicación nativa del agente, el agente es un ciudadano de primera clase que comparte el mismo actions, la misma base de datos y el mismo estado que el UI, por lo que puede hacer cualquier cosa que los botones puedan hacer. Ver [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder). - - - -```html -
-
- IA añadida por encima -
Barra lateral de chat
- -
- mundo de IA separado
no puede tocar la app -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### ¿Es de código abierto? {#is-this-open-source} - -Sí. El marco y todas las plantillas son de código abierto. Puede ejecutar todo localmente, autohospedarse o utilizar la nube de Builder.io para alojamiento administrado, colaboración y funciones de equipo. - -### ¿Cuánto cuesta? {#how-much} - -El marco en sí es gratuito. Los dos costos que verás en la práctica: - -- **Uso de IA.** Traes tu propia clave API (Anthropic, OpenAI, etc.) y pagas directamente al proveedor del modelo. No hacemos ningún margen de beneficio. -- **Alojamiento.** Lo que sea que cobre tu anfitrión. La mayoría de las plantillas funcionan bien en niveles gratuitos (Netlify, Vercel, Cloudflare) para cargas de trabajo pequeñas. - -Si prefiere no administrar nada de esto, la versión alojada en `agent-native.com` (operada por Builder.io) incluye inferencia y alojamiento en un plan por puesto. - -### ¿Puedo alojar esto yo mismo? {#can-i-self-host} - -Sí. Elija cualquier host que ejecute Node (Netlify, Vercel, Cloudflare, AWS, Deno Deploy, su propio servidor) y cualquier base de datos SQL (Postgres, SQLite, Turso, D1). El marco está diseñado para ser portátil. Empiece con la [guía rápida de Docker local](https://www.agent-native.com/docs/deployment#self-host-quickstart) y use [Deployment](/docs/deployment) para producción. - -### ¿Qué modelos de IA admite? {#what-models} - -Anthropic Claude, OpenAI (familia GPT-5), Google Gemini y cualquier proveedor que hable la forma OpenAI API (incluidos los modelos locales a través de Ollama). Configuras el modelo en la configuración; El cambio es un cambio de configuración, no una reescritura de código. La ruta más probada del marco es Claude, por lo que esa es la recomendación predeterminada. - -### ¿Necesito saber AI/ML? {#do-i-need-to-know-ai} - -No. No se entrenan modelos, no se ajustan ni se ocupan de incrustaciones. Creas una aplicación web normal y, en la versión alojada, apenas creas nada. El marco maneja la integración del agente: enrutamiento de mensajes, ejecución de actions, estado de sincronización. - -### ¿Puedo migrar una aplicación existente a agente nativo? {#can-i-use-existing-code} - -Puedes, pero el agente nativo funciona mejor cuando se construye desde cero. La arquitectura (base de datos compartida, sincronización de sondeos, actions, estado de la aplicación) debe estar integrada en todo momento. Partir de una app y personalizarla es el camino recomendado. Piense en ello como el cambio de una computadora de escritorio primero a una computadora móvil primero: _puede_ modernizarse, pero crear contenido nativo es mejor. - -## Plantillas y lo que puedes crear {#templates} - -### ¿Qué plantillas están disponibles? {#what-templates-are-available} - -El marco se entrega con plantillas listas para producción que incluyen [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (planos visuales y resúmenes de relaciones públicas), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) y más. Cada una es una aplicación completa con UI, agente actions, esquema de base de datos e instrucciones de IA listas para usar. Consulte [Templates](/docs/cloneable-saas) para ver el catálogo completo. - -### ¿Puedo personalizar plantillas? {#can-i-customize-templates} - -Ese es el punto. Empieza con una plantilla y personalízala en tu propio repositorio y flujo de desarrollo. Después, el agente integrado opera la aplicación resultante mediante sus actions y datos. - -### ¿Puedo crear algo que las plantillas no cubran? {#build-from-scratch} - -Sí. Si desea una app agentic básica, ejecute `npx @agent-native/core@latest create my-chat-app --template chat`; obtiene hilos de chat duraderos, actions, autenticación, estado de ejecución respaldado por SQL, renderizado nativo en línea y espacio para agregar sus propias pantallas. Si crea una automatización sin navegador, ejecute `npx @agent-native/core@latest create my-agent --headless`. Consulte [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps) y [Chat](/docs/template-chat). - -### ¿Puedo probarlo sin bifurcar una plantilla? {#try-with-a-skill} - -Sí: instale una habilidad en un agente de codificación que ya usa con un comando y no requiere andamio. Consulte [Skills Guide](/docs/skills-guide#app-backed-skills) para ver el tutorial. - -## Capacidades del agente {#agent-capabilities} - -### ¿Edita el agente integrado el código fuente de la aplicación? {#can-the-agent-modify-code} - -No de forma predeterminada. Solo puede editar el código fuente si el host le concede intencionalmente herramientas de escritura de repository/workspace. De lo contrario, trabaja mediante actions, estado respaldado por SQL e integraciones configuradas. Para cambiar componentes, rutas, estilos o actions, usa el flujo normal de tu repositorio o un frame de desarrollo/Builder con capacidad de código. - -### ¿Pueden los usuarios hablar con el agente desde fuera de la aplicación? {#external-channels} - -Sí. El mismo agente se ejecuta en tu web UI, en Slack, en Telegram, por correo electrónico y desde otros agentes (vía [A2A](/docs/a2a-protocol)). Es el mismo agente con la misma memoria y el mismo actions, solo que se llega a través de diferentes canales. Ver [Messaging the agent](/docs/messaging). - -### ¿Pueden los agentes hablar entre sí? {#can-agents-talk-to-each-other} - -Sí, a través del [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Cada aplicación nativa del agente obtiene automáticamente un punto final A2A. Desde la aplicación de correo, puede etiquetar al agente de análisis para consultar datos. Un agente descubre qué otros agentes están disponibles, los llama a través del protocolo y muestra los resultados en UI. No se necesita configuración: la tarjeta de agente se genera automáticamente a partir del actions de su plantilla. - -### ¿Qué puede ver el agente en la aplicación? {#what-can-the-agent-see} - -El agente siempre sabe lo que el usuario está viendo actualmente. El UI escribe el estado de navegación en la base de datos en cada cambio de ruta: qué vista está abierta, qué elemento está seleccionado. El agente lee esto antes de actuar. Si un correo electrónico está abierto, el agente sabe qué correo electrónico. Si se selecciona una diapositiva, el agente sabe qué diapositiva. Ver [Context Awareness](/docs/context-awareness). - -## Preguntas de desarrollo {#development} - -### ¿Qué herramientas de codificación de IA funcionan con el agente nativo? {#which-ai-tools-work} - -Cualquier herramienta de codificación de IA que lea las instrucciones del proyecto. El marco utiliza AGENTS.md como estándar universal y crea automáticamente enlaces simbólicos para herramientas específicas: - -- **Código Claude**: lee CLAUDE.md (enlazado simbólicamente desde AGENTS.md mediante la configuración de CLI) -- **Cursor**: lee AGENTS.md directamente o `.cursorrules` (ubicación heredada del cursor) si está presente en su proyecto -- **Windsurf**: lee .windsurfrules (enlazado simbólicamente desde AGENTS.md mediante la configuración de CLI) -- **Codex, Gemini y otros**: trabaje a través del panel de agente integrado -- **Builder.io**: agente alojado en la nube con edición visual y colaboración - -### ¿Puedo usar mi propia base de datos? {#can-i-use-my-own-database} - -Sí. Configure `DATABASE_URL` y el marco lo detectará automáticamente. Las bases de datos compatibles incluyen SQLite, Postgres (Neon, Supabase, Plain), Turso (libSQL) y Cloudflare D1. Todo SQL es independiente del dialecto a través de Drizzle ORM: el mismo código funciona en todas partes. - -### ¿Dónde puedo implementar? {#where-can-i-deploy} - -En cualquier lugar. El servidor se ejecuta en Nitro, que se compila en cualquier objetivo de implementación: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda y Bun. También puede utilizar el alojamiento de Builder.io para implementaciones administradas. Ver el [Deployment guide](/docs/deployment). - -## Arquitectura {#architecture} - -### ¿Por qué SSE más encuestas en lugar de WebSocket? {#why-polling-not-websockets} - -SSE proporciona a las escrituras del mismo proceso una ruta inmediata al navegador, y una encuesta ligera de contador de versiones sigue siendo la alternativa porque funciona en todos los entornos de implementación, incluidos los sin servidor y los perimetrales, donde es posible que los sockets persistentes no estén disponibles. Ver [Key Concepts — Sincronización en vivo](/docs/key-concepts#polling-sync). - - - -```html -
-
Escritura en BD
- -
-
- SSE
/_agent-native/events · instant -
-
- Sondeo
/_agent-native/poll · universal fallback -
-
- -
Recarga del navegador
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### ¿Por qué el UI no puede llamar directamente a un LLM? {#why-no-inline-llm-calls} - -La IA no es determinista, por lo que necesita un flujo de conversación para brindar retroalimentación e iteración (no botones de un solo uso) y el agente ya tiene su código base, instrucciones, skills y el historial del que carece una llamada en línea. Dirigir todo a través del agente también es lo que permite que la aplicación se controle desde Slack, Telegram u otro agente. Ver [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge). - -### ¿Por qué es esto un marco y no una biblioteca? {#why-framework-not-library} - -La base de datos compartida, la sincronización en vivo, el sistema actions y el estado de la aplicación solo funcionan porque están conectados desde cero: el UI reacciona instantáneamente a los cambios del agente, los agentes se comunican y el agente comprende lo que el usuario está mirando. Una biblioteca te da piezas; esto es una arquitectura. Ver [Key Concepts](/docs/key-concepts). diff --git a/packages/core/docs/content/locales/fr-FR/faq.mdx b/packages/core/docs/content/locales/fr-FR/faq.mdx deleted file mode 100644 index c5f7d635e1..0000000000 --- a/packages/core/docs/content/locales/fr-FR/faq.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: "FAQ" -description: "Questions courantes sur l'agent natif : de quoi s'agit-il, à qui s'adresse-t-il, ce que vous pouvez créer et comment cela fonctionne." ---- - -# FAQ - -Questions courantes sur les agents natifs, organisées de "Je cherche juste" à "Je suis en train de configurer l'authentification en ce moment." - -## Les bases {#general} - -### Qu'est-ce que l'agent natif ? {#what-is-agent-native} - -Agent-native est un cadre permettant de créer des applications dans lesquelles l'agent IA et le produit qui l'entoure sont des partenaires égaux. Le chemin courant commence par le chat, ajoute des actions typées, rend des résultats structurés en ligne, puis grandit vers des pages durables autour du même état SQL. L'invariant est que les agents et les humains partagent le même actions, la même base de données et le même état. Voir [What Is Agent-Native?](/docs/what-is-agent-native) pour l'explication complète. - -### À qui est-ce destiné ? {#who-is-this-for} - -Agent-native est destiné aux personnes qui souhaitent qu'une véritable application et un agent IA fonctionnent à partir des mêmes données et actions. Les chemins courants sont : - -- **Utilisez une application hébergée** si vous souhaitez recevoir un courrier, un calendrier, des formulaires, un plan ou un autre modèle fini sans configuration – commencez par le [template gallery](/templates). -- **Commencez avec Chat** si vous souhaitez le chemin par défaut depuis zéro : les utilisateurs parlent immédiatement à l'agent, puis vous étendez avec actions, résultats natifs et écrans – commencez par [Getting Started](/docs/getting-started) ou [Chat](/docs/template-chat). -- **Commencez automation-first** si vous créez des tâches planifiées, files, scripts, integration workers ou workflows d'agents externes sans UI navigateur pour le moment — commencez par [Automation-First Apps](/docs/pure-agent-apps). -- ** Créez et personnalisez un modèle ** si vous souhaitez créer votre propre produit SaaS avec authentification, base de données, UI et agent actions déjà câblés – voir [Templates](/docs/cloneable-saas). -- **Construisez à partir de zéro** si vous souhaitez les primitives de structure pour un nouveau produit piloté par agent : commencez par [Getting Started](/docs/getting-started). -- **Connectez un autre agent ou un autre outil de code** si vous souhaitez que Claude, ChatGPT, Codex, Cursor ou GitHub Copilot / VS Code utilisent une application native d'agent – voir [External Agents](/docs/external-agents) et [Skills Guide](/docs/skills-guide). - -### En quoi est-ce différent de l'ajout de l'IA à une application existante ? {#how-is-this-different} - -La plupart des applications intègrent l'IA après coup, ce qui ne permet pas réellement de _faire_ des choses dans l'application. Dans une application native d'agent, l'agent est un citoyen de première classe qui partage le même actions, la même base de données et le même état que le UI, il peut donc faire tout ce que les boutons peuvent faire. Voir [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder). - - - -```html -
-
- IA ajoutée après coup -
Barre latérale de chat
- -
- monde IA séparé
ne peut pas modifier l’app -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### Est-ce open source ? {#is-this-open-source} - -Oui. Le framework et tous les modèles sont open source. Vous pouvez tout exécuter localement, vous auto-héberger ou utiliser le cloud de Builder.io pour l'hébergement géré, la collaboration et les fonctionnalités d'équipe. - -### Combien ça coûte ? {#how-much} - -Le framework lui-même est gratuit. Les deux coûts que vous verrez en pratique : - -- **Utilisation de l'IA.** Vous apportez votre propre clé API (Anthropic, OpenAI, etc.) et payez directement le fournisseur de modèles. Il n'y a aucun balisage de notre part. -- **Hébergement.** Quels que soient les frais facturés par votre hôte. La plupart des modèles fonctionnent correctement sur les niveaux gratuits (Netlify, Vercel, Cloudflare) pour les petites charges de travail. - -Si vous préférez ne rien gérer de tout cela, la version hébergée sur `agent-native.com` (exploitée par Builder.io) regroupe l'inférence et l'hébergement dans un forfait par siège. - -### Puis-je héberger cela moi-même ? {#can-i-self-host} - -Oui. Choisissez n'importe quel hôte qui exécute Node — Netlify, Vercel, Cloudflare, AWS, Deno Deploy, votre propre serveur — et n'importe quelle base de données SQL (Postgres, SQLite, Turso, D1). Le framework est conçu pour être portable. Commencez par le [guide Docker local rapide](https://www.agent-native.com/docs/deployment#self-host-quickstart), puis utilisez [Deployment](/docs/deployment) pour la production. - -### Quels modèles d'IA est-il pris en charge ? {#what-models} - -Anthropic Claude, OpenAI (famille GPT-5), Google Gemini et tout fournisseur parlant la forme OpenAI API (y compris les modèles locaux via Ollama). Vous configurez le modèle dans les paramètres ; la commutation est un changement de configuration, pas une réécriture de code. Le chemin le plus testé du framework est Claude, c'est donc la recommandation par défaut. - -### Dois-je connaître l'IA/ML ? {#do-i-need-to-know-ai} - -Non. Vous ne formez pas de modèles, n'ajustez pas et ne gérez pas les intégrations. Vous créez une application Web standard – et sur la version hébergée, vous ne créez pratiquement rien. Le framework gère l'intégration de l'agent : routage des messages, exécution de actions, état de synchronisation. - -### Puis-je migrer une application existante vers une application native pour agent ? {#can-i-use-existing-code} - -C'est possible, mais l'agent natif fonctionne mieux lorsqu'il est construit à partir de zéro. L'architecture (base de données partagée, synchronisation des interrogations, actions, état de l'application) doit être intégrée partout. Partir d’une app et la personnaliser est le chemin recommandé. Pensez-y comme au passage d'un ordinateur de bureau d'abord à un mobile d'abord : vous _pouvez_ effectuer une mise à niveau, mais construire en natif, c'est mieux. - -## Modèles et ce que vous pouvez créer {#templates} - -### Quels modèles sont disponibles ? {#what-templates-are-available} - -Le framework est livré avec des modèles prêts pour la production, notamment [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (plans visuels et récapitulatifs des relations publiques), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), et bien plus encore. Chacune est une application complète avec UI, l'agent actions, un schéma de base de données et des instructions IA prêtes à l'emploi. Voir [Templates](/docs/cloneable-saas) pour le catalogue complet. - -### Puis-je personnaliser les modèles ? {#can-i-customize-templates} - -C'est là tout l'intérêt. Partez d'un template et personnalisez-le dans votre propre dépôt et votre flux de développement. L'agent intégré exploite ensuite l'application obtenue via ses actions et ses données. - -### Puis-je créer quelque chose que les modèles ne couvrent pas ? {#build-from-scratch} - -Oui. Si vous souhaitez une app agentic de base, exécutez `npx @agent-native/core@latest create my-chat-app --template chat` ; vous bénéficiez de fils de discussion durables, de actions, d'une authentification, d'un état d'exécution soutenu par SQL, d'un rendu natif en ligne et d'un espace pour ajouter vos propres écrans. Si vous créez une automation sans navigateur, exécutez `npx @agent-native/core@latest create my-agent --headless`. Voir [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps) et [Chat](/docs/template-chat). - -### Puis-je l'essayer sans créer de modèle ? {#try-with-a-skill} - -Oui : installez une compétence dans un agent de codage que vous utilisez déjà avec une seule commande et aucun échafaudage requis. Consultez le [Skills Guide](/docs/skills-guide#app-backed-skills) pour la procédure pas à pas. - -## Capacités de l'agent {#agent-capabilities} - -### L'agent intégré modifie-t-il le code source de l'application ? {#can-the-agent-modify-code} - -Pas par défaut. Il ne peut modifier le code source que si l'hôte lui accorde intentionnellement des outils d'écriture repository/workspace. Sinon, il agit via les actions, l'état stocké en SQL et les intégrations configurées. Pour modifier les composants, itinéraires, styles ou actions, utilisez le flux normal de votre dépôt ou un frame de développement/Builder capable de modifier le code. - -### Les utilisateurs peuvent-ils parler à l'agent depuis l'extérieur de l'application ? {#external-channels} - -Oui. Le même agent s'exécute sur votre site Web UI, dans Slack, dans Telegram, par courrier électronique et à partir d'autres agents (via [A2A](/docs/a2a-protocol)). C'est le même agent avec la même mémoire et le même actions, accessible via différents canaux. Voir [Messaging the agent](/docs/messaging). - -### Les agents peuvent-ils communiquer entre eux ? {#can-agents-talk-to-each-other} - -Oui, via le [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Chaque application native d'agent obtient automatiquement un point de terminaison A2A. Depuis l'application de messagerie, vous pouvez marquer l'agent d'analyse pour interroger les données. Un agent découvre quels autres agents sont disponibles, les appelle via le protocole et affiche les résultats dans le UI. Aucune configuration nécessaire : la carte d'agent est générée automatiquement à partir du actions de votre modèle. - -### Que peut voir l'agent dans l'application ? {#what-can-the-agent-see} - -L'agent sait toujours ce que l'utilisateur consulte actuellement. Le UI écrit l'état de navigation dans la base de données à chaque changement d'itinéraire — quelle vue est ouverte, quel élément est sélectionné. L'agent lit ceci avant d'agir. Si un email est ouvert, l'agent sait quel email. Si une diapositive est sélectionnée, l'agent sait quelle diapositive. Voir [Context Awareness](/docs/context-awareness). - -## Questions de développement {#development} - -### Quels outils de codage d'IA fonctionnent avec les agents natifs ? {#which-ai-tools-work} - -Tout outil de codage d'IA qui lit les instructions du projet. Le framework utilise AGENTS.md comme standard universel et crée automatiquement des liens symboliques pour des outils spécifiques : - -- **Code Claude** — lit CLAUDE.md (lié symboliquement à partir de AGENTS.md par la configuration CLI) -- **Curseur** — lit directement AGENTS.md, ou `.cursorrules` (emplacement hérité du curseur) s'il est présent dans votre projet -- **Windsurf** — lit .windsurfrules (lié symboliquement depuis AGENTS.md par la configuration CLI) -- **Codex, Gemini et autres** — travaillez via le panneau d'agent intégré -- **Builder.io** – agent hébergé dans le cloud avec édition visuelle et collaboration - -### Puis-je utiliser ma propre base de données ? {#can-i-use-my-own-database} - -Oui. Définissez `DATABASE_URL` et le framework le détecte automatiquement. Les bases de données prises en charge incluent SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL) et Cloudflare D1. Tous les SQL sont indépendants du dialecte via Drizzle ORM — le même code fonctionne partout. - -### Où puis-je déployer ? {#where-can-i-deploy} - -N'importe où. Le serveur fonctionne sur Nitro, qui se compile sur n'importe quelle cible de déploiement : Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda et Bun. Vous pouvez également utiliser l'hébergement de Builder.io pour les déploiements gérés. Voir le [Deployment guide](/docs/deployment). - -## Architecture {#architecture} - -### Pourquoi SSE plus sondage au lieu de WebSocket ? {#why-polling-not-websockets} - -SSE donne aux écritures du même processus un chemin immédiat vers le navigateur, et un sondage léger du compteur de versions reste la solution de secours car il fonctionne dans tous les environnements de déploiement, y compris sans serveur et en périphérie, où les sockets persistants peuvent ne pas être disponibles. Voir [Key Concepts — Synchronisation en direct](/docs/key-concepts#polling-sync). - - - -```html -
-
Écriture BD
- -
-
- SSE
/_agent-native/events · instant -
-
- Sondage
/_agent-native/poll · universal fallback -
-
- -
Rechargement navigateur
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### Pourquoi le UI ne peut-il pas appeler directement un LLM ? {#why-no-inline-llm-calls} - -L'IA n'est pas déterministe, vous avez donc besoin d'un flux de conversation pour donner des commentaires et itérer (et non de boutons ponctuels) et l'agent dispose déjà de votre base de code, de vos instructions, de skills et de l'historique qui manque à un appel en ligne. Tout acheminer via l'agent permet également à l'application d'être pilotée depuis Slack, Telegram ou un autre agent. Voir [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge). - -### Pourquoi s'agit-il d'un framework et non d'une bibliothèque ? {#why-framework-not-library} - -La base de données partagée, la synchronisation en direct, le système actions et l'état de l'application ne fonctionnent que parce qu'ils sont connectés ensemble depuis le début : le UI réagit instantanément aux changements d'agent, les agents communiquent et l'agent comprend ce que l'utilisateur regarde. Une bibliothèque vous donne des pièces ; c'est une architecture. Voir [Key Concepts](/docs/key-concepts). diff --git a/packages/core/docs/content/locales/hi-IN/faq.mdx b/packages/core/docs/content/locales/hi-IN/faq.mdx deleted file mode 100644 index be7a30a98b..0000000000 --- a/packages/core/docs/content/locales/hi-IN/faq.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: "FAQ" -description: "एजेंट-नेटिव के बारे में सामान्य प्रश्न - यह क्या है, यह किसके लिए है, आप क्या बना सकते हैं और यह कैसे काम करता है।" ---- - -# FAQ - -एजेंट-नेटिव के बारे में सामान्य प्रश्न, "मैं बस देख रहा हूं" से लेकर "मैं अभी प्रमाणीकरण कर रहा हूं" तक व्यवस्थित। - -## बुनियादी बातें {#general} - -### एजेंट-नेटिव क्या है? {#what-is-agent-native} - -Agent-native ऐप्स बनाने के लिए एक framework है जहां AI agent और उसके आसपास की product surface समान भागीदार हैं. सामान्य रास्ता chat से शुरू होता है, typed actions जोड़ता है, structured results inline render करता है, और उसी SQL state के ऊपर durable pages तक बढ़ता है. अपरिवर्तनीय यह है कि agent और मनुष्य समान actions, database और state साझा करते हैं. संपूर्ण स्पष्टीकरण के लिए [What Is Agent-Native?](/docs/what-is-agent-native) देखें। - -### यह किसके लिए है? {#who-is-this-for} - -एजेंट-नेटिव उन लोगों के लिए है जो एक ही डेटा और actions से काम करने के लिए एक वास्तविक ऐप और एक AI एजेंट चाहते हैं। सामान्य पथ हैं: - -- **अगर आप मेल, कैलेंडर, फॉर्म, प्लान या बिना किसी सेटअप वाला कोई अन्य तैयार टेम्पलेट चाहते हैं तो होस्टेड ऐप का उपयोग करें** - [template gallery](/templates) से शुरू करें। -- **Chat से शुरू करें** यदि आप default from-scratch path चाहते हैं: users तुरंत agent से बात करें और आप actions, native results और screens से विस्तार करें - [Getting Started](/docs/getting-started) या [Chat](/docs/template-chat) से शुरू करें। -- **automation-first से शुरू करें** यदि आप scheduled jobs, queues, scripts, integration workers या external agent workflows बना रहे हैं जिन्हें अभी browser UI नहीं चाहिए - [Automation-First Apps](/docs/pure-agent-apps) से शुरू करें। -- \*\*यदि आप अपना स्वयं का SaaS उत्पाद ऑथ, डेटाबेस, UI और एजेंट actions के साथ पहले से ही वायर्ड चाहते हैं, तो टेम्पलेट को फोर्क और कस्टमाइज़ करें - [Templates](/docs/cloneable-saas) देखें। -- **शुरुआत से निर्माण** यदि आप नए एजेंट-संचालित उत्पाद के लिए फ्रेमवर्क प्रिमिटिव चाहते हैं - [Getting Started](/docs/getting-started) से शुरू करें। -- \*\*यदि आप एजेंट-नेटिव ऐप का उपयोग करने के लिए Claude, ChatGPT, Codex, कर्सर, या GitHub कोपायलट / VS कोड चाहते हैं तो किसी अन्य एजेंट या कोड टूल को कनेक्ट करें - [External Agents](/docs/external-agents) और [Skills Guide](/docs/skills-guide) देखें। - -### यह किसी मौजूदा ऐप में AI जोड़ने से किस प्रकार भिन्न है? {#how-is-this-different} - -ज्यादातर ऐप्स एआई को एक विचार के रूप में लागू करते हैं जो वास्तव में ऐप में काम नहीं कर सकता है। एजेंट-नेटिव ऐप में एजेंट एक प्रथम श्रेणी का नागरिक होता है जो actions, डेटाबेस और स्थिति को UI के समान साझा करता है, इसलिए यह बटन द्वारा किया जा सकने वाला कुछ भी कर सकता है। [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder) देखें. - - - -```html -
-
- ऊपर से जोड़ी गई AI -
चैट साइडबार
- -
- अलग AI दुनिया
ऐप को छू नहीं सकता -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### क्या यह खुला स्रोत है? {#is-this-open-source} - -हां. रूपरेखा और सभी टेम्पलेट खुले स्रोत हैं। आप सब कुछ स्थानीय रूप से चला सकते हैं, स्वयं-होस्ट कर सकते हैं, या प्रबंधित होस्टिंग, सहयोग और टीम सुविधाओं के लिए Builder.io के क्लाउड का उपयोग कर सकते हैं। - -### इसकी लागत कितनी है? {#how-much} - -फ्रेमवर्क स्वयं मुफ़्त है। ये दो लागतें आप व्यवहार में देखेंगे: - -- **एआई उपयोग।** आप अपनी खुद की API कुंजी (एंथ्रोपिक, OpenAI, आदि) लाएं और मॉडल प्रदाता को सीधे भुगतान करें। हमारी ओर से कोई मार्कअप नहीं है। -- **होस्टिंग.** आपका होस्ट जो भी शुल्क लेता है। अधिकांश टेम्प्लेट छोटे वर्कलोड के लिए फ्री टियर (नेटलिफाई, वर्सेल, क्लाउडफ्लेयर) पर ठीक चलते हैं। - -यदि आप इनमें से कुछ भी प्रबंधित नहीं करना चाहते हैं, तो `agent-native.com` (Builder.io द्वारा संचालित) पर होस्ट किया गया संस्करण अनुमान और होस्टिंग को प्रति-सीट योजना में बंडल करता है। - -### क्या मैं इसे स्वयं होस्ट कर सकता हूं? {#can-i-self-host} - -हां. कोई भी होस्ट चुनें जो नोड चलाता हो - नेटलिफाई, वर्सेल, क्लाउडफ्लेयर, AWS, डेनो डिप्लॉय, आपका अपना सर्वर - और कोई भी SQL डेटाबेस (Postgres, SQLite, Turso, D1)। ढांचा पोर्टेबल होने के लिए बनाया गया है। पहले [स्थानीय Docker quickstart](https://www.agent-native.com/docs/deployment#self-host-quickstart) से शुरू करें, फिर production के लिए [Deployment](/docs/deployment) देखें. - -### यह किन AI मॉडल का समर्थन करता है? {#what-models} - -एंथ्रोपिक Claude, OpenAI (GPT-5 परिवार), गूगल जेमिनी, और कोई भी प्रदाता जो OpenAI API आकार बोलता है (ओलामा के माध्यम से स्थानीय मॉडल सहित)। आप सेटिंग्स में मॉडल को कॉन्फ़िगर करते हैं; स्विचिंग एक कॉन्फ़िगरेशन परिवर्तन है, कोड पुनर्लेखन नहीं। फ़्रेमवर्क का सबसे भारी परीक्षण पथ Claude है, इसलिए यह डिफ़ॉल्ट अनुशंसा है। - -### क्या मुझे AI/ML जानने की आवश्यकता है? {#do-i-need-to-know-ai} - -नहीं. आप मॉडलों को प्रशिक्षित नहीं करते, फाइन-ट्यून नहीं करते, या एम्बेडिंग से नहीं निपटते। आप एक नियमित वेब ऐप बनाते हैं - और होस्ट किए गए संस्करण पर, आप मुश्किल से कुछ भी बनाते हैं। फ्रेमवर्क एजेंट एकीकरण को संभालता है: संदेशों को रूट करना, actions चलाना, सिंकिंग स्थिति। - -### क्या मैं किसी मौजूदा ऐप को एजेंट-नेटिव में स्थानांतरित कर सकता हूं? {#can-i-use-existing-code} - -आप कर सकते हैं, लेकिन एजेंट-नेटिव सबसे अच्छा तब काम करता है जब उसे ज़मीन से ऊपर बनाया जाता है। आर्किटेक्चर - साझा डेटाबेस, पोलिंग सिंक, actions, एप्लिकेशन स्थिति - को संपूर्ण रूप से एकीकृत करने की आवश्यकता है। एक ऐप से शुरू करना और उसे अनुकूलित करना अनुशंसित पथ है। इसे डेस्कटॉप-फर्स्ट से मोबाइल-फर्स्ट में बदलाव की तरह समझें: आप रेट्रोफिट कर सकते हैं, लेकिन देशी निर्माण करना बेहतर है। - -## टेम्प्लेट और आप क्या बना सकते हैं {#templates} - -### कौन से टेम्पलेट उपलब्ध हैं? {#what-templates-are-available} - -फ्रेमवर्क [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (विजुअल प्लान और पीआर रिकैप्स), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch), और अधिक सहित उत्पादन-तैयार टेम्पलेट्स के साथ आता है। प्रत्येक UI, एजेंट actions, डेटाबेस स्कीमा और AI निर्देशों के साथ एक संपूर्ण ऐप है। संपूर्ण कैटलॉग के लिए [Templates](/docs/cloneable-saas) देखें। - -### क्या मैं टेम्प्लेट कस्टमाइज़ कर सकता हूं? {#can-i-customize-templates} - -यही पूरी बात है। किसी template से शुरू करें और उसे अपने repository और development workflow में customize करें। Embedded agent फिर resulting app को उसके actions और data के माध्यम से चलाता है। - -### क्या मैं कुछ ऐसा बना सकता हूं जो टेम्पलेट्स में शामिल न हो? {#build-from-scratch} - -हां. यदि आप basic agentic app चाहते हैं, तो `npx @agent-native/core@latest create my-chat-app --template chat` चलाएँ; आपको durable chat threads, actions, auth, SQL-backed runtime state, native inline rendering और अपनी screens जोड़ने की जगह मिलती है. यदि आप no-browser automation बना रहे हैं, तो `npx @agent-native/core@latest create my-agent --headless` चलाएं. [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps), और [Chat](/docs/template-chat) देखें। - -### क्या मैं बिना टेम्पलेट फोर्क किए इसे आज़मा सकता हूं? {#try-with-a-skill} - -हाँ - एक कोडिंग एजेंट में एक कौशल स्थापित करें जिसे आप पहले से ही एक कमांड के साथ उपयोग कर रहे हैं और किसी मचान की आवश्यकता नहीं है। वॉकथ्रू के लिए [Skills Guide](/docs/skills-guide#app-backed-skills) देखें। - -## एजेंट क्षमताएं {#agent-capabilities} - -### क्या embedded agent ऐप का source code संपादित करता है? {#can-the-agent-modify-code} - -डिफ़ॉल्ट रूप से नहीं। वह source code केवल तभी संपादित कर सकता है जब host जानबूझकर repository/workspace write tooling दे। अन्यथा embedded agent actions, SQL-backed state और configured integrations के माध्यम से काम करता है। Components, routes, styles या actions बदलने के लिए अपने repository workflow या अलग code-capable development/Builder frame का उपयोग करें। - -### क्या उपयोगकर्ता ऐप के बाहर से एजेंट से बात कर सकते हैं? {#external-channels} - -हां. वही एजेंट आपके वेब UI में, Slack में, टेलीग्राम में, ईमेल पर और अन्य एजेंटों से ([A2A](/docs/a2a-protocol) के माध्यम से) चलता है। यह समान मेमोरी और समान actions वाला एक ही एजेंट है, बस विभिन्न चैनलों के माध्यम से पहुंचा है। [Messaging the agent](/docs/messaging) देखें. - -### क्या एजेंट एक दूसरे से बात कर सकते हैं? {#can-agents-talk-to-each-other} - -हां, [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol) के माध्यम से। प्रत्येक एजेंट-नेटिव ऐप को स्वचालित रूप से एक A2A एंडपॉइंट मिलता है। मेल ऐप से, आप डेटा क्वेरी करने के लिए एनालिटिक्स एजेंट को टैग कर सकते हैं। एक एजेंट पता लगाता है कि अन्य एजेंट क्या उपलब्ध हैं, उन्हें प्रोटोकॉल पर कॉल करता है, और UI में परिणाम दिखाता है। किसी कॉन्फ़िगरेशन की आवश्यकता नहीं है - एजेंट कार्ड आपके टेम्पलेट के actions से स्वतः उत्पन्न होता है। - -### एजेंट ऐप में क्या देख सकता है? {#what-can-the-agent-see} - -एजेंट को हमेशा पता होता है कि उपयोगकर्ता वर्तमान में क्या देख रहा है। UI प्रत्येक मार्ग परिवर्तन पर डेटाबेस में नेविगेशन स्थिति लिखता है - कौन सा दृश्य खुला है, कौन सा आइटम चुना गया है। कार्रवाई करने से पहले एजेंट इसे पढ़ता है। यदि कोई ईमेल खुला है, तो एजेंट को पता होता है कि कौन सा ईमेल खुला है। यदि कोई स्लाइड चुनी जाती है, तो एजेंट को पता होता है कि कौन सी स्लाइड है। [Context Awareness](/docs/context-awareness) देखें. - -## विकास प्रश्न {#development} - -### कौन से AI कोडिंग टूल एजेंट-नेटिव के साथ काम करते हैं? {#which-ai-tools-work} - -कोई भी एआई कोडिंग टूल जो प्रोजेक्ट निर्देश पढ़ता है। फ्रेमवर्क AGENTS.md को सार्वभौमिक मानक के रूप में उपयोग करता है और विशिष्ट उपकरणों के लिए स्वचालित रूप से सिम्लिंक बनाता है: - -- **Claude कोड** - CLAUDE.md पढ़ता है (CLI सेटअप द्वारा AGENTS.md से सिम्लिंक किया गया) -- **कर्सर** - सीधे AGENTS.md पढ़ता है, या यदि आपके प्रोजेक्ट में मौजूद है तो `.cursorrules` (कर्सर का विरासत स्थान) पढ़ता है -- **विंडसर्फ** - पढ़ता है .windsurfrules (CLI सेटअप द्वारा AGENTS.md से सिम्लिंक किया गया) -- **Codex, मिथुन, और अन्य** - एम्बेडेड एजेंट पैनल के माध्यम से काम करें -- **Builder.io** - दृश्य संपादन और सहयोग के साथ क्लाउड-होस्टेड एजेंट - -### क्या मैं अपने स्वयं के डेटाबेस का उपयोग कर सकता हूं? {#can-i-use-my-own-database} - -हां. `DATABASE_URL` सेट करें और फ्रेमवर्क इसे स्वतः पहचान लेता है। समर्थित डेटाबेस में SQLite, Postgres (नियॉन, सुपाबेस, प्लेन), टुर्सो (libSQL), और क्लाउडफ्लेयर D1 शामिल हैं। सभी SQL Drizzle ORM के माध्यम से बोली-अज्ञेयवादी हैं - एक ही कोड हर जगह काम करता है। - -### मैं कहां तैनात कर सकता हूं? {#where-can-i-deploy} - -कहीं भी. सर्वर Nitro पर चलता है, जो किसी भी परिनियोजन लक्ष्य को संकलित करता है: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda, और bun। आप प्रबंधित परिनियोजन के लिए Builder.io की होस्टिंग का भी उपयोग कर सकते हैं। [Deployment guide](/docs/deployment) देखें. - -## वास्तुकला {#architecture} - -### WebSockets के बजाय SSE प्लस पोलिंग क्यों? {#why-polling-not-websockets} - -SSE समान-प्रक्रिया ब्राउज़र के लिए एक तत्काल पथ लिखता है, और एक हल्का संस्करण-काउंटर पोल फ़ॉलबैक रहता है क्योंकि यह हर परिनियोजन वातावरण में काम करता है - सर्वर रहित और किनारे सहित, जहां लगातार सॉकेट उपलब्ध नहीं हो सकते हैं। [Key Concepts — लाइव सिंक](/docs/key-concepts#polling-sync) देखें. - - - -```html -
-
DB लेखन
- -
-
- SSE
/_agent-native/events · instant -
-
- पोल
/_agent-native/poll · universal fallback -
-
- -
ब्राउज़र फिर से fetch करता है
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### UI सीधे LLM को कॉल क्यों नहीं कर सकता? {#why-no-inline-llm-calls} - -एआई गैर-नियतात्मक है, इसलिए आपको फीडबैक देने और पुनरावृत्त करने के लिए वार्तालाप प्रवाह की आवश्यकता है - एक-शॉट बटन की नहीं - और एजेंट के पास पहले से ही आपका कोडबेस, निर्देश, skills और इतिहास है जो इनलाइन कॉल में नहीं है। एजेंट के माध्यम से सब कुछ रूट करने से ऐप को Slack, टेलीग्राम या किसी अन्य एजेंट से संचालित किया जा सकता है। [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge) देखें. - -### यह एक ढांचा क्यों है, लाइब्रेरी क्यों नहीं? {#why-framework-not-library} - -साझा डेटाबेस, लाइव सिंक, actions सिस्टम और एप्लिकेशन स्थिति केवल इसलिए काम करते हैं क्योंकि वे जमीन से एक साथ जुड़े हुए हैं - UI एजेंट परिवर्तनों पर तुरंत प्रतिक्रिया करता है, एजेंट संचार करते हैं, और एजेंट समझता है कि उपयोगकर्ता क्या देख रहा है। एक पुस्तकालय आपको टुकड़े देता है; यह एक वास्तुकला है. [Key Concepts](/docs/key-concepts) देखें. diff --git a/packages/core/docs/content/locales/ja-JP/faq.mdx b/packages/core/docs/content/locales/ja-JP/faq.mdx deleted file mode 100644 index 7e11c232e7..0000000000 --- a/packages/core/docs/content/locales/ja-JP/faq.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: "FAQ" -description: "エージェント ネイティブについてよくある質問 — エージェント ネイティブとは何なのか、誰向けなのか、何を構築できるのか、どのように機能するのかなどです。" ---- - -# FAQ - -エージェント ネイティブに関するよくある質問を、「探しているだけです」から「現在認証を接続しているところです」までまとめました。 - -## 基本 {#general} - -### エージェントネイティブとは何ですか? {#what-is-agent-native} - -エージェントネイティブは、AI エージェントとその周囲の製品表面が対等なパートナーとなるアプリを構築するためのフレームワークです。通常の流れは chat から始まり、typed actions を追加し、構造化結果をインライン表示し、同じ SQL state の上に永続ページを増やします。不変条件は、エージェントと人間が同じ actions、データベース、状態を共有することです。完全な説明については、[What Is Agent-Native?](/docs/what-is-agent-native) を参照してください。 - -### これは誰のためのものですか? {#who-is-this-for} - -エージェント ネイティブは、実際のアプリと AI エージェントが同じデータと actions から動作することを望む人向けです。一般的なパスは次のとおりです。 - -- メール、カレンダー、フォーム、プラン、または設定なしで完成した別のテンプレートが必要な場合は、**ホストされたアプリを使用します**。[template gallery](/templates) から始めてください。 -- ユーザーがすぐに agent と会話でき、actions、ネイティブ結果、画面へ拡張する既定のゼロからの道が必要な場合は、**チャットから始めます**。[Getting Started](/docs/getting-started) または [Chat](/docs/template-chat) から始めます。 -- 予定タスク、queues、scripts、integration workers、またはまだブラウザー UI が不要な外部 agent workflows を作る場合は、**automation-first で開始**します。[Automation-First Apps](/docs/pure-agent-apps) から始めます。 -- 認証、データベース、UI、エージェント actions がすでに接続されている独自の SaaS 製品が必要な場合は、**テンプレートをフォークしてカスタマイズします**。[Templates](/docs/cloneable-saas) を参照してください。 -- **最初から構築** 新しいエージェント駆動製品のフレームワーク プリミティブが必要な場合は、[Getting Started](/docs/getting-started) から始めます。 -- **別のエージェントまたはコード ツールを接続します** Claude、ChatGPT、Codex、カーソル、または GitHub Copilot / VS Code でエージェント ネイティブ アプリを使用する場合は、「[External Agents](/docs/external-agents) および [Skills Guide](/docs/skills-guide)」を参照してください。 - -### これは、既存のアプリに AI を追加することとどう違うのですか? {#how-is-this-different} - -ほとんどのアプリは後付けで AI を追加していますが、実際にアプリ内で何かを行うことはできません。エージェント ネイティブ アプリでは、エージェントは UI と同じ actions、データベース、状態を共有する第一級市民であるため、ボタンで実行できることはすべて実行できます。 [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder) を参照してください。 - - - -```html -
-
- 後付けの AI -
チャットサイドバー
- -
- 分離された AI 世界
アプリを操作できない -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### オープンソースですか? {#is-this-open-source} - -はい。フレームワークとすべてのテンプレートはオープンソースです。すべてをローカルで実行したり、セルフホストしたり、管理されたホスティング、コラボレーション、チーム機能のために Builder.io のクラウドを使用したりできます。 - -### 料金はいくらですか? {#how-much} - -フレームワーク自体は無料です。実際に発生する 2 つのコスト: - -- **AI の使用法。** 独自の API キー (Anthropic、OpenAI など) を持参し、モデル プロバイダーに直接支払います。弊社からの値上げはありません。 -- **ホスティング** ホストの料金に応じて。ほとんどのテンプレートは、小規模なワークロードの無料枠 (Netlify、Vercel、Cloudflare) で問題なく動作します。 - -これらを一切管理したくない場合は、`agent-native.com` のホスト バージョン (Builder.io によって運営) で、推論とホスティングがシートごとのプランにバンドルされています。 - -### これを自分でホストできますか? {#can-i-self-host} - -はい。ノードを実行する任意のホスト (Netlify、Vercel、Cloudflare、AWS、Deno Deploy、独自のサーバー)、および任意の SQL データベース (Postgres、SQLite、Turso、D1) を選択します。フレームワークは移植できるように構築されています。まず [ローカル Docker クイックスタート](https://www.agent-native.com/docs/deployment#self-host-quickstart) を試し、その後、本番環境については [Deployment](/docs/deployment) を参照してください。 - -### どの AI モデルをサポートしていますか? {#what-models} - -Anthropic Claude、OpenAI (GPT-5 ファミリー)、Google Gemini、および OpenAI API シェイプを話すプロバイダー (Ollama 経由のローカル モデルを含む)。モデルは設定で構成します。切り替えは構成の変更であり、コードの書き換えではありません。フレームワークの最も重いテスト済みパスは Claude であるため、これがデフォルトの推奨事項です。 - -### AI/ML について知る必要がありますか? {#do-i-need-to-know-ai} - -いいえ。モデルをトレーニングしたり、微調整したり、埋め込みを処理したりすることはありません。通常の Web アプリを構築しますが、ホストされたバージョンでは、ほとんど何も構築しません。フレームワークは、メッセージのルーティング、actions の実行、状態の同期など、エージェントの統合を処理します。 - -### 既存のアプリをエージェントネイティブに移行できますか? {#can-i-use-existing-code} - -可能ですが、エージェントネイティブは最初から構築した場合に最適に機能します。アーキテクチャ (共有データベース、ポーリング同期、actions、アプリケーションの状態) は、全体にわたって統合される必要があります。アプリから開始してカスタマイズすることをお勧めします。これは、デスクトップ ファーストからモバイル ファーストへの移行のようなものだと考えてください。改造することはできますが、ネイティブに構築する方が優れています。 - -## テンプレートと作成できるもの {#templates} - -### どのようなテンプレートが利用可能ですか? {#what-templates-are-available} - -このフレームワークには、[Chat](/docs/template-chat)、[Mail](/docs/template-mail)、[Calendar](/docs/template-calendar)、[Forms](/docs/template-forms)、[Plan](/docs/template-plan) (ビジュアル プランと PR の要約)、[Analytics](/docs/template-analytics)、[Dispatch](/docs/template-dispatch) などの本番環境に対応したテンプレートが付属しています。それぞれは、UI、エージェント actions、データベース スキーマ、AI 命令を備えた完全なアプリで、すぐに使用できます。完全なカタログについては、[Templates](/docs/cloneable-saas) を参照してください。 - -### テンプレートをカスタマイズできますか? {#can-i-customize-templates} - -それが要点です。テンプレートから始め、独自のリポジトリと開発ワークフローでカスタマイズします。埋め込みエージェントは、完成したアプリを actions とデータを通じて操作します。 - -### テンプレートでカバーされていないものを構築できますか? {#build-from-scratch} - -はい。基本的な agentic app が必要な場合は、`npx @agent-native/core@latest create my-chat-app --template chat` を実行します。耐久性のあるチャット スレッド、actions、認証、SQL に基づくランタイム状態、ネイティブ インライン表示、および独自の画面を追加する余地が得られます。ブラウザーなしの automation を作る場合は、`npx @agent-native/core@latest create my-agent --headless` を実行します。[Getting Started](/docs/getting-started)、[Automation-First Apps](/docs/pure-agent-apps)、および [Chat](/docs/template-chat) を参照してください。 - -### テンプレートをフォークせずに試してみることはできますか? {#try-with-a-skill} - -はい — 1 つのコマンドですでに使用しているコーディング エージェントにスキルをインストールします。スキャフォールドは必要ありません。チュートリアルについては、[Skills Guide](/docs/skills-guide#app-backed-skills) を参照してください。 - -## エージェントの機能 {#agent-capabilities} - -### 埋め込みエージェントはアプリのソースコードを編集しますか? {#can-the-agent-modify-code} - -デフォルトでは編集しません。ホストが repository/workspace の書き込みツールを意図的に付与した場合に限り編集できます。それ以外では、埋め込みエージェントは actions、SQL に保存された状態、設定済みの統合を通じて動作します。コンポーネント、ルート、スタイル、actions を変更する場合は、通常のリポジトリ ワークフローまたはコード対応の開発/Builder フレームを使用してください。 - -### ユーザーはアプリの外部からエージェントと会話できますか? {#external-channels} - -はい。同じエージェントが、Web UI、Slack、Telegram、電子メール、および他のエージェント ([A2A](/docs/a2a-protocol) 経由) で実行されます。それは同じメモリと同じ actions を持つ同じエージェントであり、異なるチャネルを通じて到達しただけです。 [Messaging the agent](/docs/messaging) を参照してください。 - -### エージェント同士は会話できますか? {#can-agents-talk-to-each-other} - -はい、[A2A (Agent-to-Agent) protocol](/docs/a2a-protocol) 経由です。すべてのエージェント ネイティブ アプリは、自動的に A2A エンドポイントを取得します。メール アプリから、分析エージェントにタグを付けてデータをクエリできます。エージェントは、利用可能な他のエージェントを検出し、プロトコル経由でそれらを呼び出し、UI に結果を表示します。設定は必要ありません。エージェント カードはテンプレートの actions から自動生成されます。 - -### エージェントはアプリで何を確認できますか? {#what-can-the-agent-see} - -エージェントは、ユーザーが現在何を表示しているかを常に把握しています。 UI は、ルートが変更されるたびに、どのビューが開いているか、どの項目が選択されているかなど、ナビゲーション状態をデータベースに書き込みます。エージェントはアクションを実行する前にこれを読みます。電子メールが開封されている場合、エージェントはどの電子メールを認識しているかがわかります。スライドが選択されている場合、エージェントはどのスライドであるかを認識します。 [Context Awareness](/docs/context-awareness) を参照してください。 - -## 開発に関する質問 {#development} - -### エージェント ネイティブで動作する AI コーディング ツールはどれですか? {#which-ai-tools-work} - -プロジェクトの指示を読み取る AI コーディング ツール。このフレームワークは、汎用標準として AGENTS.md を使用し、特定のツールのシンボリックリンクを自動作成します。 - -- **Claude コード** — CLAUDE.md を読み取ります (CLI セットアップによって AGENTS.md からシンボリックリンクされます) -- **Cursor** — AGENTS.md を直接読み取るか、プロジェクト内に存在する場合は `.cursorrules` (カーソルの従来の場所) を読み取ります -- **Windsurf** — .windsurfrules を読み取ります (CLI セットアップによって AGENTS.md からシンボリックリンクされます) -- **Codex、Gemini、その他** — 埋め込みエージェント パネルを介して動作します -- **Builder.io** — ビジュアル編集とコラボレーションを備えたクラウドホスト型エージェント - -### 独自のデータベースを使用できますか? {#can-i-use-my-own-database} - -はい。 `DATABASE_URL` を設定すると、フレームワークがそれを自動検出します。サポートされているデータベースには、SQLite、Postgres (Neon、Supabase、plain)、Turso (libSQL)、Cloudflare D1 が含まれます。すべての SQL は、Drizzle ORM を介して方言に依存しません。同じコードがどこでも機能します。 - -### どこに導入できますか? {#where-can-i-deploy} - -どこでも。サーバーは Nitro 上で実行され、任意のデプロイメント ターゲット (Node.js、Cloudflare Workers/Pages、Netlify、Vercel、Deno Deploy、AWS Lambda、および Bun) にコンパイルされます。管理された展開に Builder.io のホスティングを使用することもできます。 [Deployment guide](/docs/deployment) を参照してください。 - -## アーキテクチャ {#architecture} - -### なぜ WebSocket ではなく SSE とポーリングを使用するのですか? {#why-polling-not-websockets} - -SSE は、同一プロセス書き込みでブラウザへの即時パスを提供し、軽量のバージョン カウンター ポーリングはフォールバックのままです。これは、永続的なソケットが利用できない可能性があるサーバーレスやエッジを含むすべてのデプロイメント環境で動作するためです。 [Key Concepts — ライブ同期](/docs/key-concepts#polling-sync) を参照してください。 - - - -```html -
-
DB 書き込み
- -
-
- SSE
/_agent-native/events · instant -
-
- ポーリング
/_agent-native/poll · universal fallback -
-
- -
ブラウザー再取得
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### UI が LLM を直接呼び出せないのはなぜですか? {#why-no-inline-llm-calls} - -AI は非決定的であるため、ワンショット ボタンではなく、フィードバックを提供して反復するための会話フローが必要です。エージェントは、コードベース、指示、skills、インライン コールにはない履歴をすでに持っています。すべてをエージェント経由でルーティングすることで、Slack、Telegram、または別のエージェントからアプリを駆動できるようになります。 [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge) を参照してください。 - -### これがライブラリではなくフレームワークであるのはなぜですか? {#why-framework-not-library} - -共有データベース、ライブ同期、actions システム、およびアプリケーションの状態は、それらが根本から接続されているためにのみ機能します。UI はエージェントの変更に即座に反応し、エージェントは通信し、エージェントはユーザーが見ているものを理解します。図書館はあなたに作品を提供します。これは建築です。 [Key Concepts](/docs/key-concepts) を参照してください。 diff --git a/packages/core/docs/content/locales/ko-KR/faq.mdx b/packages/core/docs/content/locales/ko-KR/faq.mdx deleted file mode 100644 index fc6de131b8..0000000000 --- a/packages/core/docs/content/locales/ko-KR/faq.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: "FAQ" -description: "에이전트 네이티브에 대한 일반적인 질문 - 그것이 무엇인지, 누구를 위한 것인지, 무엇을 빌드할 수 있는지, 어떻게 작동하는지." ---- - -# FAQ - -에이전트 네이티브에 대한 일반적인 질문은 '그냥 보고 있는 중입니다'부터 '지금 인증을 연결 중입니다.'까지 정리되어 있습니다. - -## 기본사항 {#general} - -### 에이전트 네이티브란 무엇인가요? {#what-is-agent-native} - -에이전트 네이티브는 AI 에이전트와 그 주변의 제품 표면이 동등한 파트너인 앱을 구축하기 위한 프레임워크입니다. 일반적인 경로는 chat에서 시작해 typed actions를 추가하고, structured results를 inline으로 렌더링한 뒤, 같은 SQL state 위에 durable pages를 확장하는 것입니다. 변하지 않는 점은 에이전트와 인간이 동일한 actions, 데이터베이스 및 상태를 공유한다는 것입니다. 전체 설명은 [What Is Agent-Native?](/docs/what-is-agent-native)를 참조하세요. - -### 이것은 누구를 위한 것인가요? {#who-is-this-for} - -에이전트 네이티브는 실제 앱과 AI 에이전트가 동일한 데이터와 actions에서 작동하기를 원하는 사람들을 위한 것입니다. 일반적인 경로는 다음과 같습니다: - -- **설정 없이 메일, 캘린더, 양식, 계획 또는 기타 완성된 템플릿을 원하는 경우 호스팅된 앱을 사용하세요** — [template gallery](/templates)에서 시작하세요. -- **채팅으로 시작** 사용자가 즉시 agent와 대화하고 actions, native results, screens로 확장하는 기본 경로를 원한다면 [Getting Started](/docs/getting-started) 또는 [Chat](/docs/template-chat)로 시작하세요. -- **automation-first로 시작** 예약 작업, queues, scripts, integration workers 또는 아직 브라우저 UI가 필요 없는 외부 agent workflows를 만든다면 [Automation-First Apps](/docs/pure-agent-apps)로 시작하세요. -- **인증, 데이터베이스, UI 및 에이전트 actions가 이미 연결되어 있는 자체 SaaS 제품을 원하는 경우 템플릿을 포크하고 사용자 정의**하세요. [Templates](/docs/cloneable-saas)를 참조하세요. -- **처음부터 빌드** 새로운 에이전트 기반 제품을 위한 프레임워크 기본 요소를 원한다면 [Getting Started](/docs/getting-started)로 시작하세요. -- **다른 에이전트 또는 코드 도구 연결** Claude, ChatGPT, Codex, Cursor 또는 GitHub Copilot/VS Code를 사용하여 에이전트 기본 앱을 사용하려면 — [External Agents](/docs/external-agents) 및 [Skills Guide](/docs/skills-guide)를 참조하세요. - -### 기존 앱에 AI를 추가하는 것과 어떻게 다릅니까? {#how-is-this-different} - -대부분의 앱은 앱에서 실제로 _할_ 수 없는 일을 나중에 고려하여 AI를 추가합니다. 에이전트 네이티브 앱에서 에이전트는 동일한 actions, 데이터베이스 및 상태를 UI와 공유하는 일급 시민이므로 버튼으로 할 수 있는 모든 작업을 수행할 수 있습니다. [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder)를 참조하세요. - - - -```html -
-
- 덧붙인 AI -
채팅 사이드바
- -
- 분리된 AI 세계
앱을 다룰 수 없음 -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### 오픈소스인가요? {#is-this-open-source} - -그렇습니다. 프레임워크와 모든 템플릿은 오픈 소스입니다. 모든 것을 로컬에서 실행하거나 자체 호스트하거나 관리형 호스팅, 협업 및 팀 기능을 위해 Builder.io의 클라우드를 사용할 수 있습니다. - -### 비용은 얼마인가요? {#how-much} - -프레임워크 자체는 무료입니다. 실제로 보게 될 두 가지 비용은 다음과 같습니다. - -- **AI 사용.** 자신의 API 키(Anthropic, OpenAI 등)를 가져와 모델 제공자에게 직접 비용을 지불합니다. 우리는 마크업을 하지 않습니다. -- **호스팅.** 호스트가 청구하는 금액은 얼마든지 가능합니다. 대부분의 템플릿은 소규모 워크로드의 경우 무료 계층(Netlify, Vercel, Cloudflare)에서 잘 실행됩니다. - -이 중 어느 것도 관리하고 싶지 않은 경우 `agent-native.com`(Builder.io에서 운영)의 호스팅 버전은 추론과 호스팅을 시트별 계획으로 번들로 제공합니다. - -### 내가 직접 호스팅할 수 있나요? {#can-i-self-host} - -그렇습니다. Node(Netlify, Vercel, Cloudflare, AWS, Deno Deploy, 자체 서버) 및 SQL 데이터베이스(Postgres, SQLite, Turso, D1)를 실행하는 호스트를 선택하세요. 프레임워크는 이식 가능하도록 구축되었습니다. 먼저 [로컬 Docker 빠른 시작](https://www.agent-native.com/docs/deployment#self-host-quickstart)을 사용한 다음 프로덕션에는 [Deployment](/docs/deployment)를 참조하세요. - -### 어떤 AI 모델을 지원하나요? {#what-models} - -Anthropic Claude, OpenAI(GPT-5 제품군), Google Gemini 및 OpenAI API 형태를 사용하는 모든 제공업체(Ollama를 통한 현지 모델 포함). 설정에서 모델을 구성합니다. 전환은 코드 재작성이 아닌 구성 변경입니다. 프레임워크의 가장 무거운 테스트 경로는 Claude이므로 이것이 기본 권장 사항입니다. - -### AI/ML을 알아야 하나요? {#do-i-need-to-know-ai} - -아닙니다. 모델을 훈련하거나, 미세 조정하거나, 임베딩을 처리하지 않습니다. 일반 웹 앱을 빌드하고 호스팅 버전에서는 거의 아무것도 빌드하지 않습니다. 프레임워크는 메시지 라우팅, actions 실행, 상태 동기화 등 에이전트 통합을 처리합니다. - -### 기존 앱을 에이전트 기반 앱으로 마이그레이션할 수 있나요? {#can-i-use-existing-code} - -가능하지만 에이전트 네이티브는 처음부터 새로 구축했을 때 가장 잘 작동합니다. 공유 데이터베이스, 폴링 동기화, actions, 애플리케이션 상태 등 아키텍처가 전체적으로 통합되어야 합니다. 앱에서 시작하여 사용자 정의하는 것이 권장되는 경로입니다. 데스크톱 우선에서 모바일 우선으로 전환하는 것과 같다고 생각하세요. 개조할 수는 있지만 기본으로 구축하는 것이 더 좋습니다. - -## 템플릿 및 구축 가능한 항목 {#templates} - -### 어떤 템플릿을 사용할 수 있나요? {#what-templates-are-available} - -프레임워크에는 [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan)(시각적 계획 및 PR 요약), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) 등을 포함한 프로덕션 준비 템플릿이 함께 제공됩니다. 각각은 UI, 에이전트 actions, 데이터베이스 스키마 및 AI 지침을 갖춘 완전한 앱입니다. 전체 카탈로그는 [Templates](/docs/cloneable-saas)를 참조하세요. - -### 템플릿을 맞춤설정할 수 있나요? {#can-i-customize-templates} - -그게 요점입니다. 템플릿에서 시작해 자체 저장소와 개발 워크플로에서 사용자 지정하세요. 임베디드 에이전트는 완성된 앱을 actions와 데이터를 통해 운영합니다. - -### 템플릿에서 다루지 않는 것을 만들 수 있나요? {#build-from-scratch} - -그렇습니다. 기본 agentic app을 원한다면 `npx @agent-native/core@latest create my-chat-app --template chat`를 실행하세요. 내구성 있는 채팅 스레드, actions, 인증, SQL 지원 런타임 상태, native inline rendering 및 자신만의 화면을 추가할 수 있는 공간이 제공됩니다. 브라우저 없는 automation을 만든다면 `npx @agent-native/core@latest create my-agent --headless`를 실행하세요. [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps) 및 [Chat](/docs/template-chat)를 참조하세요. - -### 템플릿을 포크하지 않고 시도해 볼 수 있나요? {#try-with-a-skill} - -예 — 하나의 명령으로 이미 사용하고 있는 코딩 에이전트에 기술을 설치하면 스캐폴드가 필요하지 않습니다. 연습은 [Skills Guide](/docs/skills-guide#app-backed-skills)를 참조하세요. - -## 에이전트 기능 {#agent-capabilities} - -### 임베디드 에이전트가 앱의 소스 코드를 편집하나요? {#can-the-agent-modify-code} - -기본적으로는 편집하지 않습니다. 호스트가 repository/workspace 쓰기 도구를 의도적으로 부여한 경우에만 편집할 수 있습니다. 그 외에는 actions, SQL 기반 상태 및 구성된 통합을 통해 작업합니다. 구성 요소, 경로, 스타일 또는 actions를 변경하려면 일반 저장소 워크플로 또는 별도의 코드 지원 개발/Builder 프레임을 사용하세요. - -### 사용자가 앱 외부에서 상담원과 대화할 수 있나요? {#external-channels} - -그렇습니다. 동일한 에이전트가 웹 UI, Slack, Telegram, 이메일 및 기타 에이전트([A2A](/docs/a2a-protocol)를 통해)에서 실행됩니다. 동일한 메모리와 동일한 actions를 가진 동일한 에이전트이며 방금 다른 채널을 통해 도달했습니다. [Messaging the agent](/docs/messaging)를 참조하세요. - -### 상담원이 서로 대화할 수 있나요? {#can-agents-talk-to-each-other} - -예, [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol)를 통해 가능합니다. 모든 에이전트 기반 앱은 자동으로 A2A 엔드포인트를 얻습니다. 메일 앱에서 분석 에이전트에 태그를 지정하여 데이터를 쿼리할 수 있습니다. 에이전트는 사용 가능한 다른 에이전트를 찾아 프로토콜을 통해 호출하고 UI에 결과를 표시합니다. 구성이 필요하지 않습니다. 에이전트 카드는 템플릿의 actions에서 자동 생성됩니다. - -### 상담원은 앱에서 무엇을 볼 수 있나요? {#what-can-the-agent-see} - -에이전트는 사용자가 현재 무엇을 보고 있는지 항상 알고 있습니다. UI는 경로가 변경될 때마다 탐색 상태(어떤 보기가 열려 있는지, 어떤 항목이 선택되는지)를 데이터베이스에 기록합니다. 상담원은 조치를 취하기 전에 이 내용을 읽습니다. 이메일이 열려 있으면 상담원은 어떤 이메일인지 알 수 있습니다. 슬라이드가 선택되면 상담원은 어떤 슬라이드인지 알 수 있습니다. [Context Awareness](/docs/context-awareness)를 참조하세요. - -## 개발 질문 {#development} - -### 에이전트 네이티브에서는 어떤 AI 코딩 도구가 작동하나요? {#which-ai-tools-work} - -프로젝트 지침을 읽는 AI 코딩 도구입니다. 프레임워크는 AGENTS.md를 범용 표준으로 사용하고 특정 도구에 대한 심볼릭 링크를 자동 생성합니다. - -- **Claude 코드** — CLAUDE.md를 읽습니다(CLI 설정에 의해 AGENTS.md에서 심볼릭 링크됨) -- **커서** — AGENTS.md를 직접 읽거나 프로젝트에 있는 경우 `.cursorrules`(커서의 기존 위치)를 읽습니다. -- **Windsurf** — .windsurfrules를 읽습니다(CLI 설정에 의해 AGENTS.md에서 심볼릭 링크됨) -- **Codex, Gemini 및 기타** — 내장된 에이전트 패널을 통해 작업 -- **Builder.io** — 시각적 편집 및 협업 기능을 갖춘 클라우드 호스팅 에이전트 - -### 내 데이터베이스를 사용할 수 있나요? {#can-i-use-my-own-database} - -그렇습니다. `DATABASE_URL`를 설정하면 프레임워크가 이를 자동 감지합니다. 지원되는 데이터베이스에는 SQLite, Postgres(Neon, Supabase, plain), Turso(libSQL) 및 Cloudflare D1이 포함됩니다. 모든 SQL는 Drizzle ORM를 통해 방언에 구애받지 않습니다. 동일한 코드가 어디에서나 작동합니다. - -### 어디에 배포할 수 있나요? {#where-can-i-deploy} - -어디서나. 서버는 Nitro에서 실행되며 Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda 및 Bun과 같은 배포 대상으로 컴파일됩니다. 관리형 배포를 위해 Builder.io의 호스팅을 사용할 수도 있습니다. [Deployment guide](/docs/deployment)를 참조하세요. - -## 건축 {#architecture} - -### WebSocket 대신 SSE에 폴링을 더한 이유는 무엇입니까? {#why-polling-not-websockets} - -SSE는 동일 프로세스 쓰기에 브라우저에 대한 즉각적인 경로를 제공하고, 경량 버전 카운터 폴링은 영구 소켓을 사용할 수 없는 서버리스 및 에지를 포함한 모든 배포 환경에서 작동하기 때문에 대체 수단으로 남아 있습니다. [Key Concepts — 실시간 동기화](/docs/key-concepts#polling-sync)를 참조하세요. - - - -```html -
-
DB 쓰기
- -
-
- SSE
/_agent-native/events · instant -
-
- 폴링
/_agent-native/poll · universal fallback -
-
- -
브라우저 다시 가져오기
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### UI가 LLM를 직접 호출할 수 없는 이유는 무엇입니까? {#why-no-inline-llm-calls} - -AI는 비결정적이므로 피드백을 제공하고 일회성 버튼이 아닌 반복을 위한 대화 흐름이 필요하며 에이전트에는 인라인 호출에 부족한 코드베이스, 지침, skills 및 기록이 이미 있습니다. 에이전트를 통해 모든 것을 라우팅하면 Slack, Telegram 또는 다른 에이전트에서 앱을 구동할 수도 있습니다. [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge)를 참조하세요. - -### 이것이 라이브러리가 아닌 프레임워크인 이유는 무엇입니까? {#why-framework-not-library} - -공유 데이터베이스, 라이브 동기화, actions 시스템 및 애플리케이션 상태는 처음부터 함께 연결되어 있기 때문에 작동합니다. UI는 에이전트 변경 사항에 즉시 반응하고 에이전트와 통신하며 에이전트는 사용자가 보고 있는 내용을 이해합니다. 도서관은 당신에게 작품을 제공합니다. 이것은 아키텍처입니다. [Key Concepts](/docs/key-concepts)를 참조하세요. diff --git a/packages/core/docs/content/locales/pt-BR/faq.mdx b/packages/core/docs/content/locales/pt-BR/faq.mdx deleted file mode 100644 index 1eb3301889..0000000000 --- a/packages/core/docs/content/locales/pt-BR/faq.mdx +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: "FAQ" -description: "Perguntas comuns sobre agente nativo: o que é, para quem se destina, o que você pode criar e como funciona." ---- - -# FAQ - -Perguntas comuns sobre agente nativo, organizadas de "Estou apenas olhando" até "Estou conectando a autenticação agora". - -## O básico {#general} - -### O que é agente nativo? {#what-is-agent-native} - -Agent-native é uma estrutura para criar aplicativos onde o agente de IA e a superfície do produto ao seu redor são parceiros iguais. O caminho comum começa com chat, adiciona actions tipadas, renderiza resultados estruturados inline e cresce para páginas duráveis sobre o mesmo estado SQL. A invariante é que agentes e humanos compartilham o mesmo actions, banco de dados e estado. Consulte [What Is Agent-Native?](/docs/what-is-agent-native) para obter a explicação completa. - -### Para quem é isso? {#who-is-this-for} - -Agente nativo é para pessoas que desejam que um aplicativo real e um agente de IA trabalhem a partir dos mesmos dados e actions. Os caminhos comuns são: - -- **Use um aplicativo hospedado** se quiser Mail, Calendário, Formulários, Plano ou outro modelo finalizado sem configuração. Comece no [template gallery](/templates). -- **Comece com bate-papo** se quiser o caminho padrão do zero: usuários falam com o agent imediatamente, e você estende com actions, resultados nativos e telas — comece com [Getting Started](/docs/getting-started) ou [Chat](/docs/template-chat). -- **Comece automation-first** se estiver criando tarefas agendadas, filas, scripts, integration workers ou fluxos de agents externos sem UI de navegador ainda — comece com [Automation-First Apps](/docs/pure-agent-apps). -- **Bifurque e personalize um modelo** se desejar seu próprio produto SaaS com autenticação, banco de dados, UI e agente actions já conectados — consulte [Templates](/docs/cloneable-saas). -- **Compile do zero** se quiser as primitivas da estrutura para um novo produto orientado por agente — comece com [Getting Started](/docs/getting-started). -- **Conecte outro agente ou ferramenta de código** se desejar que Claude, ChatGPT, Codex, Cursor ou GitHub Copilot / VS Code usem um aplicativo nativo do agente — consulte [External Agents](/docs/external-agents) e [Skills Guide](/docs/skills-guide). - -### Qual a diferença entre isso e adicionar IA a um aplicativo existente? {#how-is-this-different} - -A maioria dos aplicativos utiliza a IA como uma reflexão tardia que não pode realmente _fazer_ coisas no aplicativo. Em um aplicativo nativo do agente, o agente é um cidadão de primeira classe que compartilha o mesmo actions, banco de dados e estado que o UI, portanto, pode fazer qualquer coisa que os botões puderem. Consulte [What Is Agent-Native?](/docs/what-is-agent-native#the-ladder). - - - -```html -
-
- IA acoplada depois -
Barra lateral de chat
- -
- mundo de IA separado
não consegue mexer no app -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### É código aberto? {#is-this-open-source} - -Sim. A estrutura e todos os modelos são de código aberto. Você pode executar tudo localmente, hospedar-se sozinho ou usar a nuvem do Builder.io para hospedagem gerenciada, colaboração e recursos de equipe. - -### Quanto custa? {#how-much} - -A estrutura em si é gratuita. Os dois custos que você verá na prática: - -- **Uso de IA.** Você traz sua própria chave API (Anthropic, OpenAI, etc.) e paga diretamente ao fornecedor do modelo. Não há nenhuma marcação nossa. -- **Hospedagem.** Quaisquer que sejam as tarifas do seu anfitrião. A maioria dos modelos funciona bem em níveis gratuitos (Netlify, Vercel, Cloudflare) para pequenas cargas de trabalho. - -Se você preferir não gerenciar nada disso, a versão hospedada no `agent-native.com` (operada pela Builder.io) agrupa inferência e hospedagem em um plano por usuário. - -### Posso hospedar isso sozinho? {#can-i-self-host} - -Sim. Escolha qualquer host que execute Node – Netlify, Vercel, Cloudflare, AWS, Deno Deploy, seu próprio servidor – e qualquer banco de dados SQL (Postgres, SQLite, Turso, D1). A estrutura foi construída para ser portátil. Comece pelo [guia rápido do Docker local](https://www.agent-native.com/docs/deployment#self-host-quickstart) e depois use [Deployment](/docs/deployment) para produção. - -### Quais modelos de IA são compatíveis? {#what-models} - -Anthropic Claude, OpenAI (família GPT-5), Google Gemini e qualquer fornecedor que fale o formato OpenAI API (incluindo modelos locais via Ollama). Você configura o modelo nas configurações; a troca é uma mudança de configuração, não uma reescrita de código. O caminho testado mais pesado da estrutura é Claude, então essa é a recomendação padrão. - -### Preciso conhecer IA/ML? {#do-i-need-to-know-ai} - -Não. Você não treina modelos, não ajusta ou lida com incorporações. Você cria um aplicativo da web normal – e na versão hospedada, você quase não constrói nada. A estrutura lida com a integração do agente: roteamento de mensagens, execução de actions, sincronização de estado. - -### Posso migrar um aplicativo existente para agente nativo? {#can-i-use-existing-code} - -Você pode, mas o agente nativo funciona melhor quando construído do zero. A arquitetura – banco de dados compartilhado, sincronização de polling, actions, estado do aplicativo – precisa ser totalmente integrada. Começar a partir de um app e personalizá-lo é o caminho recomendado. Pense nisso como a mudança do desktop para o mobile: você _pode_ fazer o retrofit, mas construir nativo é melhor. - -## Modelos e o que você pode construir {#templates} - -### Quais modelos estão disponíveis? {#what-templates-are-available} - -A estrutura vem com modelos prontos para produção, incluindo [Chat](/docs/template-chat), [Mail](/docs/template-mail), [Calendar](/docs/template-calendar), [Forms](/docs/template-forms), [Plan](/docs/template-plan) (planos visuais e recapitulações de relações públicas), [Analytics](/docs/template-analytics), [Dispatch](/docs/template-dispatch) e muito mais. Cada um é um aplicativo completo com UI, agente actions, esquema de banco de dados e instruções de IA prontas para uso. Consulte [Templates](/docs/cloneable-saas) para o catálogo completo. - -### Posso personalizar modelos? {#can-i-customize-templates} - -Esse é o ponto principal. Comece com um template e personalize-o no seu próprio repositório e fluxo de desenvolvimento. O agente incorporado então opera o aplicativo resultante por meio de suas actions e dados. - -### Posso criar algo que os modelos não cobrem? {#build-from-scratch} - -Sim. Se você deseja uma app agentic básica, execute `npx @agent-native/core@latest create my-chat-app --template chat`; você obtém threads de bate-papo duráveis, actions, autenticação, estado de tempo de execução apoiado por SQL, renderização nativa inline e espaço para adicionar suas próprias telas. Se estiver criando uma automation sem navegador, execute `npx @agent-native/core@latest create my-agent --headless`. Consulte [Getting Started](/docs/getting-started), [Automation-First Apps](/docs/pure-agent-apps) e [Chat](/docs/template-chat). - -### Posso experimentar sem bifurcar um modelo? {#try-with-a-skill} - -Sim — instale uma habilidade em um agente de codificação que você já usa com um comando e sem necessidade de scaffold. Consulte o [Skills Guide](/docs/skills-guide#app-backed-skills) para ver o passo a passo. - -## Recursos do agente {#agent-capabilities} - -### O agente incorporado edita o código-fonte do aplicativo? {#can-the-agent-modify-code} - -Não por padrão. Ele só pode editar o código-fonte quando o host concede intencionalmente ferramentas de escrita de repository/workspace. Caso contrário, trabalha por meio de actions, estado respaldado por SQL e integrações configuradas. Para alterar componentes, rotas, estilos ou actions, use o fluxo normal do seu repositório ou um frame de desenvolvimento/Builder separado com capacidade de código. - -### Os usuários podem falar com o agente de fora do aplicativo? {#external-channels} - -Sim. O mesmo agente é executado em seu web UI, em Slack, em Telegram, por e-mail e de outros agentes (via [A2A](/docs/a2a-protocol)). É o mesmo agente com a mesma memória e o mesmo actions, apenas alcançado através de canais diferentes. Consulte [Messaging the agent](/docs/messaging). - -### Os agentes podem conversar entre si? {#can-agents-talk-to-each-other} - -Sim, através do [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol). Cada aplicativo nativo do agente obtém automaticamente um endpoint A2A. No aplicativo de e-mail, você pode marcar o agente de análise para consultar dados. Um agente descobre quais outros agentes estão disponíveis, chama-os pelo protocolo e mostra os resultados no UI. Não é necessária configuração: o cartão do agente é gerado automaticamente a partir do actions do seu modelo. - -### O que o agente pode ver no aplicativo? {#what-can-the-agent-see} - -O agente sempre sabe o que o usuário está visualizando no momento. O UI grava o estado de navegação no banco de dados em cada mudança de rota – qual visualização está aberta, qual item está selecionado. O agente lê isso antes de agir. Se um e-mail estiver aberto, o agente saberá qual e-mail. Se um slide for selecionado, o agente saberá qual slide. Consulte [Context Awareness](/docs/context-awareness). - -## Perguntas de desenvolvimento {#development} - -### Quais ferramentas de codificação de IA funcionam com agentes nativos? {#which-ai-tools-work} - -Qualquer ferramenta de codificação de IA que leia instruções do projeto. A estrutura usa AGENTS.md como padrão universal e cria automaticamente links simbólicos para ferramentas específicas: - -- **Código Claude** — lê CLAUDE.md (linkado simbolicamente de AGENTS.md pela configuração CLI) -- **Cursor** — lê AGENTS.md diretamente ou `.cursorrules` (local legado do Cursor) se presente em seu projeto -- **Windsurf** — lê .windsurfrules (linkado simbolicamente de AGENTS.md pela configuração CLI) -- **Codex, Gemini e outros** — trabalhe por meio do painel de agente integrado -- **Builder.io** — agente hospedado na nuvem com edição visual e colaboração - -### Posso usar meu próprio banco de dados? {#can-i-use-my-own-database} - -Sim. Defina `DATABASE_URL` e a estrutura o detecta automaticamente. Os bancos de dados suportados incluem SQLite, Postgres (Neon, Supabase, plain), Turso (libSQL) e Cloudflare D1. Todo SQL é independente de dialeto via Drizzle ORM — o mesmo código funciona em qualquer lugar. - -### Onde posso implantar? {#where-can-i-deploy} - -Em qualquer lugar. O servidor é executado em Nitro, que compila para qualquer destino de implantação: Node.js, Cloudflare Workers/Pages, Netlify, Vercel, Deno Deploy, AWS Lambda e Bun. Você também pode usar a hospedagem Builder.io para implantações gerenciadas. Veja o [Deployment guide](/docs/deployment). - -## Arquitetura {#architecture} - -### Por que SSE mais polling em vez de WebSockets? {#why-polling-not-websockets} - -SSE fornece às gravações do mesmo processo um caminho imediato para o navegador, e uma pesquisa leve de contador de versões continua sendo a alternativa porque funciona em todos os ambientes de implantação - incluindo sem servidor e de borda, onde soquetes persistentes podem não estar disponíveis. Consulte [Key Concepts — Sincronização ao vivo](/docs/key-concepts#polling-sync). - - - -```html -
-
Escrita no DB
- -
-
- SSE
/_agent-native/events · instant -
-
- Polling
/_agent-native/poll · universal fallback -
-
- -
Recarregamento do navegador
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### Por que o UI não pode chamar um LLM diretamente? {#why-no-inline-llm-calls} - -A IA não é determinística, portanto, você precisa de fluxo de conversa para fornecer feedback e iterar (não botões únicos) e o agente já tem sua base de código, instruções, skills e histórico que faltam em uma chamada inline. Rotear tudo através do agente também é o que permite que o aplicativo seja conduzido a partir de Slack, Telegram ou outro agente. Consulte [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge). - -### Por que isso é um framework e não uma biblioteca? {#why-framework-not-library} - -O banco de dados compartilhado, a sincronização ao vivo, o sistema actions e o estado do aplicativo só funcionam porque estão conectados desde o início: o UI reage instantaneamente às alterações do agente, os agentes se comunicam e o agente entende o que o usuário está vendo. Uma biblioteca oferece peças; isso é uma arquitetura. Consulte [Key Concepts](/docs/key-concepts). diff --git a/packages/core/docs/content/locales/zh-CN/faq.mdx b/packages/core/docs/content/locales/zh-CN/faq.mdx deleted file mode 100644 index b152a6c1ff..0000000000 --- a/packages/core/docs/content/locales/zh-CN/faq.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: "FAQ" -description: "有关原生代理的常见问题 - 它是什么、它的用途、您可以构建什么以及它如何工作。" ---- - -# FAQ - -有关代理原生的常见问题，从“我只是在寻找”到“我现在正在连接身份验证”。 - -## 基础知识 {#general} - -### 什么是代理原生？ {#what-is-agent-native} - -Agent-native 是一个用于构建应用程序的框架，其中 AI 代理及其周围的产品界面是平等的合作伙伴。通常的路径是从聊天开始，添加 typed actions，在聊天中渲染结构化结果，然后围绕同一份 SQL state 扩展成持久页面。不变的是智能体和人类共享相同的 actions、数据库和状态。完整解释请参见 [What Is Agent-Native?](/docs/what-is-agent-native)。 - -### 这是给谁的？ {#who-is-this-for} - -Agent-native 适合那些想要真正的应用程序和 AI 代理使用相同数据和 actions 工作的人。常见的路径是： - -- **如果您需要邮件、日历、表单、计划或其他无需设置的成品模板，请使用托管应用程序** - 从 [template gallery](/templates) 开始。 -- **从聊天开始**如果您想要默认的从零构建路径：用户可以立即与 agent 对话，然后您用 actions、原生结果和屏幕扩展它 - 从 [Getting Started](/docs/getting-started) 或 [Chat](/docs/template-chat) 开始。 -- **从 automation-first 开始**如果您正在构建定时任务、队列、脚本、integration worker 或暂时没有浏览器 UI 的外部 agent 工作流 — 从 [Automation-First Apps](/docs/pure-agent-apps) 开始。 -- **分叉并自定义模板**如果您想要自己的 SaaS 产品，并且已连接身份验证、数据库、UI 和代理 actions — 请参阅 [Templates](/docs/cloneable-saas)。 -- **从头开始构建**如果您想要新的代理驱动产品的框架原语 - 从 [Getting Started](/docs/getting-started) 开始。 -- **如果您希望 Claude、ChatGPT、Codex、Cursor 或 GitHub Copilot / VS Code 使用代理本机应用程序，请连接另一个代理或代码工具** - 请参阅 [External Agents](/docs/external-agents) 和 [Skills Guide](/docs/skills-guide)。 - -### 这与向现有应用添加 AI 有何不同？ {#how-is-this-different} - -大多数应用程序将人工智能作为事后的想法，实际上无法在应用程序中*做*事情。在代理原生应用程序中，代理是一等公民，与 UI 共享相同的 actions、数据库和状态，因此它可以执行按钮可以执行的任何操作。参见[What Is Agent-Native?](/docs/what-is-agent-native#the-ladder)。 - - - -```html -
-
- 外挂式 AI -
聊天侧边栏
- -
- 独立的 AI 世界
无法操作应用 -
-
App UI & data
-
- -
- Agent-native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### 它是开源的吗？ {#is-this-open-source} - -是的。该框架和所有模板都是开源的。您可以在本地运行所有内容、自行托管或使用 Builder.io 的云来实现托管、协作和团队功能。 - -### 需要多少钱？ {#how-much} - -框架本身是免费的。您在实践中会看到的两种成本： - -- **AI 使用。** 您携带自己的 API 密钥（Anthropic、OpenAI 等）并直接向模型提供商付款。我们没有加价。 -- **托管。** 无论您的主机收费多少。对于小型工作负载，大多数模板都可以在免费套餐（Netlify、Vercel、Cloudflare）上正常运行。 - -如果您不想管理其中任何内容，`agent-native.com` 上的托管版本（由 Builder.io 运营）可将推理和托管捆绑到每席位计划中。 - -### 我可以自己主持吗？ {#can-i-self-host} - -是的。选择运行 Node 的任何主机 — Netlify、Vercel、Cloudflare、AWS、Deno Deploy、您自己的服务器 — 以及任何 SQL 数据库（Postgres、SQLite、Turso、D1）。该框架是为了可移植而构建的。先从[本地 Docker 快速入门](https://www.agent-native.com/docs/deployment#self-host-quickstart)开始，然后参阅[Deployment](/docs/deployment)进行生产部署。 - -### 支持哪些AI模型？ {#what-models} - -Anthropic Claude、OpenAI（GPT-5 系列）、Google Gemini 以及使用 OpenAI API 形状的任何提供商（包括通过 Ollama 的本地模型）。您可以在设置中配置模型；切换是配置更改，而不是代码重写。该框架最重的测试路径是 Claude，因此这是默认推荐。 - -### 我需要了解人工智能/机器学习吗？ {#do-i-need-to-know-ai} - -没有。您不需要训练模型、微调或处理嵌入。您构建了一个常规的 Web 应用程序 - 在托管版本上，您几乎不需要构建任何东西。该框架处理代理集成：路由消息、运行 actions、同步状态。 - -### 我可以将现有应用迁移到代理原生吗？ {#can-i-use-existing-code} - -可以，但是从头开始构建原生代理效果最好。架构——共享数据库、轮询同步、actions、应用程序状态——需要始终集成。从应用开始并自定义它是推荐的路径。可以把它想象成从桌面优先到移动优先的转变：你*可以*改造，但构建原生更好。 - -## 模板以及您可以构建的内容 {#templates} - -### 有哪些模板可用？ {#what-templates-are-available} - -该框架附带了可用于生产的模板，包括 [Chat](/docs/template-chat)、[Mail](/docs/template-mail)、[Calendar](/docs/template-calendar)、[Forms](/docs/template-forms)、[Plan](/docs/template-plan)（视觉计划和 PR 回顾）、[Analytics](/docs/template-analytics)、[Dispatch](/docs/template-dispatch) 等。每个都是一个完整的应用程序，包含 UI、代理 actions、数据库架构和 AI 指令。完整目录请参见 [Templates](/docs/cloneable-saas)。 - -### 我可以自定义模板吗？ {#can-i-customize-templates} - -这就是重点。从模板开始，在自己的代码库和开发流程中进行定制。嵌入式代理随后通过 actions 和数据操作生成的应用程序。 - -### 我可以构建模板未涵盖的内容吗？ {#build-from-scratch} - -是的。如果你想要一个基本的 agentic app，请运行 `npx @agent-native/core@latest create my-chat-app --template chat`；您可以获得持久的聊天线程、actions、身份验证、SQL 支持的运行时状态、原生内联结果渲染，以及添加自己屏幕的空间。如果您正在构建 no-browser automation，请运行 `npx @agent-native/core@latest create my-agent --headless`。请参阅 [Getting Started](/docs/getting-started)、[Automation-First Apps](/docs/pure-agent-apps) 和 [Chat](/docs/template-chat)。 - -### 我可以在不分叉模板的情况下尝试它吗？ {#try-with-a-skill} - -是的——通过一个命令将一项技能安装到您已经使用的编码代理中，不需要脚手架。请参阅 [Skills Guide](/docs/skills-guide#app-backed-skills) 了解演练。 - -## 代理能力 {#agent-capabilities} - -### 嵌入式代理会编辑应用程序源代码吗？ {#can-the-agent-modify-code} - -默认不会。只有当主机有意授予 repository/workspace 写入工具时，它才能编辑源代码。否则，嵌入式代理通过 actions、SQL 支持的状态和已配置的集成工作。要修改组件、路由、样式或 actions，请使用代码库的正常开发流程，或使用单独的代码能力开发/Builder frame。 - -### 用户可以从应用程序外部与代理交谈吗？ {#external-channels} - -是的。相同的代理在您的网络 UI、Slack、Telegram、通过电子邮件以及其他代理（通过 [A2A](/docs/a2a-protocol)）中运行。这是同一个特工，具有相同的内存和相同的 actions，只是通过不同的渠道到达。参见[Messaging the agent](/docs/messaging)。 - -### 代理可以互相交谈吗？ {#can-agents-talk-to-each-other} - -是的，通过 [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol)。每个代理本机应用程序都会自动获取 A2A 端点。从邮件应用程序中，您可以标记分析代理以查询数据。代理发现其他可用代理，通过协议调用它们，并在 UI 中显示结果。无需配置 - 代理卡是根据模板的 actions 自动生成的。 - -### 客服人员可以在应用程序中看到什么？ {#what-can-the-agent-see} - -代理始终知道用户当前正在查看的内容。 UI 在每次路线更改时将导航状态写入数据库 - 打开哪个视图、选择哪个项目。代理在采取行动之前会阅读此内容。如果电子邮件已打开，代理就知道是哪封电子邮件。如果选择了一张幻灯片，代理就知道是哪张幻灯片。参见[Context Awareness](/docs/context-awareness)。 - -## 开发问题 {#development} - -### 哪些人工智能编码工具可与代理原生配合使用？ {#which-ai-tools-work} - -任何读取项目指令的人工智能编码工具。该框架使用 AGENTS.md 作为通用标准，并自动为特定工具创建符号链接： - -- **Claude 代码** — 读取 CLAUDE.md（通过 CLI 设置从 AGENTS.md 进行符号链接） -- **光标** - 直接读取 AGENTS.md，或者如果项目中存在 `.cursorrules`（光标的旧位置） -- **Windsurf** — 读取 .windsurfrules（通过 CLI 设置从 AGENTS.md 进行符号链接） -- **Codex、Gemini 等** — 通过嵌入式代理面板工作 -- **Builder.io** — 具有可视化编辑和协作功能的云托管代理 - -### 我可以使用自己的数据库吗？ {#can-i-use-my-own-database} - -是的。设置 `DATABASE_URL` ，框架会自动检测它。支持的数据库包括 SQLite、Postgres（Neon、Supabase、plain）、Turso (libSQL) 和 Cloudflare D1。所有 SQL 通过 Drizzle ORM 都是与方言无关的 - 相同的代码在任何地方都可以工作。 - -### 我可以在哪里部署？ {#where-can-i-deploy} - -任何地方。服务器在 Nitro 上运行，可编译为任何部署目标：Node.js、Cloudflare Workers/Pages、Netlify、Vercel、Deno Deploy、AWS Lambda 和 Bun。您还可以使用 Builder.io 的托管进行托管部署。请参阅 [Deployment guide](/docs/deployment)。 - -## 架构 {#architecture} - -### 为什么是 SSE 加轮询而不是 WebSocket？ {#why-polling-not-websockets} - -SSE 为同进程写入提供了到浏览器的直接路径，而轻量级版本计数器轮询仍然是后备方案，因为它适用于每个部署环境 - 包括无服务器和边缘，其中持久套接字可能不可用。参见[Key Concepts — 实时同步](/docs/key-concepts#polling-sync)。 - - - -```html -
-
数据库写入
- -
-
- SSE
/_agent-native/events · instant -
-
- 轮询
/_agent-native/poll · universal fallback -
-
- -
浏览器重新获取
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### 为什么UI不能直接调用LLM？ {#why-no-inline-llm-calls} - -人工智能是非确定性的，因此您需要对话流来提供反馈和迭代 - 而不是一次性按钮 - 并且代理已经拥有内联调用所缺乏的代码库、指令、skills 和历史记录。通过代理路由所有内容还可以让应用程序从 Slack、Telegram 或其他代理驱动。参见[Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge)。 - -### 为什么这是一个框架而不是一个库？ {#why-framework-not-library} - -共享数据库、实时同步、actions 系统和应用程序状态之所以有效，是因为它们从头开始连接在一起 - UI 立即对代理更改做出反应，代理进行通信，并且代理了解用户正在查看的内容。图书馆为你提供作品；这是一个架构。参见[Key Concepts](/docs/key-concepts)。 diff --git a/packages/core/docs/content/locales/zh-TW/faq.mdx b/packages/core/docs/content/locales/zh-TW/faq.mdx deleted file mode 100644 index a416ea03e1..0000000000 --- a/packages/core/docs/content/locales/zh-TW/faq.mdx +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: "FAQ" -description: "有關原生代理的常見問題 - 它是什麼、它的用途、您可以建置什麼以及它如何工作。" ---- - -# FAQ - -有關 Agent-Native 的常見問題，從“我只是在尋找”到“我現在正在連線驗證”。 - -## 基礎知識 {#general} - -### 什麼是 Agent-Native？ {#what-is-agent-native} - -Agent-Native 是一個用於建置應用程式的框架，其中 AI 代理及其周圍的產品介面是平等的合作夥伴。通常的路徑是從聊天開始，新增 typed actions，在聊天中渲染結構化結果，然後圍繞同一份 SQL state 擴展成持久頁面。不變的是智慧體和人類共用相同的 actions、資料庫和狀態。完整解釋請參見 [What Is Agent-Native?](/docs/what-is-agent-native)。 - -### 這是給誰的？ {#who-is-this-for} - -Agent-Native 適合那些想要真正的應用程式和 AI 代理使用相同資料和 actions 工作的人。常見的路徑是： - -- **如果您需要郵件、行事曆、表單、計畫或其他無需設定的成品範本，請使用託管應用程式** - 從 [template gallery](/templates) 開始。 -- **從聊天開始**如果您想要預設的從零建置路徑：使用者可以立即與 agent 對話，然後您用 actions、原生結果和畫面擴展它 - 從 [Getting Started](/docs/getting-started) 或 [Chat](/docs/template-chat) 開始。 -- **從 automation-first 開始**如果您正在建置排程工作、佇列、腳本、integration worker 或暫時沒有瀏覽器 UI 的外部 agent 工作流程 — 從 [Automation-First Apps](/docs/pure-agent-apps) 開始。 -- **分叉並自訂範本**如果您想要自己的 SaaS 產品，並且已連線驗證、資料庫、UI 和代理 actions — 請參閱 [Templates](/docs/cloneable-saas)。 -- **從頭開始建置**如果您想要新的代理驅動產品的框架原語 - 從 [Getting Started](/docs/getting-started) 開始。 -- **如果您希望 Claude、ChatGPT、Codex、Cursor 或 GitHub Copilot / VS Code 使用 Agent-Native 應用程式，請連線另一個代理或程式碼工具** - 請參閱 [External Agents](/docs/external-agents) 和 [Skills Guide](/docs/skills-guide)。 - -### 這與向現有應用新增 AI 有何不同？ {#how-is-this-different} - -大多數應用程式將人工智慧作為事後的想法，實際上無法在應用程式中*做*事情。在 Agent-Native 應用程式中，代理是一等公民，與 UI 共用相同的 actions、資料庫和狀態，因此它可以執行按鈕可以執行的任何操作。參見[What Is Agent-Native?](/docs/what-is-agent-native#the-ladder)。 - - - -```html -
-
- 外掛式 AI -
聊天側邊欄
- -
- 獨立的 AI 世界
無法操作應用 -
-
App UI & data
-
- -
- Agent-Native -
-
UI
-
Agent
-
- -
shared actions, DB & state
-
-
-``` - -```css -.diagram-vs { - display: flex; - align-items: stretch; - gap: 18px; - flex-wrap: wrap; -} -.diagram-vs .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; - align-items: center; - flex: 1; - min-width: 200px; -} -.diagram-vs .diagram-row2 { - display: flex; - gap: 8px; -} -.diagram-vs .diagram-arrow { - font-size: 20px; - line-height: 1; -} -.diagram-vs .diagram-divider { - width: 1px; - align-self: stretch; - background: currentColor; - opacity: 0.15; -} -``` - - - -### 它是開放原始碼的嗎？ {#is-this-open-source} - -是的。此框架和所有範本都是開放原始碼的。您可以在本機執行所有內容、自行託管或使用 Builder.io 的雲端來實現託管、協作和團隊功能。 - -### 需要多少錢？ {#how-much} - -框架本身是免費的。您在實踐中會看到的兩種成本： - -- **AI 使用。** 您攜帶自己的 API 金鑰（Anthropic、OpenAI 等）並直接向模型提供者付款。我們沒有加價。 -- **託管。** 無論您的主機收費多少。對於小型工作負載，大多數範本都可以在免費套餐（Netlify、Vercel、Cloudflare）上正常執行。 - -如果您不想管理其中任何內容，`agent-native.com` 上的託管版本（由 Builder.io 運營）可將推理和託管捆綁到每席位計畫中。 - -### 我可以自己主持嗎？ {#can-i-self-host} - -是的。選取執行 Node 的任何主機 — Netlify、Vercel、Cloudflare、AWS、Deno Deploy、您自己的伺服器 — 以及任何 SQL 資料庫（Postgres、SQLite、Turso、D1）。此框架是為了可移植而建置的。先從[本機 Docker 快速入門](https://www.agent-native.com/docs/deployment#self-host-quickstart)開始，然後參閱[Deployment](/docs/deployment)進行正式環境部署。 - -### 支援哪些 AI 模型？ {#what-models} - -Anthropic Claude、OpenAI（GPT-5 系列）、Google Gemini 以及使用 OpenAI API 形狀的任何提供者（包括透過 Ollama 的本機模型）。您可以在設定中設定模型；切換是設定更改，而不是程式碼重寫。此框架最重的測試路徑是 Claude，因此這是預設推薦。 - -### 我需要了解人工智慧/機器學習嗎？ {#do-i-need-to-know-ai} - -沒有。您不需要訓練模型、微調或處理嵌入。您建置了一個一般的 Web 應用程式 - 在託管版本上，您幾乎不需要建置任何東西。此框架處理代理整合：路由訊息、執行 actions、同步狀態。 - -### 我可以將現有應用遷移到 Agent-Native 嗎？ {#can-i-use-existing-code} - -可以，但是從頭開始建置原生代理效果最好。架構——共用資料庫、輪詢同步、actions、應用程式狀態——需要始終整合。從應用程式開始並自訂它是推薦的路徑。可以把它想象成從桌面優先到行動優先的轉變：你*可以*改造，但建置原生更好。 - -## 範本以及您可以建置的內容 {#templates} - -### 有哪些範本可用？ {#what-templates-are-available} - -此框架附帶了可用於正式環境的範本，包括 [Chat](/docs/template-chat)、[Mail](/docs/template-mail)、[Calendar](/docs/template-calendar)、[Forms](/docs/template-forms)、[Plan](/docs/template-plan)（視覺計畫和 PR 回顧）、[Analytics](/docs/template-analytics)、[Dispatch](/docs/template-dispatch) 等。每個都是一個完整的應用程式，包含 UI、代理 actions、資料庫架構和 AI 指令。完整目錄請參見 [Templates](/docs/cloneable-saas)。 - -### 我可以自訂範本嗎？ {#can-i-customize-templates} - -這就是重點。從範本開始，在自己的程式碼庫和開發流程中進行自訂。嵌入式代理隨後透過 actions 和資料操作產生的應用程式。 - -### 我可以建置範本未涵蓋的內容嗎？ {#build-from-scratch} - -是的。如果你想要一個基本的 agentic app，請執行 `npx @agent-native/core@latest create my-chat-app --template chat`；您可以獲得持久的聊天對話串、actions、驗證、SQL 支援的執行時狀態、原生內嵌結果渲染，以及新增自己畫面的空間。如果您正在建置 no-browser automation，請執行 `npx @agent-native/core@latest create my-agent --headless`。請參閱 [Getting Started](/docs/getting-started)、[Automation-First Apps](/docs/pure-agent-apps) 和 [Chat](/docs/template-chat)。 - -### 我可以在不分叉範本的情況下嘗試它嗎？ {#try-with-a-skill} - -是的——透過一個指令將一項技能安裝到您已經使用的編碼代理中，不需要腳手架。請參閱 [Skills Guide](/docs/skills-guide#app-backed-skills) 了解演練。 - -## 代理能力 {#agent-capabilities} - -### 嵌入式代理會編輯應用程式原始碼嗎？ {#can-the-agent-modify-code} - -預設不會。只有當主機有意授予 repository/workspace 寫入工具時，它才能編輯原始碼。否則，嵌入式代理透過 actions、SQL 支援的狀態和已設定的整合來工作。若要修改元件、路由、樣式或 actions，請使用程式碼庫的正常開發流程，或使用獨立的程式碼能力開發/Builder frame。 - -### 使用者可以從應用程式外部與代理交談嗎？ {#external-channels} - -是的。相同的代理在您的網路 UI、Slack、Telegram、透過電子郵件以及其他代理（透過 [A2A](/docs/a2a-protocol)）中執行。這是同一個代理，具有相同的記憶和相同的 actions，只是透過不同的管道到達。參見[Messaging the agent](/docs/messaging)。 - -### 代理可以互相交談嗎？ {#can-agents-talk-to-each-other} - -是的，透過 [A2A (Agent-to-Agent) protocol](/docs/a2a-protocol)。每個 Agent-Native 應用程式都會自動取得 A2A 端點。從郵件應用程式中，您可以標記分析代理以查詢資料。代理發現其他可用代理，透過協議呼叫它們，並在 UI 中顯示結果。無需設定 - 代理卡是根據範本的 actions 自動產生的。 - -### 代理可以在應用程式中看到什麼？ {#what-can-the-agent-see} - -代理始終知道使用者目前正在檢視的內容。 UI 在每次路由更改時將導覽狀態寫入資料庫 - 開啟哪個檢視、選取哪個專案。代理在採取行動之前會閱讀此內容。如果電子郵件已開啟，代理就知道是哪封電子郵件。如果選取了一張幻燈片，代理就知道是哪張幻燈片。參見[Context Awareness](/docs/context-awareness)。 - -## 開發問題 {#development} - -### 哪些人工智慧編碼工具可與 Agent-Native 配合使用？ {#which-ai-tools-work} - -任何讀取專案指令的人工智慧編碼工具。此框架使用 AGENTS.md 作為通用標準，並自動為特定工具建立符號連結： - -- **Claude 程式碼** — 讀取 CLAUDE.md（透過 CLI 設定從 AGENTS.md 進行符號連結） -- **游標** - 直接讀取 AGENTS.md，或者如果專案中存在 `.cursorrules`（游標的舊位置） -- **Windsurf** — 讀取 .windsurfrules（透過 CLI 設定從 AGENTS.md 進行符號連結） -- **Codex、Gemini 等** — 透過嵌入式代理面板工作 -- **Builder.io** — 具有視覺化編輯和協作功能的雲端託管代理 - -### 我可以使用自己的資料庫嗎？ {#can-i-use-my-own-database} - -是的。設定 `DATABASE_URL` ，框架會自動偵測它。支援的資料庫包括 SQLite、Postgres（Neon、Supabase、plain）、Turso (libSQL) 和 Cloudflare D1。所有 SQL 透過 Drizzle ORM 都是與方言無關的 - 相同的程式碼在任何地方都可以工作。 - -### 我可以在哪裡部署？ {#where-can-i-deploy} - -任何地方。伺服器在 Nitro 上執行，可編譯為任何部署目標：Node.js、Cloudflare Workers/Pages、Netlify、Vercel、Deno Deploy、AWS Lambda 和 Bun。您還可以使用 Builder.io 的託管進行託管部署。請參閱 [Deployment guide](/docs/deployment)。 - -## 架構 {#architecture} - -### 為什麼是 SSE 加輪詢而不是 WebSocket？ {#why-polling-not-websockets} - -SSE 為同行程寫入提供了到瀏覽器的直接路徑，而輕量級版本計數器輪詢仍然是後備方案，因為它適用於每個部署環境 - 包括無伺服器和邊緣，其中持久 socket 可能不可用。參見[Key Concepts — 即時同步](/docs/key-concepts#polling-sync)。 - - - -```html -
-
資料庫寫入
- -
-
- SSE
/_agent-native/events · instant -
-
- 輪詢
/_agent-native/poll · universal fallback -
-
- -
瀏覽器重新取得
-
-``` - -```css -.diagram-transport { - display: flex; - align-items: center; - gap: 12px; - flex-wrap: wrap; -} -.diagram-transport .diagram-col { - display: flex; - flex-direction: column; - gap: 8px; -} -.diagram-transport .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` - - - -### 為什麼 UI 不能直接呼叫 LLM？ {#why-no-inline-llm-calls} - -人工智慧是非確定性的，因此您需要對話流來提供意見回饋和迭代 - 而不是一次性按鈕 - 並且代理已經擁有行內呼叫所缺乏的程式碼庫、指令、skills 和歷史紀錄。透過代理路由所有內容還可以讓應用程式從 Slack、Telegram 或其他代理驅動。參見[Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge)。 - -### 為什麼這是一個框架而不是一個庫？ {#why-framework-not-library} - -共用資料庫、即時同步、actions 系統和應用程式狀態之所以有效，是因為它們從頭開始連線在一起 - UI 立即對代理更改做出反應，代理進行通信，並且代理了解使用者正在檢視的內容。程式庫提供零件；這是一個架構。參見[Key Concepts](/docs/key-concepts)。 diff --git a/packages/core/docs/content/syncing-template-changes.mdx b/packages/core/docs/content/syncing-template-changes.mdx index ea6e62ba47..f5fed4698e 100644 --- a/packages/core/docs/content/syncing-template-changes.mdx +++ b/packages/core/docs/content/syncing-template-changes.mdx @@ -25,7 +25,9 @@ agent-native upgrade agent-native template sync ``` -`sync` defaults to the template version matching your installed `@agent-native/core`, so running it after `upgrade` keeps code and packages on the same version. +`sync` defaults to the template version matching your installed `@agent-native/core`, so running it after `upgrade` keeps code and packages on the same version. Running the bare `agent-native upgrade` bumps `@agent-native/*` dependencies to `latest`, installs, refreshes scaffold skills (`skills update scaffold --project`), and runs typecheck when available. Use `agent-native upgrade check` first for a doctor-only report of framework overrides/patches and pending bumps. + +Do **not** fix a broken upgrade with `pnpm.overrides`, `patchedDependencies`, or edits under `node_modules/@agent-native/*` (especially core/dispatch) — those mask the real incompatibility instead of resolving it. If upgrade or typecheck fails, fix app-level code or ask, then re-run upgrade. Look before you merge: diff --git a/packages/core/docs/content/writing-agent-instructions.mdx b/packages/core/docs/content/writing-agent-instructions.mdx index d62cb8fd63..7492195c40 100644 --- a/packages/core/docs/content/writing-agent-instructions.mdx +++ b/packages/core/docs/content/writing-agent-instructions.mdx @@ -102,6 +102,14 @@ data and the same actions. Keep one canonical instructions file: `AGENTS.md`. If a client expects `CLAUDE.md`, make it a symlink to `AGENTS.md` rather than a second copy. Two hand-maintained files drift, and the agent ends up with contradictory rules. One source of truth, linked where needed. +`AGENTS.md` is the universal standard the framework builds on, so any AI coding tool that reads project instructions works out of the box: + +- **Claude Code** — reads `CLAUDE.md` (symlinked from `AGENTS.md` by the CLI setup) +- **Cursor** — reads `AGENTS.md` directly, or `.cursorrules` (Cursor's legacy location) if present +- **Windsurf** — reads `AGENTS.md` directly, or `.windsurfrules` (Windsurf's legacy location) if present +- **Codex, Gemini, and others** — work via the embedded agent panel +- **Builder.io** — cloud-hosted agent with visual editing and collaboration + ## SKILL.md frontmatter must say what AND when {#skill-frontmatter} The `description` is the only thing the agent sees when deciding whether to read a skill. It must answer two questions: what the skill covers, and when to trigger it. A description that only describes the topic will not fire. diff --git a/packages/docs/app/components/docs-slug-redirects.ts b/packages/docs/app/components/docs-slug-redirects.ts index f38063ddd7..c8e328889f 100644 --- a/packages/docs/app/components/docs-slug-redirects.ts +++ b/packages/docs/app/components/docs-slug-redirects.ts @@ -13,6 +13,11 @@ export const DOCS_SLUG_REDIRECTS: Record = { resources: "agent-resources", secrets: "security", workspace: "agent-resources", + // FAQ folded into What Is Agent-Native and rehomed into the docs it + // answered questions about (deployment, environment-variables, + // writing-agent-instructions, cloneable-saas, key-concepts, + // syncing-template-changes). + faq: "what-is-agent-native", // Plans docs consolidated into the single template-plan page. "visual-plans": "template-plan", // Toolkit -ui pages merged into their parent kit doc. diff --git a/packages/docs/app/components/docsNavItems.ts b/packages/docs/app/components/docsNavItems.ts index 5985a52e59..430f6c8660 100644 --- a/packages/docs/app/components/docsNavItems.ts +++ b/packages/docs/app/components/docsNavItems.ts @@ -51,7 +51,6 @@ const NAV_SECTION_CONFIG: NavSectionConfig[] = [ labelKey: "agentSurfaces", slug: "agent-surfaces", }, - { id: "faq", labelKey: "faq", slug: "faq" }, ], }, { From 43082144ffc320c62999e8177045b52b89c46104 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Tue, 18 Aug 2026 14:04:43 -0700 Subject: [PATCH 2/5] get rid of excessive em dashes --- packages/core/docs/content/deployment.mdx | 4 ++-- packages/core/docs/content/environment-variables.mdx | 2 +- packages/core/docs/content/key-concepts.mdx | 2 +- .../core/docs/content/syncing-template-changes.mdx | 2 +- .../core/docs/content/writing-agent-instructions.mdx | 10 +++++----- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/core/docs/content/deployment.mdx b/packages/core/docs/content/deployment.mdx index f968cfd1f0..167ab8ef32 100644 --- a/packages/core/docs/content/deployment.mdx +++ b/packages/core/docs/content/deployment.mdx @@ -5,11 +5,11 @@ description: "Deploy agent-native apps to any platform with Nitro presets — No # Deployment -Agent-native apps use [Nitro](https://nitro.build) under the hood, which means you can deploy to any platform with zero config changes — just set a preset. Pick any host that runs Node — Netlify, Vercel, Cloudflare, AWS Lambda, Deno Deploy, or your own server — paired with any Drizzle-compatible SQL database (Postgres, SQLite, Turso, D1). Nothing here requires Builder.io or any particular cloud; self-hosting the whole stack is a first-class path, not a workaround. +Agent-native apps use [Nitro](https://nitro.build) under the hood, which means you can deploy to any platform with zero config changes: just set a preset. Pick any host that runs Node, such as Netlify, Vercel, Cloudflare, AWS Lambda, Deno Deploy, or your own server, paired with any Drizzle-compatible SQL database (Postgres, SQLite, Turso, D1). Nothing here requires Builder.io or any particular cloud; self-hosting the whole stack is a first-class path, not a workaround. ## Cost {#cost} -The framework itself is free — no license fee, and no markup on top of your model provider. In practice you'll see two costs: +The framework itself is free: no license fee, and no markup on top of your model provider. In practice you'll see two costs: - **AI usage.** You bring your own API key (Anthropic, OpenAI, etc.) and pay the model provider directly. - **Hosting.** Whatever your host charges. Most templates run fine on free tiers (Netlify, Vercel, Cloudflare) for small workloads. diff --git a/packages/core/docs/content/environment-variables.mdx b/packages/core/docs/content/environment-variables.mdx index e4deecc549..8403ffad56 100644 --- a/packages/core/docs/content/environment-variables.mdx +++ b/packages/core/docs/content/environment-variables.mdx @@ -128,7 +128,7 @@ Every provider key below selects its engine on its own: dropping one in is enough, and `AGENT_ENGINE` is only needed to pick between several. Supported models span Anthropic Claude, OpenAI (GPT-5 family), Google Gemini, -and any provider that speaks the OpenAI API shape via `OPENAI_BASE_URL` — +and any provider that speaks the OpenAI API shape via `OPENAI_BASE_URL`, including OpenAI-compatible gateways like LiteLLM. The model is chosen in Settings, so switching providers is a configuration change, not a code rewrite. Claude is the framework's most heavily tested path and the default diff --git a/packages/core/docs/content/key-concepts.mdx b/packages/core/docs/content/key-concepts.mdx index 0b36222f71..6b6e6d020f 100644 --- a/packages/core/docs/content/key-concepts.mdx +++ b/packages/core/docs/content/key-concepts.mdx @@ -370,7 +370,7 @@ Every consumer calls the same underlying function, so there is only one implemen When the agent changes data, the UI needs to reflect that without a manual refresh. `useDbSync()` is what makes that automatic. Same-process writes stream over `/_agent-native/events`; `/_agent-native/poll` remains the cross-process and serverless fallback. When the agent writes to the database (application state, settings, or domain data), a version counter increments and the client invalidates the relevant React Query caches. -SSE covers the common case instead of WebSockets because it gives same-process writes an immediate path to the browser with plain HTTP, while the version-counter poll stays as a fallback that works in every deployment environment — including serverless and edge, where persistent sockets may not be available. +SSE covers the common case instead of WebSockets because it gives same-process writes an immediate path to the browser with plain HTTP, while the version-counter poll stays as a fallback that works in every deployment environment, including serverless and edge, where persistent sockets may not be available. ```ts // Client: subscribe to agent/UI data changes once near the app shell diff --git a/packages/core/docs/content/syncing-template-changes.mdx b/packages/core/docs/content/syncing-template-changes.mdx index f5fed4698e..4e63cb3555 100644 --- a/packages/core/docs/content/syncing-template-changes.mdx +++ b/packages/core/docs/content/syncing-template-changes.mdx @@ -27,7 +27,7 @@ agent-native template sync `sync` defaults to the template version matching your installed `@agent-native/core`, so running it after `upgrade` keeps code and packages on the same version. Running the bare `agent-native upgrade` bumps `@agent-native/*` dependencies to `latest`, installs, refreshes scaffold skills (`skills update scaffold --project`), and runs typecheck when available. Use `agent-native upgrade check` first for a doctor-only report of framework overrides/patches and pending bumps. -Do **not** fix a broken upgrade with `pnpm.overrides`, `patchedDependencies`, or edits under `node_modules/@agent-native/*` (especially core/dispatch) — those mask the real incompatibility instead of resolving it. If upgrade or typecheck fails, fix app-level code or ask, then re-run upgrade. +Do **not** fix a broken upgrade with `pnpm.overrides`, `patchedDependencies`, or edits under `node_modules/@agent-native/*` (especially core/dispatch); those mask the real incompatibility instead of resolving it. If upgrade or typecheck fails, fix app-level code or ask, then re-run upgrade. Look before you merge: diff --git a/packages/core/docs/content/writing-agent-instructions.mdx b/packages/core/docs/content/writing-agent-instructions.mdx index 7492195c40..33c08c1e0a 100644 --- a/packages/core/docs/content/writing-agent-instructions.mdx +++ b/packages/core/docs/content/writing-agent-instructions.mdx @@ -104,11 +104,11 @@ Keep one canonical instructions file: `AGENTS.md`. If a client expects `CLAUDE.m `AGENTS.md` is the universal standard the framework builds on, so any AI coding tool that reads project instructions works out of the box: -- **Claude Code** — reads `CLAUDE.md` (symlinked from `AGENTS.md` by the CLI setup) -- **Cursor** — reads `AGENTS.md` directly, or `.cursorrules` (Cursor's legacy location) if present -- **Windsurf** — reads `AGENTS.md` directly, or `.windsurfrules` (Windsurf's legacy location) if present -- **Codex, Gemini, and others** — work via the embedded agent panel -- **Builder.io** — cloud-hosted agent with visual editing and collaboration +- **Claude Code**: reads `CLAUDE.md` (symlinked from `AGENTS.md` by the CLI setup) +- **Cursor**: reads `AGENTS.md` directly, or `.cursorrules` (Cursor's legacy location) if present +- **Windsurf**: reads `AGENTS.md` directly, or `.windsurfrules` (Windsurf's legacy location) if present +- **Codex, Gemini, and others**: work via the embedded agent panel +- **Builder.io**: cloud-hosted agent with visual editing and collaboration ## SKILL.md frontmatter must say what AND when {#skill-frontmatter} From 77bfd47c9784d853b8404e721deb74f42a30c202 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Wed, 19 Aug 2026 13:01:13 -0700 Subject: [PATCH 3/5] docs: add Templates card to What is Agent-Native next steps Closes a navigation gap left by the overview/getting-started revamp: neither page signposted Templates or Automation-First Apps as alternate starting points anymore. Co-Authored-By: Claude Sonnet 5 --- packages/core/docs/content/what-is-agent-native.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/packages/core/docs/content/what-is-agent-native.mdx b/packages/core/docs/content/what-is-agent-native.mdx index cf3a9a8774..90f9105275 100644 --- a/packages/core/docs/content/what-is-agent-native.mdx +++ b/packages/core/docs/content/what-is-agent-native.mdx @@ -108,4 +108,8 @@ together. See how the same model supports apps led by a UI, chat, automation, or another agent. +### [Templates](/docs/cloneable-saas) + +Start from a complete SaaS product instead of building up from Chat. + From 3b54e799917ec1dc0517c323df94ec050c292478 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Wed, 19 Aug 2026 13:32:15 -0700 Subject: [PATCH 4/5] test: update sidebar fixture and add changeset for FAQ removal - DocsSidebar.test.tsx still expected a 'faq' nav item under Overview - add the missing changeset for the @agent-native/core docs changes Co-Authored-By: Claude Sonnet 5 --- .changeset/fold-faq-into-what-is-agent-native.md | 5 +++++ packages/docs/app/components/DocsSidebar.test.tsx | 1 - 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 .changeset/fold-faq-into-what-is-agent-native.md diff --git a/.changeset/fold-faq-into-what-is-agent-native.md b/.changeset/fold-faq-into-what-is-agent-native.md new file mode 100644 index 0000000000..3c3f94994a --- /dev/null +++ b/.changeset/fold-faq-into-what-is-agent-native.md @@ -0,0 +1,5 @@ +--- +"@agent-native/core": patch +--- + +Removed the FAQ docs page and folded its content into What Is Agent-Native and the docs pages each answer actually belonged to (deployment, environment variables, writing agent instructions, templates, key concepts, syncing template changes). diff --git a/packages/docs/app/components/DocsSidebar.test.tsx b/packages/docs/app/components/DocsSidebar.test.tsx index 1b5eb2ba35..64662aaa3e 100644 --- a/packages/docs/app/components/DocsSidebar.test.tsx +++ b/packages/docs/app/components/DocsSidebar.test.tsx @@ -93,7 +93,6 @@ describe("DocsSidebar", () => { "what-is-agent-native", "key-concepts", "agent-surfaces", - "faq", ]); expect(overview?.items.some((item) => item.id === "deployment")).toBe( false, From 1de3ceb66b7f239384439954a4bc3d5d2a6e1d7e Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Wed, 19 Aug 2026 13:58:30 -0700 Subject: [PATCH 5/5] chore: retrigger CI Co-Authored-By: Claude Sonnet 5