diff --git a/.changeset/rewrite-key-concepts-doc.md b/.changeset/rewrite-key-concepts-doc.md new file mode 100644 index 0000000000..b11b2fc89e --- /dev/null +++ b/.changeset/rewrite-key-concepts-doc.md @@ -0,0 +1,5 @@ +--- +"@agent-native/core": patch +--- + +Rework the Key Concepts doc for clarity: reordered "What Agent Native includes" into a table right after the five rules, removed em dashes and rhetorical questions throughout, added missing context around the SQL stores and action examples, and translated into all 10 locales. diff --git a/packages/core/docs/content/key-concepts.mdx b/packages/core/docs/content/key-concepts.mdx index 20e6056f42..4fab467995 100644 --- a/packages/core/docs/content/key-concepts.mdx +++ b/packages/core/docs/content/key-concepts.mdx @@ -1,21 +1,21 @@ --- title: "Key Concepts" -description: "How agent-native apps work across three layers: the Core framework, optional Toolkit building blocks, and optional Templates, plus the shared actions, SQL database, app-agent loop, and portability contract." +description: "How agent-native apps work across three layers: the Core framework, optional Toolkit building blocks, and optional Templates, plus the shared actions, SQL database, app-agent loop, and portability rules." --- # Key Concepts -How agent-native apps work under the hood — the principles and the architecture. This page is the contract; for the vision and the case for building this way, see [What Is Agent-Native?](/docs/what-is-agent-native). +How agent-native apps work under the hood: the principles and the architecture. This page is the contract: the fixed rules an app has to follow to count as agent-native. For the vision and the case for building this way, see [What Is Agent-Native?](/docs/what-is-agent-native). ## The three layers {#three-layers} -Agent Native is a framework, not a single template. It has three layers: +Agent Native is a framework with three layers: -| Layer | What it is | -| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Core - the framework** | The foundational runtime contract: actions, SQL and Drizzle helpers, auth, application state, agent execution, access checks, routing, and live sync. Every app can use Core directly. | -| **Toolkit - optional reusable pieces for the framework** | Shared app-building UI and product systems such as primitives, editors, sharing, collaboration, settings, and agent UX. Apps can use, compose, or fork the pieces they need. | -| **Templates - optional apps built on Core** | Complete, domain-specific apps with routes, schema, actions, instructions, and visual identity. First-party and custom templates commonly use Toolkit, and can be forked and used as starting points. | +| Layer | What it is | +| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Core: the framework** | The foundational runtime contract: actions, SQL and Drizzle helpers, auth, application state, agent execution, access checks, routing, and live sync. Every app can use Core directly. | +| **Toolkit: optional reusable pieces** | Shared app-building UI and product systems such as primitives, editors, sharing, collaboration, settings, and agent UX. Apps can use, compose, or fork the pieces they need. | +| **Templates: optional apps built on Core** | Complete, domain-specific apps with routes, schema, actions, instructions, and visual identity. First-party and custom templates commonly use Toolkit, and can be forked and used as starting points. | Core is the foundation. Toolkit and Templates are optional: a template can use Toolkit, but Toolkit is not required to build an app on Core. @@ -23,9 +23,11 @@ Core is the foundation. Toolkit and Templates are optional: a template can use T At runtime, every agent-native app is three things working together: -- **Agent** — Autonomous AI that reads data, writes data, runs actions, and uses configured tools. It can also modify source when its frame is intentionally granted workspace and write tooling. Customizable with skills and instructions. -- **Application** — The product surface around the agent. This may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations. -- **Computer** — Database, browser, and configured tool runtimes. Agents work through the app's action and data surface; an app may expose that same action surface over MCP, while external MCP servers remain optional add-ons rather than the foundation. +- **Agent:** The autonomous AI. It reads data, writes data, runs actions, and uses whatever tools are configured. When its frame is intentionally granted workspace access and write tooling, it can also modify the app's own source. Customizable with skills and instructions. +- **Application:** The product surface around the agent. It may start as chat, add native inline results, grow into a small control plane, or become a full React UI with dashboards, flows, and visualizations. +- **Computer:** The database, browser, and configured tool runtimes the agent acts through. Agents work through the app's own action and data surface; that same surface can optionally be exposed over MCP, but external MCP servers stay an add-on, not the foundation. + +The diagram below shows the agent and the application side by side, both with two-way arrows into one shared computer layer underneath. Neither one owns the data. Instead, they read and write the same SQL store, so a change either side makes is visible to the other immediately, with no sync layer to build in between. @@ -88,12 +90,13 @@ At runtime, every agent-native app is three things working together: -Automation-first apps can run the same production app-agent loop from the folder with `pnpm agent`, while UI apps mount the embedded agent panel and run locally with `pnpm dev`. In the cloud, Builder.io provides a managed frame — the environment that hosts the agent next to your app — with collaboration, visual editing, and managed infrastructure for teams. +That same agent-application-computer loop is what runs locally and in production. Automation-first apps run it straight from the folder with `pnpm agent`; UI apps mount the embedded agent panel and add `pnpm dev`. In the cloud, Builder.io hosts the identical loop as a managed frame: the environment that runs the agent next to your app. It handles collaboration, visual editing, and infrastructure for you. ## Agent building blocks {#agent-building-blocks} Every agent-native app has the same agent building blocks, regardless of whether -the product surface is chat-first, automation-first, or a full UI: +the product surface is chat-first, automation-first, or a full UI. Each one lives +in its own file: -| Building block | Use it for | Loaded when | -| ---------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | -| **Instructions** | Stable guidance the agent should carry into every task: what the app is, invariants, tone, indexes | Every turn | -| **Skills** | Reusable behavior: how to follow a workflow, apply a policy, inspect evidence, or verify an output | On demand when the skill description matches the task | -| **Actions** | Real operations: read or write data, call APIs, send messages, run approvals, produce typed results | Listed as tools every turn; executed only when called | +A turn is one exchange with the agent: it reads its context, decides what to do, and responds. Loaded every turn means the file re-enters that context each time, not just once at session start. + +| Building block | File | Use it for | Loaded when | +| ---------------- | -------------------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | +| **Instructions** | `AGENTS.md` | Stable guidance the agent should carry into every task: what the app is, invariants, tone, indexes | Every turn | +| **Skills** | `.agents/skills//SKILL.md` | Reusable behavior: how to follow a workflow, apply a policy, inspect evidence, or verify an output | On demand when the skill description matches the task | +| **Actions** | `actions/.ts` | Real operations: read or write data, call APIs, send messages, run approvals, produce typed results | Listed as tools every turn; executed only when called | Skills and actions work together. A skill teaches the agent how to do a class of work; an action is the code path it can call while doing that work. For example, @@ -128,41 +133,59 @@ and write the actual data. Five rules govern the architecture: -1. **Data lives in SQL** — all app state lives in the database via Drizzle ORM -2. **All AI goes through the agent** — no inline LLM calls -3. **Actions for agent operations** — complex work runs as actions -4. **Live sync keeps the UI in sync** — database changes stream over SSE with polling as the universal fallback -5. **Application state in SQL** — ephemeral UI state lives in the database, readable by both agent and UI +1. **Data lives in SQL:** all app state lives in the database via Drizzle ORM. +2. **All AI goes through the agent:** no inline LLM calls; every AI interaction flows through the agent chat bridge. +3. **Actions for agent operations:** complex work runs as a typed action, not inline code. +4. **Live sync keeps the UI in sync:** database changes stream over SSE, with polling as the universal fallback. +5. **Application state in SQL:** ephemeral UI state lives in the database, readable by both agent and UI. ## The four-area checklist {#four-area-checklist} Every user-facing feature should update all applicable areas. Skipping an applicable area breaks the agent-native contract; forcing a screen onto an automation that no human needs to browse is also a smell. -| Area | Description | -| ---------------- | -------------------------------------------------------------- | -| **1. UI** | Page, component, or dialog the user interacts with | -| **2. Action** | Agent-callable action in actions/ for the same operation | -| **3. Skills** | Update AGENTS.md and/or create a skill documenting the pattern | -| **4. App-State** | Navigation state, view-screen data, and navigate commands | +- **1. UI:** Page, component, or dialog the user interacts with. +- **2. Action:** Agent-callable action in `actions/` for the same operation. +- **3. Skills:** Update `AGENTS.md` and/or create a skill documenting the pattern. +- **4. App-State:** Navigation state, view-screen data, and navigate commands. A feature with only UI is invisible to the agent. A full UI feature with only actions is invisible to the user. A feature without app-state means the agent is blind to what the user is doing. An automation-first operation can legitimately start with action + instructions and add chat, UI, or app-state later when humans need to browse, approve, configure, or share it. +## What Agent Native includes {#what-you-get-for-free} + +Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the five rules above, you inherit: + +| Feature | What it gives you | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| One action = every surface | Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation. | +| Full agent resources per user | Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, and connected MCP servers. All SQL-backed, no dev-box required. See [Agent Resources](/docs/agent-resources). | +| Drop-in React components | `` and `` render chat + resources anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent). | +| BYO agent chat runtimes | The same chat UI can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or your own normalized HTTP stream. See [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes). | +| Live sync between agent and UI | Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below. | +| Auth, orgs, RBAC | Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication). For more than one user, start with [Organizations, Teams & Permissions](/docs/organizations-teams-permissions). | +| Context awareness | The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness). | +| MCP client + server, both directions | The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol). | +| Inter-app delegation | Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`. | +| Sub-agent teams | Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams). | +| Portability | Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). | + ## Data in SQL {#data-in-sql} All application state lives in a SQL database via Drizzle ORM. Schemas are provider-agnostic; the supported databases, `DATABASE_URL` config, and portability rules live in [Database](/docs/database). Core SQL stores are auto-created and available in every template: -- `application_state` — ephemeral UI state (navigation, drafts, selections) -- `settings` — persistent key-value config -- `oauth_tokens` — OAuth credentials -- `sessions` — auth sessions +- `application_state`: ephemeral UI state (navigation, drafts, selections) +- `settings`: persistent key-value config +- `oauth_tokens`: OAuth credentials +- `sessions`: auth sessions + +Each row below expands to show its fields: +To add your own domain data, define a table with the same schema helpers used by the core stores above: + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -247,12 +272,18 @@ export const forms = table("forms", { }); ``` +Both you and the agent can inspect that data from the terminal, without a separate SQL client: + ```bash # Core actions for quick database inspection pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` +`db-schema` prints every table's columns and types. `db-query` runs read-only SQL directly, which is useful for checking an action's writes without opening a database client. + + + The production agent chat plugin defaults raw SQL tools to read-only (`frameworkTools: { database: "read" }`), so agents inspect app-owned data with `db-schema` / `db-query` and perform writes through typed app actions. Set @@ -268,12 +299,14 @@ chat, and email. See list, the `"minimal"` preset, and why disabling a group leaves its HTTP routes mounted. + + ## Agent chat bridge {#agent-chat-bridge} -The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work — with full conversation history, skills, instructions, and the ability to iterate. +The UI never calls an LLM directly. When a user clicks "Generate chart" or "Write summary", the UI sends a message to the agent via `postMessage`. The agent does the work. It has full conversation history, skills, instructions, and the ability to iterate. ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -282,16 +315,19 @@ sendToAgentChat({ }); ``` -Why not call an LLM inline? +In short: + +- **AI is non-deterministic**: You need conversation flow to give feedback and iterate, not one-shot buttons. +- **Context matters**: The agent has the app's instructions, skills, and history. An inline call has none of that. +- **The agent can do more**: It can run actions, browse the web, and chain multiple steps together. -- **AI is non-deterministic.** You need conversation flow to give feedback and iterate — not one-shot buttons. -- **Context matters.** The agent has the app's instructions, skills, and history. An inline call has none of that. -- **The agent can do more.** It can run actions, browse the web, and chain multiple steps together. -- **External execution.** Because everything goes through the agent and actions, any app can be driven from Slack, Telegram, scheduled jobs, scripts, or another agent via [A2A](/docs/a2a-protocol). +**[External execution](/docs/a2a-protocol)** + +Because everything goes through the agent and actions, any app can be driven from Slack, Telegram, scheduled jobs, scripts, or another agent via A2A. ## Actions system {#actions-system} -When the agent needs to do something complex — call an API, process data, query the database — it runs an **action**. Actions are TypeScript files in `actions/` that export a default `defineAction()`: +When the agent needs to do something complex, like calling an API, processing data, or querying the database, it runs an **action**. Actions are TypeScript files in `actions/` that export a default `defineAction()`: ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -309,19 +345,30 @@ export default defineAction({ }); ``` -One `defineAction()` call gives you: +This action fetches JSON from a source API and returns it. `defineAction()` wraps the function with a zod schema for its input (`source`), so the framework can validate that input, generate a JSON Schema the agent can call, and infer types for the frontend hook, all from this one definition. + +One `defineAction()` call reaches five different consumers automatically. The diagram shows the fan-out from a single action; the list below explains what each consumer gets: + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **Agent tool** — the agent sees it with the zod-derived JSON Schema and can call it. -- **Frontend hook** — `useActionMutation("fetch-data")` with full TypeScript inference. -- **Framework transport** — auto-mounted behind the client hooks. -- **CLI** — `pnpm action fetch-data --source=signups` for scripting and agent dev loops. -- **MCP tool / A2A tool** — when MCP server or A2A is enabled, the same action shows up there too. +- **Agent tool:** the agent sees it with the zod-derived JSON Schema and can call it. +- **Frontend hook:** `useActionMutation("fetch-data")` with full TypeScript inference. +- **Framework transport:** auto-mounted behind the client hooks. +- **CLI:** `pnpm action fetch-data --source=signups` for scripting and agent dev loops. +- **MCP tool / A2A tool:** when MCP server or A2A is enabled, the same action shows up there too. -Same logic, one definition, wired to every consumer automatically. See [Actions](/docs/actions) for the full reference. +Every consumer calls the same underlying function, so there is only one implementation to write and maintain. See [Actions](/docs/actions) for the full reference. ## Live sync {#polling-sync} -Database changes are synced to the UI through `useDbSync()`. 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. +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. ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -329,6 +376,8 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` +Call this once, near the root of the app. It subscribes the whole app to change events, so any component using `useActionQuery` or a source-versioned `useQuery` refetches automatically when the data it reads changes. + The flow is: 1. Agent runs an action that writes to the database @@ -337,7 +386,9 @@ The flow is: 4. `useActionQuery` hooks and source-versioned `useQuery` hooks refetch 5. Components render the new data without a page reload - +The diagram traces that same sequence end to end: + + ```html
@@ -384,16 +435,16 @@ The flow is: -This works in all deployment environments — including serverless and edge — because it uses the database, not in-memory state or file system watchers. +This works in all deployment environments, including serverless and edge, because it uses the database instead of in-memory state or file system watchers. ## Frames {#frames} -A _frame_ is the environment that hosts the agent next to your app — locally that's the embedded panel; in the cloud it's Builder.io's managed surface. See [Frames](/docs/frames). +A _frame_ is the environment that hosts the agent next to your app. Locally that's the embedded panel; in the cloud it's Builder.io's managed surface. See [Frames](/docs/frames). Agent-native apps include an embedded agent panel that provides the AI agent alongside the app UI. This is what makes the architecture work: the agent needs a computer (database, browser, code execution), and the app needs the agent for AI work. -- **Embedded Agent Panel** — Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally. Free and open source. -- **Cloud** — Deploy to any cloud with real-time collaboration, visual editing, roles and permissions. Best for teams. +- **Embedded Agent Panel:** Chat and optional CLI terminal built into every app. Supports Claude Code, Codex, Gemini, OpenCode, and Builder.io. Runs locally, free and open source. +- **Cloud:** Deploy to any cloud with real-time collaboration, visual editing, roles, and permissions. Best for teams. ## Context awareness {#context-awareness} @@ -405,7 +456,11 @@ For example, when you open an email thread the UI upserts a row like: { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -The UI writes this on route change; the agent reads it (via `view-screen`) before taking any action, so it always knows which thread — or chart, or slide — you're focused on. + + +The UI writes this on route change; the agent reads it (via `view-screen`) before taking any action, so it always knows which thread, chart, or slide you're focused on. + + See [Context Awareness](/docs/context-awareness) for the full pattern: navigation state, view-screen, navigate commands, and jitter prevention. @@ -413,7 +468,7 @@ See [Context Awareness](/docs/context-awareness) for the full pattern: navigatio Implement a domain operation once as an action; the framework exposes it to every consumer. The same `defineAction()` becomes an agent tool, a typesafe UI hook, an HTTP endpoint, a CLI command, an MCP tool, and an A2A tool, with optional `link`, `mcpApp`, native-widget metadata, or Generative UI wrappers added only when a surface needs richer interaction. Skills and instructions cover behavior. -For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape — chat, inline UI, full app pages, embedded sidecar, automation, or external-agent access — see [Agent Surfaces](/docs/agent-surfaces). +For the full protocol/surface matrix (MCP server and OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, and the adapter horizon for ACP and A2UI), and for choosing a product shape (chat, inline UI, full app pages, embedded sidecar, automation, or external-agent access), see [Agent Surfaces](/docs/agent-surfaces). ## App code and customization {#agent-modifies-code} @@ -430,43 +485,46 @@ without source changes, use [Extensions](/docs/extensions). Two architectural rules keep apps portable across databases and hosts: - **Database-agnostic.** Write schemas with `@agent-native/core/db/schema` and reads/writes with Drizzle's portable query DSL so the same code runs on any supported provider. Use raw SQL only for additive migrations or one-off maintenance, kept parameterized and dialect-agnostic. See [Database](/docs/database). -- **Hosting-agnostic.** The server runs on Nitro and compiles to any deployment target. Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins, and never assume a persistent server process — serverless and edge are stateless, so keep all state in SQL. See [Deployment](/docs/deployment). +- **Hosting-agnostic.** The server runs on Nitro and compiles to any deployment target. Never use Node-specific APIs (`fs`, `child_process`, `path`) in server routes or plugins, and never assume a persistent server process. Serverless and edge are stateless, so keep all state in SQL. See [Deployment](/docs/deployment). ## Agent Resources {#workspace} -Every user gets a personal set of **agent resources** — instructions, skills, memory, custom sub-agents, scheduled jobs, and connected MCP servers — all stored in SQL rather than files. That makes Claude-Code-level customization viable inside multi-tenant SaaS without spinning up a container per user. See [Agent Resources](/docs/agent-resources). +Every user gets a personal set of **agent resources**: instructions, skills, memory, custom sub-agents, scheduled jobs, and connected MCP servers, all stored in SQL rather than files. That makes Claude-Code-level customization viable inside multi-tenant SaaS without spinning up a container per user. See [Agent Resources](/docs/agent-resources). ## Related building blocks {#building-blocks} These sit on top of the same contract and have their own deep dives: -- **[Dispatch](/docs/dispatch)** — the workspace control plane: shared inbox, secrets vault, scheduled jobs, and an orchestrator that delegates to specialist apps over A2A. -- **[Extensions](/docs/extensions)** — sandboxed Alpine.js mini-apps the agent creates at runtime, no source changes or migrations. -- **[A2A Protocol](/docs/a2a-protocol)** — how apps in the same workspace discover and call each other over JSON-RPC. +- **[Dispatch](/docs/dispatch):** the workspace control plane, with a shared inbox, secrets vault, scheduled jobs, and an orchestrator that delegates to specialist apps over A2A. +- **[Extensions](/docs/extensions):** sandboxed Alpine.js mini-apps the agent creates at runtime, with no source changes or migrations. +- **[A2A Protocol](/docs/a2a-protocol):** how apps in the same workspace discover and call each other over JSON-RPC. -## What you get for free {#what-you-get-for-free} +## What's next {#deep-dives} -Adopting the framework is valuable mostly because of what you stop having to build. The moment your app follows the five rules, you inherit: + -- **One action = every surface.** Every action defined with `defineAction()` is simultaneously an agent tool, a typesafe frontend hook (`useActionQuery` / `useActionMutation`), a framework-owned HTTP transport, a CLI command, an MCP tool for external clients, and an A2A tool for other agent-native apps. Optional `link` and `mcpApp` metadata add deep links and MCP Apps UI without a second implementation. -- **A full set of agent resources per user.** Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, connected MCP servers — all SQL-backed, no dev-box required. See [Agent Resources](/docs/agent-resources). -- **Drop-in React components.** `` and `` render chat + resources anywhere in your app. See [Drop-in Agent](/docs/drop-in-agent). -- **BYO agent chat runtimes.** The same chat UI can sit on top of OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, or your own normalized HTTP stream. See [Native Chat UI](/docs/native-chat-ui#byo-agent-runtimes). -- **Live sync between agent and UI.** Same-process writes stream immediately over `/_agent-native/events`; a lightweight poll keeps serverless, cron, and cross-process writes convergent. Mutating actions invalidate action-backed queries automatically, so agent-created records appear without a manual refresh. See [Live Sync](#polling-sync) below. -- **Auth, orgs, RBAC.** Better Auth with orgs/members/roles is wired in for every template. See [Authentication](/docs/authentication). Building for more than one user? Start with [Organizations, Teams & Permissions](/docs/organizations-teams-permissions). -- **Context awareness.** The agent always knows what the user is looking at through the `navigation` app-state key. See [Context Awareness](/docs/context-awareness). -- **MCP client + server, both directions.** The app ingests MCP servers (local, remote, hub-shared) _and_ exposes its own actions as an MCP server. See [MCP Clients](/docs/mcp-clients) and [MCP Protocol](/docs/mcp-protocol). -- **Inter-app delegation.** Agents in different apps talk over [A2A](/docs/a2a-protocol). Same-origin deploys skip JWT; cross-origin uses a shared `A2A_SECRET`. -- **Sub-agent teams.** Spawn a sub-agent with its own thread and tools, surfaced as a chip inline in chat. See [Agent Teams](/docs/agent-teams). -- **Portability.** Any Drizzle-supported SQL database, any Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). +### [What Is Agent-Native?](/docs/what-is-agent-native) -That's the "and everything else" you'd otherwise be gluing together yourself. +The vision and philosophy behind these rules. -## What's next {#deep-dives} +### [Context Awareness](/docs/context-awareness) + +Navigation state, view-screen, and navigate commands in depth. + +### [Skills Guide](/docs/skills-guide) + +Framework skills, domain skills, and creating custom skills. + +### [Native Chat UI](/docs/native-chat-ui) + +Action-declared tables, charts, and BYO runtime posture. + +### [Agent Surfaces](/docs/agent-surfaces) + +Chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths. + +### [A2A Protocol](/docs/a2a-protocol) + +Agent-to-agent communication. -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — the vision and philosophy behind these rules -- [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen, and navigate commands in depth -- [**Skills Guide**](/docs/skills-guide) — framework skills, domain skills, and creating custom skills -- [**Native Chat UI**](/docs/native-chat-ui) — action-declared tables, charts, and BYO runtime posture -- [**Agent Surfaces**](/docs/agent-surfaces) — chat, native inline UI, full app pages, embedded sidecar, automation, and external-agent paths -- [**A2A Protocol**](/docs/a2a-protocol) — agent-to-agent communication + diff --git a/packages/core/docs/content/locales/ar-SA/key-concepts.mdx b/packages/core/docs/content/locales/ar-SA/key-concepts.mdx index 7cc0358581..6b8ab74abe 100644 --- a/packages/core/docs/content/locales/ar-SA/key-concepts.mdx +++ b/packages/core/docs/content/locales/ar-SA/key-concepts.mdx @@ -1,46 +1,50 @@ --- title: "المفاهيم الأساسية" -description: "كيفية عمل تطبيقات الوكيل الأصلية: actions أولاً، قاعدة بيانات SQL، حلقة وكيل التطبيق، UI الاختيارية، مزامنة الاستقصاء، نقاط دخول الوكيل الخارجي، الوعي بالسياق، وقابلية النقل." +description: "كيفية عمل تطبيقات agent-native عبر ثلاث طبقات: إطار Core، ولبنات Toolkit الاختيارية، وTemplates الاختيارية، إضافة إلى الإجراءات المشتركة، وقاعدة بيانات SQL، وحلقة التطبيق-الوكيل، وقواعد قابلية النقل." --- # المفاهيم الأساسية -كيفية عمل التطبيقات الأصلية للوكيل تحت الغطاء - المبادئ والبنية. هذه الصفحة هي العقد. لرؤية وحالة البناء بهذه الطريقة، راجع [What Is Agent-Native?](/docs/what-is-agent-native). +كيفية عمل تطبيقات agent-native من الداخل: المبادئ والبنية المعمارية. هذه الصفحة هي العقد: القواعد الثابتة التي يجب أن يتبعها التطبيق ليُحسب agent-native. للاطلاع على الرؤية ومبرر البناء بهذه الطريقة، راجع [ما هو Agent-Native؟](/docs/what-is-agent-native). ## الطبقات الثلاث {#three-layers} -Agent Native هو framework وليس قالبًا واحدًا: +Agent Native هو إطار عمل مكوَّن من ثلاث طبقات: -- **Core - framework:** عقد التشغيل والبيانات الأساسي الذي يمكن لكل تطبيق استخدامه. -- **Toolkit - أجزاء اختيارية قابلة لإعادة الاستخدام:** واجهة المستخدم وأنظمة المنتج المشتركة التي يمكن للتطبيقات اعتمادها أو تركيبها أو fork لها. -- **Templates - تطبيقات اختيارية:** تطبيقات كاملة مبنية على Core، وتستخدم Toolkit غالبًا، ويمكن fork لها واستخدامها كنقطة بداية. +| الطبقة | ما هي | +| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Core: الإطار** | العقد الأساسي لوقت التشغيل: الإجراءات، ومساعدات SQL وDrizzle، والمصادقة، وحالة التطبيق، وتنفيذ الوكيل، وفحوصات الوصول، والتوجيه (routing)، والمزامنة المباشرة. يمكن لكل تطبيق استخدام Core مباشرةً. | +| **Toolkit: قطع اختيارية قابلة لإعادة الاستخدام** | UI مشتركة لبناء التطبيقات وأنظمة منتج مثل العناصر الأولية، والمحررات، والمشاركة، والتعاون، والإعدادات، وتجربة الوكيل (agent UX). يمكن للتطبيقات استخدام القطع التي تحتاجها أو تركيبها أو عمل fork لها. | +| **Templates: تطبيقات اختيارية مبنية على Core** | تطبيقات كاملة خاصة بمجال معيَّن، بمسارات، ومخطط، وإجراءات، وتعليمات، وهوية بصرية. تستخدم Templates الرسمية والمخصصة عادةً Toolkit، ويمكن عمل fork لها واستخدامها كنقاط انطلاق. | -Core هو الأساس. Toolkit وTemplates اختياريان. +Core هو الأساس. Toolkit وTemplates اختياريان: يمكن لقالب (template) استخدام Toolkit، لكن Toolkit ليس شرطًا لبناء تطبيق على Core. ## الهندسة المعمارية {#the-architecture} -يتكون كل تطبيق وكيل أصلي من ثلاثة أشياء تعمل معًا: +في وقت التشغيل، كل تطبيق agent-native هو ثلاثة أشياء تعمل معًا: -- **Agent** — الذكاء الاصطناعي المستقل الذي يقرأ البيانات، ويكتب البيانات، ويشغل actions، ويستخدم الأدوات المكوّنة. قابلة للتخصيص باستخدام skills والتعليمات. -- **التطبيق** — سطح المنتج حول العامل. قد يكون هذا الإجراء فقط في البداية، أو دردشة غنية، أو مستوى تحكم صغير، أو واجهة React كامل مع لوحات المعلومات، وعمليات التدفق، والمرئيات. -- **الكمبيوتر** — قاعدة البيانات، المتصفح، تنفيذ التعليمات البرمجية. يعمل الوكلاء عبر سطح إجراءات التطبيق وبياناته؛ ويمكن للتطبيق كشف سطح الإجراءات نفسه عبر MCP، بينما تظل خوادم MCP الخارجية إضافات اختيارية وليست الأساس. +- **الوكيل:** الذكاء الاصطناعي المستقل. يقرأ البيانات، ويكتبها، ويُشغِّل الإجراءات، ويستخدم أي أدوات مُهيَّأة. عندما يُمنح إطاره عمدًا وصولًا إلى مساحة العمل وأدوات كتابة، يمكنه أيضًا تعديل الكود المصدري للتطبيق نفسه. قابل للتخصيص بالمهارات والتعليمات. +- **التطبيق:** سطح المنتج حول الوكيل. قد يبدأ كدردشة، ثم يضيف نتائج مضمَّنة أصلية، وينمو ليصبح مستوى تحكم صغيرًا، أو يصبح UI كاملًا مبنيًا بـ React مع لوحات معلومات، وتدفقات، ومرئيات. +- **الكمبيوتر:** قاعدة البيانات، والمتصفح، وأوقات تشغيل الأدوات المُهيَّأة التي يتصرف الوكيل من خلالها. يعمل الوكلاء عبر سطح الإجراءات والبيانات الخاص بالتطبيق نفسه؛ ويمكن اختياريًا عرض هذا السطح نفسه عبر MCP، لكن خوادم MCP الخارجية تبقى إضافة، وليست الأساس. - +يُظهر المخطط أدناه الوكيل والتطبيق جنبًا إلى جنب، وكلاهما بسهمين ثنائيي الاتجاه إلى طبقة كمبيوتر مشتركة واحدة أسفلهما. لا يملك أي منهما البيانات. بدلًا من ذلك، يقرآن ويكتبان إلى نفس متجر SQL، بحيث يكون أي تغيير يُجريه أي طرف مرئيًا للطرف الآخر فورًا، دون طبقة مزامنة يجب بناؤها بينهما. + + ```html
- Agentالوكيليقرأ + يكتب البيانات، وينفذ الإجراءات، ويستخدم الأدوات المكوّنةيقرأ + يكتب البيانات، يُشغِّل الإجراءات، يستخدم الأدوات + المُهيَّأة
- Applicationالتطبيقالإجراء فقط، أو الدردشة، أو مستوى التحكم، أو واجهة المستخدم React - الكاملةدردشة، نتائج مضمَّنة، مستوى تحكم، أو UI كامل بـ React
@@ -48,8 +52,8 @@ Core هو الأساس. Toolkit وTemplates اختياريان. ↓ ↑
- حاسوب
SQL قاعدة البيانات · المتصفح · تنفيذ التعليمات البرمجيةقاعدة بيانات SQL · متصفح · تنفيذ كود
@@ -87,105 +91,126 @@ Core هو الأساس. Toolkit وTemplates اختياريان. -يمكن للتطبيقات مقطوعة الرأس تشغيل نفس حلقة وكيل تطبيق الإنتاج من المجلد باستخدام `pnpm agent`، بينما تقوم تطبيقات UI بتثبيت لوحة الوكيل المضمنة وتشغيلها محليًا باستخدام `pnpm dev`. في السحابة، يوفر Builder.io إطارًا مُدارًا - البيئة التي تستضيف الوكيل بجوار تطبيقك - مع التعاون والتحرير المرئي والبنية الأساسية المُدارة للفرق. +نفس حلقة الوكيل-التطبيق-الكمبيوتر هذه هي ما يعمل محليًا وفي الإنتاج. تُشغِّلها تطبيقات الأتمتة أولاً مباشرةً من المجلد باستخدام `pnpm agent`؛ بينما تُثبِّت تطبيقات UI لوحة الوكيل المضمَّنة وتضيف `pnpm dev`. في السحابة، يستضيف Builder.io نفس الحلقة كإطار مُدار: البيئة التي تُشغِّل الوكيل بجانب تطبيقك. وهو يتولى التعاون، والتحرير المرئي، والبنية التحتية نيابةً عنك. -## العناصر الأساسية للوكيل {#agent-building-blocks} +## عناصر بناء الوكيل {#agent-building-blocks} -يحتوي كل تطبيق وكيل أصلي على نفس العناصر الأساسية للوكيل، بغض النظر عما إذا كان -يجب أن يكون سطح المنتج بدون رأس، أو للدردشة أولاً، أو UI كاملاً: +كل تطبيق agent-native يملك نفس عناصر بناء الوكيل، بغض النظر عمّا إذا كان +سطح المنتج دردشة أولًا، أو أتمتة أولًا، أو UI كاملًا. يعيش كل عنصر +في ملفه الخاص: /SKILL.md", - note: "سلوك قابل لإعادة الاستخدام: خطوات workflow، سياسات، أمثلة، مراجع، وقوائم ما يجب فعله وما لا يجب فعله", + note: "سلوك قابل لإعادة الاستخدام: خطوات سير العمل، والسياسات، والأمثلة، والمراجع، وقوائم ما يجب وما لا يجب فعله", }, { path: "actions/.ts", - note: "قدرة قابلة للتنفيذ: عملية typed مكشوفة لل agent و UI و CLI و HTTP و MCP و A2A و jobs و webhooks", + note: "قدرة قابلة للتنفيذ: عملية مكتوبة الأنواع مكشوفة للوكيل، وUI، وCLI، وHTTP، وMCP، وA2A، والمهام، والـwebhooks", }, ]} /> -| كتلة البناء | استخدمه من أجل | تم التحميل عندما | -| ------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | -| **التعليمات** | توجيه ثابت يجب على الوكيل تنفيذه في كل مهمة: ما هو التطبيق، الثوابت، النغمة، الفهارس | كل دورة | -| **Skills** | السلوك القابل لإعادة الاستخدام: كيفية متابعة سير العمل، أو تطبيق سياسة، أو فحص الأدلة، أو التحقق من المخرجات | عند الطلب عندما يتطابق وصف المهارة مع المهمة | -| **Actions** | العمليات الحقيقية: قراءة البيانات أو كتابتها، والاتصال بـ API، وإرسال الرسائل، وتشغيل الموافقات، وإنتاج النتائج المكتوبة | يتم إدراجه كأدوات في كل دور؛ يتم تنفيذه فقط عند الاتصال | +الدور الواحد هو تبادل واحد مع الوكيل: يقرأ سياقه، ويقرر ما يجب فعله، ثم يستجيب. "يُحمَّل في كل دور" يعني أن الملف يعود إلى ذلك السياق في كل مرة، وليس مرة واحدة فقط عند بدء الجلسة. + +| كتلة البناء | الملف | استخدمه من أجل | يُحمَّل عندما | +| ------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | +| **التعليمات** | `AGENTS.md` | توجيه ثابت يجب أن يحمله الوكيل إلى كل مهمة: ما هو التطبيق، الثوابت، النبرة، الفهارس | كل دور | +| **المهارات** | `.agents/skills//SKILL.md` | سلوك قابل لإعادة الاستخدام: كيفية اتباع سير عمل، أو تطبيق سياسة، أو فحص أدلة، أو التحقق من مخرَج | عند الطلب، عندما يطابق وصف المهارة المهمة | +| **الإجراءات** | `actions/.ts` | عمليات حقيقية: قراءة البيانات أو كتابتها، واستدعاء واجهات API، وإرسال الرسائل، وتشغيل الموافقات، وإنتاج نتائج مكتوبة الأنواع | مُدرجة كأدوات في كل دور؛ تُنفَّذ فقط عند استدعائها | -يعمل Skills وactions معًا. مهارة تعلم الوكيل كيفية القيام بفصل -العمل؛ الإجراء هو مسار التعليمات البرمجية الذي يمكنه الاتصال به أثناء القيام بهذا العمل. على سبيل المثال، +تعمل المهارات والإجراءات معًا. تُعلّم المهارة الوكيل كيفية القيام بفئة من +العمل؛ والإجراء هو مسار الكود الذي يمكنه استدعاؤه أثناء القيام بذلك العمل. على سبيل المثال، قد تخبر مهارة `customer-research` الوكيل بالمصادر التي يجب فحصها و -كيفية تلخيص الأدلة أثناء جلب `search-crm` و`create-brief` actions -واكتب البيانات الفعلية. +كيفية تلخيص الأدلة، بينما يقوم إجراءا `search-crm` و`create-brief` +بجلب البيانات الفعلية وكتابتها. + +تحكم خمس قواعد البنية المعمارية: + +1. **البيانات موجودة في SQL:** تعيش كل حالة التطبيق في قاعدة البيانات عبر Drizzle ORM. +2. **كل الذكاء الاصطناعي يمر عبر الوكيل:** لا توجد استدعاءات LLM مضمَّنة؛ يتدفق كل تفاعل بالذكاء الاصطناعي عبر جسر دردشة الوكيل. +3. **الإجراءات لعمليات الوكيل:** يعمل العمل المعقد كإجراء مكتوب الأنواع، وليس كود مضمَّن. +4. **المزامنة المباشرة تُبقي UI متزامنة:** تتدفق تغييرات قاعدة البيانات عبر SSE، مع الاستقصاء كإجراء احتياطي عام. +5. **حالة التطبيق في SQL:** تعيش حالة UI العابرة في قاعدة البيانات، وتكون قابلة للقراءة من الوكيل وUI معًا. -خمس قواعد تحكم البنية: +## قائمة التحقق ذات المجالات الأربعة {#four-area-checklist} -1. **البيانات موجودة في SQL** — جميع حالات التطبيق موجودة في قاعدة البيانات عبر Drizzle ORM -2. **كل الذكاء الاصطناعي يمر عبر الوكيل** — لا توجد مكالمات LLM مضمنة -3. **Actions لعمليات الوكيل** — يتم تشغيل العمل المعقد كـ actions -4. **المزامنة المباشرة تحافظ على مزامنة UI** — تدفق تغييرات قاعدة البيانات عبر SSE مع الاستقصاء كإجراء احتياطي عالمي -5. **حالة التطبيق في SQL** — تعيش حالة UI المؤقتة في قاعدة البيانات ويمكن للوكيل وUI قراءتها +يجب أن تُحدِّث كل ميزة تواجه المستخدم جميع المجالات القابلة للتطبيق. تخطي مجال قابل للتطبيق يكسر عقد agent-native؛ كما أن فرض شاشة على أتمتة لا يحتاج أي إنسان لتصفحها يُعد أيضًا مؤشر خلل. -## قائمة التحقق ذات المناطق الأربعة {#four-area-checklist} +- **1. UI:** الصفحة أو المكوّن أو مربع الحوار الذي يتفاعل معه المستخدم. +- **2. الإجراء:** إجراء قابل لاستدعاء الوكيل في `actions/` لنفس العملية. +- **3. المهارات:** حدِّث `AGENTS.md` و/أو أنشئ مهارة توثِّق النمط. +- **4. حالة التطبيق:** حالة التنقل، وبيانات `view-screen`، وأوامر `navigate`. -يجب على كل ميزة تواجه المستخدم تحديث جميع المجالات القابلة للتطبيق. يؤدي تخطي منطقة قابلة للتطبيق إلى كسر عقد الوكيل الأصلي؛ إجبار UI على بدائية الحركة فقط هو أيضًا رائحة. +الميزة التي تحتوي على UI فقط تكون غير مرئية للوكيل. ميزة UI كاملة تحتوي على إجراءات فقط تكون غير مرئية للمستخدم. الميزة التي لا تملك حالة تطبيق تعني أن الوكيل أعمى عمّا يفعله المستخدم. يمكن لعملية الأتمتة أولاً أن تبدأ بشكل مشروع بإجراء + تعليمات، ثم تضيف الدردشة أو UI أو حالة التطبيق لاحقًا عندما يحتاج البشر إلى تصفحها أو الموافقة عليها أو تهيئتها أو مشاركتها. -| المساحة | الوصف | -| ------------------- | -------------------------------------------------------- | -| **1. UI** | الصفحة أو المكون أو مربع الحوار الذي يتفاعل معه المستخدم | -| **2. الإجراء** | إجراء يمكن استدعاء الوكيل فيه في actions/ لنفس العملية | -| **3. Skills** | تحديث AGENTS.md و/أو إنشاء مهارة لتوثيق النمط | -| **4. حالة التطبيق** | حالة التنقل وبيانات شاشة العرض وأوامر التنقل | +## ما الذي يتضمنه Agent Native {#what-you-get-for-free} -الميزة التي تحتوي على UI فقط تكون غير مرئية للوكيل. ميزة UI الكاملة مع actions فقط غير مرئية للمستخدم. الميزة التي لا تحتوي على حالة التطبيق تعني أن الوكيل لا يرى ما يفعله المستخدم. يمكن أن تبدأ العملية بدون رأس بطريقة شرعية من خلال تعليمات الإجراء + وإضافة UI/app-state لاحقًا عندما يحتاج البشر إلى تصفحها أو الموافقة عليها أو تهيئتها أو مشاركتها. +تكمن قيمة اعتماد الإطار غالبًا فيما تتوقف عن الحاجة إلى بنائه. بمجرد أن يتبع تطبيقك القواعد الخمس أعلاه، فإنك ترث: + +| الميزة | ما الذي تحصل عليه | +| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| إجراء واحد = كل سطح | كل إجراء مُعرَّف باستخدام `defineAction()` هو في الوقت نفسه أداة وكيل، وخطاف واجهة أمامية آمن للأنواع (`useActionQuery` / `useActionMutation`)، ونقل HTTP مملوك للإطار، وأمر CLI، وأداة MCP للعملاء الخارجيين، وأداة A2A لتطبيقات agent-native الأخرى. تضيف البيانات الوصفية الاختيارية `link` و`mcpApp` روابط عميقة وواجهات MCP Apps بدون تنفيذ ثانٍ. | +| موارد وكيل كاملة لكل مستخدم | المهارات، و`LEARNINGS.md` المشتركة، و`memory/MEMORY.md` الشخصية، و`AGENTS.md`، ووكلاء فرعيون مخصصون، ومهام مجدولة، وخوادم MCP متصلة. جميعها مدعومة بـ SQL، دون الحاجة إلى صندوق تطوير. راجع [موارد الوكيل](/docs/agent-resources). | +| مكونات React جاهزة للإضافة | يعرض `` و`` الدردشة + الموارد في أي مكان في تطبيقك. راجع [Drop-in Agent](/docs/drop-in-agent). | +| أوقات تشغيل دردشة وكيل توفرها بنفسك (BYO) | يمكن لنفس واجهة الدردشة أن تعمل فوق OpenAI Agents، أو OpenAI Responses، أو Claude Agent SDK، أو Vercel AI SDK، أو AG-UI، أو تدفق HTTP مُوحَّد خاص بك. راجع [واجهة المحادثة الأصيلة](/docs/native-chat-ui#byo-agent-runtimes). | +| مزامنة مباشرة بين الوكيل وUI | تتدفق الكتابات داخل نفس العملية فورًا عبر `/_agent-native/events`؛ ويُبقي استقصاء خفيف الوزن عمليات الكتابة بدون خادم، وcron، وعبر العمليات متقاربة. تُبطل الإجراءات المُغيِّرة للبيانات الاستعلامات المدعومة بالإجراءات تلقائيًا، بحيث تظهر السجلات التي أنشأها الوكيل دون تحديث يدوي. راجع [المزامنة المباشرة](#polling-sync) أدناه. | +| المصادقة، والمؤسسات، وRBAC | Better Auth مع المؤسسات/الأعضاء/الأدوار موصولة مسبقًا في كل قالب. راجع [المصادقة](/docs/authentication). لأكثر من مستخدم واحد، ابدأ بـ [المؤسسات والفرق والأذونات](/docs/organizations-teams-permissions). | +| الوعي بالسياق | يعرف الوكيل دائمًا ما ينظر إليه المستخدم من خلال مفتاح حالة التطبيق `navigation`. راجع [الوعي بالسياق](/docs/context-awareness). | +| عميل وخادم MCP، في الاتجاهين | يستوعب التطبيق خوادم MCP (محلية، أو بعيدة، أو مشتركة عبر hub) _و_ يعرض إجراءاته الخاصة كخادم MCP. راجع [عملاء MCP](/docs/mcp-clients) و[MCP Protocol](/docs/mcp-protocol). | +| التفويض بين التطبيقات | تتحدث الوكلاء في تطبيقات مختلفة عبر [A2A](/docs/a2a-protocol). عمليات النشر من نفس الأصل تتخطى JWT؛ ويستخدم النشر عبر الأصول `A2A_SECRET` مشتركًا. | +| فرق الوكلاء الفرعيين | أنشئ وكيلًا فرعيًا بخيطه وأدواته الخاصة، يظهر كشريحة مضمَّنة في الدردشة. راجع [Agent Teams](/docs/agent-teams). | +| قابلية النقل | أي قاعدة بيانات SQL مدعومة من Drizzle، وأي مضيف متوافق مع Nitro (Node، وWorkers، وNetlify، وVercel، وDeno، وLambda، وBun). | ## البيانات في SQL {#data-in-sql} -توجد جميع حالات التطبيق في قاعدة بيانات SQL عبر Drizzle ORM. المخططات لا تعتمد على المزود؛ قواعد البيانات المدعومة وتكوين `DATABASE_URL` وقواعد النقل موجودة في [Database](/docs/database). +تعيش كل حالة التطبيق في قاعدة بيانات SQL عبر Drizzle ORM. المخططات لا تعتمد على المزوِّد؛ قواعد البيانات المدعومة، وتهيئة `DATABASE_URL`، وقواعد قابلية النقل موجودة في [Database](/docs/database). يتم إنشاء متاجر SQL الأساسية تلقائيًا وهي متاحة في كل قالب: -- `application_state` — حالة UI سريعة الزوال (التنقل، المسودات، التحديدات) -- `settings` — تكوين قيمة المفتاح المستمر -- `oauth_tokens` — بيانات اعتماد OAuth -- `sessions` — جلسات المصادقة +- `application_state`: حالة UI عابرة (التنقل، المسودات، التحديدات) +- `settings`: تهيئة قيمة-مفتاح دائمة +- `oauth_tokens`: بيانات اعتماد OAuth +- `sessions`: جلسات المصادقة + +يتوسع كل صف أدناه لعرض حقوله: +لإضافة بياناتك الخاصة بالمجال، عرِّف جدولًا باستخدام نفس مساعدات المخطط المستخدمة في المتاجر الأساسية أعلاه: + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -246,28 +273,30 @@ export const forms = table("forms", { }); ``` +يمكنك أنت والوكيل معًا فحص تلك البيانات من الطرفية، دون الحاجة إلى عميل SQL منفصل: + ```bash -# الإجراءات الأساسية للفحص السريع لقاعدة البيانات +# إجراءات Core لفحص قاعدة البيانات بسرعة pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -يقوم البرنامج الإضافي للدردشة مع وكيل الإنتاج بتعيين أدوات SQL الخام إلى القراءة فقط افتراضيًا -(`frameworkTools: { database: "read" }`)، لذلك يفحص الوكلاء بيانات التطبيق باستخدام `db-schema` / -`db-query` ويجرون عمليات الكتابة عبر actions التطبيق المكتوبة. عيّن -`database: "write"` (أو `true`) فقط لأسطح الصيانة المقصودة التي يجب أن تعرض -`db-exec` / `db-patch` ذات النطاق؛ أو عيّن -`database: "off"` / `false` للمطالبة بالتطبيق المكتوب actions لجميع البيانات -الوصول. +تطبع `db-schema` أعمدة كل جدول وأنواعها. تُشغِّل `db-query` SQL للقراءة فقط مباشرةً، وهو أمر مفيد للتحقق من كتابات إجراء ما دون فتح عميل قاعدة بيانات. + + + +يقوم البرنامج الإضافي للدردشة مع وكيل الإنتاج بتعيين أدوات SQL الخام إلى القراءة فقط افتراضيًا (`frameworkTools: { database: "read" }`)، لذلك يفحص الوكلاء بيانات التطبيق باستخدام `db-schema` / `db-query` ويجرون عمليات الكتابة عبر actions التطبيق المكتوبة. عيّن `database: "write"` (أو `true`) فقط لأسطح الصيانة المقصودة التي يجب أن تعرض `db-exec` / `db-patch` ذات النطاق؛ أو عيّن `database: "off"` / `false` للمطالبة بالتطبيق المكتوب actions لجميع البيانات الوصول. + + يتحكم `frameworkTools` ببقية أدوات الإطار نفسها بالطريقة ذاتها: المشاركة، وتعليقات المراجعة، وسجل الإصدارات، وfeature flags، والتعريب، والتدقيق، وContext X-Ray، والملف الشخصي، والأتمتة، وdocs، وresources، وweb، والتفويض بين التطبيقات، والمحادثة، والبريد. راجع [Production Agent Tools](/docs/deployment#production-agent-tools) للقائمة الكاملة والإعداد المسبق `"minimal"` وسبب بقاء مسارات HTTP مثبّتة عند إيقاف مجموعة. ## جسر دردشة الوكيل {#agent-chat-bridge} -لا يتصل UI مطلقًا بـ LLM مباشرة. عندما ينقر المستخدم على "إنشاء مخطط" أو "كتابة ملخص"، يرسل UI رسالة إلى الوكيل عبر `postMessage`. يقوم الوكيل بالعمل — مع سجل المحادثات الكامل، وskills، والتعليمات، والقدرة على التكرار. +لا يستدعي UI أبدًا LLM مباشرةً. عندما ينقر المستخدم على "إنشاء رسم بياني" أو "كتابة ملخص"، يرسل UI رسالة إلى الوكيل عبر `postMessage`. يقوم الوكيل بالعمل. لديه سجل المحادثة الكامل، والمهارات، والتعليمات، والقدرة على التكرار. ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -276,16 +305,19 @@ sendToAgentChat({ }); ``` -لماذا لا تتصل بـ LLM المضمّن؟ +باختصار: + +- **الذكاء الاصطناعي غير حتمي:** تحتاج إلى تدفق محادثة لتقديم الملاحظات والتكرار، وليس أزرارًا تُستخدم مرة واحدة. +- **السياق مهم:** يمتلك الوكيل تعليمات التطبيق ومهاراته وسجله. الاستدعاء المضمَّن لا يملك أيًا من ذلك. +- **يمكن للوكيل فعل المزيد:** يمكنه تشغيل إجراءات، وتصفح الويب، وربط خطوات متعددة معًا. -- **الذكاء الاصطناعي غير حتمي.** أنت بحاجة إلى تدفق المحادثة لتقديم التعليقات والتكرار - وليس الأزرار التي تستخدم مرة واحدة. -- **السياق مهم.** يمتلك الوكيل قاعدة التعليمات البرمجية الكاملة والتعليمات وskills والسجل. المكالمة المضمنة لا تحتوي على أي من ذلك. -- **يمكن للوكيل فعل المزيد.** يمكنه تشغيل actions، وتصفح الويب، وتسلسل خطوات متعددة معًا. -- **التنفيذ بدون مراقبة.** نظرًا لأن كل شيء يمر عبر الوكيل، يمكن تشغيل أي تطبيق بالكامل من Slack أو Telegram أو وكيل آخر عبر [A2A](/docs/a2a-protocol). +**[التنفيذ الخارجي](/docs/a2a-protocol)** -## نظام Actions {#actions-system} +بما أن كل شيء يمر عبر الوكيل والإجراءات، يمكن تشغيل أي تطبيق من Slack، أو Telegram، أو مهام مجدولة، أو نصوص برمجية، أو وكيل آخر عبر A2A. -عندما يحتاج الوكيل إلى القيام بشيء معقد - استدعاء API ومعالجة البيانات والاستعلام عن قاعدة البيانات - فإنه يقوم بتشغيل **إجراء**. Actions هي ملفات TypeScript في `actions/` والتي تقوم بتصدير `defineAction()` الافتراضي: +## نظام الإجراءات {#actions-system} + +عندما يحتاج الوكيل إلى القيام بشيء معقد، مثل استدعاء API، أو معالجة بيانات، أو الاستعلام عن قاعدة البيانات، فإنه يُشغِّل **إجراءً**. الإجراءات هي ملفات TypeScript في `actions/` تُصدِّر `defineAction()` افتراضيًا: ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -303,19 +335,30 @@ export default defineAction({ }); ``` -تمنحك مكالمة `defineAction()` واحدة ما يلي: +يجلب هذا الإجراء JSON من واجهة API مصدر ويعيده. يغلِّف `defineAction()` الدالة بمخطط zod لمدخلها (`source`)، بحيث يمكن للإطار التحقق من صحة ذلك المدخل، وتوليد مخطط JSON يمكن للوكيل استدعاءه، واستنتاج الأنواع لخطاف الواجهة الأمامية، كل ذلك من هذا التعريف الواحد. + +يصل استدعاء `defineAction()` واحد تلقائيًا إلى خمسة مستهلكين مختلفين. يوضح المخطط الانتشار من إجراء واحد؛ وتشرح القائمة أدناه ما يحصل عليه كل مستهلك: + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **أداة الوكيل** — يراها الوكيل باستخدام مخطط JSON المشتق من zod ويمكنه الاتصال بها. -- **الخطاف الأمامي** — `useActionMutation("fetch-data")` مع استدلال TypeScript الكامل. -- **نقل الإطار** — يتم تثبيته تلقائيًا خلف خطافات العميل. -- **CLI** — `pnpm action fetch-data --source=signups` للبرمجة النصية وحلقات تطوير الوكيل. -- **أداة MCP / أداة A2A** — عند تمكين خادم MCP أو A2A، يظهر نفس الإجراء هناك أيضًا. +- **أداة الوكيل:** يراها الوكيل بمخطط JSON المشتق من zod ويمكنه استدعاؤها. +- **خطاف الواجهة الأمامية:** `useActionMutation("fetch-data")` مع استدلال TypeScript كامل. +- **نقل الإطار:** يُثبَّت تلقائيًا خلف خطافات العميل. +- **CLI:** `pnpm action fetch-data --source=signups` للبرمجة النصية وحلقات تطوير الوكيل. +- **أداة MCP / أداة A2A:** عند تفعيل خادم MCP أو A2A، يظهر نفس الإجراء هناك أيضًا. -نفس المنطق، وتعريف واحد، يتم توصيله تلقائيًا لكل مستهلك. راجع [Actions](/docs/actions) للحصول على المرجع الكامل. +يستدعي كل مستهلك نفس الدالة الأساسية، لذا لا يوجد سوى تنفيذ واحد يجب كتابته وصيانته. راجع [الإجراءات](/docs/actions) للحصول على المرجع الكامل. ## المزامنة المباشرة {#polling-sync} -تتم مزامنة تغييرات قاعدة البيانات مع UI من خلال `useDbSync()`. نفس العملية تكتب الدفق عبر `/_agent-native/events`؛ يظل `/_agent-native/poll` هو الإجراء الاحتياطي متعدد العمليات وبدون خادم. عندما يكتب الوكيل إلى قاعدة البيانات (حالة التطبيق أو الإعدادات أو بيانات المجال)، يزيد عداد الإصدار ويقوم العميل بإبطال ذاكرة التخزين المؤقت للاستعلام React ذات الصلة. +عندما يُغيِّر الوكيل البيانات، يحتاج UI إلى عكس ذلك دون تحديث يدوي. `useDbSync()` هو ما يجعل ذلك تلقائيًا. تتدفق الكتابات داخل نفس العملية عبر `/_agent-native/events`؛ ويبقى `/_agent-native/poll` هو الإجراء الاحتياطي عبر العمليات وبدون خادم. عندما يكتب الوكيل إلى قاعدة البيانات (حالة التطبيق، أو الإعدادات، أو بيانات المجال)، يزداد عداد الإصدار ويُبطل العميل ذواكر التخزين المؤقت لـ React Query ذات الصلة. ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -323,21 +366,25 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` +استدعِ هذا مرة واحدة، بالقرب من جذر التطبيق. فهو يشترك بالتطبيق بأكمله في أحداث التغيير، بحيث تُعيد أي مكوِّن يستخدم `useActionQuery` أو `useQuery` ذات إصدار مصدر جلب البيانات تلقائيًا عندما تتغير البيانات التي يقرؤها. + التدفق هو: -1. يقوم الوكيل بتشغيل إجراء يكتب إلى قاعدة البيانات +1. يُشغِّل الوكيل إجراءً يكتب إلى قاعدة البيانات 2. يُصدر الخادم حدث تغيير بمصدر مثل `"action"` أو `"settings"` -3. يتلقاها `useDbSync` عبر SSE أو الاستقصاء الاحتياطي -4. إعادة جلب الخطافات `useActionQuery` والخطافات `useQuery` ذات الإصدار المصدر +3. يتلقاه `useDbSync` عبر SSE أو الإجراء الاحتياطي بالاستقصاء +4. تُعيد خطافات `useActionQuery` وخطافات `useQuery` ذات إصدار مصدر الجلب 5. تعرض المكونات البيانات الجديدة دون إعادة تحميل الصفحة - +يتتبع المخطط نفس هذا التسلسل من البداية إلى النهاية: + + ```html
إجراء الوكيل
يكتب في قاعدة البياناتيكتب إلى قاعدة البيانات
@@ -349,12 +396,12 @@ useDbSync({ queryClient });
useDbSyncSSE · poll fallback + >SSE · الاستقصاء الاحتياطي
إعادة جلب الاستعلام
عرض دون إعادة تحميلعرض، بدون إعادة تحميل
@@ -382,88 +429,95 @@ useDbSync({ queryClient }); -يعمل هذا في جميع بيئات النشر - بما في ذلك بيئات النشر بدون خادم وبيئات Edge - لأنه يستخدم قاعدة البيانات، وليس مراقبي حالة الذاكرة أو نظام الملفات. +يعمل هذا في جميع بيئات النشر، بما في ذلك serverless وedge، لأنه يستخدم قاعدة البيانات بدلاً من الحالة داخل الذاكرة أو مراقبي نظام الملفات. ## الإطارات {#frames} -A _frame_ هي البيئة التي تستضيف الوكيل بجوار تطبيقك - محليًا هي اللوحة المضمنة؛ في السحابة، يوجد السطح المُدار لـ Builder.io. انظر [Frames](/docs/frames). +_الإطار (frame)_ هو البيئة التي تستضيف الوكيل بجانب تطبيقك. محليًا هو اللوحة المضمَّنة؛ وفي السحابة هو السطح المُدار من Builder.io. راجع [الإطارات](/docs/frames). -تتضمن تطبيقات الوكيل الأصلية لوحة وكيل مضمنة توفر وكيل الذكاء الاصطناعي إلى جانب التطبيق UI. وهذا ما يجعل البنية تعمل: يحتاج الوكيل إلى جهاز كمبيوتر (قاعدة بيانات، ومتصفح، وتنفيذ التعليمات البرمجية)، ويحتاج التطبيق إلى الوكيل لعمل الذكاء الاصطناعي. +تتضمن تطبيقات agent-native لوحة وكيل مضمَّنة توفر وكيل الذكاء الاصطناعي إلى جانب UI التطبيق. هذا ما يجعل البنية المعمارية تعمل: يحتاج الوكيل إلى كمبيوتر (قاعدة بيانات، ومتصفح، وتنفيذ كود)، ويحتاج التطبيق إلى الوكيل للقيام بعمل الذكاء الاصطناعي. -- **Embedded Agent Panel** — الدردشة ومحطة CLI الاختيارية المدمجة في كل تطبيق. يدعم كود Claude، وCodex، وGemini، وOpenCode، وBuilder.io. يعمل محليا. مجاني ومفتوح المصدر. -- **السحابة** — النشر على أي سحابة من خلال التعاون في الوقت الفعلي والتحرير المرئي والأدوار والأذونات. الأفضل للفرق. +- **لوحة الوكيل المضمَّنة:** دردشة وطرفية CLI اختيارية مدمجتان في كل تطبيق. تدعم Claude Code، وCodex، وGemini، وOpenCode، وBuilder.io. تعمل محليًا، مجانية ومفتوحة المصدر. +- **السحابة:** انشر على أي سحابة مع التعاون في الوقت الفعلي، والتحرير المرئي، والأدوار، والأذونات. الأنسب للفرق. ## الوعي بالسياق {#context-awareness} -يعرف الوكيل دائمًا ما يبحث عنه المستخدم. يكتب UI مفتاح `navigation` لحالة التطبيق عند كل تغيير للمسار. يقرأها الوكيل من خلال الإجراء `view-screen` قبل التصرف. +يعرف الوكيل دائمًا ما ينظر إليه المستخدم. يكتب UI مفتاح `navigation` إلى application-state عند كل تغيير للمسار. يقرأه الوكيل عبر إجراء `view-screen` قبل التصرف. -على سبيل المثال، عند فتح سلسلة رسائل بريد إلكتروني، يقوم UI بإدراج صف مثل: +على سبيل المثال، عند فتح سلسلة رسائل بريد إلكتروني، يُدرج UI أو يُحدِّث صفًا مثل: ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -يكتب UI هذا عند تغيير المسار؛ يقرأها الوكيل (عبر `view-screen`) قبل اتخاذ أي إجراء، حتى يعرف دائمًا أي موضوع - أو مخطط، أو شريحة - التي تركز عليها. + + +يكتب UI هذا عند تغيير المسار؛ ويقرأه الوكيل (عبر `view-screen`) قبل اتخاذ أي إجراء، بحيث يعرف دائمًا أي سلسلة رسائل، أو رسم بياني، أو شريحة تُركِّز عليها. + + -راجع [Context Awareness](/docs/context-awareness) للتعرف على النمط الكامل: حالة التنقل، وشاشة العرض، وأوامر التنقل، ومنع الاهتزاز. +راجع [الوعي بالسياق](/docs/context-awareness) للاطلاع على النمط الكامل: حالة التنقل، وview-screen، وأوامر navigate، ومنع الاهتزاز. ## إجراء واحد، وأسطح متعددة {#protocols} -تنفيذ عملية المجال مرة واحدة كإجراء؛ الإطار يعرضه لكل مستهلك. تصبح نفس `defineAction()` أداة وكيل، وخطاف UI آمن، ونقطة نهاية HTTP، وأمر CLI، وأداة MCP، وأداة A2A، مع إضافة `link` الاختيارية، أو `mcpApp`، أو بيانات تعريف عنصر واجهة المستخدم الأصلية الصريحة فقط عندما يحتاج السطح إليها. Skills والتعليمات تغطي السلوك. +نفِّذ عملية المجال مرة واحدة كإجراء؛ ويعرضها الإطار لكل مستهلك. يصبح نفس `defineAction()` أداة وكيل، وخطاف UI آمن الأنواع، ونقطة نهاية HTTP، وأمر CLI، وأداة MCP، وأداة A2A، مع إضافة بيانات وصفية اختيارية مثل `link`، أو `mcpApp`، أو عنصر واجهة أصلي، أو أغلفة Generative UI فقط عندما يحتاج سطح ما إلى تفاعل أغنى. تغطي المهارات والتعليمات السلوك. -للاطلاع على البروتوكول الكامل/المصفوفة السطحية (خادم MCP وOAuth وتطبيقات MCP وA2A والارتباطات العميقة وعناصر واجهة المستخدم للدردشة الأصلية وموصلات AgentChatRuntime وAgent Web وأفق المحول لـ ACP وA2UI)، ولاختيار شكل المنتج - بدون رأس أو دردشة غنية أو عربة جانبية مضمنة أو تطبيق كامل - راجع [Agent Surfaces](/docs/agent-surfaces). +للاطلاع على مصفوفة البروتوكولات/الأسطح الكاملة (خادم MCP وOAuth، وMCP Apps، وA2A، والروابط العميقة، وعناصر واجهة الدردشة الأصلية، وGenerative UI، وموصلات AgentChatRuntime، وAgent Web، وأفق المحوِّلات لـ ACP وA2UI)، ولاختيار شكل المنتج (دردشة، أو UI مضمَّن، أو صفحات تطبيق كاملة، أو sidecar مضمَّن، أو أتمتة، أو وصول وكيل خارجي)، راجع [أسطح الوكيل](/docs/agent-surfaces). ## كود التطبيق والتخصيص {#agent-modifies-code} -لا يقوم الوكيل المضمّن بتحرير الكود المصدري افتراضيًا. ولا يمكنه فعل ذلك إلا -عندما يمنحه المضيف عمدًا أدوات كتابة repository/workspace. في التطبيق المنشور -المعتاد، يعمل الوكيل من خلال actions والحالة المدعومة بـ SQL والتكاملات المكوّنة. -Templates هي تطبيقات كاملة يمكنك fork لها وتخصيصها في مستودعك ومسار التطوير -الخاصين بك. +لا يمنح الإطار الوكيلَ المضمَّن وصولًا محيطيًا (ambient) تلقائيًا إلى الكود المصدري للتطبيق. في التطبيق المنشور، +يعمل الوكيل عادةً من خلال الإجراءات، والحالة المدعومة بـ SQL، والتكاملات المهيَّأة. يمكنه تحرير المكوِّنات، والمسارات، +والأنماط، والإجراءات عندما يُمنح إطاره عمدًا وصولًا إلى مساحة العمل +وأدوات كتابة. Templates هي تطبيقات كاملة يمكنك عمل fork لها وتخصيصها في مستودعك +ومسار تطويرك الخاصين على أي حال. للتخصيص في وقت التشغيل +دون تغييرات في الكود المصدري، استخدم [Extensions](/docs/extensions). -## محمولة بشكل افتراضي {#hosting-agnostic} +## قابل للنقل افتراضيًا {#hosting-agnostic} -هناك قاعدتان معماريتان تحافظان على إمكانية نقل التطبيقات عبر قواعد البيانات والمضيفين: +تحافظ قاعدتان معماريتان على قابلية نقل التطبيقات عبر قواعد البيانات والمضيفين: -- **لا تعرف قاعدة البيانات.** اكتب المخططات باستخدام `@agent-native/core/db/schema` وقم بالقراءة/الكتابة باستخدام الاستعلام المحمول Drizzle DSL بحيث يتم تشغيل نفس الكود على أي موفر مدعوم. استخدم SQL الخام فقط لعمليات الترحيل الإضافية أو الصيانة لمرة واحدة، مع الاحتفاظ بمعلمات ومحايدة للهجة. انظر [Database](/docs/database). -- **لا تعتمد على الاستضافة.** يعمل الخادم على Nitro ويترجم إلى أي هدف نشر. لا تستخدم أبدًا APIs الخاصة بالعقدة (`fs`، `child_process`، `path`) في مسارات الخادم أو المكونات الإضافية، ولا تفترض أبدًا عملية خادم مستمرة - بدون خادم والحافة عديمة الحالة، لذا احتفظ بكل الحالة في SQL. انظر [Deployment](/docs/deployment). +- **لا تعتمد على قاعدة بيانات معيَّنة.** اكتب المخططات باستخدام `@agent-native/core/db/schema` والقراءة/الكتابة باستخدام لغة الاستعلام المحمولة لـ Drizzle، بحيث يعمل نفس الكود على أي مزوِّد مدعوم. استخدم SQL الخام فقط لعمليات الترحيل الإضافية أو الصيانة لمرة واحدة، مع إبقائه مُعامَلًا (parameterized) ومحايدًا للهجة. راجع [Database](/docs/database). +- **لا تعتمد على استضافة معيَّنة.** يعمل الخادم على Nitro ويُصرَّف إلى أي هدف نشر. لا تستخدم أبدًا واجهات برمجة خاصة بـ Node (`fs`، `child_process`، `path`) في مسارات الخادم أو الإضافات، ولا تفترض أبدًا وجود عملية خادم دائمة. serverless وedge عديما الحالة، لذا احتفظ بكل الحالة في SQL. راجع [النشر](/docs/deployment). -## مساحة العمل {#workspace} +## موارد الوكيل {#workspace} -يحصل كل مستخدم على **مساحة عمل** — تعليمات، وskills، وذاكرة، ووكلاء فرعيين مخصصين، ومهام مجدولة، وخوادم MCP متصلة — وكلها مخزنة في SQL بدلاً من الملفات. وهذا يجعل التخصيص على مستوى الكود Claude قابلاً للتطبيق داخل SaaS متعدد المستأجرين دون تدوير حاوية لكل مستخدم. انظر [موارد الوكيل](/docs/agent-resources). +يحصل كل مستخدم على مجموعة شخصية من **موارد الوكيل**: التعليمات، والمهارات، والذاكرة، والوكلاء الفرعيون المخصصون، والمهام المجدولة، وخوادم MCP المتصلة، وكلها مخزَّنة في SQL بدلًا من الملفات. هذا يجعل التخصيص على مستوى Claude Code قابلًا للتطبيق داخل SaaS متعدد المستأجرين دون تشغيل حاوية لكل مستخدم. راجع [موارد الوكيل](/docs/agent-resources). -## العناصر الأساسية ذات الصلة {#building-blocks} +## عناصر بناء ذات صلة {#building-blocks} -توجد هذه العناصر فوق نفس العقد ولها تفاصيل خاصة بها: +تقع هذه العناصر فوق نفس العقد ولها تفصيلاتها العميقة الخاصة: -- **[Dispatch](/docs/dispatch)** — مستوى التحكم في مساحة العمل: البريد الوارد المشترك، وخزينة الأسرار، والمهام المجدولة، والمنسق الذي يفوض التطبيقات المتخصصة عبر A2A. -- **[Extensions](/docs/extensions)** — تطبيقات Alpine.js المصغرة في وضع الحماية التي ينشئها الوكيل في وقت التشغيل، بدون تغييرات في المصدر أو عمليات ترحيل. -- **[برامج البيانات](/docs/data-programs)** — نصوص `run-code` مخزَّنة يكتبها الوكيل، تغذي لوحات dashboard بنتيجة مخزَّنة مؤقتًا وقابلة للتحديث بدلاً من action مبرمَجة مسبقًا لمزوّد معين. -- **[A2A Protocol](/docs/a2a-protocol)** — كيف تكتشف التطبيقات الموجودة في مساحة العمل نفسها وتتصل ببعضها البعض عبر JSON-RPC. +- **[Dispatch](/docs/dispatch):** مستوى التحكم في مساحة العمل، مع بريد وارد مشترك، وخزنة أسرار، ومهام مجدولة، ومنسِّق يفوِّض إلى تطبيقات متخصصة عبر A2A. +- **[Extensions](/docs/extensions):** تطبيقات Alpine.js مصغَّرة معزولة (sandboxed) ينشئها الوكيل في وقت التشغيل، دون تغييرات في الكود المصدري أو عمليات ترحيل. +- **[بروتوكول A2A](/docs/a2a-protocol):** كيف تكتشف التطبيقات في نفس مساحة العمل بعضها البعض وتستدعيه عبر JSON-RPC. -## ما تحصل عليه مجانًا {#what-you-get-for-free} +## الخطوات التالية {#deep-dives} -يعد اعتماد إطار العمل أمرًا ذا قيمة في الغالب بسبب ما لم تعد بحاجة إلى بنائه. في اللحظة التي يتبع فيها تطبيقك القواعد الخمس، ترث: + -- **إجراء واحد = كل سطح.** كل إجراء محدد باستخدام `defineAction()` هو في الوقت نفسه أداة وكيل, وخطاف أمامي آمن للكتابة (`useActionQuery` / `useActionMutation`)، ووسيلة نقل HTTP مملوكة لإطار العمل، وأمر CLI، وأداة MCP للعملاء الخارجيين، وأداة A2A لتطبيقات الوكيل الأصلية الأخرى. تضيف البيانات التعريفية الاختيارية `link` و`mcpApp` روابط عميقة وتطبيقات MCP UI بدون تنفيذ ثانٍ. -- **مساحة عمل كاملة لكل مستخدم.** Skills، `LEARNINGS.md` المشتركة، `memory/MEMORY.md` الشخصية، `AGENTS.md`، الوكلاء الفرعيون المخصصون، المهام المجدولة، خوادم MCP المتصلة - جميعها مدعومة بـ SQL، لا يلزم وجود صندوق تطوير. انظر [موارد الوكيل](/docs/agent-resources). -- **مكونات React التي يمكن إضافتها.** يعرض `` و`` الدردشة + مساحة العمل في أي مكان في تطبيقك. انظر [Drop-in Agent](/docs/drop-in-agent). -- ** أوقات تشغيل دردشة وكيل BYO.** يمكن أن توجد نفس الدردشة UI أعلى وكلاء OpenAI، أو ردود OpenAI، أو Claude Agent SDK، أو Vercel AI SDK، أو AG-UI، أو دفق HTTP الخاص بك. انظر [Native واجهة الدردشة](/docs/native-chat-ui#byo-agent-runtimes). -- **مزامنة مباشرة بين الوكيل وUI.** نفس العملية تكتب الدفق مباشرة عبر `/_agent-native/events`؛ يحافظ الاستقصاء خفيف الوزن على تقارب عمليات الكتابة بدون خادم، وكرون، والعمليات المشتركة. يؤدي تغيير actions إلى إبطال الاستعلامات المدعومة بالإجراء تلقائيًا، بحيث تظهر السجلات التي أنشأها الوكيل دون تحديث يدوي. انظر [Live Sync](#polling-sync) أدناه. -- **Auth, orgs, RBAC.** يتم توصيل مصادقة أفضل مع المؤسسات/الأعضاء/الأدوار لكل قالب. انظر [Authentication](/docs/authentication). -- **الوعي بالسياق.** يعرف الوكيل دائمًا ما يبحث عنه المستخدم من خلال مفتاح حالة التطبيق `navigation`. انظر [Context Awareness](/docs/context-awareness). -- **MCP العميل + الخادم، كلا الاتجاهين.** يستوعب التطبيق خوادم MCP (المحلية والبعيدة والمشتركة في المحور) _and_ ويكشف عن actions الخاص به كخادم MCP. راجع [MCP Clients](/docs/mcp-clients) و[MCP Protocol](/docs/mcp-protocol). -- **التفويض بين التطبيقات.** يتحدث الوكلاء في التطبيقات المختلفة عبر [A2A](/docs/a2a-protocol). عمليات النشر ذات الأصل نفسه تخطي JWT؛ يستخدم cross-origin `A2A_SECRET` مشتركًا. -- **فرق الوكلاء الفرعيين.** قم بإنشاء وكيل فرعي باستخدام سلسلة الرسائل والأدوات الخاصة به، والتي تظهر كشريحة مضمنة في الدردشة. انظر [Agent Teams](/docs/agent-teams). -- **قابلية النقل.** أي قاعدة بيانات SQL مدعومة من Drizzle، أو أي مضيف متوافق مع Nitro (Node، Workers، Netlify، Vercel، Deno، Lambda، Bun). +### [ما هو Agent-Native؟](/docs/what-is-agent-native) -هذا هو "وكل شيء آخر" الذي كنت ستلصقه معًا بنفسك. +الرؤية والفلسفة الكامنتان وراء هذه القواعد. -## الخطوات التالية {#deep-dives} +### [الوعي بالسياق](/docs/context-awareness) + +حالة التنقل، وview-screen، وأوامر navigate بالتفصيل. + +### [دليل المهارات](/docs/skills-guide) + +مهارات الإطار، ومهارات المجال، وإنشاء مهارات مخصصة. + +### [واجهة المحادثة الأصيلة](/docs/native-chat-ui) + +جداول ورسوم بيانية مُعلَنة من الإجراءات، ووضعية أوقات تشغيل BYO. + +### [أسطح الوكيل](/docs/agent-surfaces) + +الدردشة، وUI مضمَّن أصلي، وصفحات تطبيق كاملة، وsidecar مضمَّن، وأتمتة، ومسارات الوكيل الخارجي. + +### [بروتوكول A2A](/docs/a2a-protocol) + +التواصل من وكيل إلى وكيل. -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — الرؤية والفلسفة وراء هذه القواعد -- [**Context Awareness**](/docs/context-awareness) — حالة التنقل وأمرا view-screen وnavigate بالتفصيل -- [**Skills Guide**](/docs/skills-guide) — skills الإطار والمجال وإنشاء skills مخصصة -- [**Native Chat UI**](/docs/native-chat-ui) — جداول ومخططات معلنة بواسطة actions ودعم أوقات التشغيل التي توفرها بنفسك -- [**Agent Surfaces**](/docs/agent-surfaces) — الدردشة والواجهة الأصلية المضمنة وصفحات التطبيق الكاملة والواجهة الجانبية المضمنة والأتمتة ومسارات الوكلاء الخارجيين -- [**A2A Protocol**](/docs/a2a-protocol) — الاتصال من وكيل إلى وكيل + diff --git a/packages/core/docs/content/locales/de-DE/key-concepts.mdx b/packages/core/docs/content/locales/de-DE/key-concepts.mdx index 463029dee3..89fa99478d 100644 --- a/packages/core/docs/content/locales/de-DE/key-concepts.mdx +++ b/packages/core/docs/content/locales/de-DE/key-concepts.mdx @@ -1,31 +1,35 @@ --- -title: "Schlüsselkonzepte" -description: "So funktionieren agentennative Apps: actions zuerst, SQL-Datenbank, App-Agent-Schleife, optionales UI, Abfragesynchronisierung, Einstiegspunkte für externe Agenten, Kontextbewusstsein und Portabilität." +title: "Kernkonzepte" +description: "Wie agentennative Apps über drei Ebenen hinweg funktionieren: das Core-Framework, optionale Toolkit-Bausteine und optionale Templates, sowie die gemeinsamen Aktionen, die SQL-Datenbank, die App-Agent-Schleife und die Portabilitätsregeln." --- -# Schlüsselkonzepte +# Kernkonzepte -Wie agentennative Apps unter der Haube funktionieren – die Prinzipien und die Architektur. Diese Seite ist der Vertrag; Die Vision und die Argumente für den Aufbau auf diese Weise finden Sie unter [What Is Agent-Native?](/docs/what-is-agent-native). +Wie agentennative Apps im Detail funktionieren: die Prinzipien und die Architektur. Diese Seite ist der Vertrag: die festen Regeln, denen eine App folgen muss, um als agentennativ zu gelten. Für die Vision und die Begründung, warum man so baut, siehe [Was ist Agent-Native?](/docs/what-is-agent-native). ## Die drei Ebenen {#three-layers} -Agent Native ist ein Framework, keine einzelne Vorlage: +Agent Native ist ein Framework mit drei Ebenen: -- **Core - das Framework:** der grundlegende Laufzeit- und Datenvertrag für jede App. -- **Toolkit - optionale wiederverwendbare Bausteine:** gemeinsame UI- und Produktsysteme, die Apps übernehmen, kombinieren oder forken können. -- **Templates - optionale Apps:** vollständige, auf Core aufgebaute Domänen-Apps, die häufig Toolkit verwenden und als Ausgangspunkt geforkt und genutzt werden können. +| Ebene | Was es ist | +| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Core: das Framework** | Der grundlegende Laufzeitvertrag: Aktionen, SQL- und Drizzle-Hilfsfunktionen, Auth, Anwendungsstatus, Agentenausführung, Zugriffsprüfungen, Routing und Live-Synchronisierung. Jede App kann Core direkt verwenden. | +| **Toolkit: optionale wiederverwendbare Bausteine** | Gemeinsame UI- und Produktsysteme zum App-Bau, etwa Primitives, Editoren, Freigabe, Zusammenarbeit, Einstellungen und Agent-UX. Apps können die benötigten Bausteine verwenden, kombinieren oder forken. | +| **Templates: optionale Apps auf Core-Basis** | Vollständige, domänenspezifische Apps mit Routen, Schema, Aktionen, Anweisungen und visueller Identität. Erstanbieter- und benutzerdefinierte Templates verwenden häufig Toolkit und können geforkt und als Ausgangspunkt verwendet werden. | -Core ist die Grundlage. Toolkit und Templates sind optional. +Core ist die Grundlage. Toolkit und Templates sind optional: Ein Template kann Toolkit verwenden, aber Toolkit ist nicht erforderlich, um eine App auf Core aufzubauen. ## Die Architektur {#the-architecture} -Bei jeder agentennativen App arbeiten drei Dinge zusammen: +Zur Laufzeit ist jede agentennative App drei Dinge, die zusammenarbeiten: -- **Agent** – Autonome KI, die Daten liest, Daten schreibt, actions ausführt und konfigurierte Tools nutzt. Anpassbar mit skills und Anleitung. -- **Anwendung** – Die Produktoberfläche um den Agenten. Dabei kann es sich zunächst um einen reinen Aktionsmodus, einen umfassenden Chat, eine kleine Steuerungsebene oder um eine vollständige React-UI mit Dashboards, Abläufen und Visualisierungen handeln. -- **Computer** – Datenbank, Browser, Codeausführung. Agenten arbeiten über die Aktions- und Datenoberfläche der App; die App kann dieselbe Aktionsoberfläche über MCP bereitstellen. Externe MCP-Server sind optionale Add-ons und nicht die Grundlage. +- **Agent:** Die autonome KI. Sie liest Daten, schreibt Daten, führt Aktionen aus und verwendet alle konfigurierten Tools. Wenn ihrem Frame absichtlich Workspace-Zugriff und Schreib-Tooling gewährt wird, kann sie auch den eigenen Quellcode der App ändern. Anpassbar mit Skills und Anweisungen. +- **Anwendung:** Die Produktoberfläche rund um den Agenten. Sie kann als Chat beginnen, native Inline-Ergebnisse hinzufügen, zu einer kleinen Steuerzentrale heranwachsen oder zu einer vollständigen React-UI mit Dashboards, Abläufen und Visualisierungen werden. +- **Computer:** Die Datenbank, der Browser und die konfigurierten Tool-Laufzeiten, über die der Agent handelt. Agenten arbeiten über die eigene Aktions- und Datenoberfläche der App; dieselbe Oberfläche kann optional über MCP freigegeben werden, aber externe MCP-Server bleiben ein Add-on, nicht das Fundament. - +Das folgende Diagramm zeigt den Agenten und die Anwendung nebeneinander, beide mit Doppelpfeilen in eine gemeinsame Computer-Ebene darunter. Keiner von beiden besitzt die Daten. Stattdessen lesen und schreiben sie denselben SQL-Speicher, sodass eine Änderung von der einen Seite sofort für die andere sichtbar ist, ohne dass dazwischen eine Sync-Schicht gebaut werden muss. + + ```html
@@ -33,14 +37,15 @@ Bei jeder agentennativen App arbeiten drei Dinge zusammen:
Agentliest und schreibt Daten, führt Actions aus, nutzt konfigurierte + >liest + schreibt Daten, führt Aktionen aus, nutzt konfigurierte Tools
- ApplicationAnwendungaction-only, chat, control plane, or full React-UIChat, Inline-Ergebnisse, Steuerzentrale oder vollständige + React-UI
@@ -49,7 +54,7 @@ Bei jeder agentennativen App arbeiten drei Dinge zusammen:
Computer
SQL-Datenbank · browser · code executionSQL-Datenbank · Browser · Codeausführung
@@ -87,93 +92,114 @@ Bei jeder agentennativen App arbeiten drei Dinge zusammen: -Headless-Apps können mit `pnpm agent` dieselbe Produktions-App-Agent-Schleife aus dem Ordner ausführen, während UI-Apps das eingebettete Agent-Panel bereitstellen und lokal mit `pnpm dev` ausführen. In der Cloud bietet Builder.io einen verwalteten Rahmen – die Umgebung, die den Agenten neben Ihrer App hostet – mit Zusammenarbeit, visueller Bearbeitung und verwalteter Infrastruktur für Teams. +Dieselbe Agent-Anwendung-Computer-Schleife läuft lokal und in Produktion. Automation-first-Apps führen sie direkt aus dem Ordner mit `pnpm agent` aus; UI-Apps binden das eingebettete Agent-Panel ein und ergänzen `pnpm dev`. In der Cloud hostet Builder.io dieselbe Schleife als verwaltetes Frame: die Umgebung, die den Agenten neben Ihrer App ausführt. Sie übernimmt Zusammenarbeit, visuelles Bearbeiten und Infrastruktur für Sie. -## Agent-Bausteine {#agent-building-blocks} +## Bausteine des Agenten {#agent-building-blocks} -Jede agentennative App verfügt über die gleichen Agentenbausteine, unabhängig davon, ob -Die Produktoberfläche ist Headless, Chat-First oder eine vollständige UI: +Jede agentennative App hat dieselben Bausteine des Agenten, unabhängig davon, ob +die Produktoberfläche Chat-first, Automation-first oder eine vollständige UI ist. Jeder Baustein +lebt in seiner eigenen Datei: /SKILL.md", - note: "Wiederverwendbares Verhalten: Workflow-Schritte, Policies, Beispiele, Referenzen und Do/Don’t-Listen", + note: "wiederverwendbares Verhalten: Workflow-Schritte, Richtlinien, Beispiele, Referenzen und Do/Don't-Listen", }, { path: "actions/.ts", - note: "Ausführbare Fähigkeit: typisierte Operation für Agent, UI, CLI, HTTP, MCP, A2A, Jobs und Webhooks", + note: "ausführbare Fähigkeit: typisierte Operation, die dem Agenten, der UI, der CLI, HTTP, MCP, A2A, Jobs und Webhooks zur Verfügung steht", }, ]} /> -| Baustein | Verwenden Sie es für | Geladen, wenn | -| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | -| **Anleitung** | Stabile Anleitung, die der Agent bei jeder Aufgabe übernehmen sollte: was die App ist, Invarianten, Ton, Indizes | Jede Runde | -| **Skills** | Wiederverwendbares Verhalten: wie man einem Arbeitsablauf folgt, eine Richtlinie anwendet, Beweise prüft oder eine Ausgabe überprüft | Auf Anfrage, wenn die Fähigkeitsbeschreibung mit der Aufgabe übereinstimmt | -| **Actions** | Echte Operationen: Daten lesen oder schreiben, APIs aufrufen, Nachrichten senden, Genehmigungen ausführen, typisierte Ergebnisse erzeugen | Immer wieder als Werkzeuge aufgeführt; wird nur bei Aufruf ausgeführt | +Eine Runde ist ein Austausch mit dem Agenten: Er liest seinen Kontext, entscheidet, was zu tun ist, und antwortet. „Bei jeder Runde geladen" bedeutet, dass die Datei jedes Mal erneut in diesen Kontext gelangt, nicht nur einmal zu Sitzungsbeginn. + +| Baustein | Datei | Wofür | Geladen wann | +| --------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| **Anweisungen** | `AGENTS.md` | Stabile Anleitung, die der Agent in jede Aufgabe mitnehmen soll: was die App ist, Invarianten, Ton, Indizes | Jede Runde | +| **Skills** | `.agents/skills//SKILL.md` | Wiederverwendbares Verhalten: wie man einem Workflow folgt, eine Richtlinie anwendet, Belege prüft oder eine Ausgabe verifiziert | Bei Bedarf, wenn die Skill-Beschreibung zur Aufgabe passt | +| **Actions** | `actions/.ts` | Echte Operationen: Daten lesen oder schreiben, APIs aufrufen, Nachrichten senden, Genehmigungen durchführen, typisierte Ergebnisse erzeugen | Als Tools bei jeder Runde aufgelistet; ausgeführt nur bei Aufruf | -Skills und actions arbeiten zusammen. Eine Fertigkeit bringt dem Agenten bei, wie man eine Klasse von -Arbeit; Eine Aktion ist der Codepfad, den sie während der Ausführung dieser Arbeit aufrufen kann. Beispiel: -Ein `customer-research`-Skill kann dem Agenten mitteilen, welche Quellen überprüft werden sollen und -wie man Beweise zusammenfasst, während `search-crm` und `create-brief` actions abgerufen werden -und schreiben Sie die tatsächlichen Daten. +Skills und Actions arbeiten zusammen. Ein Skill bringt dem Agenten bei, wie er eine +Klasse von Arbeit erledigt; eine Aktion ist der Codepfad, den er dabei aufrufen kann. Ein +Skill `customer-research` könnte dem Agenten beispielsweise sagen, welche Quellen er prüfen +und wie er Belege zusammenfassen soll, während die Aktionen `search-crm` und `create-brief` +die eigentlichen Daten abrufen und schreiben. Fünf Regeln bestimmen die Architektur: -1. **Daten befinden sich in SQL** – der gesamte App-Status befindet sich in der Datenbank über Drizzle ORM -2. **Die gesamte KI läuft über den Agent** – keine Inline-LLM-Aufrufe -3. **Actions für Agentenoperationen** – komplexe Arbeiten werden als actions ausgeführt -4. **Live-Synchronisierung hält UI synchron** – Datenbankänderungen werden über SSE gestreamt, wobei Polling als universeller Fallback dient -5. **Anwendungsstatus liegt in SQL** – flüchtiger UI-Status lebt in der Datenbank und ist für Agent und UI lesbar +1. **Daten leben in SQL:** Der gesamte App-Zustand lebt in der Datenbank via Drizzle ORM. +2. **Alle KI läuft über den Agenten:** keine Inline-LLM-Aufrufe; jede KI-Interaktion läuft über die Agent-Chat-Bridge. +3. **Aktionen für Agentenoperationen:** komplexe Arbeit läuft als typisierte Aktion, nicht als Inline-Code. +4. **Live Sync hält die UI synchron:** Datenbankänderungen werden über SSE gestreamt, mit Polling als universellem Fallback. +5. **Anwendungsstatus in SQL:** flüchtiger UI-Zustand lebt in der Datenbank, lesbar sowohl von Agent als auch UI. ## Die Vier-Bereiche-Checkliste {#four-area-checklist} -Jede benutzerseitige Funktion sollte alle anwendbaren Bereiche aktualisieren. Durch das Überspringen eines anwendbaren Bereichs wird der Agent-native-Vertrag gebrochen. Einen UI auf ein Nur-Aktion-Grundelement zu zwingen, ist ebenfalls ein Geruch. +Jedes benutzerseitige Feature sollte alle zutreffenden Bereiche aktualisieren. Einen zutreffenden Bereich auszulassen bricht den agentennativen Vertrag; einer Automatisierung, die kein Mensch durchsuchen muss, einen Bildschirm aufzuzwingen, ist ebenfalls ein Smell. + +- **1. UI:** Seite, Komponente oder Dialog, mit der/dem der Benutzer interagiert. +- **2. Aktion:** Agentenaufrufbare Aktion in `actions/` für denselben Vorgang. +- **3. Skills:** `AGENTS.md` aktualisieren und/oder einen Skill erstellen, der das Muster dokumentiert. +- **4. App-State:** Navigationsstatus, view-screen-Daten und navigate-Befehle. + +Ein Feature mit nur UI ist für den Agenten unsichtbar. Ein vollständiges UI-Feature mit nur Aktionen ist für den Benutzer unsichtbar. Ein Feature ohne App-State bedeutet, dass der Agent nicht sieht, was der Benutzer tut. Ein Automation-first-Vorgang kann legitim mit Aktion + Anweisungen beginnen und später Chat, UI oder App-State hinzufügen, wenn Menschen ihn durchsuchen, genehmigen, konfigurieren oder teilen müssen. -| Bereich | Beschreibung | -| ----------------- | ----------------------------------------------------------------------------------- | -| **1. UI** | Seite, Komponente oder Dialog, mit dem der Benutzer interagiert | -| **2. Aktion** | Von einem Agenten aufrufbare Aktion in actions/ für denselben Vorgang | -| **3. Skills** | AGENTS.md aktualisieren und/oder einen Skill erstellen, der das Muster dokumentiert | -| **4. App-Status** | Navigationsstatus, Bildschirmdaten und Navigationsbefehle | +## Was Agent Native enthält {#what-you-get-for-free} -Eine Funktion mit nur UI ist für den Agenten unsichtbar. Eine vollständige UI-Funktion mit nur actions ist für den Benutzer unsichtbar. Eine Funktion ohne App-Status bedeutet, dass der Agent nicht wahrnimmt, was der Benutzer tut. Ein Headless-Vorgang kann legitimerweise mit Aktion + Anweisungen beginnen und UI/app-state später hinzufügen, wenn Menschen ihn durchsuchen, genehmigen, konfigurieren oder teilen müssen. +Das Framework zu übernehmen ist vor allem deshalb wertvoll, weil man dadurch vieles nicht mehr selbst bauen muss. Sobald Ihre App den fünf obigen Regeln folgt, erben Sie: + +| Feature | Was es Ihnen gibt | +| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Eine Aktion = jede Oberfläche | Jede mit `defineAction()` definierte Aktion ist gleichzeitig ein Agenten-Tool, ein typsicherer Frontend-Hook (`useActionQuery` / `useActionMutation`), ein Framework-eigener HTTP-Transport, ein CLI-Befehl, ein MCP-Tool für externe Clients und ein A2A-Tool für andere agentennative Apps. Optionale `link`- und `mcpApp`-Metadaten fügen Deep Links und MCP-Apps-UI hinzu, ohne eine zweite Implementierung. | +| Vollständige Agent-Ressourcen pro Benutzer | Skills, gemeinsame `LEARNINGS.md`, persönliche `memory/MEMORY.md`, `AGENTS.md`, benutzerdefinierte Sub-Agenten, geplante Jobs und verbundene MCP-Server. Alles SQL-basiert, keine Dev-Box erforderlich. Siehe [Agent Resources](/docs/agent-resources). | +| Drop-in React-Komponenten | `` und `` rendern Chat + Ressourcen überall in Ihrer App. Siehe [Drop-in Agent](/docs/drop-in-agent). | +| BYO Agent-Chat-Runtimes | Dieselbe Chat-UI kann auf OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI oder Ihrem eigenen normalisierten HTTP-Stream aufsetzen. Siehe [Nativer Chat-Oberfläche](/docs/native-chat-ui#byo-agent-runtimes). | +| Live Sync zwischen Agent und UI | Schreibvorgänge im selben Prozess werden sofort über `/_agent-native/events` gestreamt; ein leichtgewichtiges Polling hält serverlose, Cron- und prozessübergreifende Schreibvorgänge konvergent. Mutierende Aktionen invalidieren aktionsbasierte Queries automatisch, sodass vom Agenten erstellte Datensätze ohne manuelles Neuladen erscheinen. Siehe [Live Sync](#polling-sync) weiter unten. | +| Auth, Orgs, RBAC | Better Auth mit Orgs/Mitgliedern/Rollen ist in jedes Template fest verdrahtet. Siehe [Authentication](/docs/authentication). Für mehr als einen Benutzer beginnen Sie mit [Organizations, Teams & Permissions](/docs/organizations-teams-permissions). | +| Kontextbewusstsein | Der Agent weiß über den App-State-Key `navigation` immer, was der Benutzer gerade betrachtet. Siehe [Kontextbewusstsein](/docs/context-awareness). | +| MCP-Client + -Server, beide Richtungen | Die App nimmt MCP-Server auf (lokal, remote, Hub-geteilt) _und_ stellt ihre eigenen Aktionen als MCP-Server bereit. Siehe [MCP Clients](/docs/mcp-clients) und [MCP Protocol](/docs/mcp-protocol). | +| App-übergreifende Delegation | Agenten in unterschiedlichen Apps kommunizieren über [A2A](/docs/a2a-protocol). Same-Origin-Deployments überspringen JWT; Cross-Origin verwendet ein gemeinsames `A2A_SECRET`. | +| Sub-Agent-Teams | Erzeugen Sie einen Sub-Agenten mit eigenem Thread und eigenen Tools, dargestellt als Chip inline im Chat. Siehe [Agent Teams](/docs/agent-teams). | +| Portabilität | Jede von Drizzle unterstützte SQL-Datenbank, jeder Nitro-kompatible Host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). | ## Daten in SQL {#data-in-sql} -Der gesamte Anwendungsstatus befindet sich in einer SQL-Datenbank über Drizzle ORM. Schemata sind anbieterunabhängig; Die unterstützten Datenbanken, die `DATABASE_URL`-Konfiguration und die Portabilitätsregeln sind live in [Database](/docs/database). +Der gesamte Anwendungsstatus lebt in einer SQL-Datenbank via Drizzle ORM. Schemas sind anbieteragnostisch; die unterstützten Datenbanken, die `DATABASE_URL`-Konfiguration und die Portabilitätsregeln finden Sie unter [Database](/docs/database). + +Core-SQL-Stores werden automatisch erstellt und sind in jedem Template verfügbar: -Kern-SQL-Stores werden automatisch erstellt und sind in jeder Vorlage verfügbar: +- `application_state`: flüchtiger UI-Zustand (Navigation, Entwürfe, Auswahlen) +- `settings`: persistente Key-Value-Konfiguration +- `oauth_tokens`: OAuth-Anmeldedaten +- `sessions`: Auth-Sitzungen -- `application_state` – kurzlebiger UI-Status (Navigation, Entwürfe, Auswahl) -- `settings` – persistente Schlüsselwertkonfiguration -- `oauth_tokens` – OAuth-Anmeldeinformationen -- `sessions` – Authentifizierungssitzungen +Jede Zeile unten lässt sich aufklappen, um ihre Felder anzuzeigen: +Um eigene Domänendaten hinzuzufügen, definieren Sie eine Tabelle mit denselben Schema-Hilfsfunktionen, die auch die Core-Stores oben verwenden: + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -246,28 +274,30 @@ export const forms = table("forms", { }); ``` +Sowohl Sie als auch der Agent können diese Daten vom Terminal aus untersuchen, ohne einen separaten SQL-Client: + ```bash -# Kernaktionen für eine schnelle Datenbankinspektion +# Core-Actions für die schnelle Datenbankprüfung pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -Das Produktions-Agent-Chat-Plugin setzt rohe SQL-Werkzeuge standardmäßig auf read-only -(`frameworkTools: { database: "read" }`). Agenten prüfen App-Daten mit `db-schema` / -`db-query` und schreiben über typisierte App-Actions. Setze -`database: "write"` (oder `true`) nur für bewusste Wartungsflächen, die -auch scoped `db-exec` / `db-patch` anbieten sollen; `database: "off"` / -`false` erfordert typisierte App-Actions für alle Daten -Zugriff. +`db-schema` gibt die Spalten und Typen jeder Tabelle aus. `db-query` führt schreibgeschütztes SQL direkt aus, was nützlich ist, um die Schreibvorgänge einer Aktion zu überprüfen, ohne einen Datenbank-Client zu öffnen. + + + +Das Produktions-Agent-Chat-Plugin setzt rohe SQL-Werkzeuge standardmäßig auf read-only (`frameworkTools: { database: "read" }`). Agenten prüfen App-Daten mit `db-schema` / `db-query` und schreiben über typisierte App-Actions. Setze `database: "write"` (oder `true`) nur für bewusste Wartungsflächen, die auch scoped `db-exec` / `db-patch` anbieten sollen; setze `database: "off"` / `false`, um für jeden Datenzugriff typisierte App-Actions zu verlangen. `frameworkTools` steuert die übrigen framework-eigenen Tools genauso: Sharing, Review-Kommentare, Versionshistorie, Feature-Flags, Lokalisierung, Audit, Context X-Ray, Profil, Automatisierungen, Docs, Resources, Web, App-übergreifende Delegation, Chat und E-Mail. Siehe [Production Agent Tools](/docs/deployment#production-agent-tools) für die vollständige Liste, das `"minimal"`-Preset und warum eine abgeschaltete Gruppe ihre HTTP-Routen behält. + + ## Agent-Chat-Brücke {#agent-chat-bridge} -Der UI ruft niemals einen LLM direkt auf. Wenn ein Benutzer auf „Diagramm erstellen“ oder „Zusammenfassung schreiben“ klickt, sendet der UI über `postMessage` eine Nachricht an den Agenten. Der Agent übernimmt die Arbeit – mit vollständigem Gesprächsverlauf, skills, Anweisungen und der Möglichkeit zur Iteration. +Die UI ruft niemals direkt ein LLM auf. Wenn ein Benutzer auf „Diagramm erstellen" oder „Zusammenfassung schreiben" klickt, sendet die UI über `postMessage` eine Nachricht an den Agenten. Der Agent erledigt die Arbeit. Er hat den vollständigen Gesprächsverlauf, Skills, Anweisungen und die Fähigkeit zu iterieren. ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -276,16 +306,19 @@ sendToAgentChat({ }); ``` -Warum nicht einen LLM inline aufrufen? +Kurz gesagt: + +- **KI ist nicht deterministisch**: Sie brauchen einen Gesprächsverlauf, um Feedback zu geben und zu iterieren, nicht Einweg-Buttons. +- **Kontext ist wichtig**: Der Agent hat die Anweisungen, Skills und den Verlauf der App. Ein Inline-Aufruf hat nichts davon. +- **Der Agent kann mehr**: Er kann Aktionen ausführen, im Web browsen und mehrere Schritte miteinander verketten. -- **KI ist nicht deterministisch.** Sie benötigen einen Gesprächsfluss, um Feedback zu geben und zu iterieren – keine One-Shot-Schaltflächen. -- **Der Kontext ist wichtig.** Der Agent verfügt über Ihre vollständige Codebasis, Anweisungen, skills und den Verlauf. Ein Inline-Anruf hat nichts davon. -- **Der Agent kann mehr.** Er kann actions ausführen, im Internet surfen, Code ändern und mehrere Schritte miteinander verketten. -- **Headless-Ausführung.** Da alles über den Agenten läuft, kann jede App vollständig von Slack, Telegram oder einem anderen Agenten über [A2A](/docs/a2a-protocol) gesteuert werden. +**[External execution](/docs/a2a-protocol)** + +Da alles über den Agenten und Aktionen läuft, kann jede App von Slack, Telegram, geplanten Jobs, Skripten oder einem anderen Agenten über A2A gesteuert werden. ## Actions-System {#actions-system} -Wenn der Agent etwas Komplexes tun muss – einen API aufrufen, Daten verarbeiten, die Datenbank abfragen – führt er eine **Aktion** aus. Actions sind TypeScript-Dateien in `actions/`, die ein Standard-`defineAction()` exportieren: +Wenn der Agent etwas Komplexes tun muss, etwa eine API aufrufen, Daten verarbeiten oder die Datenbank abfragen, führt er eine **Aktion** aus. Aktionen sind TypeScript-Dateien in `actions/`, die standardmäßig ein `defineAction()` exportieren: ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -303,19 +336,30 @@ export default defineAction({ }); ``` -Ein `defineAction()`-Aufruf ergibt Folgendes: +Diese Aktion holt JSON von einer Quell-API ab und gibt es zurück. `defineAction()` umschließt die Funktion mit einem Zod-Schema für ihre Eingabe (`source`), sodass das Framework diese Eingabe validieren, ein JSON Schema erzeugen kann, das der Agent aufrufen kann, und Typen für den Frontend-Hook ableiten kann – alles aus dieser einen Definition. + +Ein einzelner `defineAction()`-Aufruf erreicht automatisch fünf verschiedene Verbraucher. Das Diagramm zeigt die Verteilung von einer einzelnen Aktion aus; die Liste darunter erklärt, was jeder Verbraucher erhält: -- **Agent-Tool** – der Agent sieht es mit dem von Zod abgeleiteten JSON-Schema und kann es aufrufen. -- **Frontend-Hook** – `useActionMutation("fetch-data")` mit vollständiger TypeScript-Inferenz. -- **Framework-Transport** – automatisch hinter den Client-Hooks gemountet. -- **CLI** – `pnpm action fetch-data --source=signups` für Skripterstellung und Agent-Entwicklungsschleifen. -- **MCP-Tool / A2A-Tool** – wenn der MCP-Server oder A2A aktiviert ist, wird die gleiche Aktion auch dort angezeigt. +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -Gleiche Logik, eine Definition, automatisch mit jedem Verbraucher verbunden. Die vollständige Referenz finden Sie unter [Actions](/docs/actions). +- **Agenten-Tool:** Der Agent sieht sie mit dem von Zod abgeleiteten JSON Schema und kann sie aufrufen. +- **Frontend-Hook:** `useActionMutation("fetch-data")` mit vollständiger TypeScript-Inferenz. +- **Framework-Transport:** automatisch hinter den Client-Hooks eingebunden. +- **CLI:** `pnpm action fetch-data --source=signups` für Skripterstellung und Agent-Dev-Schleifen. +- **MCP-Tool / A2A-Tool:** Wenn MCP-Server oder A2A aktiviert ist, taucht dieselbe Aktion auch dort auf. -## Live-Synchronisierung {#polling-sync} +Jeder Verbraucher ruft dieselbe zugrunde liegende Funktion auf, sodass es nur eine Implementierung zu schreiben und zu warten gibt. Die vollständige Referenz finden Sie unter [Actions](/docs/actions). -Datenbankänderungen werden über `useDbSync()` mit dem UI synchronisiert. Gleicher Prozess schreibt Stream über `/_agent-native/events`; `/_agent-native/poll` bleibt der prozessübergreifende und serverlose Fallback. Wenn der Agent in die Datenbank schreibt (Anwendungsstatus, Einstellungen oder Domänendaten), erhöht sich ein Versionszähler und der Client macht die relevanten React-Abfragecaches ungültig. +## Live Sync {#polling-sync} + +Wenn der Agent Daten ändert, muss die UI das ohne manuelles Neuladen widerspiegeln. `useDbSync()` macht das automatisch. Schreibvorgänge im selben Prozess werden über `/_agent-native/events` gestreamt; `/_agent-native/poll` bleibt der prozessübergreifende und serverlose Fallback. Wenn der Agent in die Datenbank schreibt (Anwendungsstatus, Einstellungen oder Domänendaten), erhöht sich ein Versionszähler und der Client invalidiert die relevanten React-Query-Caches. ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -323,36 +367,40 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` +Rufen Sie dies einmal auf, nahe der Wurzel der App. Dadurch abonniert die gesamte App Änderungsereignisse, sodass jede Komponente, die `useActionQuery` oder ein quellversioniertes `useQuery` verwendet, automatisch neu abruft, wenn sich die gelesenen Daten ändern. + Der Ablauf ist: -1. Agent führt eine Aktion aus, die in die Datenbank schreibt -2. Der Server gibt ein Änderungsereignis mit einer Quelle wie `"action"` oder `"settings"` aus +1. Der Agent führt eine Aktion aus, die in die Datenbank schreibt +2. Der Server sendet ein Änderungsereignis mit einer Quelle wie `"action"` oder `"settings"` 3. `useDbSync` empfängt es über SSE oder den Polling-Fallback -4. `useActionQuery`-Hooks und quellversionierte `useQuery`-Hooks werden erneut abgerufen -5. Komponenten rendern die neuen Daten, ohne dass die Seite neu geladen werden muss +4. `useActionQuery`-Hooks und quellversionierte `useQuery`-Hooks rufen erneut ab +5. Komponenten rendern die neuen Daten ohne Neuladen der Seite - +Das Diagramm zeichnet genau diese Abfolge von Anfang bis Ende nach: + + ```html
- Agentenaktion
schreibt in die DB + Agent-Aktion
schreibt in DB
Änderungsereignis
source: action / settingsQuelle: action / settings
useDbSyncSSE · poll fallback + >SSE · Poll-Fallback
- Query erneut laden
rendern, kein NeuladenRender, kein Neuladen
@@ -380,89 +428,96 @@ Der Ablauf ist: -Dies funktioniert in allen Bereitstellungsumgebungen – einschließlich serverloser und Edge-Umgebungen –, da die Datenbank und nicht In-Memory-Status- oder Dateisystem-Watcher verwendet werden. +Das funktioniert in allen Deployment-Umgebungen, einschließlich serverlos und Edge, weil die Datenbank verwendet wird statt In-Memory-Zustand oder Dateisystem-Watcher. ## Frames {#frames} -Ein _Frame_ ist die Umgebung, die den Agenten neben Ihrer App hostet – lokal ist das das eingebettete Panel; In der Cloud ist es die verwaltete Oberfläche von Builder.io. Siehe [Frames](/docs/frames). +Ein _Frame_ ist die Umgebung, die den Agenten neben Ihrer App hostet. Lokal ist das embedded Panel; in der Cloud ist es die verwaltete Oberfläche von Builder.io. Siehe [Frames](/docs/frames). -Agent-native Apps umfassen ein eingebettetes Agent-Panel, das den KI-Agenten neben der App UI bereitstellt. Dadurch funktioniert die Architektur: Der Agent benötigt einen Computer (Datenbank, Browser, Codeausführung) und die App benötigt den Agenten für die KI-Arbeit. +Agentennative Apps enthalten ein eingebettetes Agent-Panel, das den KI-Agenten neben der App-UI bereitstellt. Das ist es, was die Architektur funktionieren lässt: Der Agent braucht einen Computer (Datenbank, Browser, Codeausführung), und die App braucht den Agenten für KI-Arbeit. -- **Embedded Agent Panel** – Chat und optionales CLI-Terminal in jede App integriert. Unterstützt Claude-Code, Codex, Gemini, OpenCode und Builder.io. Läuft lokal. Kostenlos und Open Source. -- **Cloud** – Bereitstellung in jeder Cloud mit Echtzeit-Zusammenarbeit, visueller Bearbeitung, Rollen und Berechtigungen. Am besten für Teams. +- **Embedded Agent Panel:** Chat und optionales CLI-Terminal, in jede App eingebaut. Unterstützt Claude Code, Codex, Gemini, OpenCode und Builder.io. Läuft lokal, kostenlos und Open Source. +- **Cloud:** In jeder Cloud bereitstellen, mit Echtzeit-Zusammenarbeit, visuellem Bearbeiten, Rollen und Berechtigungen. Am besten für Teams. ## Kontextbewusstsein {#context-awareness} -Der Agent weiß immer, was der Benutzer sieht. Der UI schreibt bei jeder Routenänderung einen `navigation`-Schlüssel in den Anwendungsstatus. Der Agent liest es über die Aktion `view-screen`, bevor er handelt. +Der Agent weiß immer, was der Benutzer gerade betrachtet. Die UI schreibt bei jeder Routenänderung einen `navigation`-Key in den Anwendungsstatus. Der Agent liest ihn über die Aktion `view-screen`, bevor er handelt. -Wenn Sie beispielsweise einen E-Mail-Thread öffnen, fügt UI eine Zeile ein wie: +Wenn Sie beispielsweise einen E-Mail-Thread öffnen, fügt die UI eine Zeile wie diese ein oder aktualisiert sie: ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -Der UI schreibt dies bei Routenänderung; Der Agent liest es (über `view-screen`), bevor er eine Aktion ausführt, sodass er immer weiß, auf welchen Thread – oder welches Diagramm oder welche Folie – Sie sich konzentrieren. + + +Die UI schreibt dies bei jeder Routenänderung; der Agent liest es (über `view-screen`), bevor er irgendeine Aktion durchführt, sodass er immer weiß, auf welchen Thread, welches Diagramm oder welche Folie Sie gerade fokussiert sind. -Das vollständige Muster finden Sie unter [Context Awareness](/docs/context-awareness): Navigationsstatus, Anzeigebildschirm, Navigationsbefehle und Jitter-Verhinderung. + + +Das vollständige Muster – Navigationsstatus, view-screen, navigate-Befehle und Jitter-Vermeidung – finden Sie unter [Kontextbewusstsein](/docs/context-awareness). ## Eine Aktion, viele Oberflächen {#protocols} -Implementieren Sie einen Domänenvorgang einmal als Aktion. Das Framework macht es jedem Verbraucher zugänglich. Derselbe `defineAction()` wird zu einem Agententool, einem typsicheren UI-Hook, einem HTTP-Endpunkt, einem CLI-Befehl, einem MCP-Tool und einem A2A-Tool, wobei optionale `link`-, `mcpApp`- oder explizite native Widget-Metadaten nur dann hinzugefügt werden, wenn eine Oberfläche sie benötigt. Skills und Anweisungen decken das Verhalten ab. +Implementieren Sie einen Domänenvorgang einmal als Aktion; das Framework stellt ihn jedem Verbraucher zur Verfügung. Dasselbe `defineAction()` wird zu einem Agenten-Tool, einem typsicheren UI-Hook, einem HTTP-Endpunkt, einem CLI-Befehl, einem MCP-Tool und einem A2A-Tool, mit optionalen `link`-, `mcpApp`-, Native-Widget-Metadaten oder Generative-UI-Wrappern, die nur hinzugefügt werden, wenn eine Oberfläche reichhaltigere Interaktion benötigt. Skills und Anweisungen decken das Verhalten ab. -Die vollständige Protokoll-/Oberflächenmatrix (MCP-Server und OAuth, MCP-Apps, A2A, Deep Links, native Chat-Widgets, AgentChatRuntime-Konnektoren, Agent Web und der Adapterhorizont für ACP und A2UI) sowie Informationen zur Auswahl einer Produktform – Headless, Rich Chat, eingebetteter Sidecar oder vollständige App – finden Sie unter [Agent Surfaces](/docs/agent-surfaces). +Die vollständige Protokoll-/Oberflächen-Matrix (MCP-Server und OAuth, MCP Apps, A2A, Deep Links, native Chat-Widgets, Generative UI, AgentChatRuntime-Connectoren, Agent Web und der Adapter-Horizont für ACP und A2UI) sowie die Wahl einer Produktform (Chat, Inline-UI, vollständige App-Seiten, eingebetteter Sidecar, Automatisierung oder Zugriff durch externe Agenten) finden Sie unter [Agent-Oberflächen](/docs/agent-surfaces). ## App-Code und Anpassung {#agent-modifies-code} -Der eingebettete Agent bearbeitet Quellcode nicht standardmäßig. Das ist nur -möglich, wenn der Host ihm bewusst Repository-/Workspace-Schreibwerkzeuge -bereitstellt. In einer gewöhnlichen bereitgestellten App arbeitet der Agent -über Actions, SQL-gestützten Zustand und konfigurierte Integrationen. Templates -sind vollständige Apps, die Sie in Ihrem eigenen Repository und -Entwicklungsablauf forken und anpassen können. +Das Framework gewährt dem eingebetteten Agenten keinen impliziten Zugriff auf den Quellcode +einer App. In einer bereitgestellten App arbeitet der Agent normalerweise über Aktionen, +SQL-basierten Zustand und konfigurierte Integrationen. Er kann Komponenten, Routen, +Styles und Aktionen bearbeiten, wenn seinem Frame absichtlich Workspace- und Schreib-Tooling +gewährt wird. Templates sind vollständige Apps, die Sie in Ihrem eigenen Repository und +Entwicklungsworkflow forken und anpassen können, so oder so. Für Laufzeitanpassung +ohne Quellcodeänderungen verwenden Sie [Extensions](/docs/extensions). ## Standardmäßig portabel {#hosting-agnostic} -Zwei Architekturregeln sorgen dafür, dass Apps über Datenbanken und Hosts hinweg portierbar sind: +Zwei architektonische Regeln halten Apps über Datenbanken und Hosts hinweg portabel: -- **Datenbankunabhängig.** Schreiben Sie Schemata mit `@agent-native/core/db/schema` und lesen/schreiben Sie mit der tragbaren Abfrage DSL von Drizzle, sodass derselbe Code auf jedem unterstützten Anbieter ausgeführt wird. Verwenden Sie rohes SQL nur für additive Migrationen oder einmalige Wartungsarbeiten, parametrisiert und dialektunabhängig. Siehe [Database](/docs/database). -- **Hosting-agnostisch.** Der Server läuft auf Nitro und kompiliert zu jedem Bereitstellungsziel. Verwenden Sie niemals knotenspezifische APIs (`fs`, `child_process`, `path`) in Serverrouten oder Plugins und gehen Sie niemals von einem dauerhaften Serverprozess aus – serverlos und Edge sind zustandslos, also behalten Sie alle Zustände in SQL bei. Siehe [Deployment](/docs/deployment). +- **Datenbankagnostisch.** Schreiben Sie Schemas mit `@agent-native/core/db/schema` und Lese-/Schreibvorgänge mit Drizzles portabler Query-DSL, sodass derselbe Code auf jedem unterstützten Anbieter läuft. Verwenden Sie rohes SQL nur für additive Migrationen oder einmalige Wartung, parametrisiert und dialektagnostisch gehalten. Siehe [Database](/docs/database). +- **Hosting-agnostisch.** Der Server läuft auf Nitro und kompiliert zu jedem Deployment-Ziel. Verwenden Sie in Server-Routen oder -Plugins niemals Node-spezifische APIs (`fs`, `child_process`, `path`), und gehen Sie niemals von einem dauerhaften Serverprozess aus. Serverless und Edge sind zustandslos, also halten Sie den gesamten Zustand in SQL. Siehe [Deployment](/docs/deployment). -## Arbeitsbereich {#workspace} +## Agent Resources {#workspace} -Jeder Benutzer erhält einen persönlichen **Arbeitsbereich** – Anweisungen, skills, Speicher, benutzerdefinierte Subagenten, geplante Jobs und verbundene MCP-Server – alles gespeichert in SQL und nicht in Dateien. Dadurch ist eine Anpassung auf Claude-Code-Ebene in SaaS mit mehreren Mandanten realisierbar, ohne dass pro Benutzer ein Container erstellt werden muss. Siehe [Agent-Ressourcen](/docs/agent-resources). +Jeder Benutzer erhält ein persönliches Set an **Agent Resources**: Anweisungen, Skills, Memory, benutzerdefinierte Sub-Agenten, geplante Jobs und verbundene MCP-Server, alle in SQL statt in Dateien gespeichert. Das macht Anpassung auf Claude-Code-Niveau innerhalb von Multi-Tenant-SaaS möglich, ohne pro Benutzer einen Container hochzufahren. Siehe [Agent Resources](/docs/agent-resources). ## Verwandte Bausteine {#building-blocks} -Diese basieren auf demselben Vertrag und haben ihre eigenen Tiefgänge: +Diese bauen auf demselben Vertrag auf und haben eigene Deep Dives: + +- **[Dispatch](/docs/dispatch):** die Workspace-Steuerzentrale, mit gemeinsamem Posteingang, Secrets Vault, geplanten Jobs und einem Orchestrator, der über A2A an spezialisierte Apps delegiert. +- **[Extensions](/docs/extensions):** sandboxed Alpine.js-Mini-Apps, die der Agent zur Laufzeit erstellt, ohne Quellcodeänderungen oder Migrationen. +- **[A2A-Protokoll](/docs/a2a-protocol):** wie Apps im selben Workspace einander über JSON-RPC entdecken und aufrufen. + +## Was kommt als nächstes {#deep-dives} + + + +### [Was ist Agent-Native?](/docs/what-is-agent-native) + +Die Vision und Philosophie hinter diesen Regeln. + +### [Kontextbewusstsein](/docs/context-awareness) + +Navigationsstatus, view-screen und navigate-Befehle im Detail. + +### [Skills-Anleitung](/docs/skills-guide) + +Framework-Skills, Domain-Skills und das Erstellen eigener Skills. -- **[Dispatch](/docs/dispatch)** – die Steuerungsebene des Arbeitsbereichs: gemeinsamer Posteingang, Geheimspeicher, geplante Jobs und ein Orchestrator, der über A2A an spezielle Apps delegiert. -- **[Extensions](/docs/extensions)** – Sandbox-Alpine.js-Mini-Apps, die der Agent zur Laufzeit erstellt, keine Quelländerungen oder Migrationen. -- **[Datenprogramme](/docs/data-programs)** – gespeicherte, vom Agenten verfasste `run-code`-Skripte, die Dashboard-Panels ein zwischengespeichertes, aktualisierbares Ergebnis liefern statt einer fest codierten Provider-action. -- **[A2A Protocol](/docs/a2a-protocol)** – wie Apps im selben Arbeitsbereich einander über JSON-RPC erkennen und aufrufen. +### [Nativer Chat-Oberfläche](/docs/native-chat-ui) -## Was Sie kostenlos bekommen {#what-you-get-for-free} +Von Aktionen deklarierte Tabellen, Diagramme und BYO-Runtime-Haltung. -Die Übernahme des Frameworks ist vor allem deshalb wertvoll, weil Sie nichts mehr erstellen müssen. Sobald Ihre App die fünf Regeln befolgt, erben Sie Folgendes: +### [Agent-Oberflächen](/docs/agent-surfaces) -- **Eine Aktion = jede Oberfläche.** Jede mit `defineAction()` definierte Aktion ist gleichzeitig ein Agent-Tool, ein typsicherer Frontend-Hook (`useActionQuery` / `useActionMutation`), ein Framework-eigener HTTP-Transport, ein CLI-Befehl, ein MCP-Tool für externe Clients und ein A2A-Tool für andere agentennative Apps. Optionale `link`- und `mcpApp`-Metadaten fügen Deep Links und MCP Apps UI ohne eine zweite Implementierung hinzu. -- **Ein vollständiger Arbeitsbereich pro Benutzer.** Skills, gemeinsam genutzter `LEARNINGS.md`, persönlicher `memory/MEMORY.md`, `AGENTS.md`, benutzerdefinierte Subagenten, geplante Jobs, verbundene MCP-Server – alle SQL-gestützt, keine Entwicklungsbox erforderlich. Siehe [Agent-Ressourcen](/docs/agent-resources). -- **Drop-in-React-Komponenten.** `` und `` rendern Chat und Arbeitsbereich überall in Ihrer App. Siehe [Drop-in Agent](/docs/drop-in-agent). -- **BYO-Agenten-Chat-Laufzeiten.** Derselbe Chat-Oberfläche kann auf OpenAI-Agenten, OpenAI-Antworten, Claude-Agenten SDK, Vercel AI SDK, AG-UI oder Ihrem eigenen normalisierten HTTP-Stream sitzen. Siehe [Native Chat-Oberfläche](/docs/native-chat-ui#byo-agent-runtimes). -- **Live-Synchronisierung zwischen Agent und UI.** Gleicher Prozess schreibt Stream sofort über `/_agent-native/events`; Eine einfache Abfrage sorgt dafür, dass serverlose, Cron- und prozessübergreifende Schreibvorgänge konvergent bleiben. Durch die Mutation actions werden aktionsgestützte Abfragen automatisch ungültig, sodass vom Agenten erstellte Datensätze ohne manuelle Aktualisierung angezeigt werden. Siehe [Live Sync](#polling-sync) unten. -- **Auth, orgs, RBAC.** Eine bessere Authentifizierung mit Organisationen/Mitgliedern/Rollen ist für jede Vorlage integriert. Siehe [Authentication](/docs/authentication). -- **Kontextbewusstsein.** Der Agent weiß über den App-Statusschlüssel `navigation` immer, was der Benutzer sieht. Siehe [Context Awareness](/docs/context-awareness). -- **MCP Client + Server, beide Richtungen.** Die App nimmt MCP-Server auf (lokal, remote, gemeinsam genutzter Hub) _und_ macht ihren eigenen actions als MCP-Server verfügbar. Siehe [MCP Clients](/docs/mcp-clients) und [MCP Protocol](/docs/mcp-protocol). -- **Inter-App-Delegation.** Agenten in verschiedenen Apps kommunizieren über [A2A](/docs/a2a-protocol). Same-Origin-Bereitstellungen überspringen JWT; Cross-Origin verwendet ein gemeinsames `A2A_SECRET`. -- **Subagententeams.** Erzeugt einen Subagenten mit eigenem Thread und eigenen Tools, der als Chip inline im Chat angezeigt wird. Siehe [Agent Teams](/docs/agent-teams). -- **Portabilität.** Jede von Drizzle unterstützte SQL-Datenbank, jeder Nitro-kompatible Host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). +Chat, native Inline-UI, vollständige App-Seiten, eingebetteter Sidecar, Automatisierung und Pfade für externe Agenten. -Das ist das „und alles andere“, was Sie sonst selbst zusammenkleben würden. +### [A2A-Protokoll](/docs/a2a-protocol) -## Wie geht es weiter? {#deep-dives} +Agent-zu-Agent-Kommunikation. -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — Die Vision und Philosophie hinter diesen Regeln -- [**Context Awareness**](/docs/context-awareness) — Navigationsstatus sowie view-screen- und navigate-Befehle im Detail -- [**Skills Guide**](/docs/skills-guide) — Framework-Skills, Domänen-Skills und das Erstellen eigener Skills -- [**Native Chat UI**](/docs/native-chat-ui) — Von Actions deklarierte Tabellen, Diagramme und die Haltung zu eigenen Laufzeiten -- [**Agent Surfaces**](/docs/agent-surfaces) — Chat, native Inline-UI, vollständige App-Seiten, eingebettete Sidecars, Automatisierung und externe Agentenpfade -- [**A2A Protocol**](/docs/a2a-protocol) — Agent-zu-Agent-Kommunikation + diff --git a/packages/core/docs/content/locales/es-ES/key-concepts.mdx b/packages/core/docs/content/locales/es-ES/key-concepts.mdx index 8a8ffa1924..6b83bec5b2 100644 --- a/packages/core/docs/content/locales/es-ES/key-concepts.mdx +++ b/packages/core/docs/content/locales/es-ES/key-concepts.mdx @@ -1,46 +1,50 @@ --- title: "Conceptos clave" -description: "Cómo funcionan las aplicaciones nativas del agente: primero actions, base de datos SQL, bucle aplicación-agente, UI opcional, sincronización de sondeo, puntos de entrada de agentes externos, conocimiento del contexto y portabilidad." +description: "Cómo funcionan las aplicaciones agent-native en tres capas: el framework Core, los bloques opcionales de Toolkit y las Plantillas opcionales, además de las actions compartidas, la base de datos SQL, el bucle aplicación-agente y las reglas de portabilidad." --- # Conceptos clave -Cómo funcionan internamente las aplicaciones nativas del agente: los principios y la arquitectura. Esta página es el contrato; para conocer la visión y los argumentos para construir de esta manera, consulte [What Is Agent-Native?](/docs/what-is-agent-native). +Cómo funcionan por dentro las aplicaciones agent-native: los principios y la arquitectura. Esta página es el contrato: las reglas fijas que una aplicación debe seguir para contar como agent-native. Para conocer la visión y los argumentos a favor de construir de esta manera, consulta [¿Qué es Agent-Native?](/docs/what-is-agent-native). ## Las tres capas {#three-layers} -Agent Native es un framework, no una sola plantilla: +Agent Native es un framework con tres capas: -- **Core - el framework:** el contrato fundamental de ejecución y datos para cualquier aplicación. -- **Toolkit - piezas reutilizables opcionales:** UI y sistemas de producto compartidos que las aplicaciones pueden adoptar, combinar o bifurcar. -- **Plantillas - aplicaciones opcionales:** aplicaciones completas de dominio construidas sobre Core, que suelen usar Toolkit y se pueden bifurcar y usar como punto de partida. +| Capa | Qué es | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Core: el framework** | El contrato fundamental de ejecución: actions, helpers de SQL y Drizzle, autenticación, estado de la aplicación, ejecución del agente, comprobaciones de acceso, enrutamiento y sincronización en vivo. Toda aplicación puede usar Core directamente. | +| **Toolkit: piezas reutilizables opcionales** | UI y sistemas de producto compartidos para construir aplicaciones, como primitivas, editores, uso compartido, colaboración, configuración y UX del agente. Las aplicaciones pueden usar, combinar o bifurcar las piezas que necesiten. | +| **Plantillas: aplicaciones opcionales construidas sobre Core** | Aplicaciones completas y específicas de dominio con rutas, esquema, actions, instrucciones e identidad visual. Las plantillas propias y las personalizadas suelen usar Toolkit, y se pueden bifurcar y usar como punto de partida. | -Core es la base. Toolkit y las plantillas son opcionales. +Core es la base. Toolkit y las Plantillas son opcionales: una plantilla puede usar Toolkit, pero Toolkit no es necesario para construir una aplicación sobre Core. ## La arquitectura {#the-architecture} -Cada aplicación nativa del agente consta de tres cosas que funcionan juntas: +En tiempo de ejecución, cada aplicación agent-native es tres cosas funcionando juntas: -- **Agente**: IA autónoma que lee y escribe datos, ejecuta actions y usa herramientas configuradas. Personalizable con skills e instrucciones. -- **Aplicación**: la superficie del producto alrededor del agente. Esto puede ser solo acción al principio, chat enriquecido, un pequeño plano de control o un UI React completo con paneles, flujos y visualizaciones. -- **Computadora**: base de datos, navegador, ejecución de código. Los agentes trabajan mediante la superficie de acciones y datos de la aplicación; la aplicación puede exponer esa misma superficie mediante MCP. Los servidores MCP externos son complementos opcionales, no la base. +- **Agente:** La IA autónoma. Lee datos, escribe datos, ejecuta actions y usa las herramientas que estén configuradas. Cuando su frame recibe intencionadamente acceso al workspace y herramientas de escritura, también puede modificar el código fuente propio de la aplicación. Personalizable con skills e instrucciones. +- **Aplicación:** La superficie de producto alrededor del agente. Puede empezar como chat, añadir resultados nativos en línea, crecer hasta convertirse en un pequeño plano de control, o convertirse en una interfaz React completa con paneles, flujos y visualizaciones. +- **Computadora:** La base de datos, el navegador y los runtimes de herramientas configurados a través de los cuales actúa el agente. Los agentes trabajan a través de la propia superficie de actions y datos de la aplicación; esa misma superficie se puede exponer opcionalmente mediante MCP, pero los servidores MCP externos siguen siendo un complemento, no la base. - +El diagrama de abajo muestra al agente y a la aplicación lado a lado, ambos con flechas bidireccionales hacia una única capa de computadora compartida debajo. Ninguno de los dos es dueño de los datos. En cambio, ambos leen y escriben en el mismo almacén SQL, de modo que un cambio realizado por cualquiera de los dos es visible para el otro de inmediato, sin necesidad de construir una capa de sincronización intermedia. + + ```html
- AgentAgentelee y escribe datos, ejecuta acciones y usa herramientas + >lee y escribe datos, ejecuta acciones, usa herramientas configuradas
- ApplicationAplicaciónaction-only, chat, control plane, or full UI Reactchat, resultados en línea, plano de control o UI React completa
@@ -48,8 +52,8 @@ Cada aplicación nativa del agente consta de tres cosas que funcionan juntas: ↓ ↑
- Computer
base de datos SQL · browser · code executionbase de datos SQL · navegador · ejecución de código
@@ -87,93 +91,115 @@ Cada aplicación nativa del agente consta de tres cosas que funcionan juntas: -Las aplicaciones headless pueden ejecutar el mismo bucle de producción de aplicación-agente desde la carpeta con `pnpm agent`, mientras que las aplicaciones UI montan el panel de agente integrado y se ejecutan localmente con `pnpm dev`. En la nube, Builder.io proporciona un marco administrado (el entorno que aloja al agente junto a su aplicación) con colaboración, edición visual e infraestructura administrada para equipos. +Ese mismo bucle agente-aplicación-computadora es lo que se ejecuta localmente y en producción. Las aplicaciones automation-first lo ejecutan directamente desde la carpeta con `pnpm agent`; las aplicaciones con UI montan el panel de agente integrado y añaden `pnpm dev`. En la nube, Builder.io aloja ese mismo bucle como un frame gestionado: el entorno que ejecuta el agente junto a tu aplicación. Se encarga de la colaboración, la edición visual y la infraestructura por ti. -## Bloques de creación de agentes {#agent-building-blocks} +## Bloques de construcción del agente {#agent-building-blocks} -Cada aplicación nativa del agente tiene los mismos componentes básicos del agente, independientemente de si -la superficie del producto es headless, chat-first o UI completo: +Cada aplicación agent-native tiene los mismos bloques de construcción del agente, +sin importar si la superficie del producto es chat-first, automation-first o una +UI completa. Cada uno vive en su propio archivo: /SKILL.md", - note: "Comportamiento reutilizable: pasos de workflow, políticas, ejemplos, referencias y listas de qué hacer y no hacer", + note: "comportamiento reutilizable: pasos del flujo de trabajo, políticas, ejemplos, referencias y listas de qué hacer y qué no hacer", }, { path: "actions/.ts", - note: "Capacidad ejecutable: operación tipada expuesta al agente, UI, CLI, HTTP, MCP, A2A, jobs y webhooks", + note: "capacidad ejecutable: operación tipada expuesta al agente, la UI, CLI, HTTP, MCP, A2A, jobs y webhooks", }, ]} /> -| Bloque de creación | Úsalo para | Cargado cuando | -| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| **Instrucciones** | Guía estable que el agente debe llevar a cabo en cada tarea: qué es la aplicación, invariantes, tono, índices | Cada turno | -| **Skills** | Comportamiento reutilizable: cómo seguir un flujo de trabajo, aplicar una política, inspeccionar pruebas o verificar un resultado | Bajo demanda cuando la descripción de la habilidad coincide con la tarea | -| **Actions** | Operaciones reales: leer o escribir datos, llamar a API, enviar mensajes, ejecutar aprobaciones, producir resultados escritos | Listados como herramientas en cada turno; ejecutado sólo cuando se llama | +Un turno es un intercambio con el agente: lee su contexto, decide qué hacer y responde. Que se cargue en cada turno significa que el archivo vuelve a entrar en ese contexto cada vez, no solo una vez al inicio de la sesión. + +| Bloque de construcción | Archivo | Úsalo para | Se carga cuando | +| ---------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| **Instrucciones** | `AGENTS.md` | Guía estable que el agente debe llevar a cada tarea: qué es la aplicación, invariantes, tono, índices | Cada turno | +| **Skills** | `.agents/skills//SKILL.md` | Comportamiento reutilizable: cómo seguir un flujo de trabajo, aplicar una política, inspeccionar evidencia o verificar un resultado | Bajo demanda, cuando la descripción de la skill coincide con la tarea | +| **Actions** | `actions/.ts` | Operaciones reales: leer o escribir datos, llamar a APIs, enviar mensajes, ejecutar aprobaciones, producir resultados tipados | Listadas como herramientas en cada turno; se ejecutan solo cuando se llaman | + +Skills y actions trabajan juntos. Una habilidad le enseña al agente cómo +realizar una clase de trabajo; una acción es la ruta de código que puede +llamar mientras realiza ese trabajo. Por ejemplo, una habilidad +`customer-research` podría indicarle al agente qué fuentes inspeccionar y +cómo resumir la evidencia, mientras que las actions `search-crm` y +`create-brief` obtienen y escriben los datos reales. + +Cinco reglas rigen la arquitectura: -Skills y actions trabajan juntos. Una habilidad le enseña al agente cómo hacer una clase de -trabajo; una acción es la ruta del código que puede llamar mientras realiza ese trabajo. Por ejemplo, -una habilidad `customer-research` podría indicarle al agente qué fuentes inspeccionar y -cómo resumir la evidencia, mientras que `search-crm` y `create-brief` actions recuperan -y escribe los datos reales. +1. **Los datos viven en SQL:** todo el estado de la aplicación vive en la base de datos a través de Drizzle ORM. +2. **Toda la IA pasa por el agente:** no hay llamadas a LLM en línea; toda interacción de IA fluye a través del puente de chat del agente. +3. **Actions para las operaciones del agente:** el trabajo complejo se ejecuta como una acción tipada, no como código en línea. +4. **La sincronización en vivo mantiene la UI sincronizada:** los cambios de la base de datos se transmiten por SSE, con el sondeo como respaldo universal. +5. **El estado de la aplicación en SQL:** el estado efímero de la UI vive en la base de datos, y tanto el agente como la UI pueden leerlo. -Cinco reglas gobiernan la arquitectura: +## La lista de verificación de las cuatro áreas {#four-area-checklist} -1. **Los datos se encuentran en SQL**: todo el estado de la aplicación se encuentra en la base de datos a través de Drizzle ORM -2. **Toda la IA pasa por el agente**: no hay llamadas LLM en línea -3. **Actions para operaciones de agente**: el trabajo complejo se ejecuta como actions -4. **La sincronización en vivo mantiene el UI sincronizado**: los cambios de la base de datos se transmiten a través del SSE con el sondeo como respaldo universal -5. **El estado de la aplicación está en SQL**: el estado efímero de la UI vive en la base de datos y es legible para el agente y la UI +Toda funcionalidad orientada al usuario debe actualizar todas las áreas aplicables. Omitir un área aplicable rompe el contrato agent-native; forzar una pantalla en una automatización que ningún humano necesita explorar también es una mala señal. -## La lista de verificación de cuatro áreas {#four-area-checklist} +- **1. UI:** Página, componente o cuadro de diálogo con el que interactúa el usuario. +- **2. Acción:** Acción invocable por el agente en `actions/` para la misma operación. +- **3. Skills:** Actualiza `AGENTS.md` y/o crea una skill que documente el patrón. +- **4. Estado de la aplicación:** Estado de navegación, datos de view-screen y comandos navigate. -Cada función orientada al usuario debe actualizar todas las áreas aplicables. Omitir un área aplicable rompe el contrato entre el agente nativo; forzar un UI a una primitiva de solo acción también es un olor. +Una funcionalidad con solo UI es invisible para el agente. Una funcionalidad de UI completa con solo actions es invisible para el usuario. Una funcionalidad sin estado de aplicación significa que el agente no ve lo que está haciendo el usuario. Una operación automation-first puede empezar legítimamente con acción + instrucciones y añadir chat, UI o estado de aplicación más adelante, cuando los humanos necesiten explorarla, aprobarla, configurarla o compartirla. -| Área | Descripción | -| ------------------------------ | --------------------------------------------------------------------------------- | -| **1. UI** | Página, componente o cuadro de diálogo con el que interactúa el usuario | -| **2. Acción** | Acción invocable por el agente en actions/ para la misma operación | -| **3. Skills** | Actualice AGENTS.md y/o cree una habilidad que documente el patrón | -| **4. Estado de la aplicación** | Estado de navegación, visualización de datos en pantalla y comandos de navegación | +## Qué incluye Agent Native {#what-you-get-for-free} -Una característica con solo UI es invisible para el agente. Una función UI completa con solo actions es invisible para el usuario. Una función sin estado de aplicación significa que el agente no ve lo que está haciendo el usuario. Una operación sin cabeza puede comenzar legítimamente con acción + instrucciones y agregar UI/app-state más tarde, cuando los humanos necesiten explorarla, aprobarla, configurarla o compartirla. +Adoptar el framework es valioso sobre todo por lo que dejas de tener que construir. En el momento en que tu aplicación sigue las cinco reglas anteriores, heredas: + +| Función | Qué te ofrece | +| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Una acción = cada superficie | Cada acción definida con `defineAction()` es simultáneamente una herramienta de agente, un hook de frontend con seguridad de tipos (`useActionQuery` / `useActionMutation`), un transporte HTTP propiedad del framework, un comando CLI, una herramienta MCP para clientes externos y una herramienta A2A para otras aplicaciones agent-native. Los metadatos opcionales `link` y `mcpApp` añaden enlaces profundos y UI de MCP Apps sin una segunda implementación. | +| Recursos completos del agente por usuario | Skills, `LEARNINGS.md` compartido, `memory/MEMORY.md` personal, `AGENTS.md`, subagentes personalizados, jobs programados y servidores MCP conectados. Todo respaldado por SQL, sin necesidad de un dev-box. Consulta [Agent Resources](/docs/agent-resources). | +| Componentes React listos para usar | `` y `` renderizan el chat y los recursos en cualquier parte de tu aplicación. Consulta [Drop-in Agent](/docs/drop-in-agent). | +| Runtimes de chat del agente BYO | La misma UI de chat puede montarse sobre OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI o tu propio stream HTTP normalizado. Consulta [Chat nativo UI](/docs/native-chat-ui#byo-agent-runtimes). | +| Sincronización en vivo entre el agente y la UI | Las escrituras del mismo proceso se transmiten de inmediato por `/_agent-native/events`; un sondeo ligero mantiene convergentes las escrituras serverless, de cron y entre procesos. Las actions que mutan invalidan automáticamente las consultas respaldadas por acciones, de modo que los registros creados por el agente aparecen sin necesidad de refrescar manualmente. Consulta [Sincronización en vivo](#polling-sync) más abajo. | +| Auth, organizaciones, RBAC | Better Auth con organizaciones/miembros/roles viene integrado en cada plantilla. Consulta [Authentication](/docs/authentication). Para más de un usuario, empieza por [Organizations, Teams & Permissions](/docs/organizations-teams-permissions). | +| Conciencia del contexto | El agente siempre sabe qué está mirando el usuario, a través de la clave de estado de aplicación `navigation`. Consulta [Conciencia del contexto](/docs/context-awareness). | +| Cliente y servidor MCP, en ambas direcciones | La aplicación ingiere servidores MCP (locales, remotos, compartidos por hub) _y_ expone sus propias actions como un servidor MCP. Consulta [MCP Clients](/docs/mcp-clients) y [MCP Protocol](/docs/mcp-protocol). | +| Delegación entre aplicaciones | Los agentes de distintas aplicaciones se comunican mediante [A2A](/docs/a2a-protocol). Los despliegues del mismo origen omiten el JWT; entre orígenes distintos se usa un `A2A_SECRET` compartido. | +| Equipos de subagentes | Genera un subagente con su propio hilo y herramientas, que aparece como un chip en línea en el chat. Consulta [Agent Teams](/docs/agent-teams). | +| Portabilidad | Cualquier base de datos SQL compatible con Drizzle, cualquier host compatible con Nitro (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). | ## Datos en SQL {#data-in-sql} -Todo el estado de la aplicación reside en una base de datos SQL a través de Drizzle ORM. Los esquemas son independientes del proveedor; las bases de datos compatibles, la configuración de `DATABASE_URL` y las reglas de portabilidad se encuentran en [Database](/docs/database). +Todo el estado de la aplicación vive en una base de datos SQL a través de Drizzle ORM. Los esquemas son independientes del proveedor; las bases de datos compatibles, la configuración de `DATABASE_URL` y las reglas de portabilidad están en [Database](/docs/database). + +Los almacenes SQL de Core se crean automáticamente y están disponibles en cada plantilla: -Las tiendas principales SQL se crean automáticamente y están disponibles en cada plantilla: +- `application_state`: estado efímero de la UI (navegación, borradores, selecciones) +- `settings`: configuración persistente de clave-valor +- `oauth_tokens`: credenciales OAuth +- `sessions`: sesiones de autenticación -- `application_state` — estado efímero de UI (navegación, borradores, selecciones) -- `settings`: configuración clave-valor persistente -- `oauth_tokens` — Credenciales OAuth -- `sessions` — sesiones de autenticación +Cada fila de abajo se expande para mostrar sus campos: +Para añadir tus propios datos de dominio, define una tabla con los mismos helpers de esquema usados por los almacenes principales anteriores: + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -246,28 +274,30 @@ export const forms = table("forms", { }); ``` +Tanto tú como el agente pueden inspeccionar esos datos desde la terminal, sin necesidad de un cliente SQL aparte: + ```bash -# Acciones principales para una inspección rápida de la base de datos +# Actions de Core para una inspección rápida de la base de datos pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -El complemento de chat del agente de producción deja las herramientas SQL sin formato en modo lectura por defecto -(`frameworkTools: { database: "read" }`), por lo que los agentes inspeccionan datos de la app con `db-schema` / -`db-query` y escriben mediante actions tipadas de la app. Establece -`database: "write"` (o `true`) solo para superficies de mantenimiento que -también deban exponer `db-exec` / `db-patch` con alcance; usa -`database: "off"` / `false` para requerir actions tipadas para todos los datos -acceso. +`db-schema` imprime las columnas y los tipos de cada tabla. `db-query` ejecuta SQL de solo lectura directamente, lo cual es útil para comprobar las escrituras de una acción sin abrir un cliente de base de datos. + + + +El complemento de chat del agente de producción deja las herramientas SQL sin formato en modo lectura por defecto (`frameworkTools: { database: "read" }`), por lo que los agentes inspeccionan datos de la app con `db-schema` / `db-query` y escriben mediante actions tipadas de la app. Establece `database: "write"` (o `true`) solo para superficies de mantenimiento que también deban exponer `db-exec` / `db-patch` con alcance; usa `database: "off"` / `false` para requerir actions tipadas para todos los datos acceso. + + `frameworkTools` gobierna igual el resto de las herramientas propias del framework: sharing, comentarios de revisión, historial de versiones, feature flags, localización, auditoría, Context X-Ray, perfil, automatizaciones, docs, resources, web, delegación entre apps, chat y email. Consulta [Production Agent Tools](/docs/deployment#production-agent-tools) para la lista completa, el preset `"minimal"` y por qué desactivar un grupo deja sus rutas HTTP montadas. ## Puente de chat del agente {#agent-chat-bridge} -El UI nunca llama directamente a un LLM. Cuando un usuario hace clic en "Generar gráfico" o "Escribir resumen", el UI envía un mensaje al agente a través de `postMessage`. El agente hace el trabajo, con historial de conversaciones completo, skills, instrucciones y capacidad de iteración. +La UI nunca llama directamente a un LLM. Cuando un usuario hace clic en "Generar gráfico" o "Escribir resumen", la UI envía un mensaje al agente mediante `postMessage`. El agente hace el trabajo. Tiene el historial completo de la conversación, skills, instrucciones y la capacidad de iterar. ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -276,16 +306,19 @@ sendToAgentChat({ }); ``` -¿Por qué no llamar a un LLM en línea? +En resumen: + +- **La IA no es determinista**: necesitas un flujo de conversación para dar feedback e iterar, no botones de un solo uso. +- **El contexto importa**: el agente tiene las instrucciones, las skills y el historial de la aplicación. Una llamada en línea no tiene nada de eso. +- **El agente puede hacer más**: puede ejecutar actions, navegar por la web y encadenar varios pasos. -- **La IA no es determinista.** Necesitas un flujo de conversación para dar retroalimentación e iterar, no botones de un solo uso. -- **El contexto importa.** El agente tiene su código base completo, instrucciones, skills e historial. Una llamada en línea no tiene nada de eso. -- **El agente puede hacer más.** Puede ejecutar actions, navegar por la web y encadenar varios pasos. -- **Ejecución sin cabeza.** Debido a que todo pasa por el agente, cualquier aplicación se puede controlar completamente desde Slack, Telegram u otro agente a través de [A2A](/docs/a2a-protocol). +**[External execution](/docs/a2a-protocol)** -## Sistema Actions {#actions-system} +Como todo pasa por el agente y las actions, cualquier aplicación se puede controlar desde Slack, Telegram, jobs programados, scripts u otro agente mediante A2A. -Cuando el agente necesita hacer algo complejo (llamar a un API, procesar datos, consultar la base de datos), ejecuta una **acción**. Actions son archivos TypeScript en `actions/` que exportan un `defineAction()` predeterminado: +## Sistema de actions {#actions-system} + +Cuando el agente necesita hacer algo complejo, como llamar a una API, procesar datos o consultar la base de datos, ejecuta una **acción**. Las actions son archivos TypeScript en `actions/` que exportan un `defineAction()` por defecto: ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -303,19 +336,30 @@ export default defineAction({ }); ``` -Una llamada `defineAction()` le brinda: +Esta acción obtiene JSON de una API de origen y lo devuelve. `defineAction()` envuelve la función con un schema de zod para su entrada (`source`), de modo que el framework puede validar esa entrada, generar un JSON Schema que el agente pueda llamar e inferir tipos para el hook de frontend, todo a partir de esta única definición. + +Una sola llamada a `defineAction()` llega automáticamente a cinco consumidores distintos. El diagrama muestra la ramificación (fan-out) a partir de una única acción; la lista de abajo explica qué obtiene cada consumidor: + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **Herramienta del agente**: el agente la ve con el esquema JSON derivado de zod y puede llamarlo. -- **Gancho frontal**: `useActionMutation("fetch-data")` con inferencia completa de TypeScript. -- **Transporte del marco**: se monta automáticamente detrás de los ganchos del cliente. -- **CLI** — `pnpm action fetch-data --source=signups` para secuencias de comandos y bucles de desarrollo de agentes. -- **Herramienta MCP/herramienta A2A**: cuando el servidor MCP o A2A está habilitado, la misma acción aparece allí también. +- **Herramienta de agente:** el agente la ve con el JSON Schema derivado de zod y puede llamarla. +- **Hook de frontend:** `useActionMutation("fetch-data")` con inferencia completa de TypeScript. +- **Transporte del framework:** montado automáticamente detrás de los hooks del cliente. +- **CLI:** `pnpm action fetch-data --source=signups` para scripts y bucles de desarrollo del agente. +- **Herramienta MCP / herramienta A2A:** cuando el servidor MCP o A2A está habilitado, la misma acción aparece también ahí. -La misma lógica, una definición, conectada automáticamente a cada consumidor. Consulte [Actions](/docs/actions) para obtener la referencia completa. +Cada consumidor llama a la misma función subyacente, así que solo hay una implementación que escribir y mantener. Consulta [Actions](/docs/actions) para la referencia completa. ## Sincronización en vivo {#polling-sync} -Los cambios en la base de datos se sincronizan con el UI a través del `useDbSync()`. El mismo proceso escribe flujo sobre `/_agent-native/events`; `/_agent-native/poll` sigue siendo la alternativa entre procesos y sin servidor. Cuando el agente escribe en la base de datos (estado de la aplicación, configuración o datos del dominio), se incrementa un contador de versiones y el cliente invalida las cachés de consultas React relevantes. +Cuando el agente cambia datos, la UI necesita reflejarlo sin un refresco manual. `useDbSync()` es lo que hace eso automático. Las escrituras del mismo proceso se transmiten por `/_agent-native/events`; `/_agent-native/poll` sigue siendo el respaldo entre procesos y para serverless. Cuando el agente escribe en la base de datos (estado de la aplicación, settings o datos de dominio), un contador de versión se incrementa y el cliente invalida las cachés relevantes de React Query. ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -323,15 +367,19 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` +Llama a esto una vez, cerca de la raíz de la aplicación. Suscribe toda la aplicación a los eventos de cambio, de modo que cualquier componente que use `useActionQuery` o un `useQuery` con versión de origen vuelve a obtener los datos automáticamente cuando cambian los datos que lee. + El flujo es: 1. El agente ejecuta una acción que escribe en la base de datos -2. El servidor emite un evento de cambio con una fuente como `"action"` o `"settings"` -3. `useDbSync` lo recibe a través de SSE o el respaldo de sondeo -4. Recuperación de ganchos `useActionQuery` y ganchos `useQuery` con versión de origen -5. Los componentes representan los nuevos datos sin recargar la página +2. El servidor emite un evento de cambio con un origen (source) como `"action"` o `"settings"` +3. `useDbSync` lo recibe por SSE o por el respaldo de sondeo +4. Los hooks `useActionQuery` y los hooks `useQuery` con versión de origen vuelven a obtener los datos +5. Los componentes renderizan los nuevos datos sin recargar la página + +El diagrama traza esa misma secuencia de principio a fin: - + ```html
@@ -347,12 +395,12 @@ El flujo es:
useDbSyncSSE · poll fallback + >SSE · respaldo de sondeo
Recarga de consulta
renderiza, sin recargarrenderiza, sin recarga
@@ -380,89 +428,97 @@ El flujo es: -Esto funciona en todos los entornos de implementación, incluidos los sin servidor y los perimetrales, porque utiliza la base de datos, no el estado en memoria ni los observadores del sistema de archivos. +Esto funciona en todos los entornos de despliegue, incluidos serverless y edge, porque usa la base de datos en lugar de estado en memoria o watchers del sistema de archivos. ## Marcos {#frames} -Un _frame_ es el entorno que aloja el agente junto a su aplicación; localmente, ese es el panel integrado; en la nube es la superficie gestionada de Builder.io. Ver [Frames](/docs/frames). +Un _frame_ es el entorno que aloja al agente junto a tu aplicación. Localmente es el panel integrado; en la nube es la superficie gestionada de Builder.io. Consulta [Frames](/docs/frames). -Las aplicaciones nativas del agente incluyen un panel de agente integrado que proporciona el agente de IA junto con la aplicación UI. Esto es lo que hace que la arquitectura funcione: el agente necesita una computadora (base de datos, navegador, ejecución de código) y la aplicación necesita al agente para que funcione la IA. +Las aplicaciones agent-native incluyen un panel de agente integrado que proporciona el agente de IA junto a la UI de la aplicación. Esto es lo que hace que la arquitectura funcione: el agente necesita una computadora (base de datos, navegador, ejecución de código), y la aplicación necesita al agente para el trabajo de IA. -- **Panel de agente integrado**: chat y terminal CLI opcional integrados en cada aplicación. Admite código Claude, Codex, Gemini, OpenCode y Builder.io. Se ejecuta localmente. Gratis y de código abierto. -- **Nube**: implemente en cualquier nube con colaboración, edición visual, roles y permisos en tiempo real. Lo mejor para equipos. +- **Panel de agente integrado:** chat y una terminal CLI opcional integrados en cada aplicación. Compatible con Claude Code, Codex, Gemini, OpenCode y Builder.io. Se ejecuta localmente, gratis y de código abierto. +- **Nube:** despliega en cualquier nube con colaboración en tiempo real, edición visual, roles y permisos. Ideal para equipos. ## Conciencia del contexto {#context-awareness} -El agente siempre sabe lo que está mirando el usuario. El UI escribe una clave `navigation` en el estado de la aplicación en cada cambio de ruta. El agente lo lee mediante la acción `view-screen` antes de actuar. +El agente siempre sabe qué está mirando el usuario. La UI escribe una clave `navigation` en application-state en cada cambio de ruta. El agente la lee mediante la acción `view-screen` antes de actuar. -Por ejemplo, cuando abres un hilo de correo electrónico, UI inserta una fila como: +Por ejemplo, cuando abres un hilo de correo la UI hace upsert de una fila como: ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -El UI escribe esto en el cambio de ruta; el agente lo lee (a través de `view-screen`) antes de realizar cualquier acción, por lo que siempre sabe en qué hilo (o gráfico o diapositiva) está centrado. + + +La UI escribe esto en cada cambio de ruta; el agente lo lee (mediante `view-screen`) antes de realizar cualquier acción, de modo que siempre sabe en qué hilo, gráfico o diapositiva estás enfocado. + + -Consulte [Context Awareness](/docs/context-awareness) para conocer el patrón completo: estado de navegación, visualización de pantalla, comandos de navegación y prevención de fluctuaciones. +Consulta [Conciencia del contexto](/docs/context-awareness) para ver el patrón completo: estado de navegación, view-screen, comandos navigate y prevención de jitter. ## Una acción, muchas superficies {#protocols} -Implementar una operación de dominio una vez como acción; el marco lo expone a todos los consumidores. El mismo `defineAction()` se convierte en una herramienta de agente, un gancho UI con seguridad de tipos, un punto final HTTP, un comando CLI, una herramienta MCP y una herramienta A2A, con metadatos opcionales de `link`, `mcpApp` o widgets nativos explícitos agregados solo cuando una superficie los necesita. Skills y las instrucciones cubren el comportamiento. +Implementa una operación de dominio una vez como acción; el framework la expone a todos los consumidores. El mismo `defineAction()` se convierte en una herramienta de agente, un hook de UI con seguridad de tipos, un endpoint HTTP, un comando CLI, una herramienta MCP y una herramienta A2A, con metadatos opcionales `link`, `mcpApp`, de widget nativo, o wrappers de Generative UI añadidos solo cuando una superficie necesita una interacción más rica. Skills e instrucciones cubren el comportamiento. -Para obtener la matriz completa de protocolo/superficie (servidor MCP y aplicaciones OAuth, MCP, A2A, enlaces profundos, widgets de chat nativos, conectores AgentChatRuntime, Agent Web y el horizonte adaptador para ACP y A2UI) y para elegir la forma del producto (sin cabeza, chat enriquecido, sidecar integrado o aplicación completa), consulte [Agent Surfaces](/docs/agent-surfaces). +Para la matriz completa de protocolos/superficies (servidor MCP y OAuth, MCP Apps, A2A, enlaces profundos, widgets de chat nativos, Generative UI, conectores AgentChatRuntime, Agent Web y el horizonte de adaptadores para ACP y A2UI), y para elegir la forma de producto (chat, UI en línea, páginas de aplicación completas, sidecar integrado, automatización o acceso de agente externo), consulta [Superficies del agente](/docs/agent-surfaces). ## Código de la aplicación y personalización {#agent-modifies-code} -El agente integrado no edita el código fuente de forma predeterminada. Solo -puede hacerlo cuando el host le concede intencionalmente herramientas de -escritura de repository/workspace. En una aplicación desplegada normal, el -agente trabaja mediante actions, estado respaldado por SQL e integraciones -configuradas. Las plantillas son aplicaciones completas que puedes bifurcar y -personalizar en tu propio repositorio y flujo de desarrollo. +El framework no le otorga al agente integrado acceso ambiental al código fuente +de una aplicación. En una aplicación desplegada, el agente normalmente trabaja +mediante actions, estado respaldado por SQL e integraciones configuradas. +Puede editar componentes, rutas, estilos y actions cuando su frame recibe +intencionadamente workspace y herramientas de escritura. Las plantillas son +aplicaciones completas que puedes bifurcar y personalizar en tu propio +repositorio y flujo de desarrollo en cualquier caso. Para personalización en +tiempo de ejecución sin cambios en el código fuente, usa [Extensions](/docs/extensions). ## Portátil por defecto {#hosting-agnostic} Dos reglas arquitectónicas mantienen las aplicaciones portátiles entre bases de datos y hosts: -- **Independiente de la base de datos.** Escriba esquemas con `@agent-native/core/db/schema` y lea/escriba con la consulta portátil DSL de Drizzle para que el mismo código se ejecute en cualquier proveedor compatible. Utilice SQL sin formato solo para migraciones aditivas o mantenimiento único, mantenido parametrizado e independiente del dialecto. Ver [Database](/docs/database). -- **Independiente del alojamiento.** El servidor se ejecuta en Nitro y se compila en cualquier destino de implementación. Nunca utilice API específicos de nodo (`fs`, `child_process`, `path`) en rutas o complementos del servidor, y nunca asuma un proceso de servidor persistente: sin servidor y perimetral no tienen estado, por lo tanto, mantenga todo el estado en SQL. Ver [Deployment](/docs/deployment). +- **Independiente de la base de datos.** Escribe los esquemas con `@agent-native/core/db/schema` y las lecturas/escrituras con el DSL de consultas portátil de Drizzle, de modo que el mismo código se ejecute en cualquier proveedor compatible. Usa SQL sin procesar solo para migraciones aditivas o mantenimiento puntual, manteniéndolo parametrizado e independiente del dialecto. Consulta [Database](/docs/database). +- **Independiente del hosting.** El servidor se ejecuta sobre Nitro y compila para cualquier destino de despliegue. Nunca uses APIs específicas de Node (`fs`, `child_process`, `path`) en rutas o plugins del servidor, y nunca asumas un proceso de servidor persistente. Serverless y edge no tienen estado, así que mantén todo el estado en SQL. Consulta [Deployment](/docs/deployment). -## Espacio de trabajo {#workspace} +## Recursos del agente {#workspace} -Cada usuario obtiene un **espacio de trabajo** personal: instrucciones, skills, memoria, subagentes personalizados, trabajos programados y servidores MCP conectados, todo almacenado en SQL en lugar de archivos. Eso hace que la personalización a nivel de código Claude sea viable dentro de SaaS multiinquilino sin necesidad de activar un contenedor por usuario. Ver [Recursos del Agente](/docs/agent-resources). +Cada usuario obtiene un conjunto personal de **recursos del agente**: instrucciones, skills, memoria, subagentes personalizados, jobs programados y servidores MCP conectados, todos almacenados en SQL en lugar de en archivos. Esto hace viable una personalización a nivel de Claude Code dentro de un SaaS multiinquilino sin necesidad de levantar un contenedor por usuario. Consulta [Agent Resources](/docs/agent-resources). ## Bloques de construcción relacionados {#building-blocks} -Estos se encuentran en la parte superior del mismo contrato y tienen sus propios detalles: +Estos se apoyan sobre el mismo contrato y tienen sus propias guías detalladas: -- **[Dispatch](/docs/dispatch)**: el plano de control del espacio de trabajo: bandeja de entrada compartida, bóveda de secretos, trabajos programados y un orquestador que delega a aplicaciones especializadas a través de A2A. -- **[Extensions](/docs/extensions)**: miniaplicaciones Alpine.js en espacio aislado que el agente crea en tiempo de ejecución, sin cambios de origen ni migraciones. -- **[Programas de datos](/docs/data-programs)**: scripts `run-code` almacenados y escritos por el agente que entregan a los paneles de dashboard un resultado en caché y actualizable, en lugar de una action de proveedor codificada. -- **[A2A Protocol](/docs/a2a-protocol)**: cómo las aplicaciones en el mismo espacio de trabajo se descubren y se llaman entre sí a través de JSON-RPC. +- **[Dispatch](/docs/dispatch):** el plano de control del workspace, con una bandeja de entrada compartida, una bóveda de secretos, jobs programados y un orquestador que delega en aplicaciones especializadas mediante A2A. +- **[Extensions](/docs/extensions):** mini-apps de Alpine.js en sandbox que el agente crea en tiempo de ejecución, sin cambios en el código fuente ni migraciones. +- **[Protocolo A2A](/docs/a2a-protocol):** cómo las aplicaciones del mismo workspace se descubren y se llaman entre sí mediante JSON-RPC. -## Lo que obtienes gratis {#what-you-get-for-free} +## Qué sigue {#deep-dives} -Adoptar el marco es valioso principalmente por lo que deja de tener que construir. En el momento en que tu aplicación sigue las cinco reglas, heredas: + -- **Una acción = cada superficie.** Cada acción definida con `defineAction()` es simultáneamente una herramienta de agente, un enlace frontal con seguridad de tipos (`useActionQuery` / `useActionMutation`), un transporte HTTP propiedad del marco, un comando CLI, una herramienta MCP para clientes externos y una herramienta A2A para otras aplicaciones nativas del agente. Los metadatos opcionales de `link` y `mcpApp` agregan enlaces profundos y aplicaciones MCP UI sin una segunda implementación. -- **Un espacio de trabajo completo por usuario.** Skills, `LEARNINGS.md` compartido, `memory/MEMORY.md` personal, `AGENTS.md`, subagentes personalizados, trabajos programados, servidores MCP conectados: todo respaldado por SQL, no se requiere dev-box. Ver [Recursos del Agente](/docs/agent-resources). -- **Componentes React integrados.** `` y `` representan el chat y el espacio de trabajo en cualquier lugar de su aplicación. Ver [Drop-in Agent](/docs/drop-in-agent). -- **Tiempos de ejecución del chat del agente BYO.** El mismo chat UI puede ubicarse encima de los agentes OpenAI, las respuestas de OpenAI, el agente Claude SDK, Vercel AI SDK, AG-UI o su propio flujo normalizado de HTTP. Ver [Native Interfaz de chat](/docs/native-chat-ui#byo-agent-runtimes). -- **Sincronización en vivo entre el agente y UI.** Las escrituras del mismo proceso se transmiten inmediatamente sobre `/_agent-native/events`; una encuesta ligera mantiene convergentes las escrituras sin servidor, cron y entre procesos. La mutación de actions invalida automáticamente las consultas respaldadas por acciones, por lo que los registros creados por el agente aparecen sin una actualización manual. Consulte [Live Sync](#polling-sync) a continuación. -- **Auth, orgs, RBAC.** Una mejor autenticación con organizaciones/miembros/roles está integrada para cada plantilla. Ver [Authentication](/docs/authentication). -- **Conciencia del contexto.** El agente siempre sabe lo que el usuario está mirando a través de la clave de estado de la aplicación `navigation`. Ver [Context Awareness](/docs/context-awareness). -- **Cliente MCP + servidor, en ambas direcciones.** La aplicación ingiere servidores MCP (locales, remotos, compartidos en concentrador) _y_ expone su propio actions como un servidor MCP. Ver [MCP Clients](/docs/mcp-clients) y [MCP Protocol](/docs/mcp-protocol). -- **Delegación entre aplicaciones.** Los agentes en diferentes aplicaciones hablan sobre [A2A](/docs/a2a-protocol). Las implementaciones del mismo origen omiten JWT; El origen cruzado utiliza un `A2A_SECRET` compartido. -- **Equipos de subagentes.** Genera un subagente con su propio hilo y herramientas, que aparece como un chip en línea en el chat. Ver [Agent Teams](/docs/agent-teams). -- **Portabilidad.** Cualquier base de datos SQL compatible con Drizzle, cualquier host compatible con Nitro (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). +### [¿Qué es Agent-Native?](/docs/what-is-agent-native) -Ese es el "y todo lo demás" que de otro modo estarías pegando tú mismo. +La visión y la filosofía detrás de estas reglas. -## Qué sigue {#deep-dives} +### [Conciencia del contexto](/docs/context-awareness) + +Estado de navegación, view-screen y comandos navigate en profundidad. + +### [Guía Skills](/docs/skills-guide) + +Skills del framework, skills de dominio y creación de skills personalizadas. + +### [Chat nativo UI](/docs/native-chat-ui) + +Tablas y gráficos declarados por actions, y postura de runtime BYO. + +### [Superficies del agente](/docs/agent-surfaces) + +Chat, UI nativa en línea, páginas de aplicación completas, sidecar integrado, automatización y rutas de agente externo. + +### [Protocolo A2A](/docs/a2a-protocol) + +Comunicación entre agentes. -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — la visión y la filosofía que sustentan estas reglas -- [**Context Awareness**](/docs/context-awareness) — estado de navegación y comandos view-screen y navigate en detalle -- [**Skills Guide**](/docs/skills-guide) — skills del framework, skills de dominio y creación de skills personalizadas -- [**Native Chat UI**](/docs/native-chat-ui) — tablas y gráficos declarados por actions y compatibilidad con tiempos de ejecución propios -- [**Agent Surfaces**](/docs/agent-surfaces) — chat, UI nativa integrada, páginas completas de aplicación, sidecar integrado, automatización y rutas de agentes externos -- [**A2A Protocol**](/docs/a2a-protocol) — comunicación entre agentes + diff --git a/packages/core/docs/content/locales/fr-FR/key-concepts.mdx b/packages/core/docs/content/locales/fr-FR/key-concepts.mdx index a249305285..3a416ae679 100644 --- a/packages/core/docs/content/locales/fr-FR/key-concepts.mdx +++ b/packages/core/docs/content/locales/fr-FR/key-concepts.mdx @@ -1,31 +1,35 @@ --- title: "Concepts clés" -description: "Fonctionnement des applications natives d'agent : actions en premier, base de données SQL, boucle application-agent, UI en option, synchronisation d'interrogation, points d'entrée d'agent externe, prise en compte du contexte et portabilité." +description: "Comment les applications agent-native fonctionnent à travers trois couches : le framework Core, les briques Toolkit facultatives et les Templates facultatifs, ainsi que les actions partagées, la base de données SQL, la boucle application-agent et les règles de portabilité." --- # Concepts clés -Comment fonctionnent les applications natives pour agents : principes et architecture. Cette page est le contrat ; pour la vision et les arguments en faveur de la construction de cette façon, voir [What Is Agent-Native?](/docs/what-is-agent-native). +Fonctionnement des applications agent-native en coulisses : les principes et l'architecture. Cette page est le contrat : les règles fixes qu'une application doit respecter pour être considérée comme agent-native. Pour la vision et les arguments en faveur de cette approche, voir [Qu'est-ce qu'Agent-Native ?](/docs/what-is-agent-native). ## Les trois couches {#three-layers} -Agent Native est un framework, pas un modèle unique : +Agent Native est un framework composé de trois couches : -- **Core - le framework :** le contrat fondamental d’exécution et de données pour toute application. -- **Toolkit - des briques réutilisables facultatives :** des interfaces et systèmes produit partagés que les applications peuvent adopter, composer ou forker. -- **Templates - des applications facultatives :** des applications métier complètes construites sur Core, qui utilisent souvent Toolkit et peuvent être forkées et utilisées comme point de départ. +| Couche | Ce que c'est | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Core : le framework** | Le contrat d'exécution fondamental : actions, assistants SQL et Drizzle, authentification, état de l'application, exécution de l'agent, contrôles d'accès, routage et synchronisation en direct. Chaque application peut utiliser Core directement. | +| **Toolkit : briques réutilisables facultatives** | UI de construction d'application partagée et systèmes produit tels que primitives, éditeurs, partage, collaboration, paramètres et UX de l'agent. Les applications peuvent utiliser, composer ou forker les pièces dont elles ont besoin. | +| **Templates : applications facultatives construites sur Core** | Applications complètes et spécifiques à un domaine, avec routes, schéma, actions, instructions et identité visuelle. Les templates officiels et personnalisés utilisent couramment Toolkit, et peuvent être forkés et utilisés comme points de départ. | -Core est la base. Toolkit et les templates sont facultatifs. +Core est la base. Toolkit et Templates sont facultatifs : un template peut utiliser Toolkit, mais Toolkit n'est pas nécessaire pour construire une application sur Core. ## L'architecture {#the-architecture} -Chaque application native pour agent est composée de trois éléments qui fonctionnent ensemble : +À l'exécution, chaque application agent-native est composée de trois éléments qui fonctionnent ensemble : -- **Agent** – IA autonome qui lit et écrit des données, exécute des actions et utilise les outils configurés. Personnalisable avec skills et instructions. -- **Application** — Surface du produit autour de l'agent. Il peut s'agir au début d'une action uniquement, d'un chat riche, d'un petit plan de contrôle ou d'un UI React complet avec des tableaux de bord, des flux et des visualisations. -- **Ordinateur** — Base de données, navigateur, exécution de code. Les agents travaillent via la surface d'actions et de données de l'application ; l'application peut exposer cette même surface via MCP. Les serveurs MCP externes restent des modules complémentaires facultatifs, et non la base. +- **Agent :** l'IA autonome. Elle lit des données, écrit des données, exécute des actions et utilise les outils configurés. Lorsque son cadre reçoit intentionnellement un accès à l'espace de travail et des outils d'écriture, elle peut aussi modifier le code source de l'application elle-même. Personnalisable avec des skills et des instructions. +- **Application :** la surface produit autour de l'agent. Elle peut commencer par du chat, ajouter des résultats natifs en ligne, évoluer vers un petit plan de contrôle, ou devenir une UI React complète avec tableaux de bord, flux et visualisations. +- **Ordinateur :** la base de données, le navigateur et les environnements d'exécution d'outils configurés à travers lesquels l'agent agit. Les agents travaillent via la surface d'actions et de données propre à l'application ; cette même surface peut être exposée en option via MCP, mais les serveurs MCP externes restent un module complémentaire, pas le socle. - +Le diagramme ci-dessous montre l'agent et l'application côte à côte, chacun avec des flèches bidirectionnelles vers une même couche ordinateur partagée en dessous. Aucun des deux ne possède les données. Ils lisent et écrivent plutôt le même magasin SQL, si bien qu'un changement effectué par l'un des deux est immédiatement visible pour l'autre, sans couche de synchronisation à construire entre les deux. + + ```html
@@ -33,14 +37,14 @@ Chaque application native pour agent est composée de trois éléments qui fonc
Agentlit et écrit des données, exécute des actions et utilise les outils + >lit et écrit des données, exécute des actions, utilise les outils configurés
Applicationaction-only, chat, control plane, or full UI Reactchat, résultats en ligne, plan de contrôle, ou UI React complète
@@ -48,8 +52,8 @@ Chaque application native pour agent est composée de trois éléments qui fonc ↓ ↑
- Computer
base de données SQL · browser · code executionbase de données SQL · navigateur · exécution de code
@@ -87,87 +91,108 @@ Chaque application native pour agent est composée de trois éléments qui fonc -Les applications Headless peuvent exécuter la même boucle application-agent de production à partir du dossier avec `pnpm agent`, tandis que les applications UI montent le panneau d'agent intégré et s'exécutent localement avec `pnpm dev`. Dans le cloud, Builder.io fournit un cadre géré (l'environnement qui héberge l'agent à côté de votre application) avec collaboration, édition visuelle et infrastructure gérée pour les équipes. +Cette même boucle agent-application-ordinateur est ce qui s'exécute en local et en production. Les applications automation-first l'exécutent directement depuis le dossier avec `pnpm agent` ; les applications UI montent le panneau d'agent intégré et ajoutent `pnpm dev`. Dans le cloud, Builder.io héberge la même boucle sous forme de cadre géré : l'environnement qui exécute l'agent à côté de votre application. Il gère la collaboration, l'édition visuelle et l'infrastructure pour vous. -## Blocs de construction des agents {#agent-building-blocks} +## Blocs de construction de l'agent {#agent-building-blocks} -Chaque application native d'agent possède les mêmes éléments de base d'agent, que -la surface du produit est sans tête, avec conversation d'abord ou UI complète : +Chaque application agent-native possède les mêmes blocs de construction d'agent, que +la surface produit soit chat-first, automation-first, ou une UI complète. Chacun vit +dans son propre fichier : /SKILL.md", - note: "Comportement réutilisable : étapes de workflow, politiques, exemples, références et listes à faire/ne pas faire", + note: "comportement réutilisable : étapes de workflow, politiques, exemples, références et listes à faire/à ne pas faire", }, { path: "actions/.ts", - note: "Capacité exécutable : opération typée exposée à l'agent, UI, CLI, HTTP, MCP, A2A, jobs et webhooks", + note: "capacité exécutable : opération typée exposée à l'agent, à l'UI, au CLI, à l'HTTP, MCP, A2A, aux jobs et aux webhooks", }, ]} /> -| Bloc de base | Utilisez-le pour | Chargé quand | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | -| **Instructions** | Aide stable que l'agent doit apporter dans chaque tâche : qu'est-ce que l'application, invariants, ton, index | Chaque tour | -| **Skills** | Comportement réutilisable : comment suivre un flux de travail, appliquer une politique, inspecter des preuves ou vérifier un résultat | Sur demande lorsque la description de la compétence correspond à la tâche | -| **Actions** | Opérations réelles : lire ou écrire des données, appeler des API, envoyer des messages, exécuter des approbations, produire des résultats saisis | Répertorié comme outils à chaque tour ; exécuté uniquement lorsqu'il est appelé | +Un tour est un échange avec l'agent : il lit son contexte, décide quoi faire, puis répond. « Chargé à chaque tour » signifie que le fichier réintègre ce contexte à chaque fois, pas seulement une fois au début de la session. + +| Bloc de base | Fichier | À utiliser pour | Chargé quand | +| ---------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | +| **Instructions** | `AGENTS.md` | Directive stable que l'agent doit porter dans chaque tâche : ce qu'est l'application, les invariants, le ton, les index | Chaque tour | +| **Skills** | `.agents/skills//SKILL.md` | Comportement réutilisable : comment suivre un workflow, appliquer une politique, inspecter des preuves ou vérifier un résultat | À la demande, lorsque la description du skill correspond à la tâche | +| **Actions** | `actions/.ts` | Opérations réelles : lire ou écrire des données, appeler des API, envoyer des messages, exécuter des approbations, produire des résultats typés | Listées comme outils à chaque tour ; exécutées seulement quand elles sont appelées | -Skills et actions fonctionnent ensemble. Une compétence apprend à l'agent comment effectuer un cours de -travail ; une action est le chemin de code qu'elle peut appeler lors de l'exécution de ce travail. Par exemple, -une compétence `customer-research` peut indiquer à l'agent quelles sources inspecter et -comment résumer les preuves, pendant que `search-crm` et `create-brief` actions récupèrent -et écrivez les données réelles. +Skills et actions fonctionnent ensemble. Un skill apprend à l'agent comment réaliser +une catégorie de travail ; une action est le chemin de code qu'il peut appeler en +réalisant ce travail. Par exemple, un skill `customer-research` peut indiquer à +l'agent quelles sources inspecter et comment résumer les preuves, tandis que les +actions `search-crm` et `create-brief` récupèrent et écrivent les données réelles. -Cinq règles régissent l'architecture : +Cinq règles régissent l'architecture : -1. **Les données se trouvent dans SQL** — tous les états de l'application se trouvent dans la base de données via Drizzle ORM -2. **Toute l'IA passe par l'agent** — aucun appel LLM en ligne -3. **Actions pour les opérations d'agent** — les travaux complexes s'exécutent en tant que actions -4. **La synchronisation en direct maintient le UI synchronisé** — les modifications de la base de données sont diffusées sur le SSE avec l'interrogation comme solution de secours universelle -5. **L'état de l'application est dans SQL** — l'état UI éphémère vit dans la base de données et est lisible par l'agent et l'UI +1. **Les données vivent dans SQL :** tout l'état de l'application vit dans la base de données via Drizzle ORM. +2. **Toute l'IA passe par l'agent :** aucun appel LLM en ligne ; chaque interaction IA transite par le pont de chat de l'agent. +3. **Des actions pour les opérations de l'agent :** le travail complexe s'exécute sous forme d'action typée, pas de code en ligne. +4. **La synchronisation en direct garde l'UI synchronisée :** les changements de base de données sont diffusés en flux via SSE, avec l'interrogation comme solution de repli universelle. +5. **L'état de l'application dans SQL :** l'état éphémère de l'UI vit dans la base de données, lisible à la fois par l'agent et l'UI. ## La liste de contrôle en quatre domaines {#four-area-checklist} -Chaque fonctionnalité destinée aux utilisateurs doit mettre à jour toutes les zones applicables. Ignorer une zone applicable rompt le contrat agent-natif ; forcer un UI sur une primitive d'action uniquement est aussi une odeur. +Chaque fonctionnalité destinée à l'utilisateur doit mettre à jour toutes les zones applicables. Ignorer une zone applicable rompt le contrat agent-native ; forcer un écran sur une automatisation qu'aucun humain n'a besoin de parcourir est également un signe révélateur. + +- **1. UI :** page, composant ou boîte de dialogue avec laquelle l'utilisateur interagit. +- **2. Action :** action appelable par l'agent dans `actions/` pour la même opération. +- **3. Skills :** mettre à jour `AGENTS.md` et/ou créer un skill documentant le pattern. +- **4. App-State :** état de navigation, données view-screen et commandes navigate. + +Une fonctionnalité avec uniquement une UI est invisible pour l'agent. Une fonctionnalité UI complète sans action correspondante est invisible pour l'utilisateur. Une fonctionnalité sans app-state signifie que l'agent est aveugle à ce que fait l'utilisateur. Une opération automation-first peut légitimement commencer par une action et des instructions, puis ajouter du chat, une UI ou de l'app-state plus tard, lorsque des humains ont besoin de la parcourir, de l'approuver, de la configurer ou de la partager. -| Zone | Description | -| ---------------------------- | ----------------------------------------------------------------------------- | -| **1. UI** | Page, composant ou boîte de dialogue avec lequel l'utilisateur interagit | -| **2. Action** | Action appelable par l'agent dans actions/ pour la même opération | -| **3. Skills** | Mettez à jour AGENTS.md et/ou créez une compétence documentant le modèle | -| **4. État de l'application** | État de navigation, données de l'écran d'affichage et commandes de navigation | +## Ce qu'Agent Native inclut {#what-you-get-for-free} -Une fonctionnalité avec uniquement UI est invisible pour l'agent. Une fonctionnalité UI complète avec uniquement actions est invisible pour l'utilisateur. Une fonctionnalité sans état d’application signifie que l’agent est aveugle à ce que fait l’utilisateur. Une opération sans tête peut légitimement commencer par une action + des instructions et ajouter UI/app-state plus tard lorsque des humains ont besoin de la parcourir, de l'approuver, de la configurer ou de la partager. +Adopter le framework est utile surtout pour ce que vous arrêtez de devoir construire. Dès que votre application suit les cinq règles ci-dessus, vous héritez de : -## Données dans SQL {#data-in-sql} +| Fonctionnalité | Ce que cela vous apporte | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Une action = toutes les surfaces | Chaque action définie avec `defineAction()` est simultanément un outil d'agent, un hook frontend typesafe (`useActionQuery` / `useActionMutation`), un transport HTTP appartenant au framework, une commande CLI, un outil MCP pour les clients externes, et un outil A2A pour les autres applications agent-native. Les métadonnées facultatives `link` et `mcpApp` ajoutent des liens profonds et une UI MCP Apps sans seconde implémentation. | +| Ressources d'agent complètes par utilisateur | Skills, `LEARNINGS.md` partagé, `memory/MEMORY.md` personnel, `AGENTS.md`, sous-agents personnalisés, jobs planifiés et serveurs MCP connectés. Le tout adossé à SQL, sans machine de développement nécessaire. Voir [Agent Resources](/docs/agent-resources). | +| Composants React prêts à l'emploi | `` et `` affichent le chat et les ressources n'importe où dans votre application. Voir [Drop-in Agent](/docs/drop-in-agent). | +| Environnements d'exécution de chat d'agent BYO | La même UI de chat peut reposer sur OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, ou votre propre flux HTTP normalisé. Voir [Chat natif UI](/docs/native-chat-ui#byo-agent-runtimes). | +| Synchronisation en direct entre l'agent et l'UI | Les écritures dans le même processus sont diffusées immédiatement via `/_agent-native/events` ; une interrogation légère maintient la convergence des écritures serverless, cron et inter-processus. Les actions de mutation invalident automatiquement les requêtes adossées aux actions, si bien que les enregistrements créés par l'agent apparaissent sans actualisation manuelle. Voir [Live Sync](#polling-sync) ci-dessous. | +| Auth, organisations, RBAC | Better Auth avec organisations/membres/rôles est intégré pour chaque template. Voir [Authentication](/docs/authentication). Pour plus d'un utilisateur, commencez par [Organizations, Teams & Permissions](/docs/organizations-teams-permissions). | +| Conscience du contexte | L'agent sait toujours ce que l'utilisateur regarde grâce à la clé d'app-state `navigation`. Voir [Conscience du contexte](/docs/context-awareness). | +| Client + serveur MCP, dans les deux sens | L'application ingère des serveurs MCP (locaux, distants, partagés par hub) _et_ expose ses propres actions en tant que serveur MCP. Voir [MCP Clients](/docs/mcp-clients) et [MCP Protocol](/docs/mcp-protocol). | +| Délégation inter-applications | Les agents de différentes applications communiquent via [A2A](/docs/a2a-protocol). Les déploiements de même origine se passent de JWT ; l'origine croisée utilise un `A2A_SECRET` partagé. | +| Équipes de sous-agents | Générez un sous-agent avec son propre fil et ses propres outils, présenté sous forme de puce en ligne dans le chat. Voir [Agent Teams](/docs/agent-teams). | +| Portabilité | N'importe quelle base de données SQL prise en charge par Drizzle, n'importe quel hôte compatible Nitro (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). | -Tous les états de l'application se trouvent dans une base de données SQL avec Drizzle ORM. Les schémas sont indépendants du fournisseur ; les bases de données prises en charge, la configuration `DATABASE_URL` et les règles de portabilité résident dans [Database](/docs/database). +## Données en SQL {#data-in-sql} -Les magasins Core SQL sont créés automatiquement et disponibles dans chaque modèle : +Tout l'état de l'application vit dans une base de données SQL via Drizzle ORM. Les schémas sont indépendants du fournisseur ; les bases de données prises en charge, la configuration `DATABASE_URL` et les règles de portabilité se trouvent dans [Database](/docs/database). -- `application_state` — état éphémère UI (navigation, brouillons, sélections) -- `settings` — configuration clé-valeur persistante -- `oauth_tokens` — Identifiants OAuth -- `sessions` — sessions d'authentification +Les magasins SQL Core sont créés automatiquement et disponibles dans chaque template : + +- `application_state` : état UI éphémère (navigation, brouillons, sélections) +- `settings` : configuration clé-valeur persistante +- `oauth_tokens` : identifiants OAuth +- `sessions` : sessions d'authentification + +Chaque ligne ci-dessous se déploie pour afficher ses champs : +Pour ajouter vos propres données de domaine, définissez une table avec les mêmes assistants de schéma que ceux utilisés par les magasins core ci-dessus : + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -246,28 +273,30 @@ export const forms = table("forms", { }); ``` +Vous et l'agent pouvez tous deux inspecter ces données depuis le terminal, sans client SQL séparé : + ```bash -# Actions de base pour une inspection rapide de la base de données +# Actions Core pour une inspection rapide de la base de données pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -Le plug-in de chat de l'agent de production met les outils SQL bruts en lecture seule par défaut -(`frameworkTools: { database: "read" }`), donc les agents inspectent les données avec `db-schema` / -`db-query` et écrivent via les actions typées de l'application. Définissez -`database: "write"` (ou `true`) seulement pour les surfaces de maintenance -qui doivent exposer `db-exec` / `db-patch`; utilisez -`database: "off"` / `false` pour exiger des actions typées pour toutes les données -accès. +`db-schema` affiche les colonnes et types de chaque table. `db-query` exécute du SQL en lecture seule directement, ce qui est utile pour vérifier les écritures d'une action sans ouvrir de client de base de données. + + + +Le plug-in de chat de l'agent de production met les outils SQL bruts en lecture seule par défaut (`frameworkTools: { database: "read" }`), donc les agents inspectent les données avec `db-schema` / `db-query` et écrivent via les actions typées de l'application. Définissez `database: "write"` (ou `true`) seulement pour les surfaces de maintenance qui doivent exposer `db-exec` / `db-patch`; utilisez `database: "off"` / `false` pour exiger des actions typées pour tout accès aux données. `frameworkTools` gouverne de la même façon les autres outils propres au framework : partage, commentaires de revue, historique de versions, feature flags, localisation, audit, Context X-Ray, profil, automatisations, docs, resources, web, délégation inter-apps, chat et email. Voir [Production Agent Tools](/docs/deployment#production-agent-tools) pour la liste complète, le preset `"minimal"` et pourquoi désactiver un groupe laisse ses routes HTTP montées. + + ## Pont de discussion pour les agents {#agent-chat-bridge} -Le UI n’appelle jamais directement un LLM. Lorsqu'un utilisateur clique sur « Générer un graphique » ou « Écrire un résumé », le UI envoie un message à l'agent via `postMessage`. L'agent fait le travail – avec un historique complet des conversations, skills, des instructions et la possibilité d'itérer. +L'UI n'appelle jamais un LLM directement. Lorsqu'un utilisateur clique sur « Générer un graphique » ou « Rédiger un résumé », l'UI envoie un message à l'agent via `postMessage`. L'agent effectue le travail. Il dispose de l'historique complet de la conversation, des skills, des instructions et de la capacité d'itérer. ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -276,16 +305,19 @@ sendToAgentChat({ }); ``` -Pourquoi ne pas appeler un LLM en ligne ? +En bref : + +- **L'IA est non déterministe** : vous avez besoin d'un flux de conversation pour donner du feedback et itérer, pas de boutons à usage unique. +- **Le contexte compte** : l'agent dispose des instructions, des skills et de l'historique de l'application. Un appel en ligne n'a rien de tout cela. +- **L'agent peut faire plus** : il peut exécuter des actions, naviguer sur le web et enchaîner plusieurs étapes. -- **L'IA n'est pas déterministe.** Vous avez besoin d'un flux de conversation pour donner votre avis et itérer, et non de boutons ponctuels. -- **Le contexte est important.** L'agent dispose de votre base de code complète, de vos instructions, de skills et de votre historique. Un appel en ligne n'a rien de tout cela. -- **L'agent peut faire plus.** Il peut exécuter des actions, parcourir le Web et enchaîner plusieurs étapes. -- **Exécution sans tête.** Comme tout passe par l'agent, n'importe quelle application peut être entièrement pilotée depuis Slack, Telegram ou un autre agent via [A2A](/docs/a2a-protocol). +**[Exécution externe](/docs/a2a-protocol)** -## Système Actions {#actions-system} +Comme tout passe par l'agent et les actions, n'importe quelle application peut être pilotée depuis Slack, Telegram, des jobs planifiés, des scripts, ou un autre agent via A2A. -Lorsque l'agent doit effectuer quelque chose de complexe (appeler un API, traiter des données, interroger la base de données), il exécute une **action**. Actions sont des fichiers TypeScript dans `actions/` qui exportent un `defineAction()` par défaut : +## Système d'actions {#actions-system} + +Lorsque l'agent doit faire quelque chose de complexe, comme appeler une API, traiter des données ou interroger la base de données, il exécute une **action**. Les actions sont des fichiers TypeScript dans `actions/` qui exportent un `defineAction()` par défaut : ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -303,19 +335,30 @@ export default defineAction({ }); ``` -Un appel `defineAction()` vous donne : +Cette action récupère du JSON depuis une API source et le retourne. `defineAction()` encapsule la fonction avec un schéma zod pour son entrée (`source`), afin que le framework puisse valider cette entrée, générer un schéma JSON que l'agent peut appeler, et inférer les types pour le hook frontend, le tout à partir de cette seule définition. + +Un seul appel à `defineAction()` atteint automatiquement cinq consommateurs différents. Le diagramme montre l'éventail à partir d'une seule action ; la liste ci-dessous explique ce que reçoit chaque consommateur : + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **Outil d'agent** : l'agent le voit avec le schéma JSON dérivé de zod et peut l'appeler. -- **Hook frontal** — `useActionMutation("fetch-data")` avec inférence TypeScript complète. -- **Framework transport** — monté automatiquement derrière les hooks client. -- **CLI** — `pnpm action fetch-data --source=signups` pour les boucles de script et de développement d'agent. -- **Outil MCP / Outil A2A** — lorsque le serveur MCP ou A2A est activé, la même action s'affiche également. +- **Outil d'agent :** l'agent le voit avec le schéma JSON dérivé de zod et peut l'appeler. +- **Hook frontend :** `useActionMutation("fetch-data")` avec inférence TypeScript complète. +- **Transport du framework :** monté automatiquement derrière les hooks client. +- **CLI :** `pnpm action fetch-data --source=signups` pour le scripting et les boucles de développement de l'agent. +- **Outil MCP / outil A2A :** lorsque le serveur MCP ou A2A est activé, la même action y apparaît également. -Même logique, une définition, connectée automatiquement à chaque consommateur. Voir [Actions](/docs/actions) pour la référence complète. +Chaque consommateur appelle la même fonction sous-jacente, il n'y a donc qu'une seule implémentation à écrire et à maintenir. Voir [Actions](/docs/actions) pour la référence complète. ## Synchronisation en direct {#polling-sync} -Les modifications de la base de données sont synchronisées avec le UI via `useDbSync()`. Le même processus écrit le flux sur `/_agent-native/events` ; `/_agent-native/poll` reste la solution de secours inter-processus et sans serveur. Lorsque l'agent écrit dans la base de données (état de l'application, paramètres ou données de domaine), un compteur de version s'incrémente et le client invalide les caches de requête React pertinents. +Lorsque l'agent modifie des données, l'UI doit le refléter sans actualisation manuelle. C'est `useDbSync()` qui rend cela automatique. Les écritures dans le même processus sont diffusées via `/_agent-native/events` ; `/_agent-native/poll` reste la solution de repli inter-processus et serverless. Lorsque l'agent écrit dans la base de données (état de l'application, settings ou données de domaine), un compteur de version s'incrémente et le client invalide les caches React Query pertinents. ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -323,37 +366,39 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` -Le flux est : +Appelez-le une fois, près de la racine de l'application. Cela abonne toute l'application aux événements de changement, si bien que tout composant utilisant `useActionQuery` ou un `useQuery` versionné par source se rafraîchit automatiquement lorsque les données qu'il lit changent. + +Le flux est : 1. L'agent exécute une action qui écrit dans la base de données 2. Le serveur émet un événement de changement avec une source telle que `"action"` ou `"settings"` -3. `useDbSync` le reçoit via SSE ou le secours d'interrogation -4. Récupération des hooks `useActionQuery` et des hooks `useQuery` avec version source +3. `useDbSync` le reçoit via SSE ou la solution de repli d'interrogation +4. Les hooks `useActionQuery` et les hooks `useQuery` versionnés par source se rafraîchissent 5. Les composants affichent les nouvelles données sans rechargement de page - +Le diagramme retrace cette même séquence de bout en bout : + + ```html
- Action d’agent
écrit en base de données + Action d'agent
écrit en base
Événement de changement
source: action / settingssource : action / settings
useDbSyncSSE · poll fallback + >SSE · repli par interrogation
- Relance de requête
rendu, sans rechargement
@@ -382,89 +427,90 @@ Le flux est : -Cela fonctionne dans tous les environnements de déploiement, y compris sans serveur et en périphérie, car il utilise la base de données, et non les observateurs d'état en mémoire ou du système de fichiers. +Cela fonctionne dans tous les environnements de déploiement, y compris serverless et edge, car cela utilise la base de données plutôt que l'état en mémoire ou les observateurs de système de fichiers. ## Cadres {#frames} -Un _frame_ est l'environnement qui héberge l'agent à côté de votre application ; localement, il s'agit du panneau intégré ; dans le cloud, c'est la surface gérée de Builder.io. Voir [Frames](/docs/frames). +Un _cadre_ est l'environnement qui héberge l'agent à côté de votre application. En local, c'est le panneau intégré ; dans le cloud, c'est la surface gérée de Builder.io. Voir [Frames](/docs/frames). -Les applications natives d'agent incluent un panneau d'agent intégré qui fournit l'agent IA ainsi que l'application UI. C'est ce qui fait fonctionner l'architecture : l'agent a besoin d'un ordinateur (base de données, navigateur, exécution de code) et l'application a besoin de l'agent pour le travail de l'IA. +Les applications agent-native incluent un panneau d'agent intégré qui fournit l'agent IA aux côtés de l'UI de l'application. C'est ce qui fait fonctionner l'architecture : l'agent a besoin d'un ordinateur (base de données, navigateur, exécution de code), et l'application a besoin de l'agent pour le travail d'IA. -- **Panneau d'agent intégré** — Chat et terminal CLI en option intégrés à chaque application. Prend en charge le code Claude, Codex, Gemini, OpenCode et Builder.io. Fonctionne localement. Gratuit et open source. -- **Cloud** : déployez sur n'importe quel cloud avec une collaboration en temps réel, une édition visuelle, des rôles et des autorisations. Idéal pour les équipes. +- **Panneau d'agent intégré :** chat et terminal CLI optionnel intégrés à chaque application. Prend en charge Claude Code, Codex, Gemini, OpenCode et Builder.io. S'exécute en local, gratuit et open source. +- **Cloud :** déployez sur n'importe quel cloud avec collaboration en temps réel, édition visuelle, rôles et permissions. Idéal pour les équipes. ## Conscience du contexte {#context-awareness} -L'agent sait toujours ce que l'utilisateur regarde. Le UI écrit une clé `navigation` dans l'état de l'application à chaque changement d'itinéraire. L'agent le lit via l'action `view-screen` avant d'agir. +L'agent sait toujours ce que l'utilisateur regarde. L'UI écrit une clé `navigation` dans l'application-state à chaque changement de route. L'agent la lit via l'action `view-screen` avant d'agir. -Par exemple, lorsque vous ouvrez un fil de discussion de courrier électronique, le UI insère une ligne comme : +Par exemple, lorsque vous ouvrez un fil d'e-mail, l'UI fait un upsert d'une ligne comme : ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -Le UI écrit ceci lors du changement d'itinéraire ; l'agent le lit (via `view-screen`) avant d'entreprendre toute action, afin qu'il sache toujours sur quel fil de discussion (ou graphique ou diapositive) vous vous concentrez. + + +L'UI écrit ceci à chaque changement de route ; l'agent la lit (via `view-screen`) avant d'entreprendre toute action, de sorte qu'il sait toujours sur quel fil, graphique ou diapositive vous êtes concentré. -Voir [Context Awareness](/docs/context-awareness) pour le modèle complet : état de navigation, écran d'affichage, commandes de navigation et prévention de l'instabilité. + + +Voir [Conscience du contexte](/docs/context-awareness) pour le pattern complet : état de navigation, view-screen, commandes navigate et prévention du jitter. ## Une action, plusieurs surfaces {#protocols} -Implémenter une opération de domaine une fois en tant qu'action ; le cadre l'expose à chaque consommateur. Le même `defineAction()` devient un outil d'agent, un hook UI de sécurité de type, un point de terminaison HTTP, une commande CLI, un outil MCP et un outil A2A, avec en option des métadonnées `link`, `mcpApp` ou explicites de widget natif ajoutées uniquement lorsqu'une surface en a besoin. Skills et les instructions couvrent le comportement. +Implémentez une opération de domaine une seule fois sous forme d'action ; le framework l'expose à tous les consommateurs. Le même `defineAction()` devient un outil d'agent, un hook UI typesafe, un endpoint HTTP, une commande CLI, un outil MCP et un outil A2A, avec des métadonnées optionnelles `link`, `mcpApp`, de widget natif, ou des wrappers Generative UI ajoutés uniquement lorsqu'une surface a besoin d'une interaction plus riche. Les skills et les instructions couvrent le comportement. -Pour la matrice complète de protocole/surface (serveur MCP et applications OAuth, MCP, A2A, liens profonds, widgets de discussion natifs, connecteurs AgentChatRuntime, agent Web et horizon d'adaptateur pour ACP et A2UI), et pour choisir une forme de produit (sans tête, chat riche, side-car intégré ou application complète), voir [Agent Surfaces](/docs/agent-surfaces). +Pour la matrice complète des protocoles/surfaces (serveur MCP et OAuth, MCP Apps, A2A, liens profonds, widgets de chat natifs, Generative UI, connecteurs AgentChatRuntime, Agent Web, et l'horizon d'adaptateurs pour ACP et A2UI), et pour choisir une forme de produit (chat, UI en ligne, pages d'application complètes, sidecar intégré, automatisation ou accès agent externe), voir [Surfaces d'agent](/docs/agent-surfaces). ## Code de l'application et personnalisation {#agent-modifies-code} -L'agent intégré ne modifie pas le code source par défaut. Il ne peut le faire -que si l'hôte lui accorde intentionnellement des outils d'écriture -repository/workspace. Dans une application déployée ordinaire, l'agent agit via -les actions, l'état stocké en SQL et les intégrations configurées. Les -templates sont des applications complètes que vous pouvez forker et -personnaliser dans votre propre dépôt et votre flux de développement. +Le framework n'accorde pas à l'agent intégré un accès ambiant au code source de l'application. Dans une application déployée, l'agent travaille normalement via les actions, l'état adossé à SQL et les intégrations configurées. Il peut modifier des composants, des routes, des styles et des actions lorsque son cadre reçoit intentionnellement l'accès à l'espace de travail et des outils d'écriture. Les templates sont des applications complètes que vous pouvez forker et personnaliser dans votre propre dépôt et flux de développement, dans tous les cas. Pour une personnalisation à l'exécution sans modification du code source, utilisez [Extensions](/docs/extensions). ## Portable par défaut {#hosting-agnostic} -Deux règles architecturales garantissent la portabilité des applications entre les bases de données et les hôtes : +Deux règles architecturales garantissent la portabilité des applications entre bases de données et hébergeurs : -- **Agnostique de base de données.** Écrivez des schémas avec `@agent-native/core/db/schema` et lit/écrit avec la requête portable DSL de Drizzle afin que le même code s'exécute sur n'importe quel fournisseur pris en charge. Utilisez le SQL brut uniquement pour les migrations additives ou la maintenance ponctuelle, conservé paramétré et indépendant du dialecte. Voir [Database](/docs/database). -- **Agnostique en matière d'hébergement.** Le serveur s'exécute sur Nitro et se compile sur n'importe quelle cible de déploiement. N'utilisez jamais de API spécifiques au nœud (`fs`, `child_process`, `path`) dans les routes de serveur ou les plugins, et ne supposez jamais un processus de serveur persistant : le sans serveur et le Edge sont sans état, conservez donc tous les états dans SQL. Voir [Deployment](/docs/deployment). +- **Indépendant de la base de données.** Écrivez les schémas avec `@agent-native/core/db/schema` et les lectures/écritures avec le DSL de requête portable de Drizzle, afin que le même code s'exécute sur n'importe quel fournisseur pris en charge. N'utilisez du SQL brut que pour des migrations additives ou de la maintenance ponctuelle, en le gardant paramétré et indépendant du dialecte. Voir [Database](/docs/database). +- **Indépendant de l'hébergement.** Le serveur s'exécute sur Nitro et se compile vers n'importe quelle cible de déploiement. N'utilisez jamais d'API spécifiques à Node (`fs`, `child_process`, `path`) dans les routes ou plugins serveur, et ne supposez jamais un processus serveur persistant. Serverless et edge sont sans état, gardez donc tout l'état dans SQL. Voir [Deployment](/docs/deployment). -## Espace de travail {#workspace} +## Agent Resources {#workspace} -Chaque utilisateur dispose d'un **espace de travail** personnel (instructions, skills, mémoire, sous-agents personnalisés, tâches planifiées et serveurs MCP connectés), le tout stocké dans SQL plutôt que dans des fichiers. Cela rend la personnalisation au niveau du code Claude viable dans un SaaS multi-tenant sans créer de conteneur par utilisateur. Voir [Ressources de l'agent](/docs/agent-resources). +Chaque utilisateur dispose d'un ensemble personnel de **ressources d'agent** : instructions, skills, mémoire, sous-agents personnalisés, jobs planifiés et serveurs MCP connectés, le tout stocké dans SQL plutôt que dans des fichiers. Cela rend viable une personnalisation de niveau Claude Code au sein d'un SaaS multi-tenant sans avoir à lancer un conteneur par utilisateur. Voir [Agent Resources](/docs/agent-resources). ## Blocs de construction associés {#building-blocks} -Ceux-ci se trouvent au-dessus du même contrat et ont leurs propres détails : +Ceux-ci reposent sur le même contrat et ont leurs propres approfondissements : + +- **[Dispatch](/docs/dispatch) :** le plan de contrôle de l'espace de travail, avec une boîte de réception partagée, un coffre-fort de secrets, des jobs planifiés et un orchestrateur qui délègue à des applications spécialisées via A2A. +- **[Extensions](/docs/extensions) :** mini-applications Alpine.js en bac à sable que l'agent crée à l'exécution, sans modification du code source ni migrations. +- **[Protocole A2A](/docs/a2a-protocol) :** comment les applications d'un même espace de travail se découvrent et s'appellent mutuellement via JSON-RPC. -- **[Dispatch](/docs/dispatch)** : le plan de contrôle de l'espace de travail : boîte de réception partagée, coffre-fort de secrets, tâches planifiées et orchestrateur qui délègue à des applications spécialisées via A2A. -- **[Extensions](/docs/extensions)** : mini-applications Alpine.js en bac à sable que l'agent crée au moment de l'exécution, sans modification ni migration de la source. -- **[Programmes de données](/docs/data-programs)** : scripts `run-code` stockés et rédigés par l'agent qui fournissent aux panneaux de dashboard un résultat mis en cache et actualisable, au lieu d'une action de fournisseur codée en dur. -- **[A2A Protocol](/docs/a2a-protocol)** : comment les applications du même espace de travail se découvrent et s'appellent via JSON-RPC. +## Et ensuite {#deep-dives} -## Ce que vous obtenez gratuitement {#what-you-get-for-free} + -L'adoption du framework est utile principalement en raison de ce que vous n'avez plus à construire. Dès que votre application suit les cinq règles, vous héritez : +### [Qu'est-ce qu'Agent-Native ?](/docs/what-is-agent-native) -- **Une action = chaque surface.** Chaque action définie avec `defineAction()` est simultanément un outil d'agent, un hook frontal de type sécurisé (`useActionQuery` / `useActionMutation`), un transport HTTP appartenant au framework, une commande CLI, un outil MCP pour les clients externes et un outil A2A pour d'autres applications natives d'agent. Les métadonnées facultatives `link` et `mcpApp` ajoutent des liens profonds et des applications MCP UI sans seconde implémentation. -- **Un espace de travail complet par utilisateur.** Skills, `LEARNINGS.md` partagé, `memory/MEMORY.md` personnel, `AGENTS.md`, sous-agents personnalisés, tâches planifiées, serveurs MCP connectés — tous soutenus par SQL, aucune boîte de développement requise. Voir [Ressources de l'agent](/docs/agent-resources). -- **Composants React intégrés.** `` et `` affichent le chat et l'espace de travail n'importe où dans votre application. Voir [Drop-in Agent](/docs/drop-in-agent). -- **Environnements d'exécution du chat de l'agent BYO.** Le même chat UI peut s'asseoir au-dessus des agents OpenAI, des réponses OpenAI, de l'agent Claude SDK, de Vercel AI SDK, AG-UI ou de votre propre flux HTTP normalisé. Voir [Native Interface de chat](/docs/native-chat-ui#byo-agent-runtimes). -- **Synchronisation en direct entre l'agent et UI.** Le même processus écrit le flux immédiatement sur `/_agent-native/events` ; un sondage léger maintient la convergence des écritures sans serveur, cron et inter-processus. La mutation de actions invalide automatiquement les requêtes basées sur des actions, de sorte que les enregistrements créés par l'agent apparaissent sans actualisation manuelle. Voir [Live Sync](#polling-sync) ci-dessous. -- **Auth, orgs, RBAC.** Une meilleure authentification avec les organisations/membres/rôles est intégrée pour chaque modèle. Voir [Authentication](/docs/authentication). -- **Conscience du contexte.** L'agent sait toujours ce que l'utilisateur regarde grâce à la clé d'état de l'application `navigation`. Voir [Context Awareness](/docs/context-awareness). -- **Client + serveur MCP, dans les deux sens.** L'application ingère les serveurs MCP (locaux, distants, partagés par hub) _et_ expose son propre actions en tant que serveur MCP. Voir [MCP Clients](/docs/mcp-clients) et [MCP Protocol](/docs/mcp-protocol). -- **Délégation inter-applications.** Les agents de différentes applications parlent via [A2A](/docs/a2a-protocol). Les déploiements de même origine ignorent JWT ; l'origine croisée utilise un `A2A_SECRET` partagé. -- **Équipes de sous-agents.** Générez un sous-agent avec son propre fil de discussion et ses propres outils, présenté sous la forme d'une puce en ligne dans le chat. Voir [Agent Teams](/docs/agent-teams). -- **Portabilité.** Toute base de données SQL prise en charge par Drizzle, tout hôte compatible Nitro (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). +La vision et la philosophie derrière ces règles. -C'est le "et tout le reste" que vous seriez autrement en train de coller vous-même. +### [Conscience du contexte](/docs/context-awareness) -## Et ensuite {#deep-dives} +État de navigation, view-screen et commandes navigate en détail. + +### [Guide Skills](/docs/skills-guide) + +Skills du framework, skills de domaine, et création de skills personnalisés. + +### [Chat natif UI](/docs/native-chat-ui) + +Tableaux et graphiques déclarés par les actions, et posture d'exécution BYO. + +### [Surfaces d'agent](/docs/agent-surfaces) + +Chat, UI native en ligne, pages d'application complètes, sidecar intégré, automatisation et parcours d'agent externe. + +### [Protocole A2A](/docs/a2a-protocol) + +Communication agent à agent. -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — la vision et la philosophie qui sous-tendent ces règles -- [**Context Awareness**](/docs/context-awareness) — l’état de navigation et les commandes view-screen et navigate en détail -- [**Skills Guide**](/docs/skills-guide) — les skills du framework et du domaine, et la création de skills personnalisées -- [**Native Chat UI**](/docs/native-chat-ui) — les tableaux et graphiques déclarés par actions, et la prise en charge des environnements d’exécution personnalisés -- [**Agent Surfaces**](/docs/agent-surfaces) — le chat, l’UI native intégrée, les pages d’application complètes, le sidecar intégré, l’automatisation et les parcours d’agents externes -- [**A2A Protocol**](/docs/a2a-protocol) — la communication entre agents + diff --git a/packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx b/packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx index 3af84b755b..a7d1aad4e2 100644 --- a/packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx @@ -1,10 +1,10 @@ --- -title: "Agent Surfaces" +title: "एजेंट Surfaces" description: "चुनें कि एक एजेंटिक ऐप चैट से इनलाइन UI, टिकाऊ ऐप पेज, एम्बेडेड साइडकार, ऑटोमेशन और बाहरी एजेंट एक्सेस तक कैसे बढ़ता है।" search: "agentic app rich chat native chat UI full app automation headless BYO agent runtime AgentChatRuntime embed actions MCP A2A HTTP CLI" --- -# Agent Surfaces +# एजेंट Surfaces एक **surface** वह तरीका है जिससे उपयोगकर्ता (या अन्य सिस्टम) आपके ऐप के साथ इंटरैक्ट करते हैं: एक चैट विंडो, एक डैशबोर्ड पेज, एक बैकग्राउंड जॉब, किसी अन्य एजेंट से एक API कॉल। Agent-Native आपको इन्हें बिना अपनी मूल लॉजिक को फिर से बनाए मिक्स और मैच करने देता है, क्योंकि हर surface एक ही अंतर्निहित actions चलाता है। यदि आप Agent-Native में नए हैं, तो पहले [Key Concepts](/docs/key-concepts) पढ़ें। diff --git a/packages/core/docs/content/locales/hi-IN/key-concepts.mdx b/packages/core/docs/content/locales/hi-IN/key-concepts.mdx index ba1cf0e149..2f2da4efec 100644 --- a/packages/core/docs/content/locales/hi-IN/key-concepts.mdx +++ b/packages/core/docs/content/locales/hi-IN/key-concepts.mdx @@ -1,31 +1,35 @@ --- -title: "मुख्य अवधारणाएँ" -description: "एजेंट-नेटिव ऐप्स कैसे काम करते हैं: actions पहले, SQL डेटाबेस, ऐप-एजेंट लूप, वैकल्पिक UI, पोलिंग सिंक, बाहरी-एजेंट प्रवेश बिंदु, संदर्भ जागरूकता और पोर्टेबिलिटी।" +title: "मुख्य अवधारणाएं" +description: "agent-native ऐप्स तीन लेयर्स में कैसे काम करते हैं: Core framework, वैकल्पिक Toolkit बिल्डिंग ब्लॉक्स, और वैकल्पिक Templates, साथ ही shared actions, SQL database, app-agent लूप, और portability नियम।" --- -# मुख्य अवधारणाएँ +# मुख्य अवधारणाएं -एजेंट-नेटिव ऐप्स हुड के तहत कैसे काम करते हैं - सिद्धांत और वास्तुकला। यह पृष्ठ अनुबंध है; इस तरह से निर्माण की दृष्टि और मामले के लिए, [What Is Agent-Native?](/docs/what-is-agent-native) देखें। +अंदर से agent-native ऐप्स कैसे काम करते हैं: सिद्धांत और architecture। यह page वह contract है: वे तय नियम जिन्हें एक ऐप को agent-native गिने जाने के लिए follow करना होता है। इस तरह बनाने के vision और तर्क के लिए देखें [Agent-Native क्या है?](/docs/what-is-agent-native)। -## तीन परतें {#three-layers} +## तीन लेयर्स {#three-layers} -Agent Native एक framework है, कोई एक template नहीं: +Agent Native तीन लेयर्स वाला एक framework है: -- **Core - framework:** हर ऐप के लिए बुनियादी runtime और data contract। -- **Toolkit - वैकल्पिक पुन: उपयोग योग्य pieces:** साझा UI और product systems जिन्हें ऐप अपना, compose या fork कर सकते हैं। -- **Templates - वैकल्पिक apps:** Core पर बने पूर्ण domain apps, जो अक्सर Toolkit का उपयोग करते हैं और जिन्हें starting point के रूप में fork और उपयोग किया जा सकता है। +| लेयर | यह क्या है | +| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Core: framework** | मूल runtime contract: actions, SQL और Drizzle helpers, auth, application state, agent execution, access checks, routing, और live sync। हर ऐप सीधे Core का उपयोग कर सकता है। | +| **Toolkit: वैकल्पिक reusable पीस** | primitives, editors, sharing, collaboration, settings, और agent UX जैसे shared app-building UI और product systems। ऐप्स को जो पीस चाहिए उनका उपयोग, compose, या fork कर सकते हैं। | +| **Templates: Core पर बने वैकल्पिक ऐप्स** | routes, schema, actions, instructions, और visual identity वाले पूर्ण, डोमेन-specific ऐप्स। First-party और custom templates आमतौर पर Toolkit का उपयोग करते हैं, और starting points के रूप में fork करके इस्तेमाल किए जा सकते हैं। | -Core foundation है। Toolkit और Templates वैकल्पिक हैं। +Core नींव है। Toolkit और Templates वैकल्पिक हैं: एक template Toolkit का उपयोग कर सकता है, लेकिन Core पर ऐप बनाने के लिए Toolkit ज़रूरी नहीं है। -## वास्तुकला {#the-architecture} +## आर्किटेक्चर {#the-architecture} -प्रत्येक एजेंट-नेटिव ऐप तीन चीजें एक साथ काम करती हैं: +Runtime पर, हर agent-native ऐप तीन चीज़ें हैं जो साथ मिलकर काम करती हैं: -- **एजेंट** - स्वायत्त एआई जो डेटा पढ़ता है, डेटा लिखता है, actions चलाता है और configured tools का उपयोग करता है। skills और निर्देशों के साथ अनुकूलन योग्य। -- **अनुप्रयोग** - एजेंट के चारों ओर उत्पाद की सतह। यह पहली बार में केवल एक्शन, रिच चैट, एक छोटा नियंत्रण विमान, या डैशबोर्ड, प्रवाह और विज़ुअलाइज़ेशन के साथ एक पूर्ण React इंटरफेस हो सकता है। -- **कंप्यूटर** — डेटाबेस, ब्राउज़र, कोड निष्पादन। एजेंट ऐप की एक्शन और डेटा सतह के माध्यम से काम करते हैं; ऐप उसी एक्शन सतह को MCP के ज़रिए उपलब्ध करा सकता है। बाहरी MCP सर्वर वैकल्पिक ऐड-ऑन हैं, फाउंडेशन नहीं। +- **Agent:** स्वायत्त AI। यह data पढ़ता है, data लिखता है, actions चलाता है, और जो भी tools configured हैं उनका उपयोग करता है। जब इसके frame को जान-बूझकर workspace access और write tooling दी जाती है, तो यह ऐप के अपने source को भी modify कर सकता है। Skills और instructions के साथ customizable। +- **Application:** agent के इर्द-गिर्द product surface। यह chat के रूप में शुरू हो सकता है, native inline results जोड़ सकता है, एक छोटे control plane में बढ़ सकता है, या dashboards, flows, और visualizations वाला एक full React UI बन सकता है। +- **Computer:** database, browser, और configured tool runtimes जिनके ज़रिए agent काम करता है। Agents ऐप के अपने action और data surface के ज़रिए काम करते हैं; उसी surface को वैकल्पिक रूप से MCP पर expose किया जा सकता है, लेकिन external MCP servers एक add-on ही रहते हैं, foundation नहीं। - +नीचे दिया diagram agent और application को साथ-साथ दिखाता है, दोनों के नीचे एक shared computer layer में जाने वाले two-way arrows के साथ। दोनों में से कोई भी data का owner नहीं है। इसके बजाय, वे same SQL store को पढ़ते और लिखते हैं, इसलिए कोई भी side जो change करता है वह तुरंत दूसरे को दिखाई देता है, और बीच में कोई sync layer बनाने की ज़रूरत नहीं। + + ```html
@@ -33,14 +37,14 @@ Core foundation है। Toolkit और Templates वैकल्पिक ह
Agentडेटा पढ़ता और लिखता है, actions चलाता है, configured tools का उपयोग - करता हैdata पढ़ता + लिखता है, actions चलाता है, configured tools का उपयोग करता + है
Applicationसिर्फ action, chat, control plane, या full React इंटरफेसchat, inline results, control plane, या full React UI
@@ -49,7 +53,7 @@ Core foundation है। Toolkit और Templates वैकल्पिक ह
Computer
SQL डेटाबेस · browser · code executionSQL डेटाबेस · ब्राउज़र · कोड execution
@@ -87,105 +91,120 @@ Core foundation है। Toolkit और Templates वैकल्पिक ह -हेडलेस ऐप्स `pnpm agent` वाले फ़ोल्डर से समान प्रोडक्शन ऐप-एजेंट लूप चला सकते हैं, जबकि UI ऐप्स एम्बेडेड एजेंट पैनल को माउंट करते हैं और `pnpm dev` के साथ स्थानीय रूप से चला सकते हैं। क्लाउड में, Builder.io एक प्रबंधित फ्रेम प्रदान करता है - वह वातावरण जो आपके ऐप के बगल में एजेंट को होस्ट करता है - टीमों के लिए सहयोग, दृश्य संपादन और प्रबंधित बुनियादी ढांचे के साथ। +वही agent-application-computer लूप है जो locally और production में चलता है। Automation-first ऐप्स इसे सीधे folder से `pnpm agent` के साथ चलाते हैं; UI ऐप्स embedded agent panel माउंट करते हैं और `pnpm dev` जोड़ते हैं। Cloud में, Builder.io उसी लूप को एक managed frame के रूप में host करता है: वह environment जो आपके ऐप के साथ agent को चलाता है। यह आपके लिए collaboration, visual editing, और infrastructure संभालता है। -## एजेंट बिल्डिंग ब्लॉक्स {#agent-building-blocks} +## Agent बिल्डिंग ब्लॉक्स {#agent-building-blocks} -प्रत्येक एजेंट-नेटिव ऐप में समान एजेंट बिल्डिंग ब्लॉक होते हैं, चाहे कुछ भी हो -उत्पाद की सतह हेडलेस, चैट-फर्स्ट या पूर्ण UI है: +हर agent-native ऐप में समान agent बिल्डिंग ब्लॉक्स होते हैं, चाहे product surface chat-first हो, automation-first हो, या एक full UI हो। हर एक अपनी खुद की file में रहता है: /SKILL.md", - note: "reusable behavior: workflow steps, policies, examples, references, और do/don’t lists", + note: "reusable व्यवहार: workflow steps, policies, examples, references, और do/don't lists", }, { path: "actions/.ts", - note: "executable capability: agent, UI, CLI, HTTP, MCP, A2A, jobs, और webhooks को exposed typed operation", + note: "executable क्षमता: agent, UI, CLI, HTTP, MCP, A2A, jobs, और webhooks को exposed typed operation", }, ]} /> -| बिल्डिंग ब्लॉक | इसके लिए इसका उपयोग करें | जब लोड किया गया | -| -------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | -| **निर्देश** | एजेंट को प्रत्येक कार्य में स्थिर मार्गदर्शन देना चाहिए: ऐप क्या है, इनवेरिएंट, टोन, इंडेक्स | हर मोड़ | -| **Skills** | पुन: प्रयोज्य व्यवहार: वर्कफ़्लो का पालन कैसे करें, नीति कैसे लागू करें, साक्ष्य का निरीक्षण करें, या आउटपुट को सत्यापित करें | मांग पर जब कौशल विवरण कार्य से मेल खाता हो | -| **Actions** | वास्तविक संचालन: डेटा पढ़ें या लिखें, APIs पर कॉल करें, संदेश भेजें, अनुमोदन चलाएं, टाइप किए गए परिणाम उत्पन्न करें | हर मोड़ पर उपकरण के रूप में सूचीबद्ध; कॉल करने पर ही निष्पादित किया जाता है | +एक turn agent के साथ एक exchange है: यह अपना context पढ़ता है, तय करता है कि क्या करना है, और respond करता है। हर turn में loaded होने का मतलब है कि file हर बार उस context में फिर से enter होती है, न कि सिर्फ़ session शुरू होने पर एक बार। + +| बिल्डिंग ब्लॉक | File | इसके लिए उपयोग करें | कब Load होता है | +| ---------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | +| **Instructions** | `AGENTS.md` | स्थिर मार्गदर्शन जिसे agent को हर task में साथ ले जाना चाहिए: ऐप क्या है, invariants, tone, indexes | हर turn | +| **Skills** | `.agents/skills//SKILL.md` | Reusable व्यवहार: किसी workflow को कैसे follow करें, कोई policy कैसे apply करें, evidence कैसे inspect करें, या किसी output को कैसे verify करें | On demand, जब skill का description task से मेल खाए | +| **Actions** | `actions/.ts` | असली operations: data पढ़ना या लिखना, APIs कॉल करना, messages भेजना, approvals चलाना, typed results produce करना | हर turn tools के रूप में listed; केवल तभी execute होते हैं जब call किए जाएं | + +Skills और actions साथ मिलकर काम करते हैं। एक skill agent को यह सिखाती है कि किसी class के काम को कैसे किया जाए; एक action वह code path है जिसे वह उस काम को करते समय call कर सकता है। उदाहरण के लिए, एक `customer-research` skill agent को बता सकती है कि किन sources को inspect करना है और evidence को कैसे summarize करना है, जबकि `search-crm` और `create-brief` actions असली data fetch और write करते हैं। + +पांच नियम architecture को govern करते हैं: -Skills और actions एक साथ काम करते हैं। एक कौशल एजेंट को यह सिखाता है कि क्लास कैसे करनी है -कार्य; एक क्रिया वह कोड पथ है जिसे वह उस कार्य को करते समय कॉल कर सकता है। उदाहरण के लिए, -एक `customer-research` कौशल एजेंट को बता सकता है कि किन स्रोतों का निरीक्षण करना है और -साक्ष्य को सारांशित कैसे करें, जबकि `search-crm` और `create-brief` actions प्राप्त करें -और वास्तविक डेटा लिखें। +1. **Data SQL में रहता है:** सारा app state Drizzle ORM के ज़रिए database में रहता है। +2. **सारा AI agent के through जाता है:** कोई inline LLM calls नहीं; हर AI interaction agent chat bridge से होकर गुज़रता है। +3. **Agent operations के लिए Actions:** जटिल काम एक typed action के रूप में चलता है, inline code के रूप में नहीं। +4. **Live sync UI को sync में रखता है:** database में हुए changes SSE पर stream होते हैं, और polling universal fallback के रूप में काम करती है। +5. **Application state SQL में:** ephemeral UI state database में रहता है, जिसे agent और UI दोनों पढ़ सकते हैं। -पाँच नियम वास्तुकला को नियंत्रित करते हैं: +## चार-क्षेत्र चेकलिस्ट {#four-area-checklist} -1. **डेटा SQL में रहता है** - सभी ऐप स्थिति Drizzle ORM के माध्यम से डेटाबेस में रहती है -2. **सभी एआई एजेंट के माध्यम से जाते हैं** - कोई इनलाइन LLM कॉल नहीं -3. **एजेंट संचालन के लिए Actions** — जटिल कार्य actions के रूप में चलता है -4. **लाइव सिंक UI को सिंक में रखता है** - सार्वभौमिक फ़ॉलबैक के रूप में पोलिंग के साथ डेटाबेस SSE पर स्ट्रीम बदलता है -5. **Application state SQL में है** - ephemeral UI state database में रहता है और agent तथा UI दोनों पढ़ सकते हैं +हर user-facing feature को सभी applicable areas update करने चाहिए। किसी applicable area को skip करना agent-native contract को तोड़ता है; किसी ऐसे automation पर screen थोपना जिसे किसी human को browse करने की ज़रूरत ही नहीं, वह भी एक smell है। -## चार-क्षेत्रीय चेकलिस्ट {#four-area-checklist} +- **1. UI:** वह page, component, या dialog जिसके साथ user interact करता है। +- **2. Action:** उसी operation के लिए `actions/` में agent-callable action। +- **3. Skills:** `AGENTS.md` को update करें और/या pattern को document करने वाली एक skill बनाएं। +- **4. App-State:** Navigation state, view-screen data, और navigate commands। -प्रत्येक उपयोगकर्ता-सामना वाली सुविधा को सभी लागू क्षेत्रों को अद्यतन करना चाहिए। किसी लागू क्षेत्र को छोड़ने से एजेंट-मूल अनुबंध टूट जाता है; एक UI को केवल क्रिया-प्रधान प्रिमिटिव पर थोपना भी एक गंध है। +केवल UI वाला feature agent के लिए invisible होता है। केवल actions वाला full UI feature user के लिए invisible होता है। बिना app-state वाला feature मतलब agent को यह नहीं पता कि user क्या कर रहा है। एक automation-first operation जायज़ तौर पर action + instructions से शुरू हो सकता है और बाद में chat, UI, या app-state जोड़ सकता है जब humans को उसे browse, approve, configure, या share करने की ज़रूरत हो। -| क्षेत्र | विवरण | -| --------------- | ----------------------------------------------------------------------- | -| **1. UI** | पृष्ठ, घटक, या संवाद जिसके साथ उपयोगकर्ता इंटरैक्ट करता है | -| **2. कार्रवाई** | उसी ऑपरेशन के लिए actions/ में एजेंट-कॉल करने योग्य कार्रवाई | -| **3. Skills** | AGENTS.md को अपडेट करें और/या पैटर्न का दस्तावेजीकरण करने का कौशल बनाएं | -| **4. ऐप-स्टेट** | नेविगेशन स्थिति, व्यू-स्क्रीन डेटा, और नेविगेट कमांड | +## Agent Native में क्या शामिल है {#what-you-get-for-free} -केवल UI वाली सुविधा एजेंट के लिए अदृश्य है। केवल actions के साथ पूर्ण UI सुविधा उपयोगकर्ता के लिए अदृश्य है। ऐप-स्टेट के बिना एक सुविधा का मतलब है कि एजेंट इस बात से अनभिज्ञ है कि उपयोगकर्ता क्या कर रहा है। एक हेडलेस ऑपरेशन वैध रूप से एक्शन + निर्देशों के साथ शुरू हो सकता है और बाद में UI/ऐप-स्टेट जोड़ सकता है जब मनुष्यों को इसे ब्राउज़ करने, स्वीकृत करने, कॉन्फ़िगर करने या साझा करने की आवश्यकता होती है। +Framework अपनाना मुख्यतः इसलिए valuable है क्योंकि आपको जो चीज़ें बनानी बंद हो जाती हैं। जैसे ही आपका ऐप ऊपर दिए पांच नियमों को follow करता है, आपको ये मिल जाता है: -## SQL में डेटा {#data-in-sql} +| Feature | आपको क्या मिलता है | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| एक action = हर surface | `defineAction()` से define की गई हर action एक साथ एक agent tool, एक typesafe frontend hook (`useActionQuery` / `useActionMutation`), एक framework-owned HTTP transport, एक CLI command, external clients के लिए एक MCP tool, और अन्य agent-native ऐप्स के लिए एक A2A tool होती है। वैकल्पिक `link` और `mcpApp` metadata बिना किसी दूसरे implementation के deep links और MCP Apps UI जोड़ देता है। | +| प्रति user पूर्ण agent resources | Skills, shared `LEARNINGS.md`, personal `memory/MEMORY.md`, `AGENTS.md`, custom sub-agents, scheduled jobs, और connected MCP servers। सब कुछ SQL-backed है, किसी dev-box की ज़रूरत नहीं। देखें [Agent Resources](/docs/agent-resources)। | +| Drop-in React components | `` और `` आपके ऐप में कहीं भी chat + resources render करते हैं। देखें [Drop-in Agent](/docs/drop-in-agent)। | +| BYO agent chat runtimes | वही chat UI OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, या आपके अपने normalized HTTP stream के ऊपर बैठ सकता है। देखें [मूल चैट UI](/docs/native-chat-ui#byo-agent-runtimes)। | +| Agent और UI के बीच Live sync | Same-process writes तुरंत `/_agent-native/events` पर stream होते हैं; एक lightweight poll serverless, cron, और cross-process writes को convergent रखती है। Mutating actions automatically action-backed queries को invalidate कर देती हैं, इसलिए agent द्वारा बनाए गए records बिना manual refresh के दिखाई देते हैं। नीचे देखें [Live Sync](#polling-sync)। | +| Auth, orgs, RBAC | orgs/members/roles के साथ Better Auth हर template में wired है। देखें [Authentication](/docs/authentication)। एक से ज़्यादा user के लिए, शुरुआत करें [Organizations, Teams & Permissions](/docs/organizations-teams-permissions) से। | +| Context awareness | `navigation` app-state key के ज़रिए agent को हमेशा पता होता है कि user क्या देख रहा है। देखें [संदर्भ जागरूकता](/docs/context-awareness)। | +| MCP client + server, दोनों दिशाएं | ऐप MCP servers (local, remote, hub-shared) को ingest करता है _और_ अपनी actions को एक MCP server के रूप में expose करता है। देखें [MCP Clients](/docs/mcp-clients) और [MCP Protocol](/docs/mcp-protocol)। | +| Inter-app delegation | अलग-अलग ऐप्स में agents [A2A](/docs/a2a-protocol) पर बात करते हैं। Same-origin deploys JWT को skip कर देते हैं; cross-origin एक shared `A2A_SECRET` का उपयोग करता है। | +| Sub-agent teams | अपने खुद के thread और tools के साथ एक sub-agent spawn करें, जो chat में inline एक chip के रूप में दिखता है। देखें [Agent Teams](/docs/agent-teams)। | +| Portability | कोई भी Drizzle-supported SQL database, कोई भी Nitro-compatible host (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun)। | -सभी एप्लिकेशन स्थिति Drizzle ORM के माध्यम से SQL डेटाबेस में रहती है। स्कीमा प्रदाता-अज्ञेयवादी हैं; समर्थित डेटाबेस, `DATABASE_URL` कॉन्फ़िगरेशन और पोर्टेबिलिटी नियम [Database](/docs/database) में रहते हैं। +## SQL में Data {#data-in-sql} -कोर SQL स्टोर स्वतः निर्मित हैं और प्रत्येक टेम्पलेट में उपलब्ध हैं: +सारा application state Drizzle ORM के ज़रिए एक SQL database में रहता है। Schemas provider-agnostic हैं; supported databases, `DATABASE_URL` config, और portability नियम [Database](/docs/database) में हैं। -- `application_state` - अल्पकालिक UI स्थिति (नेविगेशन, ड्राफ्ट, चयन) -- `settings` — सतत कुंजी-मूल्य कॉन्फिगरेशन -- `oauth_tokens` — OAuth क्रेडेंशियल -- `sessions` — प्रमाणीकरण सत्र +Core SQL स्टोर auto-created हैं और हर template में उपलब्ध हैं: + +- `application_state`: अस्थायी UI state (navigation, drafts, selections) +- `settings`: स्थायी key-value config +- `oauth_tokens`: OAuth क्रेडेंशियल्स +- `sessions`: auth sessions + +नीचे हर row अपने fields दिखाने के लिए expand होती है: +अपना खुद का domain data जोड़ने के लिए, ऊपर दिए core stores द्वारा इस्तेमाल किए गए उन्हीं schema helpers के साथ एक table define करें: + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -246,28 +267,30 @@ export const forms = table("forms", { }); ``` +आप और agent दोनों उस data को terminal से inspect कर सकते हैं, बिना किसी अलग SQL client के: + ```bash -# त्वरित डेटाबेस निरीक्षण के लिए मुख्य कार्रवाइयां +# डेटाबेस की तुरंत जांच के लिए Core actions pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -production agent chat plugin raw SQL tools को default रूप से read-only रखता है -(`frameworkTools: { database: "read" }`), इसलिए agent app data को `db-schema` / `db-query` -से inspect करते हैं और writes typed app actions से करते हैं। `database: "write"` -(या `true`) केवल उन maintenance surfaces के लिए सेट करें जिन्हें scoped -`db-exec` / `db-patch` भी चाहिए; सभी data access के लिए typed app actions -require करने हेतु `database: "off"` / `false` सेट करें -पहुँच. +`db-schema` हर table के columns और types प्रिंट करता है। `db-query` सीधे read-only SQL चलाता है, जो बिना कोई database client खोले किसी action के writes को check करने के लिए उपयोगी है। + + + +production agent chat plugin raw SQL tools को default रूप से read-only रखता है (`frameworkTools: { database: "read" }`), इसलिए agent app data को `db-schema` / `db-query` से inspect करते हैं और writes typed app actions से करते हैं। `database: "write"` (या `true`) केवल उन maintenance surfaces के लिए सेट करें जिन्हें scoped `db-exec` / `db-patch` भी चाहिए; सभी data access के लिए typed app actions ज़रूरी बनाने के लिए `database: "off"` / `false` सेट करें। `frameworkTools` फ़्रेमवर्क के बाकी अपने टूल को भी इसी तरह नियंत्रित करता है: sharing, रिव्यू कमेंट, वर्शन इतिहास, feature flags, लोकलाइज़ेशन, ऑडिट, Context X-Ray, प्रोफ़ाइल, ऑटोमेशन, docs, resources, web, ऐप-दर-ऐप डेलिगेशन, चैट और ईमेल। पूरी सूची, `"minimal"` preset, और किसी समूह को बंद करने पर उसके HTTP रूट क्यों माउंट रहते हैं — देखें [Production Agent Tools](/docs/deployment#production-agent-tools)। + + ## एजेंट चैट ब्रिज {#agent-chat-bridge} -UI कभी भी LLM को सीधे कॉल नहीं करता है। जब कोई उपयोगकर्ता "जनरेट चार्ट" या "सारांश लिखें" पर क्लिक करता है, तो UI एजेंट को `postMessage` के माध्यम से एक संदेश भेजता है। एजेंट कार्य करता है - पूर्ण वार्तालाप इतिहास, skills, निर्देशों और पुनरावृत्त करने की क्षमता के साथ। +UI कभी सीधे किसी LLM को call नहीं करता। जब कोई user "Generate chart" या "Write summary" पर click करता है, तो UI `postMessage` के ज़रिए agent को एक message भेजता है। Agent वह काम करता है। इसके पास पूरी conversation history, skills, instructions, और iterate करने की क्षमता होती है। ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -276,16 +299,19 @@ sendToAgentChat({ }); ``` -LLM इनलाइन क्यों नहीं कॉल करते? +संक्षेप में: + +- **AI non-deterministic है**: Feedback देने और iterate करने के लिए आपको conversation flow चाहिए, one-shot buttons नहीं। +- **Context मायने रखता है**: Agent के पास ऐप के instructions, skills, और history होती है। एक inline call के पास इनमें से कुछ भी नहीं होता। +- **Agent ज़्यादा कर सकता है**: यह actions चला सकता है, web browse कर सकता है, और कई steps को एक साथ chain कर सकता है। -- **एआई गैर-नियतात्मक है।** आपको फीडबैक देने और पुनरावृत्त करने के लिए वार्तालाप प्रवाह की आवश्यकता है - एक-शॉट बटन की नहीं। -- **संदर्भ मायने रखता है।** एजेंट के पास आपका पूरा कोडबेस, निर्देश, skills और इतिहास होता है। इनलाइन कॉल में ऐसा कुछ भी नहीं होता। -- **एजेंट और भी बहुत कुछ कर सकता है।** यह actions चला सकता है, वेब ब्राउज़ कर सकता है, कोड संशोधित कर सकता है और कई चरणों को एक साथ जोड़ सकता है। -- **बिना सोचे-समझे निष्पादन।** क्योंकि सब कुछ एजेंट के माध्यम से होता है, किसी भी ऐप को पूरी तरह से Slack, टेलीग्राम, या किसी अन्य एजेंट से [A2A](/docs/a2a-protocol) के माध्यम से संचालित किया जा सकता है। +**[External execution](/docs/a2a-protocol)** + +क्योंकि सब कुछ agent और actions से होकर गुज़रता है, किसी भी ऐप को Slack, Telegram, scheduled jobs, scripts, या A2A के ज़रिए किसी दूसरे agent से चलाया जा सकता है। ## Actions सिस्टम {#actions-system} -जब एजेंट को कुछ जटिल करने की आवश्यकता होती है - API को कॉल करें, डेटा संसाधित करें, डेटाबेस से क्वेरी करें - यह एक **कार्रवाई** चलाता है। Actions, `actions/` में TypeScript फ़ाइलें हैं जो एक डिफ़ॉल्ट `defineAction()` निर्यात करती हैं: +जब agent को कुछ जटिल करना होता है, जैसे किसी API को call करना, data process करना, या database query करना, तो यह एक **action** चलाता है। Actions `actions/` में TypeScript files हैं जो एक default `defineAction()` export करती हैं: ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -303,19 +329,30 @@ export default defineAction({ }); ``` -एक `defineAction()` कॉल आपको देती है: +यह action किसी source API से JSON fetch करता है और उसे return करता है। `defineAction()` फ़ंक्शन को उसके input (`source`) के लिए एक zod schema से wrap करता है, ताकि framework उस input को validate कर सके, एक JSON Schema generate कर सके जिसे agent call कर सके, और इसी एक definition से frontend hook के लिए types infer कर सके। + +एक `defineAction()` call automatically पांच अलग-अलग consumers तक पहुंचती है। Diagram एक single action से होने वाला fan-out दिखाता है; नीचे दी list बताती है कि हर consumer को क्या मिलता है: + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **एजेंट टूल** - एजेंट इसे ज़ॉड-व्युत्पन्न JSON स्कीमा के साथ देखता है और इसे कॉल कर सकता है। -- **फ्रंटेंड हुक** - `useActionMutation("fetch-data")` पूर्ण TypeScript अनुमान के साथ। -- **फ्रेमवर्क ट्रांसपोर्ट** - क्लाइंट हुक के पीछे ऑटो-माउंटेड। -- **CLI** - स्क्रिप्टिंग और एजेंट डेव लूप के लिए `pnpm action fetch-data --source=signups`। -- **MCP टूल / A2A टूल** - जब MCP सर्वर या A2A सक्षम होता है, तो वही क्रिया वहां भी दिखाई देती है। +- **Agent tool:** agent इसे zod-derived JSON Schema के साथ देखता है और इसे call कर सकता है। +- **Frontend hook:** पूर्ण TypeScript inference के साथ `useActionMutation("fetch-data")`। +- **Framework transport:** client hooks के पीछे auto-mounted। +- **CLI:** scripting और agent dev loops के लिए `pnpm action fetch-data --source=signups`। +- **MCP tool / A2A tool:** जब MCP server या A2A enabled होता है, तो वही action वहां भी दिखाई देती है। -समान तर्क, एक परिभाषा, प्रत्येक उपभोक्ता तक स्वचालित रूप से पहुंचाई गई। संपूर्ण संदर्भ के लिए [Actions](/docs/actions) देखें। +हर consumer उसी underlying function को call करता है, इसलिए लिखने और maintain करने के लिए बस एक ही implementation है। पूरे reference के लिए देखें [Actions](/docs/actions)। -## लाइव सिंक {#polling-sync} +## Live Sync {#polling-sync} -डेटाबेस परिवर्तन `useDbSync()` के माध्यम से UI में समन्वयित होते हैं। समान-प्रक्रिया `/_agent-native/events` पर स्ट्रीम लिखती है; `/_agent-native/poll` क्रॉस-प्रोसेस और सर्वर रहित फ़ॉलबैक बना हुआ है। जब एजेंट डेटाबेस (एप्लिकेशन स्थिति, सेटिंग्स, या डोमेन डेटा) को लिखता है, तो एक संस्करण काउंटर बढ़ता है और क्लाइंट प्रासंगिक React क्वेरी कैश को अमान्य कर देता है। +जब agent data बदलता है, तो UI को उसे बिना manual refresh के reflect करना होता है। `useDbSync()` इसे automatic बनाता है। Same-process writes `/_agent-native/events` पर stream होते हैं; `/_agent-native/poll` cross-process और serverless fallback बना रहता है। जब agent database (application state, settings, या domain data) में लिखता है, तो एक version counter बढ़ता है और client relevant React Query caches को invalidate कर देता है। ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -323,24 +360,28 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` -प्रवाह है: +इसे एक बार, ऐप के root के पास call करें। यह पूरे ऐप को change events के लिए subscribe कर देता है, इसलिए `useActionQuery` या किसी source-versioned `useQuery` का उपयोग करने वाला कोई भी component जब वह जो data पढ़ता है वह बदलता है तो automatically refetch करता है। -1. एजेंट एक क्रिया चलाता है जो डेटाबेस पर लिखता है -2. सर्वर `"action"` या `"settings"` जैसे स्रोत के साथ एक परिवर्तन घटना उत्सर्जित करता है -3. `useDbSync` इसे SSE या पोलिंग फ़ॉलबैक पर प्राप्त करता है -4. `useActionQuery` हुक और स्रोत-संस्करण `useQuery` हुक पुनः प्राप्त -5. घटक पृष्ठ पुनः लोड किए बिना नया डेटा प्रस्तुत करते हैं +Flow इस प्रकार है: - +1. Agent एक ऐसी action चलाता है जो database में लिखती है +2. Server `"action"` या `"settings"` जैसे किसी source के साथ एक change event emit करता है +3. `useDbSync` इसे SSE या polling fallback पर receive करता है +4. `useActionQuery` hooks और source-versioned `useQuery` hooks refetch करते हैं +5. Components बिना page reload के नया data render करते हैं + +Diagram उसी sequence को end to end trace करता है: + + ```html
- एजेंट action
DB में लिखता है + Agent एक्शन
DB में लिखता है
- बदलाव इवेंट
source: action / settings
@@ -351,8 +392,8 @@ useDbSync({ queryClient });
- क्वेरी फिर से fetch
रेंडर, रीलोड नहींrender, बिना reload के
@@ -380,88 +421,90 @@ useDbSync({ queryClient }); -यह सभी परिनियोजन परिवेशों में काम करता है - सर्वर रहित और एज सहित - क्योंकि यह डेटाबेस का उपयोग करता है, इन-मेमोरी स्थिति या फ़ाइल सिस्टम वॉचर्स का नहीं। +यह सभी deployment environments में काम करता है, serverless और edge समेत, क्योंकि यह in-memory state या file system watchers के बजाय database का उपयोग करता है। -## फ़्रेम्स {#frames} +## Frames {#frames} -एक _frame_ वह वातावरण है जो आपके ऐप के बगल में एजेंट को होस्ट करता है - स्थानीय रूप से वह एम्बेडेड पैनल है; बादल में यह Builder.io की प्रबंधित सतह है। [Frames](/docs/frames) देखें. +एक _frame_ वह environment है जो आपके ऐप के साथ agent को host करता है। Locally यह embedded panel है; cloud में यह Builder.io का managed surface है। देखें [Frames](/docs/frames)। -एजेंट-नेटिव ऐप्स में एक एम्बेडेड एजेंट पैनल शामिल होता है जो ऐप UI के साथ AI एजेंट प्रदान करता है। यह वही है जो आर्किटेक्चर को काम करता है: एजेंट को एक कंप्यूटर (डेटाबेस, ब्राउज़र, कोड निष्पादन) की आवश्यकता होती है, और ऐप को एआई कार्य के लिए एजेंट की आवश्यकता होती है। +agent-native ऐप्स में एक embedded agent panel शामिल होता है जो app UI के साथ-साथ AI agent उपलब्ध कराता है। यही वह चीज़ है जो architecture को काम करने योग्य बनाती है: agent को एक computer चाहिए (database, browser, code execution), और ऐप को AI काम के लिए agent चाहिए। -- **एम्बेडेड एजेंट पैनल** - चैट और वैकल्पिक CLI टर्मिनल प्रत्येक ऐप में बनाया गया है। Claude कोड, Codex, जेमिनी, ओपनकोड और Builder.io को सपोर्ट करता है। स्थानीय स्तर पर चलता है. मुफ़्त और खुला स्रोत. -- **क्लाउड** - वास्तविक समय सहयोग, दृश्य संपादन, भूमिकाओं और अनुमतियों के साथ किसी भी क्लाउड पर तैनात करें। टीमों के लिए सर्वश्रेष्ठ. +- **Embedded Agent Panel:** हर ऐप में built-in Chat और वैकल्पिक CLI terminal। Claude Code, Codex, Gemini, OpenCode, और Builder.io को support करता है। Locally चलता है, free और open source। +- **Cloud:** real-time collaboration, visual editing, roles, और permissions के साथ किसी भी cloud पर deploy करें। Teams के लिए सबसे बेहतर। ## संदर्भ जागरूकता {#context-awareness} -एजेंट को हमेशा पता होता है कि उपयोगकर्ता क्या देख रहा है। UI प्रत्येक रूट परिवर्तन पर एप्लिकेशन-स्टेट के लिए एक `navigation` कुंजी लिखता है। एजेंट कार्रवाई करने से पहले इसे `view-screen` कार्रवाई के माध्यम से पढ़ता है। +Agent को हमेशा पता होता है कि user क्या देख रहा है। हर route change पर UI application-state में एक `navigation` key लिखता है। Agent एक्शन लेने से पहले इसे `view-screen` action के ज़रिए पढ़ता है। -उदाहरण के लिए, जब आप एक ईमेल थ्रेड खोलते हैं तो UI एक पंक्ति को ऊपर उठाता है: +उदाहरण के लिए, जब आप कोई email thread खोलते हैं तो UI इस तरह की एक row upsert करता है: ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -UI इसे मार्ग परिवर्तन पर लिखता है; एजेंट कोई भी कार्रवाई करने से पहले इसे (`view-screen` के माध्यम से) पढ़ता है, इसलिए यह हमेशा जानता है कि आप किस थ्रेड - या चार्ट, या स्लाइड - पर ध्यान केंद्रित कर रहे हैं। + + +UI इसे route change पर लिखता है; agent कोई भी action लेने से पहले इसे (`view-screen` के ज़रिए) पढ़ता है, इसलिए इसे हमेशा पता रहता है कि आप किस thread, chart, या slide पर focused हैं। + + -पूर्ण पैटर्न के लिए [Context Awareness](/docs/context-awareness) देखें: नेविगेशन स्थिति, व्यू-स्क्रीन, नेविगेट कमांड और घबराहट की रोकथाम। +पूरे pattern के लिए देखें [संदर्भ जागरूकता](/docs/context-awareness): navigation state, view-screen, navigate commands, और jitter prevention। -## एक क्रिया, अनेक सतह {#protocols} +## एक Action, कई Surfaces {#protocols} -एक डोमेन ऑपरेशन को एक बार क्रिया के रूप में कार्यान्वित करें; ढांचा इसे प्रत्येक उपभोक्ता के सामने उजागर करता है। वही `defineAction()` एक एजेंट टूल, एक टाइपसेफ UI हुक, एक HTTP एंडपॉइंट, एक CLI कमांड, एक MCP टूल और एक A2A टूल बन जाता है, जिसमें वैकल्पिक `link`, `mcpApp`, या स्पष्ट देशी-विजेट मेटाडेटा केवल तब जोड़ा जाता है जब किसी सतह को इसकी आवश्यकता होती है। Skills और निर्देश व्यवहार को कवर करते हैं। +किसी domain operation को एक बार action के रूप में implement करें; framework इसे हर consumer के सामने expose करता है। वही `defineAction()` एक agent tool, एक typesafe UI hook, एक HTTP endpoint, एक CLI command, एक MCP tool, और एक A2A tool बन जाता है, साथ ही वैकल्पिक `link`, `mcpApp`, native-widget metadata, या Generative UI wrappers तभी जोड़े जाते हैं जब किसी surface को richer interaction चाहिए। Behavior को Skills और instructions cover करते हैं। -पूर्ण प्रोटोकॉल/सतह मैट्रिक्स (MCP सर्वर और OAuth, MCP ऐप्स, A2A, डीप लिंक, देशी चैट विजेट, AgentChatRuntime कनेक्टर, एजेंट वेब और ACP और A2UI के लिए एडाप्टर क्षितिज) के लिए, और उत्पाद आकार चुनने के लिए - हेडलेस, रिच चैट, एम्बेडेड साइडकार, या पूर्ण ऐप - देखें [Agent Surfaces](/docs/agent-surfaces). +पूरे protocol/surface matrix (MCP server और OAuth, MCP Apps, A2A, deep links, native chat widgets, Generative UI, AgentChatRuntime connectors, Agent Web, और ACP और A2UI के लिए adapter horizon) के लिए, और एक product shape चुनने के लिए (chat, inline UI, full app pages, embedded sidecar, automation, या external-agent access), देखें [एजेंट Surfaces](/docs/agent-surfaces)। -## ऐप कोड और अनुकूलन {#agent-modifies-code} +## App कोड और कस्टमाइज़ेशन {#agent-modifies-code} -Embedded agent डिफ़ॉल्ट रूप से ऐप का source code संपादित नहीं करता। वह ऐसा -केवल तभी कर सकता है जब host जानबूझकर repository/workspace write tooling दे। -सामान्य तैनात ऐप में agent actions, SQL-backed state और configured integrations -के माध्यम से काम करता है। Templates पूर्ण apps हैं जिन्हें आप अपने repository -और development workflow में fork और customize कर सकते हैं। +Framework embedded agent को ऐप के source code तक ambient access नहीं देता। एक deployed ऐप में, agent आमतौर पर actions, SQL-backed state, और configured integrations के ज़रिए काम करता है। यह components, routes, styles, और actions को edit कर सकता है जब इसके frame को जान-बूझकर workspace और write tooling दी गई हो। Templates पूर्ण ऐप्स हैं जिन्हें आप अपने खुद के repository और development workflow में किसी भी सूरत में fork और customize कर सकते हैं। बिना source बदले runtime customization के लिए [Extensions](/docs/extensions) का उपयोग करें। ## डिफ़ॉल्ट रूप से पोर्टेबल {#hosting-agnostic} -दो वास्तुशिल्प नियम ऐप्स को डेटाबेस और होस्ट पर पोर्टेबल रखते हैं: +दो architectural नियम ऐप्स को databases और hosts के बीच portable बनाए रखते हैं: -- **डेटाबेस-अज्ञेयवादी।** `@agent-native/core/db/schema` के साथ स्कीमा लिखें और Drizzle की पोर्टेबल क्वेरी DSL के साथ पढ़ें/लिखें ताकि वही कोड किसी भी समर्थित प्रदाता पर चले। कच्चे SQL का उपयोग केवल एडिटिव माइग्रेशन या एकमुश्त रखरखाव के लिए करें, पैरामीटरयुक्त और बोली-अज्ञेयवादी रखा जाए। [Database](/docs/database) देखें. -- **होस्टिंग-अज्ञेयवादी।** सर्वर Nitro पर चलता है और किसी भी परिनियोजन लक्ष्य को संकलित करता है। सर्वर रूट या प्लगइन्स में कभी भी नोड-विशिष्ट APIs (`fs`, `child_process`, `path`) का उपयोग न करें, और कभी भी लगातार सर्वर प्रक्रिया न मानें - सर्वर रहित और एज स्टेटलेस हैं, इसलिए सभी स्थिति को SQL में रखें। [Deployment](/docs/deployment) देखें. +- **Database-agnostic.** Schemas `@agent-native/core/db/schema` के साथ लिखें और reads/writes Drizzle के portable query DSL के साथ, ताकि वही code किसी भी supported provider पर चले। Raw SQL का उपयोग केवल additive migrations या one-off maintenance के लिए करें, जिसे parameterized और dialect-agnostic रखा गया हो। देखें [Database](/docs/database)। +- **Hosting-agnostic.** Server Nitro पर चलता है और किसी भी deployment target के लिए compile होता है। Server routes या plugins में कभी भी Node-specific APIs (`fs`, `child_process`, `path`) का उपयोग न करें, और कभी भी persistent server process मान कर न चलें। Serverless और edge stateless होते हैं, इसलिए सारा state SQL में रखें। देखें [Deployment](/docs/deployment)। -## कार्यस्थान {#workspace} +## Agent Resources {#workspace} -प्रत्येक उपयोगकर्ता को एक व्यक्तिगत **कार्यक्षेत्र** मिलता है - निर्देश, skills, मेमोरी, कस्टम उप-एजेंट, निर्धारित कार्य और कनेक्टेड MCP सर्वर - सभी फ़ाइलों के बजाय SQL में संग्रहीत होते हैं। यह प्रति उपयोगकर्ता एक कंटेनर को घुमाए बिना बहु-किरायेदार SaaS के अंदर Claude-कोड-स्तरीय अनुकूलन को व्यवहार्य बनाता है। [एजेंट संसाधन](/docs/agent-resources) देखें. +हर user को **agent resources** का एक personal सेट मिलता है: instructions, skills, memory, custom sub-agents, scheduled jobs, और connected MCP servers, जो सब files के बजाय SQL में stored होते हैं। इससे per user एक container spin up किए बिना multi-tenant SaaS के अंदर Claude-Code-level customization viable बन जाती है। देखें [Agent Resources](/docs/agent-resources)। -## संबंधित भवन ब्लॉक {#building-blocks} +## संबंधित बिल्डिंग ब्लॉक्स {#building-blocks} -ये एक ही अनुबंध के शीर्ष पर बैठते हैं और उनके अपने गहरे गोता होते हैं: +ये उसी contract के ऊपर बैठते हैं और इनकी अपनी deep dives हैं: -- **[Dispatch](/docs/dispatch)** - कार्यक्षेत्र नियंत्रण विमान: साझा इनबॉक्स, रहस्य वॉल्ट, निर्धारित कार्य, और एक ऑर्केस्ट्रेटर जो A2A पर विशेषज्ञ ऐप्स को सौंपता है। -- **[Extensions](/docs/extensions)** - सैंडबॉक्स्ड Alpine.js मिनी-ऐप्स एजेंट रनटाइम पर बनाता है, कोई स्रोत परिवर्तन या माइग्रेशन नहीं। -- **[डेटा प्रोग्राम](/docs/data-programs)** - एजेंट द्वारा लिखी गई सहेजी गई `run-code` स्क्रिप्ट्स जो dashboard पैनलों को हार्डकोडेड provider action के बजाय एक कैश्ड, रिफ्रेश करने योग्य परिणाम देती हैं। -- **[A2A Protocol](/docs/a2a-protocol)** - एक ही कार्यक्षेत्र में ऐप्स JSON-RPC पर एक-दूसरे को कैसे खोजते हैं और कॉल करते हैं। +- **[Dispatch](/docs/dispatch):** workspace control plane, जिसमें एक shared inbox, secrets vault, scheduled jobs, और एक orchestrator है जो A2A पर specialist ऐप्स को delegate करता है। +- **[Extensions](/docs/extensions):** sandboxed Alpine.js mini-apps जिन्हें agent runtime पर बनाता है, बिना किसी source changes या migrations के। +- **[A2A प्रोटोकॉल](/docs/a2a-protocol):** एक ही workspace में ऐप्स JSON-RPC पर एक-दूसरे को कैसे discover और call करते हैं। -## आपको मुफ़्त में क्या मिलता है {#what-you-get-for-free} +## आगे क्या है {#deep-dives} -फ्रेमवर्क को अपनाना ज्यादातर इसलिए मूल्यवान है क्योंकि आपको निर्माण करना बंद कर देना चाहिए। जैसे ही आपका ऐप पाँच नियमों का पालन करता है, आपको यह विरासत में मिलता है: + -- **एक क्रिया = प्रत्येक सतह।** `defineAction()` के साथ परिभाषित प्रत्येक क्रिया एक साथ एक एजेंट टूल, एक टाइपसेफ फ्रंटएंड हुक (`useActionQuery` / `useActionMutation`), एक फ्रेमवर्क-स्वामित्व वाली HTTP ट्रांसपोर्ट, एक CLI कमांड, बाहरी क्लाइंट के लिए एक MCP टूल और अन्य एजेंट-मूल ऐप्स के लिए एक A2A टूल है। वैकल्पिक `link` और `mcpApp` मेटाडेटा दूसरे कार्यान्वयन के बिना डीप लिंक और MCP ऐप्स UI जोड़ते हैं। -- **प्रति उपयोगकर्ता एक पूर्ण कार्यक्षेत्र।** Skills, साझा `LEARNINGS.md`, व्यक्तिगत `memory/MEMORY.md`, `AGENTS.md`, कस्टम उप-एजेंट, निर्धारित नौकरियां, कनेक्टेड MCP सर्वर - सभी SQL-समर्थित, कोई डेव-बॉक्स आवश्यक नहीं है। [एजेंट संसाधन](/docs/agent-resources) देखें. -- **ड्रॉप-इन React घटक।** `` और `` आपके ऐप में कहीं भी चैट + वर्कस्पेस प्रस्तुत करते हैं। [Drop-in Agent](/docs/drop-in-agent) देखें. -- **BYO एजेंट चैट रनटाइम।** वही चैट UI OpenAI एजेंट, OpenAI प्रतिक्रियाएं, Claude एजेंट SDK, वर्सेल AI SDK, AG-UI, या आपकी अपनी सामान्यीकृत HTTP स्ट्रीम के शीर्ष पर बैठ सकती है। [Native चैट UI](/docs/native-chat-ui#byo-agent-runtimes) देखें. -- **एजेंट और UI के बीच लाइव सिंक।** समान प्रक्रिया `/_agent-native/events` पर तुरंत स्ट्रीम लिखती है; एक हल्का पोल सर्वर रहित, क्रॉन और क्रॉस-प्रोसेस लेखन को अभिसरण रखता है। actions को म्यूट करने से एक्शन-समर्थित क्वेरीज़ स्वचालित रूप से अमान्य हो जाती हैं, इसलिए एजेंट द्वारा बनाए गए रिकॉर्ड मैन्युअल रीफ्रेश के बिना दिखाई देते हैं। नीचे [Live Sync](#polling-sync) देखें। -- **प्रमाणीकरण, संगठन, RBAC.** प्रत्येक टेम्पलेट के लिए संगठन/सदस्यों/भूमिकाओं के साथ बेहतर प्रमाणीकरण को शामिल किया गया है। [Authentication](/docs/authentication) देखें. -- **संदर्भ जागरूकता।** एजेंट हमेशा जानता है कि उपयोगकर्ता `navigation` ऐप-स्टेट कुंजी के माध्यम से क्या देख रहा है। [Context Awareness](/docs/context-awareness) देखें. -- **MCP क्लाइंट + सर्वर, दोनों दिशाएं।** ऐप MCP सर्वर (स्थानीय, रिमोट, हब-शेयर्ड) को ग्रहण करता है _और_ अपने स्वयं के actions को MCP सर्वर के रूप में प्रदर्शित करता है। [MCP Clients](/docs/mcp-clients) और [MCP Protocol](/docs/mcp-protocol) देखें। -- **अंतर-ऐप प्रतिनिधिमंडल।** विभिन्न ऐप्स में एजेंट [A2A](/docs/a2a-protocol) पर बात करते हैं। समान-मूल परिनियोजन JWT को छोड़ें; क्रॉस-ओरिजिन एक साझा `A2A_SECRET` का उपयोग करता है। -- **उप-एजेंट टीमें।** एक उप-एजेंट को अपने स्वयं के थ्रेड और टूल के साथ तैयार करें, जो चैट में एक चिप इनलाइन के रूप में सामने आया। [Agent Teams](/docs/agent-teams) देखें. -- **पोर्टेबिलिटी।** कोई भी Drizzle-समर्थित SQL डेटाबेस, कोई भी Nitro-संगत होस्ट (नोड, वर्कर्स, नेटलिफाई, वर्सेल, डेनो, लैम्ब्डा, बन)। +### [Agent-Native क्या है?](/docs/what-is-agent-native) -यही वह "और बाकी सब कुछ" है जिसे आप अन्यथा स्वयं ही जोड़ रहे होते। +इन नियमों के पीछे का vision और philosophy। -## आगे क्या है {#deep-dives} +### [संदर्भ जागरूकता](/docs/context-awareness) + +Navigation state, view-screen, और navigate commands गहराई में। + +### [Skills गाइड](/docs/skills-guide) + +Framework skills, domain skills, और custom skills बनाना। + +### [मूल चैट UI](/docs/native-chat-ui) + +Action-declared tables, charts, और BYO runtime posture। + +### [एजेंट Surfaces](/docs/agent-surfaces) + +Chat, native inline UI, full app pages, embedded sidecar, automation, और external-agent paths। + +### [A2A प्रोटोकॉल](/docs/a2a-protocol) + +Agent-to-agent communication। -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — इन नियमों के पीछे की दृष्टि और दर्शन -- [**Context Awareness**](/docs/context-awareness) — navigation state, view-screen और navigate commands का विस्तृत विवरण -- [**Skills Guide**](/docs/skills-guide) — framework skills, domain skills और custom skills बनाना -- [**Native Chat UI**](/docs/native-chat-ui) — action-declared tables, charts और अपना runtime लाने का तरीका -- [**Agent Surfaces**](/docs/agent-surfaces) — chat, native inline UI, पूर्ण app pages, embedded sidecar, automation और external-agent paths -- [**A2A Protocol**](/docs/a2a-protocol) — agent-to-agent संचार + diff --git a/packages/core/docs/content/locales/ja-JP/key-concepts.mdx b/packages/core/docs/content/locales/ja-JP/key-concepts.mdx index c6507b4951..59d24d6d43 100644 --- a/packages/core/docs/content/locales/ja-JP/key-concepts.mdx +++ b/packages/core/docs/content/locales/ja-JP/key-concepts.mdx @@ -1,46 +1,50 @@ --- -title: "重要な概念" -description: "エージェント ネイティブ アプリの仕組み: 最初に actions、SQL データベース、アプリとエージェントのループ、オプションの UI、ポーリング同期、外部エージェントのエントリ ポイント、コンテキスト認識、移植性。" +title: "主要な概念" +description: "agent-native アプリが Core フレームワーク、オプションの Toolkit ビルディングブロック、オプションの Templates という3つのレイヤーにわたってどのように機能するか、そして共有されるアクション、SQL データベース、app-agent ループ、移植性のルールについて説明します。" --- -# 重要な概念 +# 主要な概念 -エージェント ネイティブ アプリが内部でどのように動作するか - 原理とアーキテクチャ。このページは契約書です。この方法で構築するビジョンと事例については、[What Is Agent-Native?](/docs/what-is-agent-native) を参照してください。 +agent-native アプリが内部でどのように動作するか、その原則とアーキテクチャです。このページは契約です。アプリが agent-native と見なされるために従うべき固定ルールを定めています。このように構築する理由とビジョンについては、[Agent-Nativeとは？](/docs/what-is-agent-native) を参照してください。 -## 3 つのレイヤー {#three-layers} +## 3つのレイヤー {#three-layers} -Agent Native は単一のテンプレートではなく、フレームワークです。 +Agent Native は3つのレイヤーから成るフレームワークです。 -- **Core - フレームワーク:** すべてのアプリが利用できる基本のランタイムおよびデータ契約。 -- **Toolkit - オプションの再利用可能な部品:** アプリが採用、組み合わせ、fork できる共有 UI とプロダクト システム。 -- **Templates - オプションのアプリ:** Core 上に構築された完全なドメイン アプリ。多くの場合 Toolkit を使用し、出発点として fork して利用できます。 +| レイヤー | 概要 | +| ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Core: フレームワーク** | 基盤となるランタイムの契約です。アクション、SQL と Drizzle のヘルパー、認証、アプリケーション状態、エージェントの実行、アクセスチェック、ルーティング、ライブ同期を含みます。どのアプリも Core を直接使用できます。 | +| **Toolkit: 再利用可能なオプションの部品** | プリミティブ、エディタ、共有、コラボレーション、設定、エージェント UX など、アプリ構築のための共有 UI とプロダクトシステムです。アプリは必要な部品を使用、組み合わせ、または fork できます。 | +| **Templates: Core 上に構築されたオプションのアプリ** | ルート、スキーマ、アクション、指示、ビジュアルアイデンティティを備えた、完全でドメイン特化型のアプリです。ファーストパーティおよびカスタムの Templates は一般的に Toolkit を使用し、fork して出発点として利用できます。 | -Core が基盤です。Toolkit と Templates はオプションです。 +Core が基盤です。Toolkit と Templates はオプションです。template は Toolkit を使用できますが、Core の上にアプリを構築するために Toolkit が必須というわけではありません。 ## アーキテクチャ {#the-architecture} -すべてのエージェント ネイティブ アプリは、次の 3 つの要素が連携して機能します。 +実行時には、すべての agent-native アプリは次の3つの要素が連携して動作します。 -- **エージェント** — データの読み取り、書き込み、actions の実行、および設定済みツールの利用を行う自律型 AI。 skills と説明書でカスタマイズ可能。 -- **アプリケーション** — エージェントの周囲の製品表面。これは、最初はアクションのみ、リッチ チャット、小さなコントロール プレーン、またはダッシュボード、フロー、ビジュアライゼーションを備えた完全な React UI画面 である可能性があります。 -- **コンピュータ** — データベース、ブラウザ、コード実行。エージェントはアプリのアクションとデータのサーフェスを通じて動作し、アプリは同じアクションサーフェスを MCP 経由で公開できます。外部 MCP サーバーはオプションのアドオンであり、基盤ではありません。 +- **エージェント:** 自律的な AI です。データを読み取り、書き込みを行い、アクションを実行し、設定されたツールを何でも使用します。frame に意図的に workspace アクセスと書き込みツールが付与されている場合は、アプリ自身のソースコードを変更することもできます。スキルと指示でカスタマイズ可能です。 +- **アプリケーション:** エージェントを取り巻くプロダクトサーフェスです。チャットとして始まり、ネイティブなインライン結果を追加し、小さなコントロールプレーンへ成長し、あるいはダッシュボード、フロー、ビジュアライゼーションを備えたフル React UI になることもあります。 +- **コンピュータ:** エージェントが操作対象とするデータベース、ブラウザ、設定済みのツールランタイムです。エージェントはアプリ自身のアクションとデータのサーフェスを通じて動作します。同じサーフェスは任意で MCP 経由に公開できますが、外部の MCP サーバーはあくまでアドオンであり、基盤ではありません。 - +以下の図は、エージェントとアプリケーションを並べて示し、両方から共有された computer レイヤーへ双方向の矢印が伸びている様子を表しています。どちらもデータを所有しません。代わりに、両者は同じ SQL ストアを読み書きするため、どちら側で行った変更もすぐにもう一方から見えるようになり、間に構築すべき同期レイヤーはありません。 + + ```html
- Agentエージェントデータを読み書きし、actionsを実行し、設定済みツールを利用データの読み書き、アクションの実行、設定済みツールの利用
- Applicationアプリケーションactionのみ、チャット、コントロールプレーン、または完全なReact - UI画面チャット、インライン結果、コントロールプレーン、またはフル React + UI
@@ -48,8 +52,8 @@ Core が基盤です。Toolkit と Templates はオプションです。 ↓ ↑
- Computer
SQLデータベース · browser · code executionSQL データベース · ブラウザ · コード実行
@@ -87,24 +91,23 @@ Core が基盤です。Toolkit と Templates はオプションです。 -ヘッドレス アプリは、`pnpm agent` を使用してフォルダーから同じ本番アプリ エージェント ループを実行できますが、UI アプリは埋め込みエージェント パネルをマウントし、`pnpm dev` を使用してローカルで実行します。クラウドでは、Builder.io はマネージド フレーム (アプリの隣にエージェントをホストする環境) を提供し、チーム向けのコラボレーション、ビジュアル編集、マネージド インフラストラクチャを備えています。 +同じ agent-application-computer ループが、ローカルと本番環境の両方で動作します。automation-first なアプリはフォルダから直接 `pnpm agent` で実行し、UI アプリは埋め込みエージェントパネルをマウントして `pnpm dev` を追加します。クラウドでは、Builder.io が同一のループをマネージド frame として提供します。これは、アプリの隣でエージェントを実行する環境です。コラボレーション、ビジュアル編集、インフラストラクチャを代わりに処理します。 ## エージェントの構成要素 {#agent-building-blocks} -すべてのエージェント ネイティブ アプリには、かどうかに関係なく、同じエージェント構成要素があります -製品サーフェスはヘッドレス、チャットファースト、または完全な UI です: +すべての agent-native アプリは、プロダクトサーフェスがチャットファースト、automation-first、フル UI のいずれであっても、同じエージェント構成要素を持っています。それぞれが独自のファイルに存在します。 /SKILL.md", - note: "再利用可能な振る舞い: workflow 手順、policy、例、参照、do/don’t リスト", + note: "再利用可能な振る舞い: ワークフローの手順、ポリシー、例、リファレンス、do/don't リスト", }, { path: "actions/.ts", @@ -113,55 +116,71 @@ Core が基盤です。Toolkit と Templates はオプションです。 ]} /> -| ビルディングブロック | 次の用途に使用します | いつロードされるか | -| -------------------- | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | -| **手順** | エージェントがすべてのタスクに導入すべき安定したガイダンス: アプリとは何か、不変条件、トーン、インデックス | 毎ターン | -| **Skills** | 再利用可能な動作: ワークフローに従う方法、ポリシーを適用する方法、証拠を検査する方法、または出力を検証する方法 | スキルの説明がタスクと一致する場合はオンデマンド | -| **Actions** | 実際の操作: データの読み取りまたは書き込み、API の呼び出し、メッセージの送信、承認の実行、入力された結果の生成 | 毎ターンツールとしてリストされます。呼び出されたときのみ実行される | +ターンとは、エージェントとの1回のやり取りです。エージェントはコンテキストを読み取り、何をすべきか判断し、応答します。毎ターン読み込まれるとは、セッション開始時に一度だけではなく、そのファイルが毎回コンテキストに再度入ることを意味します。 + +| 構成要素 | ファイル | 用途 | 読み込まれるタイミング | +| -------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- | +| **指示** | `AGENTS.md` | エージェントがすべてのタスクに持ち込むべき安定したガイダンス: アプリの概要、不変条件、トーン、インデックス | 毎ターン | +| **スキル** | `.agents/skills//SKILL.md` | 再利用可能な振る舞い: ワークフローに従う方法、ポリシーを適用する方法、証拠を検査する方法、出力を検証する方法 | スキルの説明がタスクと一致したときにオンデマンドで | +| **アクション** | `actions/.ts` | 実際の操作: データの読み書き、API の呼び出し、メッセージの送信、承認の実行、型付き結果の生成 | 毎ターンツールとして一覧表示され、呼び出されたときのみ実行される | + +スキルとアクションは連携して動作します。スキルはエージェントにある種の作業のやり方を教え、アクションはその作業を行う際に呼び出せるコードパスです。たとえば、`customer-research` スキルはエージェントにどのソースを調べ、どのように証拠を要約するかを伝え、`search-crm` と `create-brief` アクションが実際のデータを取得・書き込みします。 + +アーキテクチャを支配する5つのルール: -Skills と actions は連携して動作します。スキルはエージェントに次のクラスの実行方法を教えます -仕事。アクションは、その作業の実行中に呼び出すことができるコード パスです。たとえば、 -`customer-research` スキルは、どのソースを検査するかをエージェントに指示し、 -`search-crm` および `create-brief` actions フェッチ中に証拠を要約する方法 -実際のデータを書き込みます。 +1. **データは SQL に存在する:** すべてのアプリの状態は Drizzle ORM を介してデータベースに存在します。 +2. **すべての AI はエージェントを経由する:** インライン LLM 呼び出しはありません。すべての AI とのやり取りはエージェントチャットブリッジを通過します。 +3. **エージェントの操作にはアクションを使う:** 複雑な作業はインラインコードではなく、型付きアクションとして実行されます。 +4. **ライブ同期が UI を同期させ続ける:** データベースの変更は SSE 経由でストリームされ、ポーリングがユニバーサルフォールバックになります。 +5. **アプリケーション状態は SQL に:** 一時的な UI 状態はデータベースに存在し、エージェントと UI の両方から読み取れます。 -アーキテクチャを管理する 5 つのルール: +## 4つの領域のチェックリスト {#four-area-checklist} -1. **データは SQL に存在します** — すべてのアプリの状態は Drizzle ORM を介してデータベースに存在します -2. **すべての AI はエージェントを経由します** — インライン LLM 呼び出しはありません -3. **エージェント操作の場合は Actions** — 複雑な作業は actions として実行されます -4. **ライブ同期により UI の同期が維持されます** — データベース変更は、ユニバーサル フォールバックとしてポーリングを使用して SSE 経由でストリームされます -5. **アプリケーションの状態は SQL に保存されます** - 一時的な UI 状態はデータベースにあり、エージェントと UI の両方から読み取れます +ユーザー向けのすべての機能は、該当するすべての領域を更新する必要があります。該当する領域をスキップすると agent-native の契約が破られます。人間が閲覧する必要のない automation に画面を強制するのも良くない兆候です。 -## 4 つの領域のチェックリスト {#four-area-checklist} +- **1. UI:** ユーザーが操作するページ、コンポーネント、またはダイアログです。 +- **2. アクション:** 同じ操作を行う `actions/` 内のエージェント呼び出し可能なアクションです。 +- **3. スキル:** `AGENTS.md` を更新する、および/またはそのパターンを文書化するスキルを作成します。 +- **4. アプリ状態:** ナビゲーション状態、view-screen データ、navigate コマンドです。 -ユーザー向けのすべての機能は、該当するすべての領域を更新する必要があります。該当する領域をスキップすると、エージェントとネイティブの契約が破棄されます。アクションのみのプリミティブに UI を強制するのも臭いです。 +UI しか持たない機能はエージェントから見えません。アクションしか持たないフル UI 機能はユーザーから見えません。アプリ状態のない機能は、エージェントがユーザーの行動を認識できないことを意味します。automation-first な操作は、アクション + 指示から正当に開始し、人間が閲覧、承認、設定、共有する必要が出てきた時点でチャット、UI、アプリ状態を後から追加できます。 -| 面積 | 説明 | -| ------------------ | ------------------------------------------------------------------- | -| **1. UI** | ユーザーが操作するページ、コンポーネント、またはダイアログ | -| **2.アクション** | 同じ操作に対する actions/ のエージェント呼び出し可能なアクション | -| **3. Skills** | AGENTS.md を更新するか、パターンを文書化するスキルを作成する | -| **4.アプリの状態** | ナビゲーション状態、ビュー画面データ、およびナビゲーション コマンド | +## Agent Native に含まれるもの {#what-you-get-for-free} -UI のみを持つ機能はエージェントには表示されません。 actions のみを備えた完全な UI 機能は、ユーザーには表示されません。 app-state のない機能は、エージェントがユーザーの行動を認識できないことを意味します。ヘッドレス操作は、正当にアクション + 指示から開始し、後で人間が参照、承認、構成、または共有する必要があるときに UI/app-state を追加できます。 +このフレームワークを採用する価値は、主に何を構築しなくて済むようになるかにあります。アプリが上記の5つのルールに従った瞬間、次のものが手に入ります。 -## SQL のデータ {#data-in-sql} +| 機能 | 得られるもの | +| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 1つのアクション = あらゆるサーフェス | `defineAction()` で定義されたすべてのアクションは、同時にエージェントツール、型安全なフロントエンドフック (`useActionQuery` / `useActionMutation`)、フレームワーク所有の HTTP トランスポート、CLI コマンド、外部クライアント向けの MCP ツール、他の agent-native アプリ向けの A2A ツールになります。オプションの `link` と `mcpApp` メタデータは、2つ目の実装を書くことなくディープリンクと MCP Apps UI を追加します。 | +| ユーザーごとの完全なエージェントリソース | スキル、共有される `LEARNINGS.md`、個人用の `memory/MEMORY.md`、`AGENTS.md`、カスタムサブエージェント、スケジュールされたジョブ、接続された MCP サーバーです。すべて SQL でバックアップされ、dev-box は不要です。[Agent Resources](/docs/agent-resources) を参照してください。 | +| ドロップイン React コンポーネント | `` と `` は、アプリ内の任意の場所にチャット + リソースをレンダリングします。[Drop-in Agent](/docs/drop-in-agent) を参照してください。 | +| BYO エージェントチャットランタイム | 同じチャット UI を OpenAI Agents、OpenAI Responses、Claude Agent SDK、Vercel AI SDK、AG-UI、または独自の正規化された HTTP ストリームの上に置くことができます。[ネイティブ チャット UI](/docs/native-chat-ui#byo-agent-runtimes) を参照してください。 | +| エージェントと UI 間のライブ同期 | 同一プロセスの書き込みは `/_agent-native/events` 経由で即座にストリームされます。軽量なポーリングが、サーバーレス、cron、クロスプロセスの書き込みを収束させ続けます。変更を行うアクションはアクションに基づくクエリを自動的に無効化するため、エージェントが作成したレコードは手動更新なしで表示されます。下記の [Live Sync](#polling-sync) を参照してください。 | +| 認証、組織、RBAC | orgs/members/roles を備えた Better Auth がすべての template に組み込まれています。[Authentication](/docs/authentication) を参照してください。複数ユーザーの場合は、[Organizations, Teams & Permissions](/docs/organizations-teams-permissions) から始めてください。 | +| コンテキスト認識 | エージェントは `navigation` アプリ状態キーを通じて、ユーザーが何を見ているかを常に把握しています。[コンテキスト認識](/docs/context-awareness) を参照してください。 | +| MCP クライアント + サーバー、両方向 | アプリは MCP サーバー (ローカル、リモート、ハブ共有) を取り込み、_かつ_ 自身のアクションを MCP サーバーとして公開します。[MCP Clients](/docs/mcp-clients) と [MCP Protocol](/docs/mcp-protocol) を参照してください。 | +| アプリ間の委任 | 異なるアプリのエージェントは [A2A](/docs/a2a-protocol) 経由で通信します。同一オリジンのデプロイでは JWT がスキップされます。クロスオリジンでは共有の `A2A_SECRET` を使用します。 | +| サブエージェントチーム | 独自のスレッドとツールを持つサブエージェントを生成し、チャット内にインラインのチップとして表示します。[Agent Teams](/docs/agent-teams) を参照してください。 | +| 移植性 | Drizzle がサポートする任意の SQL データベース、Nitro 互換の任意のホスト (Node、Workers、Netlify、Vercel、Deno、Lambda、Bun)。 | -すべてのアプリケーションの状態は、Drizzle ORM を介して SQL データベースに保存されます。スキーマはプロバイダーに依存しません。サポートされているデータベース、`DATABASE_URL` 構成、移植性ルールは [Database](/docs/database) にあります。 +## SQL 内のデータ {#data-in-sql} -コア SQL ストアは自動作成され、すべてのテンプレートで使用できます: +すべてのアプリケーション状態は Drizzle ORM を介して SQL データベースに存在します。スキーマはプロバイダーに依存しません。サポートされるデータベース、`DATABASE_URL` の設定、移植性のルールは [Database](/docs/database) にあります。 -- `application_state` — 一時的な UI 状態 (ナビゲーション、ドラフト、選択) -- `settings` — 永続的なキーと値の構成 -- `oauth_tokens` — OAuth 資格情報 -- `sessions` — 認証セッション +Core の SQL ストアは自動作成され、すべての template で利用できます。 + +- `application_state`: 一時的な UI 状態 (ナビゲーション、下書き、選択内容) +- `settings`: 永続的なキーバリュー設定 +- `oauth_tokens`: OAuth 認証情報 +- `sessions`: 認証セッション + +以下の各行を展開すると、そのフィールドが表示されます。 +独自のドメインデータを追加するには、上記の core ストアで使用されているのと同じスキーマヘルパーでテーブルを定義します。 + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -246,28 +267,30 @@ export const forms = table("forms", { }); ``` +あなたとエージェントの両方が、別の SQL クライアントなしでターミナルからそのデータを検査できます。 + ```bash -# 迅速なデータベース検査のための主要なアクション +# データベースを手早く確認するための Core actions pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -実稼働エージェントのチャット プラグインは raw SQL ツールをデフォルトで読み取り専用にします -(`frameworkTools: { database: "read" }`)。エージェントは `db-schema` / `db-query` で -アプリ所有データを検査し、書き込みは型付きアプリ actions 経由で行います。 -スコープ付きの `db-exec` / `db-patch` も公開する必要がある意図的な -メンテナンス面だけで `database: "write"` (または `true`) を設定します。 -すべてのデータアクセスに型付きアプリ actions を要求するには -`database: "off"` / `false` を設定します。 +`db-schema` はすべてのテーブルのカラムと型を出力します。`db-query` は読み取り専用の SQL を直接実行するため、データベースクライアントを開かずにアクションの書き込みを確認するのに便利です。 + + + +実稼働エージェントのチャット プラグインは raw SQL ツールをデフォルトで読み取り専用にします (`frameworkTools: { database: "read" }`)。エージェントは `db-schema` / `db-query` でアプリ所有データを検査し、書き込みは型付きアプリ actions 経由で行います。スコープ付きの `db-exec` / `db-patch` も公開する必要がある意図的なメンテナンス面だけで `database: "write"` (または `true`) を設定します。すべてのデータアクセスに型付きアプリ actions を要求するには `database: "off"` / `false` を設定します。 `frameworkTools` は、フレームワーク自身の残りのツールも同じように制御します。共有、レビューコメント、バージョン履歴、feature flags、ローカライズ、監査、Context X-Ray、プロフィール、自動化、docs、resources、web、アプリ間委譲、チャット、メールです。完全な一覧、`"minimal"` プリセット、グループを無効にしても HTTP ルートが残る理由は [Production Agent Tools](/docs/deployment#production-agent-tools) を参照してください。 -## エージェント チャット ブリッジ {#agent-chat-bridge} + -UI が LLM を直接呼び出すことはありません。ユーザーが「チャートの生成」または「概要の書き込み」をクリックすると、UI は `postMessage` 経由でエージェントにメッセージを送信します。エージェントは、完全な会話履歴、skills、指示、反復機能を使用して作業を行います。 +## エージェントチャットブリッジ {#agent-chat-bridge} + +UI が LLM を直接呼び出すことはありません。ユーザーが「Generate chart」や「Write summary」をクリックすると、UI は `postMessage` 経由でエージェントにメッセージを送信します。作業を行うのはエージェントです。エージェントは完全な会話履歴、スキル、指示、そして繰り返し改善する能力を持っています。 ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -276,16 +299,19 @@ sendToAgentChat({ }); ``` -LLM をインラインで呼び出してみませんか? +要するに: + +- **AI は非決定的です**: フィードバックを与えて繰り返し改善するための会話フローが必要であり、ワンショットのボタンでは足りません。 +- **コンテキストが重要です**: エージェントはアプリの指示、スキル、履歴を持っています。インライン呼び出しにはそれらが一切ありません。 +- **エージェントはより多くのことができます**: アクションを実行し、Web を閲覧し、複数のステップを連鎖させることができます。 -- **AI は非決定的です。** フィードバックを提供して反復するための会話フローが必要です。ワンショット ボタンではありません。 -- **コンテキストが重要です。** エージェントには、完全なコードベース、手順、skills、および履歴が含まれています。インライン呼び出しにはそのようなことはありません。 -- **エージェントはさらに多くのことを実行できます。** actions を実行し、Web を参照し、複数のステップを連鎖させることができます。 -- **ヘッドレス実行。** すべてがエージェントを経由するため、あらゆるアプリを Slack、Telegram、または [A2A](/docs/a2a-protocol) 経由の別のエージェントから完全に駆動できます。 +**[外部実行](/docs/a2a-protocol)** -## Actions システム {#actions-system} +すべてがエージェントとアクションを経由するため、どのアプリも Slack、Telegram、スケジュールされたジョブ、スクリプト、あるいは A2A 経由の別のエージェントから操作できます。 -エージェントが何か複雑なこと (API の呼び出し、データの処理、データベースのクエリなど) を実行する必要がある場合、**アクション** を実行します。 Actions は、デフォルトの `defineAction()` をエクスポートする `actions/` 内の TypeScript ファイルです: +## アクションシステム {#actions-system} + +エージェントが API の呼び出し、データ処理、データベースへの問い合わせなど複雑なことを行う必要がある場合、**アクション** を実行します。アクションは `actions/` にある TypeScript ファイルで、デフォルトで `defineAction()` をエクスポートします。 ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -303,19 +329,30 @@ export default defineAction({ }); ``` -1 回の `defineAction()` 呼び出しで次のことが得られます: +このアクションはソース API から JSON を取得して返します。`defineAction()` は入力 (`source`) 用の zod スキーマで関数をラップするため、フレームワークはこの1つの定義だけから、その入力を検証し、エージェントが呼び出せる JSON Schema を生成し、フロントエンドフック用の型を推論できます。 + +1回の `defineAction()` 呼び出しは、自動的に5つの異なるコンシューマーに届きます。図は1つのアクションからのファンアウトを示し、以下のリストは各コンシューマーが得るものを説明します。 + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **エージェント ツール** — エージェントは zod 派生の JSON スキーマを使用してこれを認識し、呼び出すことができます。 -- **フロントエンド フック** — 完全な TypeScript 推論を備えた `useActionMutation("fetch-data")`。 -- **フレームワーク トランスポート** — クライアント フックの背後で自動マウントされます。 -- **CLI** — スクリプト作成およびエージェント開発ループ用の `pnpm action fetch-data --source=signups`。 -- **MCP ツール / A2A ツール** — MCP サーバーまたは A2A が有効になっている場合、同じアクションがそこでも表示されます。 +- **エージェントツール:** エージェントは zod から派生した JSON Schema を通じてこれを認識し、呼び出すことができます。 +- **フロントエンドフック:** 完全な TypeScript 推論を伴う `useActionMutation("fetch-data")`。 +- **フレームワークトランスポート:** クライアントフックの背後に自動マウントされます。 +- **CLI:** スクリプト作成やエージェント開発ループのための `pnpm action fetch-data --source=signups`。 +- **MCP ツール / A2A ツール:** MCP サーバーまたは A2A が有効な場合、同じアクションがそこにも表示されます。 -同じロジック、1 つの定義がすべてのコンシューマーに自動的に接続されます。完全なリファレンスについては、[Actions](/docs/actions) を参照してください。 +どのコンシューマーも同じ基盤となる関数を呼び出すため、記述・保守する実装は1つだけです。完全なリファレンスは [Actions](/docs/actions) を参照してください。 ## ライブ同期 {#polling-sync} -データベースの変更は、`useDbSync()` を通じて UI に同期されます。同じプロセスは `/_agent-native/events` 経由でストリームを書き込みます。 `/_agent-native/poll` は引き続きクロスプロセスおよびサーバーレス フォールバックです。エージェントがデータベース (アプリケーションの状態、設定、またはドメイン データ) に書き込むと、バージョン カウンターが増加し、クライアントは関連する React クエリ キャッシュを無効にします。 +エージェントがデータを変更したとき、UI は手動での更新なしにそれを反映する必要があります。`useDbSync()` がそれを自動化します。同一プロセスの書き込みは `/_agent-native/events` 経由でストリームされます。`/_agent-native/poll` は引き続きクロスプロセスおよびサーバーレス向けのフォールバックです。エージェントがデータベース (アプリケーション状態、設定、またはドメインデータ) に書き込むと、バージョンカウンターが増加し、クライアントは関連する React Query のキャッシュを無効化します。 ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -323,15 +360,19 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` -フローは次のとおりです: +これをアプリのルート付近で1回呼び出します。アプリ全体を変更イベントに購読させるため、`useActionQuery` やソースバージョン管理された `useQuery` を使用するどのコンポーネントも、読み取っているデータが変化すると自動的に再取得します。 -1. エージェントはデータベースに書き込むアクションを実行します -2. サーバーは、`"action"` や `"settings"` などのソースを使用して変更イベントを発行します -3. `useDbSync` は、SSE またはポーリング フォールバック経由で受信します -4. `useActionQuery` フックとソース バージョン対応の `useQuery` フックの再フェッチ -5. コンポーネントはページをリロードせずに新しいデータをレンダリングします +フローは次のとおりです。 - +1. エージェントがデータベースに書き込むアクションを実行する +2. サーバーが `"action"` や `"settings"` のような source を持つ変更イベントを発行する +3. `useDbSync` が SSE またはポーリングフォールバック経由でそれを受信する +4. `useActionQuery` フックとソースバージョン管理された `useQuery` フックが再取得する +5. コンポーネントがページのリロードなしに新しいデータをレンダリングする + +図は同じシーケンスを最初から最後まで示しています。 + + ```html
@@ -349,11 +390,13 @@ useDbSync({ queryClient });
useDbSyncSSE · poll fallback + >SSE · ポーリングフォールバック
- クエリ再取得
再読み込みなしで描画 + クエリ再取得
レンダリング、リロードなし
``` @@ -380,89 +423,90 @@ useDbSync({ queryClient }); -これは、メモリ内の状態やファイル システム ウォッチャーではなくデータベースを使用するため、サーバーレスやエッジを含むすべての導入環境で機能します。 +これは、インメモリの状態やファイルシステムウォッチャーの代わりにデータベースを使用するため、サーバーレスやエッジを含むあらゆるデプロイ環境で機能します。 ## フレーム {#frames} -_frame_ は、アプリの隣にエージェントをホストする環境です。ローカルでは埋め込みパネルです。クラウドでは、それは Builder.io のマネージド サーフェスです。 [Frames](/docs/frames) を参照してください。 +_frame_ とは、アプリの隣でエージェントをホストする環境です。ローカルでは埋め込みパネルが、クラウドでは Builder.io のマネージドサーフェスがこれにあたります。[Frames](/docs/frames) を参照してください。 -エージェント ネイティブ アプリには、アプリ UI とともに AI エージェントを提供する埋め込みエージェント パネルが含まれています。これがアーキテクチャを機能させるものです。エージェントにはコンピュータ (データベース、ブラウザ、コード実行) が必要であり、アプリには AI の作業のためにエージェントが必要です。 +agent-native アプリには、アプリの UI と並んで AI エージェントを提供する埋め込みエージェントパネルが含まれています。これがこのアーキテクチャを機能させる仕組みです。エージェントには computer (データベース、ブラウザ、コード実行) が必要であり、アプリは AI の作業のためにエージェントを必要とします。 -- **埋め込みエージェント パネル** — チャットとオプションの CLI ターミナルがすべてのアプリに組み込まれています。 Claude コード、Codex、Gemini、OpenCode、および Builder.io をサポートします。ローカルで実行されます。無料のオープンソース。 -- **クラウド** — リアルタイムのコラボレーション、ビジュアル編集、ロール、権限を備えた任意のクラウドに展開します。チームに最適です。 +- **埋め込みエージェントパネル:** すべてのアプリに組み込まれたチャットとオプションの CLI ターミナルです。Claude Code、Codex、Gemini、OpenCode、Builder.io をサポートします。ローカルで実行され、無料でオープンソースです。 +- **クラウド:** リアルタイムのコラボレーション、ビジュアル編集、ロール、権限を備えた任意のクラウドにデプロイします。チームに最適です。 ## コンテキスト認識 {#context-awareness} -エージェントは、ユーザーが何を見ているのかを常に知っています。 UI は、ルートが変更されるたびに、`navigation` キーをアプリケーション状態に書き込みます。エージェントは、行動する前に、`view-screen` アクションを介してそれを読み取ります。 +エージェントは、ユーザーが何を見ているかを常に把握しています。UI はルートが変わるたびに `navigation` キーを application-state に書き込みます。エージェントは行動する前に `view-screen` アクション経由でそれを読み取ります。 -たとえば、電子メール スレッドを開くと、UI は次のような行を更新/挿入します。 +たとえば、メールスレッドを開くと、UI は次のような行を upsert します。 ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -UI はルート変更時にこれを書き込みます。エージェントはアクションを実行する前にそれを (`view-screen` 経由で) 読み取るため、ユーザーがどのスレッド (グラフ、スライド) に注目しているかを常に把握します。 + + +UI はルート変更時にこれを書き込みます。エージェントは何らかのアクションを行う前に (`view-screen` 経由で) それを読み取るため、あなたがどのスレッド、チャート、スライドに注目しているかを常に把握しています。 -ナビゲーション状態、ビュー画面、ナビゲーション コマンド、ジッター防止などの完全なパターンについては、[Context Awareness](/docs/context-awareness) を参照してください。 + -## 1 つのアクションで多くの表面 {#protocols} +ナビゲーション状態、view-screen、navigate コマンド、ジッター防止を含む完全なパターンについては、[コンテキスト認識](/docs/context-awareness) を参照してください。 -ドメイン操作をアクションとして 1 回実装します。フレームワークはそれをすべての消費者に公開します。同じ `defineAction()` は、エージェント ツール、タイプセーフ UI フック、HTTP エンドポイント、CLI コマンド、MCP ツール、および A2A ツールになり、オプションの `link`、`mcpApp`、またはサーフェスで必要な場合にのみ明示的なネイティブ ウィジェット メタデータが追加されます。 Skills と手順には動作が含まれています。 +## 1つのアクション、多くのサーフェス {#protocols} -完全なプロトコル/サーフェス マトリックス (MCP サーバーと OAuth、MCP アプリ、A2A、ディープ リンク、ネイティブ チャット ウィジェット、AgentChatRuntime コネクタ、エージェント Web、および ACP と A2UI のアダプター ホライズン)、および製品の形状 (ヘッドレス、リッチ チャット、埋め込みサイドカー、フル アプリ) の選択については、を参照してください。 [Agent Surfaces](/docs/agent-surfaces). +ドメイン操作を1回だけアクションとして実装すれば、フレームワークがそれをすべてのコンシューマーに公開します。同じ `defineAction()` が、エージェントツール、型安全な UI フック、HTTP エンドポイント、CLI コマンド、MCP ツール、A2A ツールになります。オプションの `link`、`mcpApp`、ネイティブウィジェットメタデータ、あるいは Generative UI ラッパーは、サーフェスがよりリッチなインタラクションを必要とする場合にのみ追加されます。スキルと指示が振る舞いをカバーします。 + +完全なプロトコル/サーフェスのマトリックス (MCP サーバーと OAuth、MCP Apps、A2A、ディープリンク、ネイティブチャットウィジェット、Generative UI、AgentChatRuntime コネクタ、Agent Web、ACP と A2UI のアダプターホライズン) や、プロダクトの形 (チャット、インライン UI、フルアプリページ、埋め込みサイドカー、automation、外部エージェントアクセス) の選び方については、[エージェントサーフェス](/docs/agent-surfaces) を参照してください。 ## アプリのコードとカスタマイズ {#agent-modifies-code} -埋め込みエージェントは、デフォルトではアプリのソースコードを編集 -しません。ホストが repository/workspace の書き込みツールを意図的に -付与した場合に限り編集できます。通常のデプロイ済みアプリでは、 -エージェントは actions、SQL に保存された状態、設定済みの統合を通じて -動作します。Templates は、独自のリポジトリと開発ワークフローで fork -してカスタマイズできる完全なアプリです。 +フレームワークは、埋め込みエージェントにアプリのソースコードへのアンビエントなアクセスを付与しません。デプロイされたアプリでは、エージェントは通常アクション、SQL に保存された状態、設定済みのインテグレーションを通じて動作します。frame に workspace アクセスと書き込みツールが意図的に付与されている場合は、コンポーネント、ルート、スタイル、アクションを編集できます。Templates は、いずれの場合も自分自身のリポジトリと開発ワークフローで fork してカスタマイズできる完全なアプリです。ソースコードを変更せずにランタイムでカスタマイズするには、[Extensions](/docs/extensions) を使用してください。 -## デフォルトでポータブル {#hosting-agnostic} +## デフォルトで移植可能 {#hosting-agnostic} -2 つのアーキテクチャ ルールにより、データベースとホスト間でアプリの移植性が維持されます。 +2つのアーキテクチャルールが、データベースとホストをまたいだアプリの移植性を保ちます。 -- **Database-agnostic.** `@agent-native/core/db/schema` でスキーマを書き込み、Drizzle のポータブル クエリ DSL で読み取り/書き込みを行うため、サポートされているプロバイダーで同じコードが実行されます。生の SQL は追加的な移行または 1 回限りのメンテナンスの場合にのみ使用し、パラメータ化され方言に依存しないようにします。 [Database](/docs/database) を参照してください。 -- **ホスティングに依存しない** サーバーは Nitro 上で実行され、任意の展開ターゲットにコンパイルされます。サーバー ルートまたはプラグインではノード固有の API (`fs`、`child_process`、`path`) を決して使用しないでください。また、永続的なサーバー プロセスを想定しないでください。サーバーレスとエッジはステートレスであるため、すべての状態を SQL に保持します。 [Deployment](/docs/deployment) を参照してください。 +- **Database-agnostic。** `@agent-native/core/db/schema` でスキーマを記述し、Drizzle のポータブルなクエリ DSL で読み書きを行うことで、同じコードがサポートされるどのプロバイダーでも動作します。raw SQL は追加型のマイグレーションや1回限りのメンテナンスにのみ使用し、パラメータ化された、方言に依存しない形を保ってください。[Database](/docs/database) を参照してください。 +- **Hosting-agnostic。** サーバーは Nitro 上で動作し、任意のデプロイターゲットにコンパイルされます。サーバーのルートやプラグインで Node 固有の API (`fs`、`child_process`、`path`) を使用しないでください。また、永続的なサーバープロセスを前提にしないでください。サーバーレスとエッジはステートレスなので、すべての状態を SQL に保持してください。[Deployment](/docs/deployment) を参照してください。 -## ワークスペース {#workspace} +## エージェントリソース {#workspace} -すべてのユーザーは、個人用 **ワークスペース** (命令、skills、メモリ、カスタム サブエージェント、スケジュールされたジョブ、接続された MCP サーバー) を取得し、すべてファイルではなく SQL に保存されます。これにより、ユーザーごとにコンテナーを起動することなく、マルチテナント SaaS 内で Claude コード レベルのカスタマイズが可能になります。 [エージェント リソース](/docs/agent-resources) を参照してください。 +すべてのユーザーは、個人用の **エージェントリソース** 一式 (指示、スキル、メモリ、カスタムサブエージェント、スケジュールされたジョブ、接続された MCP サーバー) を持ちます。これらはすべてファイルではなく SQL に保存されます。これにより、ユーザーごとにコンテナを起動することなく、マルチテナント SaaS 内で Claude-Code レベルのカスタマイズが実現可能になります。[Agent Resources](/docs/agent-resources) を参照してください。 ## 関連する構成要素 {#building-blocks} -これらは同じ契約の上にあり、独自の詳細情報があります: +これらは同じ契約の上に成り立っており、それぞれ独自の詳細解説があります。 + +- **[Dispatch](/docs/dispatch):** 共有の受信トレイ、secrets vault、スケジュールされたジョブ、そして A2A 経由で専門アプリに委任するオーケストレーターを備えた workspace のコントロールプレーンです。 +- **[Extensions](/docs/extensions):** エージェントが実行時に作成する、サンドボックス化された Alpine.js のミニアプリです。ソースの変更やマイグレーションは不要です。 +- **[A2A プロトコル](/docs/a2a-protocol):** 同じ workspace 内のアプリが JSON-RPC 経由で互いを検出し、呼び出す仕組みです。 -- **[Dispatch](/docs/dispatch)** — ワークスペース コントロール プレーン: 共有受信トレイ、シークレット ボールト、スケジュールされたジョブ、および A2A を介して専門アプリに委任するオーケストレーター。 -- **[Extensions](/docs/extensions)** — エージェントが実行時に作成するサンドボックス化された Alpine.js ミニアプリ。ソースの変更や移行はありません。 -- **[データプログラム](/docs/data-programs)** — エージェントが作成し保存する `run-code` スクリプトで、ハードコードされた provider action の代わりに、キャッシュされ更新可能な結果を dashboard パネルに提供します。 -- **[A2A Protocol](/docs/a2a-protocol)** — 同じワークスペース内のアプリが JSON ～ RPC 経由で相互に検出して呼び出しを行う方法。 +## 次のステップ {#deep-dives} -## 無料で得られるもの {#what-you-get-for-free} + -フレームワークを採用することに価値があるのは、主に何を構築する必要がなくなるからです。アプリが 5 つのルールに従うと、次のルールが継承されます。 +### [Agent-Nativeとは？](/docs/what-is-agent-native) -- **1 つのアクション = すべてのサーフェス。** `defineAction()` で定義されたすべてのアクションは、同時にエージェント ツール、タイプセーフ フロントエンド フック (`useActionQuery` / `useActionMutation`)、フレームワーク所有の HTTP トランスポート、CLI コマンド、外部クライアント用の MCP ツール、および他のエージェント ネイティブ アプリ用の A2A ツールでもあります。オプションの `link` および `mcpApp` メタデータは、2 番目の実装なしでディープ リンクと MCP アプリ UI を追加します。 -- **ユーザーごとの完全なワークスペース。** Skills、共有 `LEARNINGS.md`、個人 `memory/MEMORY.md`、`AGENTS.md`、カスタム サブエージェント、スケジュールされたジョブ、接続された MCP サーバー — すべて SQL でサポートされており、dev-box は必要ありません。 [エージェント リソース](/docs/agent-resources) を参照してください。 -- **React コンポーネントをドロップインします。** `` および `` は、アプリ内の任意の場所にチャットとワークスペースをレンダリングします。 [Drop-in Agent](/docs/drop-in-agent) を参照してください。 -- **BYO エージェント チャット ランタイム。** 同じチャット UI は、OpenAI エージェント、OpenAI レスポンス、Claude エージェント SDK、Vercel AI SDK、AG-UI、または独自の正規化された HTTP ストリームの上に置くことができます。 [Native チャット UI](/docs/native-chat-ui#byo-agent-runtimes) を参照してください。 -- **エージェントと UI 間のライブ同期。** 同じプロセスが `/_agent-native/events` 経由でストリームをすぐに書き込みます。軽量のポーリングにより、サーバーレス、cron、およびクロスプロセス書き込みが収束されます。 actions を変更すると、アクションに基づくクエリが自動的に無効になるため、エージェントが作成したレコードは手動で更新しなくても表示されます。以下の [Live Sync](#polling-sync) を参照してください。 -- **認証、組織、RBAC。** 組織/メンバー/ロールによる優れた認証がすべてのテンプレートに組み込まれています。 [Authentication](/docs/authentication) を参照してください。 -- **コンテキスト認識。** エージェントは、`navigation` アプリ状態キーを通じてユーザーが何を見ているのかを常に認識します。 [Context Awareness](/docs/context-awareness) を参照してください。 -- **MCP クライアント + サーバー、両方向。** アプリは MCP サーバー (ローカル、リモート、ハブ共有) を取り込み、_そして_ 独自の actions を MCP サーバーとして公開します。 [MCP Clients](/docs/mcp-clients) および [MCP Protocol](/docs/mcp-protocol) を参照してください。 -- **アプリ間の委任。** 異なるアプリのエージェントは [A2A](/docs/a2a-protocol) 経由で会話します。同一オリジンのデプロイでは JWT がスキップされます。クロスオリジンは共有 `A2A_SECRET` を使用します。 -- **サブエージェント チーム。** 独自のスレッドとツールを備えたサブエージェントを生成し、チャット内にインライン チップとして表示されます。 [Agent Teams](/docs/agent-teams) を参照してください。 -- **移植性。** Drizzle でサポートされる SQL データベース、Nitro 互換のホスト (Node、Workers、Netlify、Vercel、Deno、Lambda、Bun)。 +このルールの背景にあるビジョンと理念です。 -これは、自分で接着する必要がある「その他すべて」です。 +### [コンテキスト認識](/docs/context-awareness) -## 次のステップ {#deep-dives} +ナビゲーション状態、view-screen、navigate コマンドについて詳しく解説します。 + +### [Skills ガイド](/docs/skills-guide) + +フレームワークのスキル、ドメインスキル、カスタムスキルの作成方法です。 + +### [ネイティブ チャット UI](/docs/native-chat-ui) + +アクションが宣言するテーブルやチャート、BYO ランタイムの方針です。 + +### [エージェントサーフェス](/docs/agent-surfaces) + +チャット、ネイティブインライン UI、フルアプリページ、埋め込みサイドカー、automation、外部エージェントの経路です。 + +### [A2A プロトコル](/docs/a2a-protocol) + +エージェント間通信です。 -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — これらのルールを支えるビジョンと理念 -- [**Context Awareness**](/docs/context-awareness) — ナビゲーション状態、view-screen、navigate コマンドの詳細 -- [**Skills Guide**](/docs/skills-guide) — フレームワーク skills、ドメイン skills、カスタム skills の作成 -- [**Native Chat UI**](/docs/native-chat-ui) — action で宣言する表とグラフ、および独自ランタイムへの対応 -- [**Agent Surfaces**](/docs/agent-surfaces) — チャット、ネイティブ インライン UI、完全なアプリページ、埋め込み sidecar、自動化、外部エージェント パス -- [**A2A Protocol**](/docs/a2a-protocol) — エージェント間通信 + diff --git a/packages/core/docs/content/locales/ko-KR/key-concepts.mdx b/packages/core/docs/content/locales/ko-KR/key-concepts.mdx index 6ced2262ab..ea998e85a7 100644 --- a/packages/core/docs/content/locales/ko-KR/key-concepts.mdx +++ b/packages/core/docs/content/locales/ko-KR/key-concepts.mdx @@ -1,45 +1,49 @@ --- -title: "주요 개념" -description: "에이전트 네이티브 앱 작동 방식: actions 우선, SQL 데이터베이스, 앱-에이전트 루프, 선택적 UI, 폴링 동기화, 외부 에이전트 진입점, 상황 인식 및 이식성." +title: "핵심 개념" +description: "에이전트 기반 앱이 세 개의 레이어(Core 프레임워크, 선택적 Toolkit 빌딩 블록, 선택적 Templates)에 걸쳐 작동하는 방식과, 공유되는 액션, SQL 데이터베이스, 앱-에이전트 루프, 이식성 규칙." --- -# 주요 개념 +# 핵심 개념 -에이전트 네이티브 앱이 내부적으로 작동하는 방식 — 원칙 및 아키텍처. 이 페이지는 계약서입니다. 이러한 방식으로 구축하는 비전과 사례는 [What Is Agent-Native?](/docs/what-is-agent-native)를 참조하세요. +에이전트 기반 앱이 내부적으로 작동하는 방식: 원칙과 아키텍처입니다. 이 페이지는 계약입니다. 앱이 에이전트 기반으로 인정받기 위해 따라야 하는 고정된 규칙입니다. 이런 방식으로 만드는 비전과 근거는 [Agent-Native란 무엇인가?](/docs/what-is-agent-native)를 참조하세요. -## 세 가지 레이어 {#three-layers} +## 세 개의 레이어 {#three-layers} -Agent Native는 하나의 템플릿이 아니라 프레임워크입니다. +Agent Native는 세 개의 레이어로 이루어진 프레임워크입니다: -- **Core - 프레임워크:** 모든 앱이 사용할 수 있는 기본 런타임 및 데이터 계약입니다. -- **Toolkit - 선택적 재사용 pieces:** 앱이 채택, 조합 또는 fork할 수 있는 공유 UI 및 제품 시스템입니다. -- **Templates - 선택적 앱:** Core를 기반으로 만든 완전한 도메인 앱으로, 대개 Toolkit을 사용하며 시작점으로 fork해 사용할 수 있습니다. +| 레이어 | 설명 | +| ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Core: 프레임워크** | 기본 런타임 계약입니다: 액션, SQL 및 Drizzle 헬퍼, 인증, 애플리케이션 상태, 에이전트 실행, 접근 검사, 라우팅, 라이브 동기화입니다. 모든 앱이 Core를 직접 사용할 수 있습니다. | +| **Toolkit: 선택적 재사용 가능 조각** | 프리미티브, 에디터, 공유, 협업, 설정, 에이전트 UX 같은 공유되는 앱 빌딩 UI 및 제품 시스템입니다. 앱은 필요한 조각을 사용하거나, 조합하거나, fork할 수 있습니다. | +| **Templates: Core 위에 구축된 선택적 앱** | 라우트, 스키마, 액션, 지침, 시각적 아이덴티티를 갖춘 완전한 도메인 특화 앱입니다. 자사 및 커스텀 템플릿은 흔히 Toolkit을 사용하며, 시작점으로 fork해서 사용할 수 있습니다. | -Core가 기반입니다. Toolkit과 Templates는 선택 사항입니다. +Core는 기반입니다. Toolkit과 Templates는 선택 사항입니다: 템플릿은 Toolkit을 사용할 수 있지만, Core 위에 앱을 만드는 데 Toolkit이 필수는 아닙니다. ## 아키텍처 {#the-architecture} -모든 에이전트 기반 앱은 세 가지가 함께 작동합니다. +런타임에서 모든 에이전트 기반 앱은 세 가지가 함께 작동하는 형태입니다: -- **에이전트** — 데이터를 읽고, 쓰고, actions를 실행하고, 구성된 도구를 사용하는 자율 AI입니다. skills 및 지침으로 사용자 정의할 수 있습니다. -- **적용** — 에이전트 주변의 제품 표면. 처음에는 작업만 수행할 수도 있고, 풍부한 채팅, 작은 제어 영역 또는 대시보드, 흐름, 시각화가 포함된 전체 React UI 화면일 수도 있습니다. -- **컴퓨터** — 데이터베이스, 브라우저, 코드 실행. 에이전트는 앱의 액션 및 데이터 표면을 통해 작업하며, 앱은 동일한 액션 표면을 MCP로 노출할 수 있습니다. 외부 MCP 서버는 선택적 추가 기능이며 기반이 아닙니다. +- **에이전트:** 자율적으로 동작하는 AI입니다. 데이터를 읽고 쓰고, 액션을 실행하고, 구성된 도구를 사용합니다. 프레임이 의도적으로 작업 공간 접근 권한과 쓰기 도구를 부여받은 경우, 앱 자체의 소스 코드도 수정할 수 있습니다. skills와 지침으로 커스터마이즈할 수 있습니다. +- **애플리케이션:** 에이전트를 둘러싼 제품 표면입니다. 채팅으로 시작해 네이티브 인라인 결과를 추가하거나, 작은 제어 플레인으로 성장하거나, 대시보드·플로우·시각화를 갖춘 완전한 React UI가 될 수 있습니다. +- **컴퓨터:** 에이전트가 작업을 수행하는 대상인 데이터베이스, 브라우저, 구성된 도구 런타임입니다. 에이전트는 앱 자체의 액션 및 데이터 표면을 통해 작업하며, 이 동일한 표면은 선택적으로 MCP를 통해 노출될 수 있지만, 외부 MCP 서버는 어디까지나 부가 기능이지 기반이 아닙니다. - +아래 다이어그램은 에이전트와 애플리케이션을 나란히 보여주며, 둘 다 그 아래에 있는 하나의 공유된 컴퓨터 레이어로 양방향 화살표를 뻗고 있습니다. 어느 쪽도 데이터를 소유하지 않습니다. 대신 양쪽 모두 동일한 SQL 저장소를 읽고 쓰므로, 한쪽에서 만든 변경 사항이 즉시 다른 쪽에서도 보이며, 그 사이에 별도의 동기화 레이어를 만들 필요가 없습니다. + + ```html
- Agent에이전트데이터를 읽고 쓰고, actions를 실행하고, 구성된 도구를 사용데이터를 읽고 쓰고, 액션을 실행하고, 구성된 도구를 사용
- Application애플리케이션action 전용, 채팅, 제어 평면 또는 전체 React UI 화면채팅, 인라인 결과, 제어 플레인, 또는 완전한 React UI
@@ -47,8 +51,8 @@ Core가 기반입니다. Toolkit과 Templates는 선택 사항입니다. ↓ ↑
- Computer
SQL 데이터베이스 · browser · code executionSQL 데이터베이스 · 브라우저 · 코드 실행
@@ -86,81 +90,101 @@ Core가 기반입니다. Toolkit과 Templates는 선택 사항입니다. -헤드리스 앱은 `pnpm agent`를 사용하여 폴더에서 동일한 프로덕션 앱-에이전트 루프를 실행할 수 있는 반면, UI 앱은 내장된 에이전트 패널을 마운트하고 `pnpm dev`를 사용하여 로컬로 실행할 수 있습니다. 클라우드에서 Builder.io는 협업, 시각적 편집 및 팀을 위한 관리형 인프라를 갖춘 관리형 프레임(앱 옆에 에이전트를 호스팅하는 환경)을 제공합니다. +이 동일한 에이전트-애플리케이션-컴퓨터 루프가 로컬과 프로덕션 양쪽에서 실행되는 바로 그것입니다. 자동화 우선 앱은 폴더에서 바로 `pnpm agent`로 이를 실행합니다. UI 앱은 내장된 에이전트 패널을 마운트하고 `pnpm dev`를 추가합니다. 클라우드에서는 Builder.io가 동일한 루프를 관리형 프레임으로 호스팅합니다: 앱 옆에서 에이전트를 실행하는 환경입니다. 협업, 시각적 편집, 인프라를 대신 처리해 줍니다. ## 에이전트 빌딩 블록 {#agent-building-blocks} -모든 에이전트 기반 앱에는 여부에 관계없이 동일한 에이전트 구성 요소가 있습니다. -제품 표면은 헤드리스, 채팅 우선 또는 전체 UI입니다. +모든 에이전트 기반 앱은 제품 표면이 채팅 우선이든, 자동화 우선이든, 완전한 UI든 관계없이 +동일한 에이전트 빌딩 블록을 갖습니다. 각각은 자신만의 파일에 있습니다: /SKILL.md", - note: "재사용 가능한 동작: workflow 단계, 정책, 예시, 참조, 해야 할 일/하지 말아야 할 일 목록", + note: "재사용 가능한 동작: 워크플로 단계, 정책, 예시, 참조, 해야 할 일/하지 말아야 할 일 목록", }, { path: "actions/.ts", - note: "실행 가능한 기능: 에이전트, UI, CLI, HTTP, MCP, A2A, jobs, webhooks에 노출되는 typed operation", + note: "실행 가능한 기능: 타입이 지정된 오퍼레이션으로, 에이전트, UI, CLI, HTTP, MCP, A2A, 예약된 작업, 웹훅에 노출됩니다", }, ]} /> -| 빌딩 블록 | 사용 | 로드되는 시기 | -| ----------- | --------------------------------------------------------------------------------------- | --------------------------------------------- | -| **지침** | 에이전트가 모든 작업에서 수행해야 하는 안정적인 지침: 앱이 무엇인지, 불변성, 어조, 색인 | 매 턴 | -| **Skills** | 재사용 가능한 동작: 워크플로 따르기, 정책 적용, 증거 검사 또는 출력 확인 방법 | 기술 설명이 작업과 일치할 때 요청 시 | -| **Actions** | 실제 작업: 데이터 읽기 또는 쓰기, API 호출, 메시지 보내기, 승인 실행, 입력된 결과 생성 | 매 턴마다 도구로 표시됩니다. 호출될 때만 실행 | +턴(turn)은 에이전트와의 한 번의 상호작용입니다: 컨텍스트를 읽고, 무엇을 할지 결정하고, 응답합니다. "매 턴 로드됨"은 세션 시작 시 한 번만이 아니라 매번 해당 파일이 다시 컨텍스트에 들어온다는 뜻입니다. + +| 빌딩 블록 | 파일 | 용도 | 로드 시점 | +| ---------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------- | +| **지침** | `AGENTS.md` | 에이전트가 모든 작업에 걸쳐 유지해야 하는 안정적인 안내: 앱이 무엇인지, 불변 조건, 어조, 색인 | 매 턴 | +| **Skills** | `.agents/skills//SKILL.md` | 재사용 가능한 동작: 워크플로를 따르는 방법, 정책을 적용하는 방법, 증거를 검사하는 방법, 또는 출력을 검증하는 방법 | skill 설명이 작업과 일치할 때 요청 시 | +| **액션** | `actions/.ts` | 실제 오퍼레이션: 데이터 읽기/쓰기, API 호출, 메시지 전송, 승인 실행, 타입이 지정된 결과 생성 | 매 턴 도구로 나열됨; 호출될 때만 실행 | -Skills와 actions는 함께 작동합니다. 기술은 상담원에게 다음과 같은 클래스를 수행하는 방법을 가르칩니다. -일; 작업은 해당 작업을 수행하는 동안 호출할 수 있는 코드 경로입니다. 예를 들면, -`customer-research` 기술은 에이전트에게 검사할 소스를 알려줄 수 있으며 -`search-crm` 및 `create-brief` actions를 가져오는 동안 증거를 요약하는 방법 -실제 데이터를 씁니다. +Skills와 액션은 함께 작동합니다. skill은 에이전트에게 특정 부류의 작업을 +수행하는 방법을 가르치고, 액션은 그 작업을 수행하는 동안 호출할 수 있는 +코드 경로입니다. 예를 들어 `customer-research` skill은 에이전트에게 어떤 +소스를 검사할지와 증거를 요약하는 방법을 알려주고, `search-crm` 및 +`create-brief` 액션은 실제 데이터를 가져오고 씁니다. -아키텍처를 관리하는 5가지 규칙: +다섯 가지 규칙이 이 아키텍처를 지배합니다: -1. **데이터는 SQL에 있습니다** — 모든 앱 상태는 Drizzle ORM를 통해 데이터베이스에 있습니다. -2. **모든 AI는 에이전트를 통과합니다** — 인라인 LLM 호출 없음 -3. **에이전트 작업용 Actions** — 복잡한 작업은 actions로 실행됩니다. -4. **라이브 동기화는 UI의 동기화를 유지합니다** — 폴링을 범용 폴백으로 사용하여 SSE를 통한 데이터베이스 변경 스트림 -5. **애플리케이션 상태는 SQL에 있습니다** — 임시 UI 상태는 데이터베이스에 저장되며 에이전트와 UI가 모두 읽을 수 있습니다. +1. **데이터는 SQL에 있습니다:** 모든 앱 상태는 Drizzle ORM을 통해 데이터베이스에 있습니다. +2. **모든 AI는 에이전트를 거칩니다:** 인라인 LLM 호출은 없습니다. 모든 AI 상호작용은 에이전트 채팅 브리지를 통해 흐릅니다. +3. **에이전트 오퍼레이션에는 액션을 사용합니다:** 복잡한 작업은 인라인 코드가 아니라 타입이 지정된 액션으로 실행됩니다. +4. **라이브 동기화가 UI를 동기화된 상태로 유지합니다:** 데이터베이스 변경 사항은 SSE로 스트리밍되며, 폴링이 범용 폴백 역할을 합니다. +5. **애플리케이션 상태는 SQL에 있습니다:** 임시 UI 상태는 데이터베이스에 있으며, 에이전트와 UI 모두 읽을 수 있습니다. ## 4개 영역 체크리스트 {#four-area-checklist} -사용자에게 제공되는 모든 기능은 적용 가능한 모든 영역을 업데이트해야 합니다. 해당 영역을 건너뛰면 에이전트-네이티브 계약이 중단됩니다. 액션 전용 프리미티브에 UI를 강제하는 것도 냄새입니다. +사용자에게 노출되는 모든 기능은 해당하는 모든 영역을 업데이트해야 합니다. 해당되는 영역을 건너뛰면 에이전트 기반 계약이 깨집니다. 사람이 볼 필요가 없는 자동화에 화면을 억지로 붙이는 것도 좋지 않은 신호입니다. + +- **1. UI:** 사용자가 상호작용하는 페이지, 컴포넌트, 또는 대화 상자입니다. +- **2. Action:** 동일한 오퍼레이션에 대해 `actions/`에 있는 에이전트 호출 가능한 액션입니다. +- **3. Skills:** `AGENTS.md`를 업데이트하고, 그리고/또는 해당 패턴을 문서화하는 skill을 만듭니다. +- **4. App-State:** 내비게이션 상태, view-screen 데이터, navigate 명령입니다. + +UI만 있는 기능은 에이전트에게 보이지 않습니다. 액션만 있는 완전한 UI 기능은 사용자에게 보이지 않습니다. app-state가 없는 기능은 에이전트가 사용자가 무엇을 하고 있는지 알지 못한다는 뜻입니다. 자동화 우선 오퍼레이션은 액션 + 지침으로 시작하는 것이 정당하며, 사람이 이를 탐색하거나 승인하거나 구성하거나 공유해야 할 때 채팅, UI, 또는 app-state를 나중에 추가할 수 있습니다. -| 지역 | 설명 | -| -------------- | ------------------------------------------------------- | -| **1. UI** | 사용자가 상호작용하는 페이지, 구성 요소 또는 대화 상자 | -| **2. 액션** | 동일한 작업에 대해 actions/에서 에이전트 호출 가능 작업 | -| **3. Skills** | AGENTS.md 업데이트 및/또는 패턴을 문서화하는 기술 생성 | -| **4. 앱 상태** | 탐색 상태, 화면 데이터 보기 및 명령 탐색 | +## Agent Native가 기본으로 제공하는 것 {#what-you-get-for-free} -UI만 있는 기능은 에이전트에 표시되지 않습니다. actions만 포함된 전체 UI 기능은 사용자에게 표시되지 않습니다. 앱 상태가 없는 기능은 에이전트가 사용자가 무엇을 하고 있는지 알 수 없음을 의미합니다. 헤드리스 작업은 합법적으로 작업 + 지침으로 시작하고 나중에 사람이 탐색, 승인, 구성 또는 공유해야 할 때 UI/app-state를 추가할 수 있습니다. +이 프레임워크를 채택하는 것이 가치 있는 주된 이유는 더 이상 직접 만들 필요가 없어지는 것들 때문입니다. 앱이 위의 다섯 가지 규칙을 따르는 순간, 다음을 자동으로 물려받습니다: + +| 기능 | 제공하는 것 | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 하나의 액션 = 모든 표면 | `defineAction()`으로 정의된 모든 액션은 동시에 에이전트 도구, 타입 안전한 프런트엔드 훅(`useActionQuery` / `useActionMutation`), 프레임워크가 소유하는 HTTP 전송, CLI 명령, 외부 클라이언트를 위한 MCP 도구, 그리고 다른 에이전트 기반 앱을 위한 A2A 도구가 됩니다. 선택적인 `link` 및 `mcpApp` 메타데이터는 두 번째 구현 없이 딥 링크와 MCP Apps UI를 추가합니다. | +| 사용자별 완전한 에이전트 리소스 | Skills, 공유 `LEARNINGS.md`, 개인 `memory/MEMORY.md`, `AGENTS.md`, 사용자 정의 하위 에이전트, 예약된 작업, 연결된 MCP 서버입니다. 모두 SQL 기반이며 dev-box가 필요 없습니다. [Agent Resources](/docs/agent-resources)를 참조하세요. | +| 드롭인 React 컴포넌트 | ``와 ``는 앱 어디에서나 채팅 + 리소스를 렌더링합니다. [Drop-in Agent](/docs/drop-in-agent)를 참조하세요. | +| BYO 에이전트 채팅 런타임 | 동일한 채팅 UI가 OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI, 또는 자체 정규화된 HTTP 스트림 위에서 동작할 수 있습니다. [기본 채팅 UI](/docs/native-chat-ui#byo-agent-runtimes)를 참조하세요. | +| 에이전트와 UI 간 라이브 동기화 | 동일 프로세스 쓰기는 `/_agent-native/events`를 통해 즉시 스트리밍됩니다. 가벼운 폴링이 서버리스, cron, 크로스 프로세스 쓰기를 수렴 상태로 유지합니다. 변형(mutating) 액션은 액션 기반 쿼리를 자동으로 무효화하므로, 에이전트가 생성한 레코드가 수동 새로고침 없이 나타납니다. 아래 [Live Sync](#polling-sync)를 참조하세요. | +| Auth, orgs, RBAC | orgs/members/roles를 갖춘 Better Auth가 모든 템플릿에 연결되어 있습니다. [Authentication](/docs/authentication)을 참조하세요. 사용자가 두 명 이상이라면 [Organizations, Teams & Permissions](/docs/organizations-teams-permissions)부터 시작하세요. | +| 컨텍스트 인식 | 에이전트는 `navigation` app-state 키를 통해 사용자가 무엇을 보고 있는지 항상 알고 있습니다. [상황 인식](/docs/context-awareness)를 참조하세요. | +| MCP 클라이언트 + 서버, 양방향 | 앱은 MCP 서버(로컬, 원격, 허브 공유)를 수집하는 동시에 _자체_ 액션을 MCP 서버로 노출합니다. [MCP Clients](/docs/mcp-clients)와 [MCP Protocol](/docs/mcp-protocol)을 참조하세요. | +| 앱 간 위임 | 서로 다른 앱의 에이전트가 [A2A](/docs/a2a-protocol)를 통해 대화합니다. 동일 출처 배포는 JWT를 건너뛰고, 교차 출처는 공유 `A2A_SECRET`를 사용합니다. | +| 하위 에이전트 팀 | 자체 스레드와 도구를 가진 하위 에이전트를 생성하며, 채팅에 인라인 칩으로 표시됩니다. [Agent Teams](/docs/agent-teams)를 참조하세요. | +| 이식성 | Drizzle이 지원하는 모든 SQL 데이터베이스, Nitro와 호환되는 모든 호스트(Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). | ## SQL의 데이터 {#data-in-sql} -모든 애플리케이션 상태는 Drizzle ORM를 통해 SQL 데이터베이스에 있습니다. 스키마는 공급자에 구애받지 않습니다. 지원되는 데이터베이스, `DATABASE_URL` 구성 및 이식성 규칙은 [Database](/docs/database)에 있습니다. +모든 애플리케이션 상태는 Drizzle ORM을 통해 SQL 데이터베이스에 있습니다. 스키마는 프로바이더에 구애받지 않습니다. 지원되는 데이터베이스, `DATABASE_URL` 구성, 이식성 규칙은 [Database](/docs/database)에 있습니다. + +핵심 SQL 스토어는 자동으로 생성되며 모든 템플릿에서 사용할 수 있습니다: -핵심 SQL 스토어는 자동으로 생성되며 모든 템플릿에서 사용할 수 있습니다. +- `application_state`: 임시 UI 상태(내비게이션, 초안, 선택 항목) +- `settings`: 영구적인 키-값 구성 +- `oauth_tokens`: OAuth 자격 증명 +- `sessions`: 인증 세션 -- `application_state` — 임시 UI 상태(탐색, 초안, 선택) -- `settings` — 영구 키-값 구성 -- `oauth_tokens` — OAuth 자격 증명 -- `sessions` — 인증 세션 +아래 각 행은 확장하면 필드를 보여줍니다: +자신만의 도메인 데이터를 추가하려면, 위의 핵심 스토어에서 사용된 것과 동일한 스키마 헬퍼로 테이블을 정의하세요: + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -245,28 +271,30 @@ export const forms = table("forms", { }); ``` +당신과 에이전트 모두 별도의 SQL 클라이언트 없이 터미널에서 해당 데이터를 검사할 수 있습니다: + ```bash -# 신속한 데이터베이스 검사를 위한 핵심 조치 +# 빠른 데이터베이스 점검을 위한 Core actions pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -프로덕션 에이전트 채팅 플러그인은 raw SQL 도구를 기본적으로 읽기 전용으로 둡니다 -(`frameworkTools: { database: "read" }`). 에이전트는 `db-schema` / `db-query`로 앱 소유 -데이터를 검사하고, 쓰기는 typed app actions를 통해 수행합니다. -스코프가 적용된 `db-exec` / `db-patch`도 노출해야 하는 의도적인 -유지 관리 화면에서만 `database: "write"`(또는 `true`)를 설정합니다. -모든 데이터 접근에 typed app actions를 요구하려면 `database: "off"` / -`false`를 설정합니다. +`db-schema`는 모든 테이블의 컬럼과 타입을 출력합니다. `db-query`는 읽기 전용 SQL을 직접 실행하며, 데이터베이스 클라이언트를 열지 않고도 액션이 쓴 내용을 확인할 때 유용합니다. + + + +프로덕션 에이전트 채팅 플러그인은 raw SQL 도구를 기본적으로 읽기 전용으로 둡니다(`frameworkTools: { database: "read" }`). 에이전트는 `db-schema` / `db-query`로 앱 소유 데이터를 검사하고, 쓰기는 typed app actions를 통해 수행합니다. 스코프가 적용된 `db-exec` / `db-patch`도 노출해야 하는 의도적인 유지 관리 화면에서만 `database: "write"`(또는 `true`)를 설정합니다. 모든 데이터 접근에 typed app actions를 요구하려면 `database: "off"` / `false`를 설정합니다. + + `frameworkTools`는 프레임워크 자체의 나머지 도구도 같은 방식으로 관리합니다: 공유, 리뷰 코멘트, 버전 이력, feature flags, 로컬라이제이션, 감사, Context X-Ray, 프로필, 자동화, docs, resources, web, 앱 간 위임, 채팅, 이메일. 전체 목록과 `"minimal"` 프리셋, 그룹을 꺼도 HTTP 라우트가 유지되는 이유는 [Production Agent Tools](/docs/deployment#production-agent-tools)를 참고하세요. ## 에이전트 채팅 브리지 {#agent-chat-bridge} -UI는 LLM를 직접 호출하지 않습니다. 사용자가 "차트 생성" 또는 "요약 작성"을 클릭하면 UI는 `postMessage`를 통해 에이전트에 메시지를 보냅니다. 에이전트는 전체 대화 기록, skills, 지침 및 반복 기능을 사용하여 작업을 수행합니다. +UI는 절대 LLM을 직접 호출하지 않습니다. 사용자가 "Generate chart" 또는 "Write summary"를 클릭하면, UI는 `postMessage`를 통해 에이전트에게 메시지를 보냅니다. 작업은 에이전트가 수행합니다. 에이전트는 전체 대화 기록, skills, 지침, 그리고 반복 작업을 수행할 수 있는 능력을 갖추고 있습니다. ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -275,16 +303,19 @@ sendToAgentChat({ }); ``` -LLM를 인라인으로 호출하면 어떨까요? +요약하면: + +- **AI는 비결정적입니다**: 피드백을 주고 반복하려면 일회성 버튼이 아니라 대화 흐름이 필요합니다. +- **컨텍스트가 중요합니다**: 에이전트는 앱의 지침, skills, 기록을 가지고 있습니다. 인라인 호출에는 이런 것이 전혀 없습니다. +- **에이전트는 더 많은 것을 할 수 있습니다**: 액션을 실행하고, 웹을 탐색하고, 여러 단계를 연결할 수 있습니다. -- **AI는 비결정적입니다.** 피드백을 제공하고 반복하려면 일회성 버튼이 아닌 대화 흐름이 필요합니다. -- **컨텍스트가 중요합니다.** 에이전트에는 전체 코드베이스, 지침, skills 및 기록이 있습니다. 인라인 호출에는 그런 것이 없습니다. -- **에이전트는 더 많은 일을 할 수 있습니다.** actions를 실행하고, 웹을 검색하고, 여러 단계를 함께 연결할 수 있습니다. -- **헤드리스 실행.** 모든 것이 에이전트를 통과하므로 Slack, Telegram 또는 [A2A](/docs/a2a-protocol)를 통해 다른 에이전트에서 모든 앱을 전적으로 구동할 수 있습니다. +**[외부 실행](/docs/a2a-protocol)** -## Actions 시스템 {#actions-system} +모든 것이 에이전트와 액션을 거치기 때문에, 어떤 앱이든 Slack, Telegram, 예약된 작업, 스크립트, 또는 A2A를 통한 다른 에이전트로 구동될 수 있습니다. -에이전트가 API 호출, 데이터 처리, 데이터베이스 쿼리 등 복잡한 작업을 수행해야 하는 경우 **작업**을 실행합니다. Actions는 기본 `defineAction()`를 내보내는 `actions/`의 TypeScript 파일입니다. +## 액션 시스템 {#actions-system} + +에이전트가 API 호출, 데이터 처리, 데이터베이스 쿼리처럼 복잡한 작업을 수행해야 할 때, **액션**을 실행합니다. 액션은 `actions/`에 있는 TypeScript 파일로, 기본으로 `defineAction()`을 내보냅니다: ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -302,19 +333,30 @@ export default defineAction({ }); ``` -`defineAction()` 호출 한 번으로 다음을 얻을 수 있습니다: +이 액션은 소스 API에서 JSON을 가져와 반환합니다. `defineAction()`은 입력값(`source`)에 대한 zod 스키마로 함수를 감싸므로, 프레임워크는 이 하나의 정의만으로 입력을 검증하고, 에이전트가 호출할 수 있는 JSON Schema를 생성하고, 프런트엔드 훅을 위한 타입을 추론할 수 있습니다. + +하나의 `defineAction()` 호출은 자동으로 다섯 개의 서로 다른 소비자에게 도달합니다. 다이어그램은 하나의 액션에서 뻗어나가는 팬아웃을 보여주며, 아래 목록은 각 소비자가 무엇을 얻는지 설명합니다: + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **에이전트 도구** — 에이전트는 zod 파생 JSON 스키마로 이를 보고 호출할 수 있습니다. -- **프런트엔드 후크** — 전체 TypeScript 추론이 포함된 `useActionMutation("fetch-data")`. -- **프레임워크 전송** — 클라이언트 후크 뒤에 자동으로 마운트됩니다. -- **CLI** — 스크립팅 및 에이전트 개발 루프용 `pnpm action fetch-data --source=signups`. -- **MCP 도구 / A2A 도구** — MCP 서버 또는 A2A가 활성화되면 동일한 작업이 거기에도 표시됩니다. +- **에이전트 도구:** 에이전트는 zod에서 파생된 JSON Schema로 이를 보고 호출할 수 있습니다. +- **프런트엔드 훅:** 전체 TypeScript 추론이 포함된 `useActionMutation("fetch-data")`입니다. +- **프레임워크 전송:** 클라이언트 훅 뒤에 자동으로 마운트됩니다. +- **CLI:** 스크립팅과 에이전트 개발 루프를 위한 `pnpm action fetch-data --source=signups`입니다. +- **MCP 도구 / A2A 도구:** MCP 서버 또는 A2A가 활성화되면 동일한 액션이 그곳에도 나타납니다. -동일한 논리, 하나의 정의가 모든 소비자에게 자동으로 연결됩니다. 전체 참조는 [Actions](/docs/actions)를 참조하세요. +모든 소비자는 동일한 기반 함수를 호출하므로, 작성하고 유지 관리해야 할 구현은 단 하나뿐입니다. 전체 레퍼런스는 [Actions](/docs/actions)를 참조하세요. ## 라이브 동기화 {#polling-sync} -데이터베이스 변경 사항은 `useDbSync()`를 통해 UI에 동기화됩니다. `/_agent-native/events`를 통한 동일한 프로세스 쓰기 스트림; `/_agent-native/poll`는 크로스 프로세스 및 서버리스 폴백으로 유지됩니다. 에이전트가 데이터베이스(애플리케이션 상태, 설정 또는 도메인 데이터)에 쓰면 버전 카운터가 증가하고 클라이언트는 관련 React 쿼리 캐시를 무효화합니다. +에이전트가 데이터를 변경하면, UI는 수동 새로고침 없이 이를 반영해야 합니다. `useDbSync()`가 이를 자동으로 처리합니다. 동일 프로세스 쓰기는 `/_agent-native/events`를 통해 스트리밍되며, `/_agent-native/poll`은 크로스 프로세스 및 서버리스 폴백으로 남아 있습니다. 에이전트가 데이터베이스(애플리케이션 상태, 설정, 또는 도메인 데이터)에 쓰면, 버전 카운터가 증가하고 클라이언트는 관련된 React Query 캐시를 무효화합니다. ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -322,20 +364,24 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` -흐름은 다음과 같습니다. +앱의 루트 근처에서 이를 한 번 호출하세요. 이는 앱 전체를 변경 이벤트에 구독시키므로, `useActionQuery`나 소스 버전이 지정된 `useQuery`를 사용하는 모든 컴포넌트는 자신이 읽는 데이터가 바뀌면 자동으로 다시 가져옵니다. -1. 에이전트가 데이터베이스에 쓰는 작업을 실행합니다. -2. 서버는 `"action"` 또는 `"settings"`와 같은 소스를 사용하여 변경 이벤트를 내보냅니다. -3. `useDbSync`는 SSE 또는 폴링 폴백을 통해 수신합니다. -4. `useActionQuery` 후크 및 소스 버전 `useQuery` 후크 다시 가져오기 -5. 구성 요소는 페이지를 다시 로드하지 않고도 새 데이터를 렌더링합니다. +흐름은 다음과 같습니다: - +1. 에이전트가 데이터베이스에 쓰는 액션을 실행합니다 +2. 서버가 `"action"` 또는 `"settings"`와 같은 소스를 가진 변경 이벤트를 내보냅니다 +3. `useDbSync`가 SSE 또는 폴링 폴백을 통해 이를 수신합니다 +4. `useActionQuery` 훅과 소스 버전이 지정된 `useQuery` 훅이 다시 가져옵니다 +5. 컴포넌트가 페이지 새로고침 없이 새 데이터를 렌더링합니다 + +다이어그램은 동일한 흐름을 처음부터 끝까지 추적합니다: + + ```html
- 에이전트 작업
DB에 기록 + 에이전트 액션
DB에 씀
@@ -346,12 +392,12 @@ useDbSync({ queryClient });
useDbSyncSSE · poll fallback + >SSE · 폴링 폴백
쿼리 다시 가져오기
새로고침 없이 렌더링렌더링, 새로고침 없음
@@ -383,84 +429,92 @@ useDbSync({ queryClient }); ## 프레임 {#frames} -*프레임*은 앱 옆에 있는 에이전트를 호스팅하는 환경입니다. 로컬에서는 내장 패널입니다. 클라우드에서는 Builder.io의 관리 표면입니다. [Frames](/docs/frames)를 참조하세요. +*프레임*은 앱 옆에서 에이전트를 호스팅하는 환경입니다. 로컬에서는 내장된 패널이고, 클라우드에서는 Builder.io의 관리형 표면입니다. [Frames](/docs/frames)를 참조하세요. -에이전트 네이티브 앱에는 UI 앱과 함께 AI 에이전트를 제공하는 내장형 에이전트 패널이 포함되어 있습니다. 이것이 아키텍처가 작동하는 이유입니다. 에이전트에는 컴퓨터(데이터베이스, 브라우저, 코드 실행)가 필요하고 앱에는 AI 작업을 위한 에이전트가 필요합니다. +에이전트 기반 앱에는 앱 UI와 나란히 AI 에이전트를 제공하는 내장된 에이전트 패널이 포함되어 있습니다. 이것이 이 아키텍처가 작동하는 이유입니다: 에이전트에는 컴퓨터(데이터베이스, 브라우저, 코드 실행)가 필요하고, 앱에는 AI 작업을 위한 에이전트가 필요합니다. -- **내장형 에이전트 패널** — 모든 앱에 채팅 및 선택적 CLI 터미널이 내장되어 있습니다. Claude 코드, Codex, Gemini, OpenCode 및 Builder.io를 지원합니다. 로컬로 실행됩니다. 무료 오픈 소스. -- **클라우드** — 실시간 공동 작업, 시각적 편집, 역할 및 권한을 통해 모든 클라우드에 배포합니다. 팀에 가장 적합합니다. +- **내장된 에이전트 패널:** 모든 앱에 채팅과 선택적 CLI 터미널이 내장되어 있습니다. Claude Code, Codex, Gemini, OpenCode, Builder.io를 지원합니다. 로컬에서 실행되며 무료 오픈 소스입니다. +- **클라우드:** 실시간 협업, 시각적 편집, 역할, 권한을 갖춘 모든 클라우드에 배포합니다. 팀에 가장 적합합니다. -## 상황 인식 {#context-awareness} +## 컨텍스트 인식 {#context-awareness} -에이전트는 항상 사용자가 무엇을 보고 있는지 알고 있습니다. UI는 경로가 변경될 때마다 애플리케이션 상태에 `navigation` 키를 기록합니다. 에이전트는 행동하기 전에 `view-screen` 작업을 통해 이를 읽습니다. +에이전트는 사용자가 무엇을 보고 있는지 항상 알고 있습니다. UI는 라우트가 바뀔 때마다 `navigation` 키를 애플리케이션 상태에 기록합니다. 에이전트는 행동하기 전에 `view-screen` 액션을 통해 이를 읽습니다. -예를 들어 이메일 스레드를 열면 UI는 다음과 같은 행을 업데이트합니다. +예를 들어, 이메일 스레드를 열면 UI는 다음과 같은 행을 upsert합니다: ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -UI는 경로 변경 시 이를 기록합니다. 상담원은 조치를 취하기 전에 이를 읽으므로(`view-screen`를 통해) 귀하가 집중하고 있는 스레드, 차트, 슬라이드가 무엇인지 항상 알 수 있습니다. + + +UI는 라우트가 바뀔 때 이를 기록합니다. 에이전트는 어떤 행동을 하기 전에(`view-screen`을 통해) 이를 읽으므로, 당신이 어떤 스레드, 차트, 슬라이드에 집중하고 있는지 항상 알고 있습니다. + + -탐색 상태, 화면 보기, 명령 탐색 및 지터 방지 등 전체 패턴을 보려면 [Context Awareness](/docs/context-awareness)를 참조하세요. +전체 패턴(내비게이션 상태, view-screen, navigate 명령, 지터 방지)은 [상황 인식](/docs/context-awareness)를 참조하세요. -## 하나의 작업, 다양한 표면 {#protocols} +## 하나의 액션, 여러 표면 {#protocols} -도메인 작업을 작업으로 한 번 구현합니다. 프레임워크는 이를 모든 소비자에게 노출합니다. 동일한 `defineAction()`는 에이전트 도구, 유형 안전 UI 후크, HTTP 엔드포인트, CLI 명령, MCP 도구 및 A2A 도구가 되며 선택적 `link`, `mcpApp` 또는 표면에 필요할 때만 추가된 명시적 기본 위젯 메타데이터가 있습니다. Skills 및 지침은 동작을 다룹니다. +도메인 오퍼레이션을 액션으로 한 번 구현하면, 프레임워크가 이를 모든 소비자에게 노출합니다. 동일한 `defineAction()`이 에이전트 도구, 타입 안전한 UI 훅, HTTP 엔드포인트, CLI 명령, MCP 도구, A2A 도구가 되며, 표면이 더 풍부한 상호작용을 필요로 할 때만 선택적으로 `link`, `mcpApp`, 네이티브 위젯 메타데이터, 또는 Generative UI 래퍼가 추가됩니다. Skills와 지침은 동작을 다룹니다. -전체 프로토콜/표면 매트릭스(MCP 서버 및 OAuth, MCP 앱, A2A, 딥 링크, 기본 채팅 위젯, AgentChatRuntime 커넥터, 에이전트 웹 및 ACP 및 A2UI의 어댑터 지평선) 및 제품 형태 선택(헤드리스, 리치 채팅, 임베디드 사이드카 또는 전체 앱)에 대해서는 다음을 참조하세요. [Agent Surfaces](/docs/agent-surfaces). +전체 프로토콜/표면 매트릭스(MCP 서버 및 OAuth, MCP Apps, A2A, 딥 링크, 네이티브 채팅 위젯, Generative UI, AgentChatRuntime 커넥터, Agent Web, 그리고 ACP와 A2UI를 위한 어댑터 지평선)와, 제품 형태 선택(채팅, 인라인 UI, 전체 앱 페이지, 임베디드 사이드카, 자동화, 또는 외부 에이전트 접근) 방법에 대해서는 [에이전트 서피스](/docs/agent-surfaces)를 참조하세요. ## 앱 코드와 사용자 지정 {#agent-modifies-code} -임베디드 에이전트는 기본적으로 앱의 소스 코드를 편집하지 않습니다. -호스트가 repository/workspace 쓰기 도구를 의도적으로 부여한 경우에만 -편집할 수 있습니다. 일반적인 배포 앱에서 에이전트는 actions, SQL 기반 -상태 및 구성된 통합을 통해 작업합니다. Templates는 자체 저장소와 개발 -워크플로에서 fork하고 사용자 지정할 수 있는 완전한 앱입니다. +프레임워크는 내장된 에이전트에게 앱의 소스 코드에 대한 상시(ambient) 접근 권한을 +부여하지 않습니다. 배포된 앱에서 에이전트는 보통 액션, SQL 기반 상태, 구성된 통합을 +통해 작업합니다. 프레임이 의도적으로 작업 공간과 쓰기 도구를 부여받은 경우에는 +컴포넌트, 라우트, 스타일, 액션을 편집할 수 있습니다. Templates는 완전한 앱으로, +어느 경우든 자신의 저장소와 개발 워크플로에서 fork하여 커스터마이즈할 수 있습니다. +소스 코드 변경 없이 런타임에 커스터마이즈하려면 [Extensions](/docs/extensions)를 +사용하세요. -## 기본적으로 휴대 가능 {#hosting-agnostic} +## 기본적으로 이식 가능 {#hosting-agnostic} -두 가지 아키텍처 규칙은 데이터베이스와 호스트 간에 앱의 이식성을 유지합니다. +두 가지 아키텍처 규칙이 앱을 데이터베이스와 호스트에 걸쳐 이식 가능하게 유지합니다: -- **데이터베이스에 구애받지 않음.** `@agent-native/core/db/schema`로 스키마를 작성하고 Drizzle의 휴대용 쿼리 DSL로 읽기/쓰기를 수행하므로 지원되는 모든 공급자에서 동일한 코드가 실행됩니다. 추가 마이그레이션 또는 일회성 유지 관리에만 원시 SQL를 사용하고 매개변수화되고 방언에 구애받지 않습니다. [Database](/docs/database)를 참조하세요. -- **호스팅에 구애받지 않습니다.** 서버는 Nitro에서 실행되며 모든 배포 대상으로 컴파일됩니다. 서버 경로 또는 플러그인에서 노드별 API(`fs`, `child_process`, `path`)를 사용하지 말고 영구 서버 프로세스를 가정하지 마십시오. 서버리스 및 엣지는 상태 비저장이므로 모든 상태를 SQL에 유지하세요. [Deployment](/docs/deployment)를 참조하세요. +- **데이터베이스에 구애받지 않음.** `@agent-native/core/db/schema`로 스키마를 작성하고, Drizzle의 이식 가능한 쿼리 DSL로 읽기/쓰기를 수행하면, 동일한 코드가 지원되는 모든 프로바이더에서 실행됩니다. 원시 SQL은 추가적인 마이그레이션이나 일회성 유지 관리에만 사용하고, 매개변수화하고 방언에 구애받지 않게 유지하세요. [Database](/docs/database)를 참조하세요. +- **호스팅에 구애받지 않음.** 서버는 Nitro에서 실행되며 어떤 배포 대상으로도 컴파일됩니다. 서버 라우트나 플러그인에서 Node 전용 API(`fs`, `child_process`, `path`)를 절대 사용하지 말고, 영구적인 서버 프로세스를 가정하지 마세요. 서버리스와 엣지는 상태를 저장하지 않으므로, 모든 상태를 SQL에 유지하세요. [Deployment](/docs/deployment)를 참조하세요. -## 작업 공간 {#workspace} +## 에이전트 리소스 {#workspace} -모든 사용자는 개인 **작업 공간**(지침, skills, 메모리, 사용자 정의 하위 에이전트, 예약된 작업 및 연결된 MCP 서버)을 갖게 되며 모두 파일이 아닌 SQL에 저장됩니다. 이를 통해 사용자당 컨테이너를 가동하지 않고도 다중 테넌트 SaaS 내에서 Claude 코드 수준 사용자 정의가 가능해졌습니다. [에이전트 리소스](/docs/agent-resources)를 참조하세요. +모든 사용자는 개인 **에이전트 리소스** 세트를 갖습니다: 지침, skills, 메모리, 사용자 정의 하위 에이전트, 예약된 작업, 연결된 MCP 서버로, 모두 파일이 아니라 SQL에 저장됩니다. 이는 사용자별 컨테이너를 띄우지 않고도 다중 테넌트 SaaS 내에서 Claude Code 수준의 커스터마이징을 가능하게 만듭니다. [Agent Resources](/docs/agent-resources)를 참조하세요. ## 관련 빌딩 블록 {#building-blocks} -이러한 계약은 동일한 계약에 기초하며 자체적인 심층 분석이 있습니다. +이들은 동일한 계약 위에 있으며, 각각 자체적인 심층 문서를 갖고 있습니다: -- **[Dispatch](/docs/dispatch)** — 작업 공간 제어 플레인: 공유 받은 편지함, 비밀 금고, 예약된 작업 및 A2A를 통해 전문 앱에 위임하는 오케스트레이터. -- **[Extensions](/docs/extensions)** — 에이전트가 런타임 시 생성하는 샌드박스형 Alpine.js 미니 앱, 소스 변경 또는 마이그레이션 없음. -- **[데이터 프로그램](/docs/data-programs)** — 에이전트가 작성하고 저장한 `run-code` 스크립트로, 하드코딩된 provider action 대신 캐시되고 갱신 가능한 결과를 dashboard 패널에 제공합니다. -- **[A2A Protocol](/docs/a2a-protocol)** — 동일한 작업 공간에 있는 앱이 JSON-RPC를 통해 서로를 검색하고 호출하는 방법 +- **[Dispatch](/docs/dispatch):** 공유 받은 편지함, 비밀 금고, 예약된 작업, 그리고 A2A를 통해 전문 앱에 위임하는 오케스트레이터를 갖춘 작업 공간 제어 플레인입니다. +- **[Extensions](/docs/extensions):** 에이전트가 런타임에 만드는 샌드박스화된 Alpine.js 미니 앱으로, 소스 변경이나 마이그레이션이 없습니다. +- **[A2A 프로토콜](/docs/a2a-protocol):** 동일한 작업 공간에 있는 앱들이 JSON-RPC를 통해 서로를 검색하고 호출하는 방법입니다. -## 무료로 얻는 것 {#what-you-get-for-free} +## 다음 단계 {#deep-dives} -프레임워크를 채택하는 것은 무엇보다도 더 이상 구축할 필요가 없기 때문에 가치가 있습니다. 앱이 5가지 규칙을 따르는 순간 다음이 상속됩니다. + -- **하나의 작업 = 모든 표면.** `defineAction()`로 정의된 모든 작업은 동시에 에이전트 도구, 유형 안전 프런트엔드 후크(`useActionQuery` / `useActionMutation`), 프레임워크 소유 HTTP 전송, CLI 명령, 외부 클라이언트용 MCP 도구 및 기타 에이전트 기본 앱용 A2A 도구입니다. 선택적 `link` 및 `mcpApp` 메타데이터는 두 번째 구현 없이 딥 링크와 MCP 앱 UI를 추가합니다. -- **사용자당 전체 작업 공간.** Skills, 공유 `LEARNINGS.md`, 개인 `memory/MEMORY.md`, `AGENTS.md`, 사용자 정의 하위 에이전트, 예약된 작업, 연결된 MCP 서버 — 모두 SQL 지원, dev-box가 필요하지 않습니다. [에이전트 리소스](/docs/agent-resources)를 참조하세요. -- **드롭인 React 구성 요소.** `` 및 ``는 앱의 어느 곳에서나 채팅과 작업 공간을 렌더링합니다. [Drop-in Agent](/docs/drop-in-agent)를 참조하세요. -- **BYO 에이전트 채팅 런타임.** 동일한 채팅 UI는 OpenAI 에이전트, OpenAI 응답, Claude 에이전트 SDK, Vercel AI SDK, AG-UI 또는 자체 정규화된 HTTP 스트림 위에 위치할 수 있습니다. [Native 채팅 UI](/docs/native-chat-ui#byo-agent-runtimes)를 참조하세요. -- **에이전트와 UI 간의 실시간 동기화.** 동일한 프로세스는 `/_agent-native/events`를 통해 즉시 스트림을 씁니다. 경량 폴링은 서버리스, cron 및 크로스 프로세스 쓰기를 수렴하도록 유지합니다. actions를 변형하면 작업 지원 쿼리가 자동으로 무효화되므로 에이전트가 생성한 레코드는 수동으로 새로 고치지 않고도 표시됩니다. 아래 [Live Sync](#polling-sync)를 참조하세요. -- **Auth, orgs, RBAC.** 조직/구성원/역할을 통한 더 나은 인증이 모든 템플릿에 연결되어 있습니다. [Authentication](/docs/authentication)를 참조하세요. -- **컨텍스트 인식.** 에이전트는 항상 `navigation` 앱 상태 키를 통해 사용자가 무엇을 보고 있는지 알고 있습니다. [Context Awareness](/docs/context-awareness)를 참조하세요. -- **MCP 클라이언트 + 서버, 양방향.** 앱은 MCP 서버(로컬, 원격, 허브 공유)를 수집하고\_ 자체 actions를 MCP 서버로 노출합니다. [MCP Clients](/docs/mcp-clients) 및 [MCP Protocol](/docs/mcp-protocol)를 참조하세요. -- **앱 간 위임.** 서로 다른 앱의 에이전트가 [A2A](/docs/a2a-protocol)를 통해 대화합니다. 동일 출처 배포는 JWT를 건너뜁니다. 교차 출처는 공유 `A2A_SECRET`를 사용합니다. -- **하위 에이전트 팀.** 채팅에 칩 인라인으로 표시되는 자체 스레드와 도구가 있는 하위 에이전트를 생성합니다. [Agent Teams](/docs/agent-teams)를 참조하세요. -- **이식성.** 모든 Drizzle 지원 SQL 데이터베이스, 모든 Nitro 호환 호스트(Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). +### [Agent-Native란 무엇인가?](/docs/what-is-agent-native) -이것이 바로 당신이 직접 접착했을 "및 기타 모든 것"입니다. +이 규칙들 뒤에 있는 비전과 철학입니다. -## 다음 단계 {#deep-dives} +### [상황 인식](/docs/context-awareness) + +내비게이션 상태, view-screen, navigate 명령을 깊이 다룹니다. + +### [Skills 가이드](/docs/skills-guide) + +프레임워크 skills, 도메인 skills, 커스텀 skills 만들기를 다룹니다. + +### [기본 채팅 UI](/docs/native-chat-ui) + +액션이 선언하는 테이블, 차트, BYO 런타임 태세를 다룹니다. + +### [에이전트 서피스](/docs/agent-surfaces) + +채팅, 네이티브 인라인 UI, 전체 앱 페이지, 임베디드 사이드카, 자동화, 외부 에이전트 경로를 다룹니다. + +### [A2A 프로토콜](/docs/a2a-protocol) + +에이전트 간 통신입니다. -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — 이러한 규칙의 비전과 철학입니다 -- [**Context Awareness**](/docs/context-awareness) — 탐색 상태, view-screen 및 navigate 명령을 자세히 설명합니다 -- [**Skills Guide**](/docs/skills-guide) — 프레임워크 skills, 도메인 skills 및 사용자 지정 skills 만들기입니다 -- [**Native Chat UI**](/docs/native-chat-ui) — action에서 선언한 표와 차트 및 자체 런타임 지원 방식입니다 -- [**Agent Surfaces**](/docs/agent-surfaces) — 채팅, 네이티브 인라인 UI, 전체 앱 페이지, 내장 sidecar, 자동화 및 외부 에이전트 경로입니다 -- [**A2A Protocol**](/docs/a2a-protocol) — 에이전트 간 통신입니다 + diff --git a/packages/core/docs/content/locales/pt-BR/key-concepts.mdx b/packages/core/docs/content/locales/pt-BR/key-concepts.mdx index a863a3fa25..56932d4070 100644 --- a/packages/core/docs/content/locales/pt-BR/key-concepts.mdx +++ b/packages/core/docs/content/locales/pt-BR/key-concepts.mdx @@ -1,45 +1,49 @@ --- title: "Conceitos-chave" -description: "Como funcionam os aplicativos nativos de agente: actions primeiro, banco de dados SQL, loop de agente de aplicativo, UI opcional, sincronização de pesquisa, pontos de entrada de agente externo, reconhecimento de contexto e portabilidade." +description: "Como os aplicativos agent-native funcionam em três camadas: o framework Core, os blocos de construção opcionais do Toolkit e os Templates opcionais, além das ações compartilhadas, do banco de dados SQL, do loop app-agente e das regras de portabilidade." --- # Conceitos-chave -Como os aplicativos nativos do agente funcionam nos bastidores — os princípios e a arquitetura. Esta página é o contrato; para ver a visão e os argumentos para construir desta forma, consulte [What Is Agent-Native?](/docs/what-is-agent-native). +Como os aplicativos agent-native funcionam por baixo dos panos: os princípios e a arquitetura. Esta página é o contrato: as regras fixas que um aplicativo precisa seguir para contar como agent-native. Para a visão e os argumentos para construir dessa forma, consulte [O Que É Agent-Native?](/docs/what-is-agent-native). ## As três camadas {#three-layers} -Agent Native é um framework, não um único modelo: +Agent Native é um framework com três camadas: -- **Core - o framework:** o contrato fundamental de runtime e dados que todo aplicativo pode usar. -- **Toolkit - peças reutilizáveis opcionais:** UI e sistemas de produto compartilhados que os aplicativos podem adotar, compor ou forkar. -- **Templates - aplicativos opcionais:** aplicativos de domínio completos construídos sobre Core, que normalmente usam Toolkit e podem ser forkados e usados como ponto de partida. +| Camada | O que é | +| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Core: o framework** | O contrato fundamental de runtime: ações, auxiliares de SQL e Drizzle, autenticação, estado da aplicação, execução do agente, verificações de acesso, roteamento e sincronização ao vivo. Todo aplicativo pode usar o Core diretamente. | +| **Toolkit: peças reutilizáveis opcionais** | UI compartilhada para construção de apps e sistemas de produto, como primitivos, editores, compartilhamento, colaboração, configurações e UX do agente. Os aplicativos podem usar, compor ou fazer fork das peças de que precisam. | +| **Templates: aplicativos opcionais construídos sobre o Core** | Aplicativos completos e específicos de domínio, com rotas, schema, ações, instruções e identidade visual. Templates próprios e personalizados costumam usar o Toolkit, e podem ser forkados e usados como ponto de partida. | -Core é a base. Toolkit e Templates são opcionais. +O Core é a base. Toolkit e Templates são opcionais: um template pode usar o Toolkit, mas o Toolkit não é obrigatório para construir um aplicativo sobre o Core. ## A arquitetura {#the-architecture} -Cada aplicativo nativo do agente consiste em três coisas trabalhando juntas: +Em tempo de execução, todo aplicativo agent-native é composto por três elementos que trabalham juntos: -- **Agente** — IA autônoma que lê dados, grava dados, executa actions e usa ferramentas configuradas. Personalizável com skills e instruções. -- **Aplicação** — A superfície do produto ao redor do agente. Inicialmente, isso pode ser apenas ação, bate-papo avançado, um pequeno plano de controle ou um UI React completo com painéis, fluxos e visualizações. -- **Computador** — Banco de dados, navegador, execução de código. Os agentes trabalham pela superfície de ações e dados do app; o app pode expor essa mesma superfície por MCP. Servidores MCP externos continuam sendo complementos opcionais, não a base. +- **Agente:** A IA autônoma. Ela lê dados, grava dados, executa ações e usa as ferramentas configuradas. Quando seu frame recebe intencionalmente acesso ao workspace e ferramentas de escrita, ela também pode modificar o código-fonte do próprio aplicativo. Personalizável com skills e instruções. +- **Aplicação:** A superfície do produto ao redor do agente. Pode começar como chat, adicionar resultados inline nativos, crescer até um pequeno plano de controle, ou se tornar um UI React completo, com painéis, fluxos e visualizações. +- **Computador:** O banco de dados, o navegador e os runtimes de ferramentas configurados pelos quais o agente age. Os agentes trabalham pela superfície de ações e dados do próprio aplicativo; essa mesma superfície pode, opcionalmente, ser exposta via MCP, mas servidores MCP externos continuam sendo um complemento, não a base. - +O diagrama abaixo mostra o agente e a aplicação lado a lado, ambos com setas bidirecionais para uma camada de computador compartilhada abaixo. Nenhum dos dois é dono dos dados. Em vez disso, ambos leem e gravam no mesmo armazenamento SQL, de modo que uma alteração feita por qualquer um dos lados fica visível ao outro imediatamente, sem nenhuma camada de sincronização para construir no meio do caminho. + + ```html
- AgentAgentelê e grava dados, executa ações e usa ferramentas configuradaslê + grava dados, executa ações, usa ferramentas configuradas
- ApplicationAplicaçãoaction-only, chat, control plane, or full UI Reactchat, resultados inline, plano de controle ou UI React completo
@@ -47,8 +51,8 @@ Cada aplicativo nativo do agente consiste em três coisas trabalhando juntas: ↓ ↑
- Computer
banco de dados SQL · browser · code executionbanco de dados SQL · navegador · execução de código
@@ -86,105 +90,126 @@ Cada aplicativo nativo do agente consiste em três coisas trabalhando juntas: -Aplicativos headless podem executar o mesmo loop de agente de aplicativo de produção a partir da pasta com `pnpm agent`, enquanto aplicativos UI montam o painel do agente integrado e são executados localmente com `pnpm dev`. Na nuvem, o Builder.io fornece um quadro gerenciado — o ambiente que hospeda o agente próximo ao seu aplicativo — com colaboração, edição visual e infraestrutura gerenciada para equipes. +Esse mesmo loop agente-aplicação-computador é o que roda localmente e em produção. Aplicativos automation-first o executam diretamente da pasta com `pnpm agent`; aplicativos UI montam o painel de agente incorporado e adicionam `pnpm dev`. Na nuvem, o Builder.io hospeda o mesmo loop como um frame gerenciado: o ambiente que executa o agente ao lado do seu aplicativo. Ele cuida da colaboração, da edição visual e da infraestrutura para você. ## Blocos de construção do agente {#agent-building-blocks} -Todo aplicativo nativo de agente tem os mesmos blocos de construção de agente, independentemente de -a superfície do produto é headless, chat-first ou UI completo: +Todo aplicativo agent-native tem os mesmos blocos de construção de agente, +independentemente de a superfície do produto ser chat-first, automation-first +ou um UI completo. Cada um vive em seu próprio arquivo: /SKILL.md", - note: "Comportamento reutilizável: etapas de workflow, políticas, exemplos, referências e listas do que fazer/não fazer", + note: "comportamento reutilizável: etapas de workflow, políticas, exemplos, referências e listas do que fazer/não fazer", }, { path: "actions/.ts", - note: "Capacidade executável: operação tipada exposta ao agente, UI, CLI, HTTP, MCP, A2A, jobs e webhooks", + note: "capacidade executável: operação tipada exposta ao agente, UI, CLI, HTTP, MCP, A2A, jobs e webhooks", }, ]} /> -| Bloco de construção | Use-o para | Carregado quando | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| **Instruções** | Orientação estável que o agente deve levar em cada tarefa: o que é o aplicativo, invariantes, tom, índices | Cada turno | -| **Skills** | Comportamento reutilizável: como seguir um fluxo de trabalho, aplicar uma política, inspecionar evidências ou verificar uma saída | Sob demanda quando a descrição da habilidade corresponde à tarefa | -| **Actions** | Operações reais: ler ou gravar dados, chamar APIs, enviar mensagens, executar aprovações, produzir resultados digitados | Listadas como ferramentas a cada passo; executado somente quando chamado | +Um turno é uma troca com o agente: ele lê seu contexto, decide o que fazer e responde. Carregado a cada turno significa que o arquivo volta a entrar nesse contexto a cada vez, não apenas uma vez no início da sessão. + +| Bloco de construção | Arquivo | Use para | Carregado quando | +| ------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | +| **Instruções** | `AGENTS.md` | Orientação estável que o agente deve levar para cada tarefa: o que é o aplicativo, invariantes, tom, índices | Cada turno | +| **Skills** | `.agents/skills//SKILL.md` | Comportamento reutilizável: como seguir um workflow, aplicar uma política, inspecionar evidências ou verificar uma saída | Sob demanda, quando a descrição do skill corresponde à tarefa | +| **Ações** | `actions/.ts` | Operações reais: ler ou gravar dados, chamar APIs, enviar mensagens, executar aprovações, produzir resultados tipados | Listadas como ferramentas a cada turno; executadas apenas quando chamadas | -Skills e actions trabalham juntos. Uma habilidade ensina o agente a fazer uma aula de -trabalho; uma ação é o caminho do código que ela pode chamar enquanto realiza esse trabalho. Por exemplo, -uma habilidade `customer-research` pode informar ao agente quais fontes inspecionar e -como resumir evidências, enquanto `search-crm` e `create-brief` actions buscam -e escreva os dados reais. +Skills e ações trabalham juntas. Um skill ensina o agente a fazer uma classe de +trabalho; uma ação é o caminho de código que ele pode chamar enquanto realiza esse trabalho. Por exemplo, +um skill `customer-research` pode dizer ao agente quais fontes inspecionar e +como resumir evidências, enquanto as ações `search-crm` e `create-brief` buscam +e gravam os dados reais. -Cinco regras governam a arquitetura: +Cinco regras regem a arquitetura: -1. **Os dados residem em SQL** — todo o estado do aplicativo reside no banco de dados via Drizzle ORM -2. **Toda a IA passa pelo agente** — nenhuma chamada LLM inline -3. **Actions para operações de agente** — trabalhos complexos são executados como actions -4. **A sincronização ao vivo mantém o UI sincronizado** — as alterações do banco de dados são transmitidas pelo SSE com polling como substituto universal -5. **O estado do aplicativo fica em SQL** — o estado efêmero da UI vive no banco de dados e pode ser lido pelo agente e pela UI +1. **Os dados residem em SQL:** todo o estado do aplicativo reside no banco de dados via Drizzle ORM. +2. **Toda IA passa pelo agente:** nenhuma chamada de LLM inline; toda interação de IA flui pela ponte de chat do agente. +3. **Ações para operações do agente:** trabalho complexo roda como uma ação tipada, não como código inline. +4. **A sincronização ao vivo mantém a UI sincronizada:** as alterações do banco de dados são transmitidas via SSE, com polling como substituto universal. +5. **Estado da aplicação em SQL:** o estado efêmero da UI reside no banco de dados, legível tanto pelo agente quanto pela UI. ## A lista de verificação de quatro áreas {#four-area-checklist} -Cada recurso voltado para o usuário deve atualizar todas as áreas aplicáveis. Ignorar uma área aplicável quebra o contrato do agente nativo; forçar um UI em um primitivo somente de ação também é um cheiro. +Todo recurso voltado ao usuário deve atualizar todas as áreas aplicáveis. Ignorar uma área aplicável quebra o contrato agent-native; forçar uma tela em uma automação que nenhum humano precisa navegar também é um indício de problema. + +- **1. UI:** Página, componente ou diálogo com o qual o usuário interage. +- **2. Ação:** Ação chamável pelo agente em `actions/` para a mesma operação. +- **3. Skills:** Atualize `AGENTS.md` e/ou crie um skill documentando o padrão. +- **4. App-State:** Estado de navegação, dados de view-screen e comandos de navigate. + +Um recurso apenas com UI é invisível para o agente. Um recurso de UI completo apenas com ações é invisível para o usuário. Um recurso sem app-state significa que o agente fica cego para o que o usuário está fazendo. Uma operação automation-first pode legitimamente começar apenas com ação + instruções e adicionar chat, UI ou app-state depois, quando humanos precisarem navegar, aprovar, configurar ou compartilhá-la. -| Área | Descrição | -| --------------------------- | -------------------------------------------------------------------------- | -| **1. UI** | Página, componente ou caixa de diálogo com a qual o usuário interage | -| **2. Ação** | Ação que pode ser chamada pelo agente em actions/ para a mesma operação | -| **3. Skills** | Atualize AGENTS.md e/ou crie uma habilidade documentando o padrão | -| **4. Estado do aplicativo** | Estado de navegação, dados da tela de visualização e comandos de navegação | +## O que o Agent Native inclui {#what-you-get-for-free} -Um recurso com apenas UI é invisível para o agente. Um recurso UI completo com apenas actions é invisível para o usuário. Um recurso sem estado de aplicativo significa que o agente não sabe o que o usuário está fazendo. Uma operação headless pode começar legitimamente com ação + instruções e adicionar UI/estado do aplicativo posteriormente, quando humanos precisarem navegar, aprovar, configurar ou compartilhá-lo. +Adotar o framework é valioso principalmente pelo que você deixa de precisar construir. No momento em que seu aplicativo segue as cinco regras acima, você herda: + +| Recurso | O que você ganha | +| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Uma ação = todas as superfícies | Toda ação definida com `defineAction()` é simultaneamente uma ferramenta de agente, um hook de frontend typesafe (`useActionQuery` / `useActionMutation`), um transporte HTTP de propriedade do framework, um comando CLI, uma ferramenta MCP para clientes externos e uma ferramenta A2A para outros aplicativos agent-native. Os metadados opcionais `link` e `mcpApp` adicionam deep links e UI de MCP Apps sem uma segunda implementação. | +| Recursos de agente completos por usuário | Skills, `LEARNINGS.md` compartilhado, `memory/MEMORY.md` pessoal, `AGENTS.md`, subagentes personalizados, jobs agendados e servidores MCP conectados. Tudo com suporte de SQL, sem necessidade de uma caixa de desenvolvimento. Consulte [Agent Resources](/docs/agent-resources). | +| Componentes React prontos para usar | `` e `` renderizam chat + recursos em qualquer lugar do seu aplicativo. Consulte [Drop-in Agent](/docs/drop-in-agent). | +| Runtimes de chat de agente BYO | A mesma UI de chat pode ser colocada sobre OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI ou seu próprio stream HTTP normalizado. Consulte [Bate-papo nativo UI](/docs/native-chat-ui#byo-agent-runtimes). | +| Sincronização ao vivo entre agente e UI | Gravações do mesmo processo são transmitidas imediatamente via `/_agent-native/events`; um polling leve mantém as gravações serverless, de cron e entre processos convergentes. Ações que fazem mutação invalidam automaticamente as queries baseadas em ação, de modo que registros criados pelo agente aparecem sem uma atualização manual. Veja [Live Sync](#polling-sync) abaixo. | +| Auth, orgs, RBAC | Better Auth com orgs/membros/funções já vem conectado em todo template. Consulte [Authentication](/docs/authentication). Para mais de um usuário, comece por [Organizations, Teams & Permissions](/docs/organizations-teams-permissions). | +| Reconhecimento de contexto | O agente sempre sabe o que o usuário está vendo por meio da chave de app-state `navigation`. Consulte [Consciência do Contexto](/docs/context-awareness). | +| Cliente + servidor MCP, nas duas direções | O aplicativo ingere servidores MCP (locais, remotos, compartilhados via hub) _e_ expõe suas próprias ações como um servidor MCP. Consulte [MCP Clients](/docs/mcp-clients) e [MCP Protocol](/docs/mcp-protocol). | +| Delegação entre aplicativos | Agentes em aplicativos diferentes se comunicam via [A2A](/docs/a2a-protocol). Implantações de mesma origem dispensam JWT; origens cruzadas usam um `A2A_SECRET` compartilhado. | +| Equipes de subagentes | Crie um subagente com sua própria thread e ferramentas, exibido como um chip inline no chat. Consulte [Agent Teams](/docs/agent-teams). | +| Portabilidade | Qualquer banco de dados SQL compatível com Drizzle, qualquer host compatível com Nitro (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). | ## Dados em SQL {#data-in-sql} -Todo o estado do aplicativo reside em um banco de dados SQL com Drizzle ORM. Os esquemas são independentes do provedor; os bancos de dados suportados, a configuração do `DATABASE_URL` e as regras de portabilidade residem no [Database](/docs/database). +Todo o estado da aplicação reside em um banco de dados SQL via Drizzle ORM. Os schemas são agnósticos de provedor; os bancos de dados suportados, a configuração de `DATABASE_URL` e as regras de portabilidade estão em [Database](/docs/database). + +As stores SQL do Core são criadas automaticamente e estão disponíveis em todo template: -As lojas principais SQL são criadas automaticamente e estão disponíveis em todos os modelos: +- `application_state`: estado efêmero da UI (navegação, rascunhos, seleções) +- `settings`: configuração persistente de chave-valor +- `oauth_tokens`: credenciais OAuth +- `sessions`: sessões de autenticação -- `application_state` — estado UI efêmero (navegação, rascunhos, seleções) -- `settings` — configuração de valor-chave persistente -- `oauth_tokens` — credenciais OAuth -- `sessions` — sessões de autenticação +Cada linha abaixo se expande para mostrar seus campos: +Para adicionar seus próprios dados de domínio, defina uma tabela com os mesmos helpers de schema usados pelas stores do core acima: + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -245,27 +272,30 @@ export const forms = table("forms", { }); ``` +Tanto você quanto o agente podem inspecionar esses dados pelo terminal, sem um cliente SQL separado: + ```bash -# Ações principais para inspeção rápida do banco de dados +# Actions do Core para inspeção rápida do banco de dados pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -O plug-in de bate-papo do agente de produção deixa as ferramentas SQL brutas em modo somente leitura por padrão -(`frameworkTools: { database: "read" }`). Os agentes inspecionam dados do app com `db-schema` / -`db-query` e escrevem por meio de actions tipadas do app. Defina -`database: "write"` (ou `true`) apenas para superfícies de manutenção -intencionais que também devam expor `db-exec` / `db-patch` com escopo; use -`database: "off"` / `false` para exigir actions tipadas para todo acesso a dados. +`db-schema` imprime as colunas e os tipos de cada tabela. `db-query` executa SQL somente leitura diretamente, o que é útil para verificar as gravações de uma ação sem abrir um cliente de banco de dados. + + + +O plug-in de bate-papo do agente de produção deixa as ferramentas SQL brutas em modo somente leitura por padrão (`frameworkTools: { database: "read" }`). Os agentes inspecionam dados do app com `db-schema` / `db-query` e escrevem por meio de actions tipadas do app. Defina `database: "write"` (ou `true`) apenas para superfícies de manutenção intencionais que também devam expor `db-exec` / `db-patch` com escopo; use `database: "off"` / `false` para exigir actions tipadas para todo acesso a dados. `frameworkTools` governa da mesma forma as demais ferramentas próprias do framework: sharing, comentários de revisão, histórico de versões, feature flags, localização, auditoria, Context X-Ray, perfil, automações, docs, resources, web, delegação entre apps, chat e email. Veja [Production Agent Tools](/docs/deployment#production-agent-tools) para a lista completa, o preset `"minimal"` e por que desativar um grupo mantém suas rotas HTTP montadas. -## Ponte de bate-papo do agente {#agent-chat-bridge} + -O UI nunca chama um LLM diretamente. Quando um usuário clica em “Gerar gráfico” ou “Escrever resumo”, o UI envia uma mensagem ao agente via `postMessage`. O agente faz o trabalho, com histórico completo de conversas, skills, instruções e capacidade de iteração. +## Ponte de chat do agente {#agent-chat-bridge} + +A UI nunca chama um LLM diretamente. Quando um usuário clica em "Gerar gráfico" ou "Escrever resumo", a UI envia uma mensagem ao agente via `postMessage`. O agente faz o trabalho. Ele tem histórico completo da conversa, skills, instruções e a capacidade de iterar. ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -274,16 +304,19 @@ sendToAgentChat({ }); ``` -Por que não chamar um LLM inline? +Em resumo: + +- **A IA não é determinística**: você precisa de um fluxo de conversa para dar feedback e iterar, não de botões de disparo único. +- **O contexto importa**: o agente tem as instruções, os skills e o histórico do aplicativo. Uma chamada inline não tem nada disso. +- **O agente pode fazer mais**: ele pode executar ações, navegar na web e encadear várias etapas. -- **A IA não é determinística.** Você precisa de fluxo de conversa para fornecer feedback e iterar, e não botões únicos. -- **O contexto é importante.** O agente tem sua base de código completa, instruções, skills e histórico. Uma chamada in-line não tem nada disso. -- **O agente pode fazer mais.** Ele pode executar actions, navegar na Web e encadear várias etapas. -- **Execução headless.** Como tudo passa pelo agente, qualquer aplicativo pode ser conduzido inteiramente de Slack, Telegram ou outro agente via [A2A](/docs/a2a-protocol). +**[Execução externa](/docs/a2a-protocol)** -## Sistema Actions {#actions-system} +Como tudo passa pelo agente e pelas ações, qualquer aplicativo pode ser controlado a partir do Slack, do Telegram, de jobs agendados, de scripts ou de outro agente via A2A. -Quando o agente precisa fazer algo complexo — chamar um API, processar dados, consultar o banco de dados — ele executa uma **ação**. Actions são arquivos TypeScript em `actions/` que exportam um `defineAction()` padrão: +## Sistema de ações {#actions-system} + +Quando o agente precisa fazer algo complexo, como chamar uma API, processar dados ou consultar o banco de dados, ele executa uma **ação**. Ações são arquivos TypeScript em `actions/` que exportam um `defineAction()` como padrão: ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -301,19 +334,30 @@ export default defineAction({ }); ``` -Uma chamada `defineAction()` fornece: +Essa ação busca JSON de uma API de origem e o retorna. `defineAction()` encapsula a função com um schema zod para sua entrada (`source`), de modo que o framework pode validar essa entrada, gerar um JSON Schema que o agente pode chamar e inferir tipos para o hook de frontend, tudo a partir dessa única definição. + +Uma única chamada a `defineAction()` alcança automaticamente cinco consumidores diferentes. O diagrama mostra o fan-out a partir de uma única ação; a lista abaixo explica o que cada consumidor recebe: -- **Ferramenta de agente** — o agente a vê com o esquema JSON derivado de zod e pode chamá-la. -- **Gancho de front-end** — `useActionMutation("fetch-data")` com inferência TypeScript completa. -- **Transporte de estrutura** — montado automaticamente atrás dos ganchos do cliente. -- **CLI** — `pnpm action fetch-data --source=signups` para scripts e loops de desenvolvimento de agente. -- **Ferramenta MCP / Ferramenta A2A** — quando o servidor MCP ou A2A está ativado, a mesma ação aparece lá também. +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -Mesma lógica, uma definição, conectada automaticamente a todos os consumidores. Consulte [Actions](/docs/actions) para referência completa. +- **Ferramenta de agente:** o agente a vê com o JSON Schema derivado do zod e pode chamá-la. +- **Hook de frontend:** `useActionMutation("fetch-data")` com inferência completa de TypeScript. +- **Transporte do framework:** montado automaticamente por trás dos hooks de cliente. +- **CLI:** `pnpm action fetch-data --source=signups` para scripts e loops de desenvolvimento do agente. +- **Ferramenta MCP / ferramenta A2A:** quando o servidor MCP ou o A2A está habilitado, a mesma ação também aparece lá. + +Todo consumidor chama a mesma função subjacente, então há apenas uma implementação para escrever e manter. Consulte [Actions](/docs/actions) para a referência completa. ## Sincronização ao vivo {#polling-sync} -As alterações do banco de dados são sincronizadas com UI por meio de `useDbSync()`. Fluxo de gravação do mesmo processo em `/_agent-native/events`; `/_agent-native/poll` continua sendo o substituto de processo cruzado e sem servidor. Quando o agente grava no banco de dados (estado do aplicativo, configurações ou dados de domínio), um contador de versão aumenta e o cliente invalida os caches de consulta React relevantes. +Quando o agente altera dados, a UI precisa refletir isso sem uma atualização manual. `useDbSync()` é o que torna isso automático. Gravações do mesmo processo são transmitidas via `/_agent-native/events`; `/_agent-native/poll` continua sendo o substituto para entre processos e serverless. Quando o agente grava no banco de dados (estado da aplicação, configurações ou dados de domínio), um contador de versão é incrementado e o cliente invalida os caches relevantes do React Query. ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -321,20 +365,24 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` +Chame isso uma vez, perto da raiz do aplicativo. Isso inscreve o aplicativo inteiro nos eventos de alteração, de modo que qualquer componente usando `useActionQuery` ou um `useQuery` com versão de origem refaça a busca automaticamente quando os dados que ele lê mudarem. + O fluxo é: 1. O agente executa uma ação que grava no banco de dados -2. O servidor emite um evento de alteração com uma fonte como `"action"` ou `"settings"` -3. `useDbSync` recebe por SSE ou pelo polling fallback -4. Rebusca de ganchos `useActionQuery` e ganchos `useQuery` com versão de origem +2. O servidor emite um evento de alteração com uma origem como `"action"` ou `"settings"` +3. `useDbSync` o recebe via SSE ou pelo fallback de polling +4. Os hooks `useActionQuery` e os hooks `useQuery` com versão de origem refazem a busca 5. Os componentes renderizam os novos dados sem recarregar a página - +O diagrama percorre essa mesma sequência do início ao fim: + + ```html
- Ação do agente
grava no DB + Ação do agente
grava no BD
@@ -345,11 +393,11 @@ O fluxo é:
useDbSyncSSE · poll fallback + >SSE · fallback de polling
- Refetch da consulta
renderiza, sem recarregar
@@ -378,89 +426,90 @@ O fluxo é: -Isso funciona em todos os ambientes de implantação, inclusive sem servidor e de borda, porque usa o banco de dados, e não o estado da memória ou os observadores do sistema de arquivos. +Isso funciona em todos os ambientes de implantação, incluindo serverless e edge, porque usa o banco de dados em vez de estado em memória ou observadores do sistema de arquivos. ## Quadros {#frames} -Um _frame_ é o ambiente que hospeda o agente próximo ao seu aplicativo – localmente esse é o painel incorporado; na nuvem é a superfície gerenciada do Builder.io. Consulte [Frames](/docs/frames). +Um _frame_ é o ambiente que hospeda o agente ao lado do seu aplicativo. Localmente, isso é o painel incorporado; na nuvem, é a superfície gerenciada do Builder.io. Consulte [Frames](/docs/frames). -Os aplicativos nativos do agente incluem um painel de agente incorporado que fornece o agente de IA junto com o aplicativo UI. É isso que faz a arquitetura funcionar: o agente precisa de um computador (banco de dados, navegador, execução de código) e o aplicativo precisa do agente para o trabalho de IA. +Aplicativos agent-native incluem um painel de agente incorporado que disponibiliza o agente de IA ao lado da UI do aplicativo. É isso que faz a arquitetura funcionar: o agente precisa de um computador (banco de dados, navegador, execução de código), e o aplicativo precisa do agente para o trabalho de IA. -- **Painel de agente incorporado** — Bate-papo e terminal CLI opcional integrado em cada aplicativo. Suporta código Claude, Codex, Gemini, OpenCode e Builder.io. Executa localmente. Gratuito e de código aberto. -- **Nuvem** — Implante em qualquer nuvem com colaboração em tempo real, edição visual, funções e permissões. Melhor para equipes. +- **Painel de agente incorporado:** chat e terminal CLI opcional integrados a cada aplicativo. Compatível com Claude Code, Codex, Gemini, OpenCode e Builder.io. Roda localmente, gratuito e de código aberto. +- **Nuvem:** implante em qualquer nuvem com colaboração em tempo real, edição visual, funções e permissões. Ideal para equipes. -## Consciência do contexto {#context-awareness} +## Reconhecimento de contexto {#context-awareness} -O agente sempre sabe o que o usuário está vendo. O UI grava uma chave `navigation` no estado do aplicativo em cada mudança de rota. O agente lê através da ação `view-screen` antes de agir. +O agente sempre sabe o que o usuário está vendo. A UI grava uma chave `navigation` no application-state a cada mudança de rota. O agente a lê via a ação `view-screen` antes de agir. -Por exemplo, quando você abre uma conversa de e-mail, o UI insere uma linha como: +Por exemplo, quando você abre uma thread de e-mail, a UI faz upsert de uma linha como: ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -O UI grava isso na mudança de rota; o agente lê (via `view-screen`) antes de realizar qualquer ação, para que ele sempre saiba em qual tópico (ou gráfico, ou slide) você está focado. + + +A UI grava isso a cada mudança de rota; o agente a lê (via `view-screen`) antes de realizar qualquer ação, de modo que ele sempre sabe em qual thread, gráfico ou slide você está focado. -Veja [Context Awareness](/docs/context-awareness) para o padrão completo: estado de navegação, tela de visualização, comandos de navegação e prevenção de jitter. + + +Consulte [Consciência do Contexto](/docs/context-awareness) para o padrão completo: estado de navegação, view-screen, comandos de navigate e prevenção de jitter. ## Uma ação, muitas superfícies {#protocols} -Implementar uma operação de domínio uma vez como uma ação; a estrutura expõe isso a todos os consumidores. O mesmo `defineAction()` se torna uma ferramenta de agente, um gancho UI com segurança de tipo, um endpoint HTTP, um comando CLI, uma ferramenta MCP e uma ferramenta A2A, com `link` opcional, `mcpApp` ou metadados de widget nativo explícitos adicionados apenas quando uma superfície precisa deles. Skills e instruções cobrem o comportamento. +Implemente uma operação de domínio uma vez como uma ação; o framework a expõe a todo consumidor. O mesmo `defineAction()` se torna uma ferramenta de agente, um hook de UI typesafe, um endpoint HTTP, um comando CLI, uma ferramenta MCP e uma ferramenta A2A, com `link`, `mcpApp`, metadados de widget nativo ou wrappers de Generative UI opcionais adicionados apenas quando uma superfície precisa de uma interação mais rica. Skills e instruções cobrem o comportamento. -Para obter a matriz completa de protocolo/superfície (servidor MCP e OAuth, aplicativos MCP, A2A, links diretos, widgets de bate-papo nativos, conectores AgentChatRuntime, Agent Web e o horizonte do adaptador para ACP e A2UI) e para escolher um formato de produto — sem interface, bate-papo rico, sidecar incorporado ou aplicativo completo — consulte [Agent Surfaces](/docs/agent-surfaces). +Para a matriz completa de protocolos/superfícies (servidor MCP e OAuth, MCP Apps, A2A, deep links, widgets de chat nativos, Generative UI, conectores AgentChatRuntime, Agent Web e o horizonte de adaptadores para ACP e A2UI), e para escolher um formato de produto (chat, UI inline, páginas completas de aplicativo, sidecar incorporado, automação ou acesso de agente externo), consulte [Superfícies do Agente](/docs/agent-surfaces). ## Código do aplicativo e personalização {#agent-modifies-code} -O agente incorporado não edita o código-fonte por padrão. Ele só pode fazer isso -quando o host concede intencionalmente ferramentas de escrita de -repository/workspace. Em um aplicativo implantado comum, o agente trabalha por -meio de actions, estado respaldado por SQL e integrações configuradas. Templates -são aplicativos completos que você pode forkar e personalizar no seu próprio -repositório e fluxo de desenvolvimento. +O framework não concede ao agente incorporado acesso ambiente ao código-fonte de um aplicativo. Em um aplicativo implantado, o agente normalmente trabalha por meio de ações, estado com suporte de SQL e integrações configuradas. Ele pode editar componentes, rotas, estilos e ações quando seu frame recebe intencionalmente workspace e ferramentas de escrita. Templates são aplicativos completos que você pode fazer fork e personalizar no seu próprio repositório e fluxo de desenvolvimento, de qualquer forma. Para personalização em tempo de execução sem alterações no código-fonte, use [Extensions](/docs/extensions). ## Portátil por padrão {#hosting-agnostic} -Duas regras arquitetônicas mantêm os aplicativos portáteis entre bancos de dados e hosts: +Duas regras arquiteturais mantêm os aplicativos portáteis entre bancos de dados e hosts: -- **Independente de banco de dados.** Escreva esquemas com `@agent-native/core/db/schema` e leia/grave com a consulta portátil Drizzle do DSL para que o mesmo código seja executado em qualquer provedor compatível. Use SQL bruto apenas para migrações aditivas ou manutenção única, mantido parametrizado e independente de dialeto. Consulte [Database](/docs/database). -- **Hosting-agnostic.** O servidor é executado em Nitro e compila para qualquer destino de implantação. Nunca use APIs específicos do nó (`fs`, `child_process`, `path`) em rotas de servidor ou plug-ins e nunca assuma um processo de servidor persistente - serverless e edge são stateless, portanto, mantenha todo o estado em SQL. Consulte [Deployment](/docs/deployment). +- **Agnóstico de banco de dados.** Escreva schemas com `@agent-native/core/db/schema` e leituras/gravações com o DSL de query portátil do Drizzle, para que o mesmo código rode em qualquer provedor suportado. Use SQL bruto apenas para migrações aditivas ou manutenção pontual, mantendo-o parametrizado e agnóstico de dialeto. Consulte [Database](/docs/database). +- **Agnóstico de hosting.** O servidor roda sobre Nitro e compila para qualquer destino de implantação. Nunca use APIs específicas do Node (`fs`, `child_process`, `path`) em rotas ou plugins do servidor, e nunca assuma um processo de servidor persistente. Serverless e edge são stateless, então mantenha todo o estado em SQL. Consulte [Deployment](/docs/deployment). -## Espaço de trabalho {#workspace} +## Recursos do Agente {#workspace} -Cada usuário recebe um **espaço de trabalho** pessoal — instruções, skills, memória, subagentes personalizados, trabalhos agendados e servidores MCP conectados — todos armazenados em SQL em vez de arquivos. Isso torna a personalização em nível de código Claude viável dentro de SaaS multilocatário sem criar um contêiner por usuário. Consulte [Recursos do Agente](/docs/agent-resources). +Cada usuário recebe um conjunto pessoal de **recursos de agente**: instruções, skills, memória, subagentes personalizados, jobs agendados e servidores MCP conectados, tudo armazenado em SQL em vez de arquivos. Isso torna viável uma personalização no nível do Claude Code dentro de um SaaS multi-tenant, sem precisar subir um container por usuário. Consulte [Agent Resources](/docs/agent-resources). ## Blocos de construção relacionados {#building-blocks} -Eles estão no mesmo contrato e têm seus próprios aprofundamentos: +Eles se apoiam no mesmo contrato e têm seus próprios aprofundamentos: + +- **[Dispatch](/docs/dispatch):** o plano de controle do workspace, com uma caixa de entrada compartilhada, um cofre de segredos, jobs agendados e um orquestrador que delega para aplicativos especializados via A2A. +- **[Extensions](/docs/extensions):** mini-apps Alpine.js em sandbox que o agente cria em tempo de execução, sem alterações no código-fonte ou migrações. +- **[Protocolo A2A](/docs/a2a-protocol):** como aplicativos no mesmo workspace se descobrem e se chamam via JSON-RPC. + +## O que vem a seguir {#deep-dives} + + + +### [O Que É Agent-Native?](/docs/what-is-agent-native) + +A visão e a filosofia por trás destas regras. + +### [Consciência do Contexto](/docs/context-awareness) + +Estado de navegação, view-screen e comandos de navigate em profundidade. + +### [Guia Skills](/docs/skills-guide) + +Skills do framework, skills de domínio e criação de skills personalizados. -- **[Dispatch](/docs/dispatch)** — o plano de controle do espaço de trabalho: caixa de entrada compartilhada, cofre de segredos, trabalhos agendados e um orquestrador que delega A2A a aplicativos especializados. -- **[Extensions](/docs/extensions)** — miniaplicativos Alpine.js em sandbox que o agente cria em tempo de execução, sem alterações de origem ou migrações. -- **[Programas de dados](/docs/data-programs)** — scripts `run-code` armazenados e escritos pelo agente que fornecem aos painéis de dashboard um resultado em cache e atualizável, em vez de uma action de provedor codificada. -- **[A2A Protocol](/docs/a2a-protocol)** — como aplicativos no mesmo espaço de trabalho descobrem e chamam uns aos outros por meio de JSON-RPC. +### [Bate-papo nativo UI](/docs/native-chat-ui) -## O que você ganha de graça {#what-you-get-for-free} +Tabelas e gráficos declarados por ação, e postura de runtime BYO. -Adotar o framework é valioso principalmente por causa do que você deixa de ter que construir. No momento em que seu aplicativo seguir as cinco regras, você herdará: +### [Superfícies do Agente](/docs/agent-surfaces) -- **Uma ação = cada superfície.** Cada ação definida com `defineAction()` é simultaneamente uma ferramenta de agente, um gancho de frontend typesafe (`useActionQuery`/`useActionMutation`), um transporte HTTP de propriedade da estrutura, um comando CLI, uma ferramenta MCP para clientes externos e uma ferramenta A2A para outros aplicativos nativos de agente. Os metadados `link` e `mcpApp` opcionais adicionam links diretos e aplicativos MCP UI sem uma segunda implementação. -- **Um espaço de trabalho completo por usuário.** Skills, `LEARNINGS.md` compartilhado, `memory/MEMORY.md` pessoal, `AGENTS.md`, subagentes personalizados, trabalhos agendados, servidores MCP conectados — todos com suporte de SQL, sem necessidade de caixa de desenvolvimento. Consulte [Recursos do Agente](/docs/agent-resources). -- **Componentes React integrados.** `` e `` renderizam chat + espaço de trabalho em qualquer lugar do seu aplicativo. Consulte [Drop-in Agent](/docs/drop-in-agent). -- **Tempos de execução de bate-papo do agente BYO.** O mesmo bate-papo UI pode ser colocado sobre Agentes OpenAI, Respostas OpenAI, Agente Claude SDK, Vercel AI SDK, AG-UI ou seu próprio fluxo HTTP normalizado. Consulte [Native Interface de chat](/docs/native-chat-ui#byo-agent-runtimes). -- **Sincronização ao vivo entre o agente e UI.** O mesmo processo grava fluxo imediatamente em `/_agent-native/events`; uma pesquisa leve mantém as gravações sem servidor, cron e entre processos convergentes. A mutação actions invalida automaticamente as consultas baseadas em ação, de modo que os registros criados pelo agente aparecem sem atualização manual. Veja [Live Sync](#polling-sync) abaixo. -- **Auth, orgs, RBAC.** Better Auth com organizações/membros/funções está conectado para cada modelo. Consulte [Authentication](/docs/authentication). -- **Reconhecimento de contexto.** O agente sempre sabe o que o usuário está vendo por meio da chave de estado do aplicativo `navigation`. Consulte [Context Awareness](/docs/context-awareness). -- **Cliente + servidor MCP, ambas as direções.** O aplicativo ingere servidores MCP (locais, remotos, compartilhados por hub) _e_ expõe seu próprio actions como um servidor MCP. Consulte [MCP Clients](/docs/mcp-clients) e [MCP Protocol](/docs/mcp-protocol). -- **Delegação entre aplicativos.** Agentes em diferentes aplicativos conversam pelo [A2A](/docs/a2a-protocol). Implantações de mesma origem ignoram JWT; origem cruzada usa um `A2A_SECRET` compartilhado. -- **Equipes de subagentes.** Gere um subagente com seu próprio tópico e ferramentas, exibido como um chip embutido no bate-papo. Consulte [Agent Teams](/docs/agent-teams). -- **Portabilidade.** Qualquer banco de dados SQL compatível com Drizzle, qualquer host compatível com Nitro (Node, Workers, Netlify, Vercel, Deno, Lambda, Bun). +Chat, UI inline nativa, páginas completas de aplicativo, sidecar incorporado, automação e caminhos de agente externo. -Esse é o "e tudo mais" que você mesmo estaria colando. +### [Protocolo A2A](/docs/a2a-protocol) -## Próximos passos {#deep-dives} +Comunicação entre agentes. -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — a visão e a filosofia por trás destas regras -- [**Context Awareness**](/docs/context-awareness) — estado de navegação e comandos view-screen e navigate em detalhes -- [**Skills Guide**](/docs/skills-guide) — skills do framework, skills de domínio e criação de skills personalizadas -- [**Native Chat UI**](/docs/native-chat-ui) — tabelas e gráficos declarados por actions e suporte a tempos de execução próprios -- [**Agent Surfaces**](/docs/agent-surfaces) — chat, UI nativa integrada, páginas completas de aplicativo, sidecar incorporado, automação e caminhos de agentes externos -- [**A2A Protocol**](/docs/a2a-protocol) — comunicação entre agentes + diff --git a/packages/core/docs/content/locales/zh-CN/key-concepts.mdx b/packages/core/docs/content/locales/zh-CN/key-concepts.mdx index b8fa05f729..078c012898 100644 --- a/packages/core/docs/content/locales/zh-CN/key-concepts.mdx +++ b/packages/core/docs/content/locales/zh-CN/key-concepts.mdx @@ -1,31 +1,35 @@ --- title: "关键概念" -description: "代理本机应用程序的工作原理：首先是 actions、SQL 数据库、应用程序代理循环、可选的 UI、轮询同步、外部代理入口点、上下文感知和可移植性。" +description: "代理本机应用如何在三层架构中运作：Core 框架、可选的 Toolkit 构建块，以及可选的 Templates，加上共享的 actions、SQL 数据库、应用-代理循环，以及可移植性规则。" --- # 关键概念 -代理本机应用程序如何在幕后工作 - 原则和架构。此页为合同；有关以这种方式构建的愿景和案例，请参阅 [What Is Agent-Native?](/docs/what-is-agent-native)。 +代理本机应用在幕后如何运作：原则与架构。此页是契约：一个应用要被视为代理本机应用，必须遵循的固定规则。关于这种构建方式背后的愿景与理由，请参阅 [什么是 Agent-Native？](/docs/what-is-agent-native)。 ## 三个层次 {#three-layers} -Agent Native 是一个 framework，而不是单个模板： +Agent Native 是一个具有三层架构的框架： -- **Core - framework：** 所有应用都可以使用的基础运行时和数据契约。 -- **Toolkit - 可选的可复用组件：** 应用可以采用、组合或 fork 的共享 UI 和产品系统。 -- **Templates - 可选的应用：** 构建在 Core 之上的完整领域应用，通常使用 Toolkit，也可以 fork 并作为起点使用。 +| 层级 | 内容 | +| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| **Core：框架** | 基础运行时契约：actions、SQL 和 Drizzle 辅助函数、身份验证、应用状态、代理执行、访问检查、路由和实时同步。每个应用都可以直接使用 Core。 | +| **Toolkit：可选的可复用组件** | 共享的应用构建 UI 和产品系统，例如基础组件、编辑器、共享、协作、设置和代理 UX。应用可以使用、组合或 fork 所需的组件。 | +| **Templates：基于 Core 构建的可选应用** | 完整的、特定领域的应用，具有路由、schema、actions、指令和视觉标识。第一方和自定义模板通常使用 Toolkit，也可以被 fork 并用作起点。 | -Core 是基础。Toolkit 和 Templates 都是可选的。 +Core 是基础。Toolkit 和 Templates 都是可选的：模板可以使用 Toolkit，但基于 Core 构建应用并不需要 Toolkit。 ## 架构 {#the-architecture} -每个代理本机应用程序都由三部分协同工作： +在运行时，每个代理本机应用都是三样东西协同工作： -- **代理** — 读取数据、写入数据、运行 actions 并使用已配置工具的自主 AI。可使用 skills 和说明进行定制。 -- **应用** — 试剂周围的产品表面。一开始这可能只是操作、丰富的聊天、小型控制平面或带有仪表板、流程和可视化的完整 React 界面。 -- **计算机** — 数据库、浏览器、代码执行。代理通过应用的操作和数据表面工作；应用可以通过 MCP 暴露同一个操作表面，而外部 MCP 服务器仍是可选附加组件，不是基础。 +- **代理：** 自主 AI。它读取数据、写入数据、运行 actions，并使用任何已配置的工具。当它的框架被有意授予工作区访问权限和写入工具时，它也可以修改应用自身的源代码。可通过 skills 和指令进行定制。 +- **应用：** 围绕代理的产品表面。它可能从聊天开始，加入原生内联结果，成长为一个小型控制平面，或者成为带有仪表板、流程和可视化的完整 React UI。 +- **计算机：** 数据库、浏览器，以及代理借以行动的已配置工具运行时。代理通过应用自身的 action 和数据表面工作；同一个表面也可以选择性地通过 MCP 暴露，但外部 MCP 服务器仍是一个附加项，不是基础。 - +下面的图表展示了代理和应用并排放置，二者都通过双向箭头连接到下方同一个共享的计算机层。二者都不拥有数据的所有权。相反，它们读写同一个 SQL 存储，因此任何一方所做的更改都会立即对另一方可见，中间无需构建同步层。 + + ```html
@@ -33,13 +37,13 @@ Core 是基础。Toolkit 和 Templates 都是可选的。
Agent读取和写入数据、运行 actions、使用已配置工具读取 + 写入数据，运行 actions，使用已配置的工具
Applicationaction-only, chat, control plane, or full React 界面聊天、内联结果、控制平面或完整 React UI
@@ -48,7 +52,7 @@ Core 是基础。Toolkit 和 Templates 都是可选的。
Computer
SQL 数据库 · browser · code executionSQL 数据库 · 浏览器 · 代码执行
@@ -86,103 +90,124 @@ Core 是基础。Toolkit 和 Templates 都是可选的。 -无头应用程序可以使用 `pnpm agent` 从文件夹运行相同的生产应用程序代理循环，而 UI 应用程序则安装嵌入式代理面板并使用 `pnpm dev` 在本地运行。在云中，Builder.io 提供了一个托管框架（在您的应用旁边托管代理的环境），为团队提供协作、可视化编辑和托管基础架构。 +这个相同的代理-应用-计算机循环，在本地和生产环境中运行的是同一套。自动化优先的应用直接从文件夹用 `pnpm agent` 运行它；UI 应用挂载嵌入式代理面板并加上 `pnpm dev`。在云端，Builder.io 将同一个循环托管为一个受管理的框架：在你的应用旁边运行代理的环境。它为你处理协作、可视化编辑和基础设施。 ## 代理构建块 {#agent-building-blocks} -每个代理本机应用程序都具有相同的代理构建块，无论是否 -产品表面是无头的、聊天优先的或完整的 UI： +每个代理本机应用都拥有相同的代理构建块，无论其产品 +表面是聊天优先、自动化优先，还是完整的 UI。每一个构建块 +都存放在自己的文件中： /SKILL.md", - note: "可复用行为：workflow 步骤、策略、示例、参考以及做/不做清单", + note: "可复用行为：工作流步骤、策略、示例、参考资料，以及应做/不应做清单", }, { path: "actions/.ts", - note: "可执行能力：暴露给代理、UI、CLI、HTTP、MCP、A2A、jobs 和 webhooks 的类型化操作", + note: "可执行能力：向代理、UI、CLI、HTTP、MCP、A2A、jobs 和 webhooks 暴露的类型化操作", }, ]} /> -| 构建块 | 使用它 | 加载时间 | -| ----------- | ---------------------------------------------------------------------- | -------------------------------- | -| **说明** | 代理应在每项任务中进行稳定的指导：应用程序是什么、不变量、语气、索引 | 每个回合 | -| **Skills** | 可重用行为：如何遵循工作流程、应用策略、检查证据或验证输出 | 当技能描述与任务匹配时按需 | -| **Actions** | 实际操作：读取或写入数据、调用 API、发送消息、运行审批、生成类型化结果 | 每次都被列为工具；仅在调用时执行 | +一个 turn（回合）是与代理的一次交流：它读取自己的上下文、决定要做什么，然后作出响应。"每个回合都加载"意味着该文件每次都会重新进入上下文，而不仅仅是在会话开始时加载一次。 + +| 构建块 | 文件 | 用途 | 加载时机 | +| ----------- | -------------------------------- | ---------------------------------------------------------------------- | ---------------------------------------- | +| **指令** | `AGENTS.md` | 代理应带入每项任务的稳定指导：应用是什么、不变量、语气、索引 | 每个回合 | +| **Skills** | `.agents/skills//SKILL.md` | 可复用行为：如何遵循一个工作流、应用一项策略、检查证据，或验证一个输出 | 当 skill 描述与任务匹配时按需加载 | +| **Actions** | `actions/.ts` | 真实操作：读取或写入数据、调用 API、发送消息、运行审批、生成类型化结果 | 每个回合都作为工具列出；仅在被调用时执行 | -Skills 和 actions 一起工作。一项技能教代理如何做一类 -工作；操作是它在执行该工作时可以调用的代码路径。例如， -`customer-research` 技能可能会告诉代理要检查哪些来源 -如何在 `search-crm` 和 `create-brief` actions 获取的同时总结证据 -并写入实际数据。 +Skills 和 actions 一起工作。一个 skill 教会代理如何完成一类 +工作；一个 action 则是代理在完成这类工作时可以调用的代码路径。例如， +一个 `customer-research` skill 可能会告诉代理该检查哪些来源、 +如何总结证据，而 `search-crm` 和 `create-brief` 这两个 actions +负责获取和写入实际数据。 -管理架构的五项规则： +五条规则支配着这一架构： -1. **数据存在于 SQL** - 所有应用程序状态都通过 Drizzle ORM 存在于数据库中 -2. **所有 AI 都通过代理** - 无内联 LLM 调用 -3. **Actions 用于代理操作** — 复杂的工作作为 actions 运行 -4. **实时同步使 UI 保持同步** — 通过 SSE 进行数据库更改流，并以轮询作为通用回退 -5. **应用程序状态存储在 SQL 中** - 临时 UI 状态位于数据库中，代理和 UI 都可以读取 +1. **数据存在于 SQL 中：** 所有应用状态都通过 Drizzle ORM 存在于数据库中。 +2. **所有 AI 都通过代理进行：** 没有内联 LLM 调用；每一次 AI 交互都通过代理聊天桥进行。 +3. **Actions 用于代理操作：** 复杂的工作以类型化的 action 运行，而不是内联代码。 +4. **实时同步让 UI 保持同步：** 数据库更改通过 SSE 流式传输，轮询作为通用回退方案。 +5. **应用状态存储在 SQL 中：** 临时 UI 状态存在于数据库中，代理和 UI 都可读取。 ## 四个区域清单 {#four-area-checklist} -每个面向用户的功能都应该更新所有适用的区域。跳过适用区域会破坏代理与本地合约；将 UI 强制到仅动作原语上也是一种气味。 +每个面向用户的功能都应该更新所有适用的区域。跳过一个适用的区域会破坏代理本机契约；给一个没有人类需要浏览的自动化强加一个屏幕，同样是一种代码异味。 + +- **1. UI：** 用户与之交互的页面、组件或对话框。 +- **2. Action：** `actions/` 中用于同一操作的、可供代理调用的 action。 +- **3. Skills：** 更新 `AGENTS.md`，和/或创建一个记录该模式的 skill。 +- **4. App-State：** 导航状态、view-screen 数据和 navigate 命令。 + +只有 UI 的功能对代理来说是不可见的。一个完整 UI 功能如果只有 actions，对用户来说是不可见的。没有 app-state 的功能意味着代理对用户正在做的事情视而不见。一个自动化优先的操作完全可以合理地从 action + 指令开始，等到人类需要浏览、批准、配置或分享它时，再添加聊天、UI 或 app-state。 -| 区域 | 描述 | -| ------------------- | ---------------------------------------- | -| **1. UI** | 用户与之交互的页面、组件或对话框 | -| **2。行动** | actions/中的代理可调用操作用于相同操作 | -| **3. Skills** | 更新 AGENTS.md 和/或创建记录该模式的技能 | -| **4。应用程序状态** | 导航状态、视图屏幕数据和导航命令 | +## Agent Native 包含哪些内容 {#what-you-get-for-free} -只有 UI 的功能对于代理来说是不可见的。仅包含 actions 的完整 UI 功能对用户来说是不可见的。没有应用程序状态的功能意味着代理对用户正在做的事情一无所知。无头操作可以合法地从操作 + 指令开始，并在稍后当人们需要浏览、批准、配置或共享时添加 UI/应用程序状态。 +采用这个框架之所以有价值，主要在于你不再需要自己构建的那些东西。只要你的应用遵循上述五条规则，你就会继承： -## SQL中的数据 {#data-in-sql} +| 功能 | 你获得了什么 | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| 一个 action = 每个表面 | 使用 `defineAction()` 定义的每个 action 同时是一个代理工具、一个类型安全的前端 hook（`useActionQuery` / `useActionMutation`）、一个框架自有的 HTTP 传输、一个 CLI 命令、一个供外部客户端使用的 MCP 工具，以及一个供其他代理本机应用使用的 A2A 工具。可选的 `link` 和 `mcpApp` 元数据无需第二次实现，即可添加深层链接和 MCP Apps UI。 | +| 每个用户的完整代理资源 | Skills、共享的 `LEARNINGS.md`、个人的 `memory/MEMORY.md`、`AGENTS.md`、自定义子代理、计划任务，以及已连接的 MCP 服务器。全部由 SQL 支撑，无需开发机。参见 [Agent Resources](/docs/agent-resources)。 | +| 开箱即用的 React 组件 | `` 和 `` 可以在你应用的任意位置渲染聊天 + 资源。参见 [Drop-in Agent](/docs/drop-in-agent)。 | +| BYO 代理聊天运行时 | 同一个聊天 UI 可以架在 OpenAI Agents、OpenAI Responses、Claude Agent SDK、Vercel AI SDK、AG-UI，或者你自己的规范化 HTTP 流之上。参见 [原生聊天 UI](/docs/native-chat-ui#byo-agent-runtimes)。 | +| 代理和 UI 之间的实时同步 | 同进程写入会立即通过 `/_agent-native/events` 流式传输；轻量级轮询让无服务器、cron 和跨进程写入保持收敛。变更类 actions 会自动使 action 支持的查询失效，因此代理创建的记录无需手动刷新即可出现。参见下方的 [Live Sync](#polling-sync)。 | +| Auth、orgs、RBAC | 每个模板都内置了带有 orgs/members/roles 的 Better Auth。参见 [Authentication](/docs/authentication)。如果不止一个用户，请从 [Organizations, Teams & Permissions](/docs/organizations-teams-permissions) 开始。 | +| 上下文感知 | 代理始终通过 `navigation` app-state 键知道用户正在查看什么。参见 [情境意识](/docs/context-awareness)。 | +| MCP 客户端 + 服务器，双向 | 该应用摄取 MCP 服务器（本地、远程、hub 共享的），*同时*也将自己的 actions 暴露为一个 MCP 服务器。参见 [MCP Clients](/docs/mcp-clients) 和 [MCP Protocol](/docs/mcp-protocol)。 | +| 跨应用委托 | 不同应用中的代理通过 [A2A](/docs/a2a-protocol) 通信。同源部署跳过 JWT；跨域部署使用共享的 `A2A_SECRET`。 | +| 子代理团队 | 生成一个拥有自己线程和工具的子代理，以聊天内联芯片的形式呈现。参见 [Agent Teams](/docs/agent-teams)。 | +| 可移植性 | 任何 Drizzle 支持的 SQL 数据库，任何 Nitro 兼容的主机（Node、Workers、Netlify、Vercel、Deno、Lambda、Bun）。 | -所有应用程序状态都通过 Drizzle ORM 存储在 SQL 数据库中。模式与提供者无关；支持的数据库、`DATABASE_URL` 配置和可移植性规则位于 [Database](/docs/database) 中。 +## SQL 中的数据 {#data-in-sql} -核心 SQL 商店是自动创建的，并且在每个模板中都可用： +所有应用状态都通过 Drizzle ORM 存在于一个 SQL 数据库中。Schema 与提供商无关；支持的数据库、`DATABASE_URL` 配置和可移植性规则见 [Database](/docs/database)。 -- `application_state` - 短暂的 UI 状态（导航、草稿、选择） -- `settings` — 持久键值配置 -- `oauth_tokens` — OAuth 凭证 -- `sessions` — 身份验证会话 +Core 的 SQL 存储会自动创建，并在每个模板中可用： + +- `application_state`：临时 UI 状态（导航、草稿、选择） +- `settings`：持久化的键值配置 +- `oauth_tokens`：OAuth 凭据 +- `sessions`：身份验证会话 + +下面每一行都可以展开查看其字段： +要添加你自己的领域数据，请使用与上面核心存储相同的 schema 辅助函数定义一张表： + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -243,26 +270,30 @@ export const forms = table("forms", { }); ``` +你和代理都可以直接从终端检查这些数据，无需单独的 SQL 客户端： + ```bash -# 数据库快速检查的核心动作 +# 用于快速检查数据库的 Core actions pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -生产代理聊天插件默认将原始 SQL 工具设为只读 -(`frameworkTools: { database: "read" }`)，因此代理使用 `db-schema` / `db-query` 检查应用拥有的数据， -并通过类型化应用 actions 执行写入。只有在刻意的维护界面也需要公开带范围限制的 -`db-exec` / `db-patch` 时，才设置 `database: "write"`（或 `true`）； -设置 `database: "off"` / `false` 可要求所有数据访问都通过类型化应用 actions。 +`db-schema` 会打印每张表的列和类型。`db-query` 直接运行只读 SQL，便于在不打开数据库客户端的情况下检查某个 action 的写入结果。 + + + +生产代理聊天插件默认将原始 SQL 工具设为只读（`frameworkTools: { database: "read" }`），因此代理使用 `db-schema` / `db-query` 检查应用拥有的数据，并通过类型化应用 actions 执行写入。只有在刻意的维护界面也需要公开带范围限制的 `db-exec` / `db-patch` 时，才设置 `database: "write"`（或 `true`）；设置 `database: "off"` / `false` 可要求所有数据访问都通过类型化应用 actions。 `frameworkTools` 以同样的方式管理框架自带的其余工具：分享、审阅评论、版本历史、feature flags、本地化、审计、Context X-Ray、个人资料、自动化、docs、resources、web、跨应用委派、聊天和邮件。完整列表、`"minimal"` 预设，以及为什么关闭分组仍保留其 HTTP 路由，请参见 [Production Agent Tools](/docs/deployment#production-agent-tools)。 + + ## 代理聊天桥 {#agent-chat-bridge} -UI 从不直接调用 LLM。当用户点击“生成图表”或“写入摘要”时，UI 通过 `postMessage` 向代理发送消息。代理完成工作 - 具有完整的对话历史记录、skills、指令和迭代能力。 +UI 从不直接调用 LLM。当用户点击"生成图表"或"撰写摘要"时，UI 会通过 `postMessage` 向代理发送一条消息。真正的工作由代理完成。它拥有完整的对话历史、skills、指令，以及迭代的能力。 ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -271,16 +302,19 @@ sendToAgentChat({ }); ``` -为什么不调用 LLM 内联？ +简而言之： + +- **AI 是非确定性的**：你需要对话流程来提供反馈和迭代，而不是一次性的按钮。 +- **上下文很重要**：代理拥有应用的指令、skills 和历史记录。内联调用则完全没有这些。 +- **代理能做更多事**：它可以运行 actions、浏览网页，并把多个步骤串联在一起。 -- **人工智能是不确定的。**您需要对话流来提供反馈和迭代——而不是一次性按钮。 -- **上下文很重要。**代理拥有您的完整代码库、说明、skills 和历史记录。内联调用则没有这些。 -- **代理可以做更多事情。**它可以运行 actions、浏览网页以及将多个步骤链接在一起。 -- **无头执行。**因为一切都通过代理进行，所以任何应用程序都可以完全由 Slack、Telegram 或其他代理通过 [A2A](/docs/a2a-protocol) 驱动。 +**[外部执行](/docs/a2a-protocol)** -## Actions系统 {#actions-system} +因为一切都通过代理和 actions 进行，任何应用都可以由 Slack、Telegram、计划任务、脚本，或者通过 A2A 由另一个代理来驱动。 -当代理需要做一些复杂的事情时——调用 API、处理数据、查询数据库——它会运行一个**操作**。 Actions 是 `actions/` 中的 TypeScript 文件，导出默认的 `defineAction()`： +## Actions 系统 {#actions-system} + +当代理需要做一些复杂的事情时，比如调用 API、处理数据或查询数据库，它会运行一个 **action**。Actions 是 `actions/` 目录下的 TypeScript 文件，默认导出一个 `defineAction()`： ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -298,19 +332,30 @@ export default defineAction({ }); ``` -一次 `defineAction()` 调用将为您提供： +这个 action 从一个来源 API 获取 JSON 并返回它。`defineAction()` 用一个 zod schema 包裹这个函数的输入（`source`），因此框架可以校验该输入、生成一个供代理调用的 JSON Schema，并从这一个定义中为前端 hook 推断类型。 + +一次 `defineAction()` 调用会自动触达五个不同的消费者。图表展示了从单个 action 扇出的过程；下面的列表解释了每个消费者各自获得了什么： + +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -- **代理工具** — 代理通过 zod 派生的 JSON 架构看到它并可以调用它。 -- **前端钩子** - `useActionMutation("fetch-data")` 具有完整的 TypeScript 推理。 -- **框架传输** - 自动安装在客户端挂钩后面。 -- **CLI** — `pnpm action fetch-data --source=signups` 用于脚本和代理开发循环。 -- **MCP 工具/A2A 工具** — 当启用 MCP 服务器或 A2A 时，也会显示相同的操作。 +- **代理工具：** 代理通过 zod 派生的 JSON Schema 看到它，并可以调用它。 +- **前端 hook：** `useActionMutation("fetch-data")`，具有完整的 TypeScript 推断。 +- **框架传输：** 自动挂载在客户端 hooks 之后。 +- **CLI：** `pnpm action fetch-data --source=signups`，用于脚本编写和代理开发循环。 +- **MCP 工具 / A2A 工具：** 当 MCP 服务器或 A2A 启用时，同一个 action 也会出现在那里。 -相同的逻辑，一个定义，自动连接到每个消费者。请参阅 [Actions](/docs/actions) 获取完整参考。 +每一个消费者调用的都是同一个底层函数，因此只需要编写和维护一份实现。完整参考请见 [Actions](/docs/actions)。 ## 实时同步 {#polling-sync} -数据库更改通过`useDbSync()`同步到UI。同进程通过`/_agent-native/events`写流； `/_agent-native/poll` 仍然是跨进程和无服务器的后备方案。当代理写入数据库（应用程序状态、设置或域数据）时，版本计数器会递增，并且客户端会使相关的 React 查询缓存无效。 +当代理更改数据时，UI 需要在无需手动刷新的情况下反映这一变化。`useDbSync()` 让这一切自动发生。同进程写入通过 `/_agent-native/events` 流式传输；`/_agent-native/poll` 仍然是跨进程和无服务器场景的回退方案。当代理写入数据库（应用状态、设置或领域数据）时，一个版本计数器会递增，客户端会使相关的 React Query 缓存失效。 ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -318,15 +363,19 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` -流程是： +在应用的根部附近调用一次即可。它会让整个应用订阅变更事件，因此任何使用 `useActionQuery` 或带来源版本的 `useQuery` 的组件，在其读取的数据发生变化时都会自动重新获取。 -1. 代理运行写入数据库的操作 -2. 服务器使用 `"action"` 或 `"settings"` 等源发出更改事件 -3. `useDbSync` 通过 SSE 或轮询回退接收它 -4. `useActionQuery` 挂钩和源版本 `useQuery` 挂钩重新获取 -5. 组件无需重新加载页面即可呈现新数据 +流程如下： - +1. 代理运行一个写入数据库的 action +2. 服务器发出一个带有来源（例如 `"action"` 或 `"settings"`）的变更事件 +3. `useDbSync` 通过 SSE 或轮询回退接收该事件 +4. `useActionQuery` hooks 和带来源版本的 `useQuery` hooks 重新获取数据 +5. 组件渲染新数据，无需重新加载页面 + +下面的图表端到端地追踪了这一相同的顺序： + + ```html
@@ -340,11 +389,11 @@ useDbSync({ queryClient });
useDbSyncSSE · poll fallback + >SSE · 轮询回退
- 重新获取查询
渲染，无需重载 + 查询重新获取
渲染，无需重新加载
``` @@ -371,88 +420,90 @@ useDbSync({ queryClient }); -这适用于所有部署环境（包括无服务器和边缘），因为它使用数据库，而不是内存状态或文件系统观察器。 +这在所有部署环境中都有效，包括无服务器和边缘环境，因为它依赖的是数据库，而不是内存状态或文件系统监视器。 ## 框架 {#frames} -_frame_ 是在您的应用程序旁边托管代理的环境 - 在本地是嵌入式面板；在云端，它是 Builder.io 的托管表面。参见[Frames](/docs/frames)。 +_frame_ 是在你的应用旁边托管代理的环境。在本地，它是嵌入式面板；在云端，它是 Builder.io 的托管表面。参见 [Frames](/docs/frames)。 -代理本机应用程序包括一个嵌入式代理面板，该面板与应用程序 UI 一起提供 AI 代理。这就是架构发挥作用的原因：代理需要计算机（数据库、浏览器、代码执行），而应用程序需要代理来进行 AI 工作。 +Agent-native 应用都包含一个嵌入式代理面板，在应用 UI 旁边提供 AI 代理。这正是这一架构得以运作的原因：代理需要一台计算机（数据库、浏览器、代码执行），而应用需要代理来完成 AI 工作。 -- **嵌入式代理面板** - 每个应用程序中内置聊天和可选的 CLI 终端。支持 Claude 代码、Codex、Gemini、OpenCode 和 Builder.io。在本地运行。免费且开源。 -- **云** — 通过实时协作、可视化编辑、角色和权限部署到任何云。最适合团队。 +- **嵌入式代理面板：** 内置于每个应用中的聊天和可选 CLI 终端。支持 Claude Code、Codex、Gemini、OpenCode 和 Builder.io。在本地运行，免费且开源。 +- **云：** 部署到任意云端，具备实时协作、可视化编辑、角色和权限管理。最适合团队使用。 -## 情境感知 {#context-awareness} +## 上下文感知 {#context-awareness} -代理始终知道用户在看什么。 UI 在每次路由更改时将 `navigation` 密钥写入应用程序状态。代理在执行操作之前通过 `view-screen` 操作读取它。 +代理始终知道用户正在查看什么。UI 会在每次路由变化时向 application-state 写入一个 `navigation` 键。代理在采取行动之前，会通过 `view-screen` 这个 action 读取它。 -例如，当您打开电子邮件线程时，UI 会插入一行，例如： +例如，当你打开一个邮件线程时，UI 会 upsert（更新插入）一行像这样的数据： ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -UI 在路线变更时写入此信息；代理在采取任何操作之前都会读取它（通过 `view-screen`），因此它始终知道您关注的是哪个线程 - 或图表或幻灯片。 + + +UI 会在路由变化时写入这条数据；代理在采取任何行动之前会（通过 `view-screen`）读取它，因此它始终知道你正专注于哪个线程、图表或幻灯片。 + + -请参阅 [Context Awareness](/docs/context-awareness) 了解完整模式：导航状态、视图屏幕、导航命令和抖动预防。 +完整模式请见 [情境意识](/docs/context-awareness)：导航状态、view-screen、navigate 命令，以及防抖动机制。 -## 一个动作，多个表面 {#protocols} +## 一个 action，多个表面 {#protocols} -将一个域操作作为一个动作执行一次；该框架将其暴露给每个消费者。相同的 `defineAction()` 成为代理工具、类型安全 UI 挂钩、HTTP 端点、CLI 命令、MCP 工具和 A2A 工具，并且仅在表面需要时添加可选的 `link`、`mcpApp` 或显式本机小部件元数据。 Skills 和说明涵盖行为。 +把一个领域操作实现为一个 action，只需一次；框架会将它暴露给每一个消费者。同一个 `defineAction()` 会变成一个代理工具、一个类型安全的 UI hook、一个 HTTP 端点、一个 CLI 命令、一个 MCP 工具和一个 A2A 工具，只有当某个表面需要更丰富的交互时，才会额外添加可选的 `link`、`mcpApp`、原生小部件元数据，或 Generative UI 包装器。Skills 和指令负责覆盖行为部分。 -有关完整的协议/表面矩阵（MCP 服务器和 OAuth、MCP 应用程序、A2A、深层链接、本机聊天小部件、AgentChatRuntime 连接器、Agent Web 以及 ACP 和 A2UI 的适配器范围），以及选择产品形状（无头、丰富聊天、嵌入式边车或完整应用程序），请参阅[Agent Surfaces](/docs/agent-surfaces)。 +完整的协议/表面矩阵（MCP 服务器与 OAuth、MCP Apps、A2A、深层链接、原生聊天小部件、Generative UI、AgentChatRuntime 连接器、Agent Web，以及面向 ACP 和 A2UI 的适配器展望），以及如何选择产品形态（聊天、内联 UI、完整应用页面、嵌入式 sidecar、自动化，或外部代理访问），请见 [Agent 界面](/docs/agent-surfaces)。 ## 应用代码与定制 {#agent-modifies-code} -嵌入式代理默认不编辑应用程序源代码。只有当主机有意授予 -repository/workspace 写入工具时，它才能编辑源代码。在普通的已部署 -应用中，代理通过 actions、SQL 支持的状态和已配置的集成来工作。 -Templates 是完整的应用程序，您可以在自己的代码库和开发流程中 fork -并定制它们。 +框架不会赋予嵌入式代理对应用源代码的环境访问权限。在一个已部署的应用中，代理通常通过 actions、SQL 支撑的状态和已配置的集成来工作。当它的框架被有意授予工作区和写入工具时，它可以编辑组件、路由、样式和 actions。无论哪种情况，Templates 都是完整的应用，你可以在自己的代码仓库和开发流程中 fork 并定制它们。如果需要在不修改源代码的情况下进行运行时定制，请使用 [Extensions](/docs/extensions)。 -## 默认为便携式 {#hosting-agnostic} +## 默认可移植 {#hosting-agnostic} -两条架构规则使应用程序可以跨数据库和主机移植： +两条架构规则让应用可以跨数据库和主机移植： -- **与数据库无关。** 使用 `@agent-native/core/db/schema` 写入模式并使用 Drizzle 的可移植查询 DSL 进行读/写，因此相同的代码可以在任何支持的提供程序上运行。仅将原始 SQL 用于附加迁移或一次性维护，保持参数化且与方言无关。参见[Database](/docs/database)。 -- **与主机无关。** 服务器在 Nitro 上运行并编译为任何部署目标。切勿在服务器路由或插件中使用特定于节点的 API（`fs`、`child_process`、`path`），并且切勿假设持久服务器进程 - 无服务器和边缘是无状态的，因此将所有状态保留在 SQL 中。参见[Deployment](/docs/deployment)。 +- **数据库无关。** 使用 `@agent-native/core/db/schema` 编写 schema，并使用 Drizzle 的可移植查询 DSL 进行读写，这样相同的代码可以在任何受支持的提供商上运行。仅将原始 SQL 用于增量迁移或一次性维护，且要保持参数化并与具体方言无关。参见 [Database](/docs/database)。 +- **主机无关。** 服务器运行在 Nitro 之上，可以编译到任意部署目标。切勿在服务器路由或插件中使用 Node 特有的 API（`fs`、`child_process`、`path`），也不要假设存在一个持久化的服务器进程。无服务器和边缘环境都是无状态的，因此要把所有状态保存在 SQL 中。参见 [Deployment](/docs/deployment)。 -## 工作区 {#workspace} +## 代理资源 {#workspace} -每个用户都会获得一个个人**工作空间** - 指令、skills、内存、自定义子代理、计划作业和连接的 MCP 服务器 - 全部存储在 SQL 而不是文件中。这使得 Claude 代码级定制可以在多租户 SaaS 中实现，而无需为每个用户启动一个容器。参见[代理资源](/docs/agent-resources)。 +每个用户都会获得一套个人的**代理资源**：指令、skills、记忆、自定义子代理、计划任务，以及已连接的 MCP 服务器，全部存储在 SQL 中，而不是文件中。这使得 Claude-Code 级别的定制，在多租户 SaaS 中也变得可行，而无需为每个用户启动一个容器。参见 [Agent Resources](/docs/agent-resources)。 ## 相关构建块 {#building-blocks} -这些位于同一个合约之上，并且有自己的深入研究： +以下内容建立在同一份契约之上，各自都有更深入的介绍： -- **[Dispatch](/docs/dispatch)** — 工作区控制平面：共享收件箱、机密库、计划作业以及通过 A2A 委托给专业应用程序的编排器。 -- **[Extensions](/docs/extensions)** — 代理在运行时创建的沙盒 Alpine.js 迷你应用，无需更改源或迁移。 -- **[数据程序](/docs/data-programs)** — 由 agent 编写并存储的 `run-code` 脚本，为 dashboard 面板提供缓存的、可刷新的结果，而不是硬编码的 provider action。 -- **[A2A Protocol](/docs/a2a-protocol)** — 同一工作区中的应用如何通过 JSON-RPC 发现并相互调用。 +- **[Dispatch](/docs/dispatch)：** 工作区控制平面，具有共享收件箱、secrets vault、计划任务，以及一个通过 A2A 将工作委托给专项应用的编排器。 +- **[Extensions](/docs/extensions)：** 代理在运行时创建的沙盒化 Alpine.js 迷你应用，无需修改源代码或迁移。 +- **[A2A协议](/docs/a2a-protocol)：** 同一工作区内的应用如何通过 JSON-RPC 相互发现并调用。 -## 您免费获得的东西 {#what-you-get-for-free} +## 下一步 {#deep-dives} -采用该框架很有价值，主要是因为您不再需要构建什么。一旦您的应用遵循这五个规则，您就继承了： + -- **一个操作 = 每个表面。** 使用 `defineAction()` 定义的每个操作同时是一个代理工具、类型安全前端挂钩 (`useActionQuery` / `useActionMutation`)、框架拥有的 HTTP 传输、CLI 命令、用于外部客户端的 MCP 工具以及用于其他代理本机应用程序的 A2A 工具。可选的 `link` 和 `mcpApp` 元数据添加深层链接和 MCP 应用 UI，无需第二次实现。 -- **每个用户一个完整的工作区。** Skills、共享 `LEARNINGS.md`、个人 `memory/MEMORY.md`、`AGENTS.md`、自定义子代理、计划作业、连接的 MCP 服务器 — 所有 SQL 支持，无需开发盒。参见[代理资源](/docs/agent-resources)。 -- **插入 React 组件。** `` 和 `` 在应用程序中的任何位置呈现聊天 + 工作区。参见[Drop-in Agent](/docs/drop-in-agent)。 -- **BYO 代理聊天运行时。** 相同的聊天 UI 可以位于 OpenAI 代理、OpenAI 响应、Claude 代理 SDK、Vercel AI SDK、AG-UI 或您自己的规范化 HTTP 流之上。参见[Native 聊天界面](/docs/native-chat-ui#byo-agent-runtimes)。 -- **代理和 UI 之间的实时同步。**同一进程立即通过 `/_agent-native/events` 写入流；轻量级轮询使无服务器、cron 和跨进程写入保持收敛。改变 actions 会自动使操作支持的查询失效，因此无需手动刷新即可显示代理创建的记录。请参阅下面的 [Live Sync](#polling-sync)。 -- **Auth、orgs、RBAC。** 每个模板都内置了带有 orgs/members/roles 的更好的身份验证。参见[Authentication](/docs/authentication)。 -- **上下文感知。**代理始终通过 `navigation` 应用状态键了解用户正在查看的内容。参见[Context Awareness](/docs/context-awareness)。 -- **MCP 客户端 + 服务器，双向。** 应用程序摄取 MCP 服务器（本地、远程、集线器共享）*并且*将其自己的 actions 公开为 MCP 服务器。请参阅 [MCP Clients](/docs/mcp-clients) 和 [MCP Protocol](/docs/mcp-protocol)。 -- **应用程序间委托。**不同应用程序中的代理通过 [A2A](/docs/a2a-protocol) 进行通信。同源部署跳过JWT；跨域使用共享的`A2A_SECRET`。 -- **子代理团队。** 生成一个具有自己的线程和工具的子代理，以聊天中内联的芯片形式出现。参见[Agent Teams](/docs/agent-teams)。 -- **可移植性。**任何 Drizzle 支持的 SQL 数据库、任何 Nitro 兼容的主机（Node、Workers、Netlify、Vercel、Deno、Lambda、Bun）。 +### [什么是 Agent-Native？](/docs/what-is-agent-native) -这就是“以及其他所有东西”，否则你需要自己将它们粘合在一起。 +这些规则背后的愿景和理念。 -## 下一步 {#deep-dives} +### [情境意识](/docs/context-awareness) + +深入介绍导航状态、view-screen 和 navigate 命令。 + +### [Skills指南](/docs/skills-guide) + +框架 skills、领域 skills，以及创建自定义 skills。 + +### [原生聊天 UI](/docs/native-chat-ui) + +由 action 声明的表格、图表，以及 BYO 运行时定位。 + +### [Agent 界面](/docs/agent-surfaces) + +聊天、原生内联 UI、完整应用页面、嵌入式 sidecar、自动化，以及外部代理路径。 + +### [A2A协议](/docs/a2a-protocol) + +代理间通信。 -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — 这些规则背后的愿景和理念 -- [**Context Awareness**](/docs/context-awareness) — 深入了解导航状态、view-screen 和 navigate 命令 -- [**Skills Guide**](/docs/skills-guide) — 框架 skills、领域 skills 以及创建自定义 skills -- [**Native Chat UI**](/docs/native-chat-ui) — action 声明的表格、图表和自带运行时支持 -- [**Agent Surfaces**](/docs/agent-surfaces) — 聊天、原生内联 UI、完整应用页面、嵌入式 sidecar、自动化和外部代理路径 -- [**A2A Protocol**](/docs/a2a-protocol) — 代理间通信 + diff --git a/packages/core/docs/content/locales/zh-TW/key-concepts.mdx b/packages/core/docs/content/locales/zh-TW/key-concepts.mdx index 24a164cf00..61da71216c 100644 --- a/packages/core/docs/content/locales/zh-TW/key-concepts.mdx +++ b/packages/core/docs/content/locales/zh-TW/key-concepts.mdx @@ -1,45 +1,49 @@ --- title: "關鍵概念" -description: "Agent-Native 應用程式的工作原理：首先是 actions、SQL 資料庫、應用程式代理迴圈、可選的 UI、輪詢同步、外部代理入口點、脈絡感知和可移植性。" +description: "Agent-native 應用程式如何在三個層次上運作：Core 框架、可選的 Toolkit 建置區塊，以及可選的 Templates，加上共用的動作、SQL 資料庫、應用程式與代理迴圈，以及可移植性規則。" --- # 關鍵概念 -Agent-Native 應用程式如何在幕後工作 - 原則和架構。此頁面為合同；有關以這種方式建置的願景和案例，請參閱 [What Is Agent-Native?](/docs/what-is-agent-native)。 +Agent-native 應用程式如何在幕後運作：原則與架構。此頁面就是合約：應用程式若要被視為 agent-native，就必須遵守這些固定規則。若想了解以此方式建置的願景與理由，請參閱 [什麼是 Agent-Native？](/docs/what-is-agent-native)。 ## 三個層次 {#three-layers} -Agent Native 是一個 framework，而不是單一範本： +Agent Native 是一個具有三個層次的框架： -- **Core - framework：** 所有應用程式都能使用的基礎執行階段與資料契約。 -- **Toolkit - 可選的可重複使用元件：** 應用程式可以採用、組合或 fork 的共用 UI 與產品系統。 -- **Templates - 可選的應用程式：** 建立在 Core 之上的完整領域應用程式，通常使用 Toolkit，也能 fork 並作為起點使用。 +| 層次 | 是什麼 | +| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| **Core：框架** | 基礎的執行階段合約：動作、SQL 與 Drizzle 輔助工具、驗證、應用程式狀態、代理執行、存取檢查、路由與即時同步。每個應用程式都能直接使用 Core。 | +| **Toolkit：可選的可重複使用元件** | 共用的應用程式建置 UI 與產品系統，例如基礎元件、編輯器、共用、協作、設定和代理 UX。應用程式可以採用、組合或 fork 所需的元件。 | +| **Templates：以 Core 為基礎的可選應用程式** | 具有路由、結構描述、動作、指令和視覺識別的完整領域專屬應用程式。官方與自訂範本通常會使用 Toolkit，也可以被 fork 並作為起點使用。 | -Core 是基礎。Toolkit 與 Templates 都是可選的。 +Core 是基礎。Toolkit 與 Templates 都是可選的：範本可以使用 Toolkit，但要在 Core 上建置應用程式並不需要 Toolkit。 ## 架構 {#the-architecture} -每個 Agent-Native 應用程式都由三部分協同工作： +在執行階段，每個 agent-native 應用程式都是三個協同運作的部分： -- **代理** — 讀取資料、寫入資料、執行 actions 並使用已設定工具的自主 AI。可使用 skills 和說明進行定制。 -- **應用** — 試劑週圍的產品表面。一開始這可能只是操作、豐富的聊天、小型控制平面或帶有儀表板、流程和視覺化的完整 React 介面。 -- **電腦** — 資料庫、瀏覽器、程式碼執行。代理透過應用程式的動作與資料介面工作；應用程式可以透過 MCP 公開相同的動作介面，而外部 MCP 伺服器仍是可選的附加元件，不是基礎。 +- **代理：** 自主運作的 AI。它讀取資料、寫入資料、執行動作，並使用任何已設定的工具。當其 frame 被刻意授予工作區存取權和寫入工具時，它也能修改應用程式自身的原始碼。可透過 skills 和指令進行客製化。 +- **應用程式：** 圍繞代理的產品表面。它可能一開始只是聊天，之後加入原生行內結果、成長為小型控制平面，或成為具有儀表板、流程和視覺化的完整 React UI。 +- **電腦：** 代理據以行動的資料庫、瀏覽器和已設定的工具執行環境。代理透過應用程式自身的動作與資料介面來工作；同一個介面可以選擇性地透過 MCP 公開，但外部 MCP 伺服器仍只是附加元件，不是基礎。 - +下圖顯示代理和應用程式並排在一起，兩者都有雙向箭頭指向下方同一個共用的電腦層。沒有任何一方擁有資料。相反地，它們讀取並寫入同一個 SQL 儲存，因此任一方所做的變更都會立即讓另一方看到，中間不需要建置任何同步層。 + + ```html
- Agent代理讀取和寫入資料、執行 actions、使用已設定工具讀取並寫入資料、執行動作、使用已設定的工具
- Application應用程式action-only, chat, control plane, or full React 介面聊天、行內結果、控制平面，或完整的 React UI
@@ -47,8 +51,8 @@ Core 是基礎。Toolkit 與 Templates 都是可選的。 ↓ ↑
- Computer
SQL 資料庫 · browser · code executionSQL 資料庫 · 瀏覽器 · 程式碼執行
@@ -86,103 +90,124 @@ Core 是基礎。Toolkit 與 Templates 都是可選的。 -無頭應用程式可以使用 `pnpm agent` 從資料夾執行相同的正式環境應用程式代理迴圈，而 UI 應用程式則安裝嵌入式代理面板並使用 `pnpm dev` 在本機執行。在雲端中，Builder.io 提供了一個託管框架（在您的應用旁邊託管代理的環境），為團隊提供協作、視覺化編輯和託管基礎架構。 +這個相同的代理-應用程式-電腦迴圈，會同時在本機和正式環境中運作。以自動化為優先的應用程式，可以直接用 `pnpm agent` 在資料夾中執行它；UI 應用程式則會掛載嵌入式代理面板，並加上 `pnpm dev`。在雲端中，Builder.io 會將這個相同的迴圈，以受管理的 frame 形式代管：也就是在你的應用程式旁邊執行代理的環境。它會為你處理協作、視覺化編輯和基礎設施。 -## 代理建置塊 {#agent-building-blocks} +## 代理建置區塊 {#agent-building-blocks} -每個 Agent-Native 應用程式都具有相同的代理建置塊，無論是否 -產品表面是無頭的、聊天優先的或完整的 UI： +每個 agent-native 應用程式都有相同的代理建置區塊，無論 +產品表面是以聊天為優先、以自動化為優先，還是完整的 UI。每一個都 +存在於自己的檔案中： /SKILL.md", - note: "可複用行為：workflow 步驟、策略、範例、參考以及做/不做清單", + note: "可重複使用的行為：工作流程步驟、政策、範例、參考資料，以及該做和不該做的清單", }, { path: "actions/.ts", - note: "可執行能力：暴露給代理、UI、CLI、HTTP、MCP、A2A、jobs 和 webhooks 的型別化操作", + note: "可執行的能力：向代理、UI、CLI、HTTP、MCP、A2A、jobs 和 webhooks 公開的型別化操作", }, ]} /> -| 建置塊 | 使用它 | 載入時間 | -| ----------- | ---------------------------------------------------------------------- | -------------------------------- | -| **說明** | 代理應在每項工作中進行穩定的指導：應用程式是什麼、不變數、語氣、索引 | 每個回合 | -| **Skills** | 可重用行為：如何遵循工作流程、應用策略、檢查證據或驗證輸出 | 當技能描述與工作匹配時按需 | -| **Actions** | 實際操作：讀取或寫入資料、呼叫 API、傳送訊息、執行核准、生成型別化結果 | 每次都被列為工具；僅在呼叫時執行 | +一個回合是與代理的一次交流：它讀取脈絡、決定要做什麼，然後回應。「每回合載入」表示該檔案每次都會重新進入脈絡，而不僅僅是在工作階段開始時載入一次。 + +| 建置區塊 | 檔案 | 用途 | 載入時機 | +| ----------- | -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------- | +| **說明** | `AGENTS.md` | 代理在每項任務中都應攜帶的穩定指導：應用程式是什麼、不變量、語氣、索引 | 每個回合 | +| **Skills** | `.agents/skills//SKILL.md` | 可重複使用的行為：如何遵循工作流程、套用政策、檢查證據或驗證輸出 | 當 skill 描述與任務相符時按需載入 | +| **Actions** | `actions/.ts` | 實際操作：讀取或寫入資料、呼叫 API、傳送訊息、執行核准、產生型別化結果 | 每個回合都列為工具；僅在被呼叫時才執行 | + +Skills 和 actions 協同運作。一項 skill 教導代理如何做 +一類工作；一個 action 是它在執行該工作時可以呼叫的程式碼路徑。舉例來說， +`customer-research` skill 可能會告訴代理該檢查哪些來源， +以及如何摘要證據，而 `search-crm` 和 `create-brief` 這些 actions +則負責擷取並寫入實際資料。 + +五項規則規範了這個架構： -Skills 和 actions 一起工作。一項技能教代理如何做一類 -工作；操作是它在執行該工作時可以呼叫的程式碼路徑。例如， -`customer-research` 技能可能會告訴代理要檢查哪些來源 -如何在 `search-crm` 和 `create-brief` actions 取得的同時總結證據 -並寫入實際資料。 +1. **資料存在於 SQL 中：** 所有應用程式狀態都透過 Drizzle ORM 存放在資料庫中。 +2. **所有 AI 都透過代理：** 沒有行內 LLM 呼叫；每一次 AI 互動都流經代理聊天橋接。 +3. **動作用於代理操作：** 複雜的工作以型別化動作執行，而非行內程式碼。 +4. **即時同步讓 UI 保持同步：** 資料庫變更會透過 SSE 串流，並以輪詢作為通用回退。 +5. **應用程式狀態存於 SQL：** 短暫的 UI 狀態存放在資料庫中，代理和 UI 都可以讀取。 -管理架構的五項規則： +## 四個領域檢查清單 {#four-area-checklist} -1. **資料存在於 SQL** - 所有應用程式狀態都透過 Drizzle ORM 存在於資料庫中 -2. **所有 AI 都透過代理** - 無行內 LLM 呼叫 -3. **Actions 用於代理操作** — 複雜的工作作為 actions 執行 -4. **即時同步使 UI 保持同步** — 透過 SSE 進行資料庫更改流，並以輪詢作為通用回退 -5. **應用程式狀態儲存在 SQL 中** - 暫時的 UI 狀態位於資料庫中，代理和 UI 都可以讀取 +每個面向使用者的功能都應該更新所有適用的領域。跳過某個適用的領域會破壞 agent-native 合約；把畫面硬塞進不需要人類瀏覽的自動化流程中，同樣是一種代碼異味。 -## 四個區域清單 {#four-area-checklist} +- **1. UI：** 使用者互動的頁面、元件或對話框。 +- **2. Action：** `actions/` 中對應同一操作、可供代理呼叫的 action。 +- **3. Skills：** 更新 `AGENTS.md`，並/或建立記錄該模式的 skill。 +- **4. App-State：** 導覽狀態、view-screen 資料，以及 navigate 指令。 -每個面向使用者的功能都應該更新所有適用的區域。跳過適用區域會破壞代理與本機合約；將 UI 強制到僅動作原語上也是一種氣味。 +只有 UI 的功能對代理來說是不可見的。只有 actions 的完整 UI 功能對使用者來說是不可見的。沒有 app-state 的功能代表代理對使用者正在做什麼一無所知。以自動化優先的操作可以合理地先從 action + 指令開始，等到之後人類需要瀏覽、核准、設定或分享它時，再加入聊天、UI 或 app-state。 -| 區域 | 描述 | -| ------------------- | ---------------------------------------- | -| **1. UI** | 使用者與之互動的頁面、元件或對話框 | -| **2。行動** | actions/中的代理可呼叫操作用於相同操作 | -| **3. Skills** | 更新 AGENTS.md 和/或建立紀錄該模式的技能 | -| **4。應用程式狀態** | 導覽狀態、檢視螢幕資料和導覽指令 | +## Agent Native 包含哪些內容 {#what-you-get-for-free} -只有 UI 的功能對於代理來說是不可見的。僅包含 actions 的完整 UI 功能對使用者來說是不可見的。沒有應用程式狀態的功能意味著代理對使用者正在做的事情一無所知。無頭操作可以合法地從操作 + 指令開始，並在稍後當人們需要瀏覽、核准、設定或共用時新增 UI/應用程式狀態。 +採用這個框架的價值，主要來自於你不再需要建置的東西。只要你的應用程式遵循上述五項規則，你就會繼承： + +| 功能 | 它帶給你什麼 | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 一個 action = 每個表面 | 每個以 `defineAction()` 定義的 action，同時是一個代理工具、一個型別安全的前端 hook（`useActionQuery` / `useActionMutation`）、一個框架自有的 HTTP 傳輸、一個 CLI 指令、一個供外部用戶端使用的 MCP 工具，以及一個供其他 agent-native 應用程式使用的 A2A 工具。可選的 `link` 和 `mcpApp` 中繼資料，可在不需要第二次實作的情況下新增深層連結和 MCP Apps UI。 | +| 每位使用者的完整代理資源 | Skills、共用的 `LEARNINGS.md`、個人的 `memory/MEMORY.md`、`AGENTS.md`、自訂子代理、排程工作，以及已連接的 MCP 伺服器。全部由 SQL 支援，不需要開發用機器。請參閱 [Agent Resources](/docs/agent-resources)。 | +| 隨插即用的 React 元件 | `` 和 `` 可以在應用程式中的任何位置渲染聊天 + 資源。請參閱 [Drop-in Agent](/docs/drop-in-agent)。 | +| 自帶代理聊天執行環境（BYO） | 相同的聊天 UI 可以架在 OpenAI Agents、OpenAI Responses、Claude Agent SDK、Vercel AI SDK、AG-UI，或你自己的標準化 HTTP 串流之上。請參閱 [原生聊天 UI](/docs/native-chat-ui#byo-agent-runtimes)。 | +| 代理與 UI 之間的即時同步 | 同行程的寫入會立即透過 `/_agent-native/events` 串流；輕量級輪詢則讓無伺服器、cron 和跨行程的寫入保持一致。會變更資料的 actions 會自動讓以 action 為基礎的查詢失效，因此代理建立的紀錄無需手動重新整理即可出現。請參閱下方的 [Live Sync](#polling-sync)。 | +| 驗證、組織、RBAC | 每個範本都已內建具有 orgs/members/roles 的 Better Auth。請參閱 [Authentication](/docs/authentication)。若使用者不只一位，請從 [Organizations, Teams & Permissions](/docs/organizations-teams-permissions) 開始。 | +| 情境感知 | 代理透過 `navigation` 這個 app-state 鍵，隨時知道使用者正在看什麼。請參閱 [情境意識](/docs/context-awareness)。 | +| MCP 用戶端 + 伺服器，雙向皆可 | 應用程式可以擷取 MCP 伺服器（本機、遠端、hub 共用），*同時*也能將自己的 actions 公開為 MCP 伺服器。請參閱 [MCP Clients](/docs/mcp-clients) 和 [MCP Protocol](/docs/mcp-protocol)。 | +| 跨應用程式委派 | 不同應用程式中的代理透過 [A2A](/docs/a2a-protocol) 通訊。同源部署會跳過 JWT；跨源部署則使用共用的 `A2A_SECRET`。 | +| 子代理團隊 | 產生一個擁有自己對話串和工具的子代理，並以聊天中行內的標籤形式呈現。請參閱 [Agent Teams](/docs/agent-teams)。 | +| 可移植性 | 任何 Drizzle 支援的 SQL 資料庫、任何 Nitro 相容的主機（Node、Workers、Netlify、Vercel、Deno、Lambda、Bun）。 | ## SQL 中的資料 {#data-in-sql} -所有應用程式狀態都透過 Drizzle ORM 儲存在 SQL 資料庫中。模式與提供者無關；支援的資料庫、`DATABASE_URL` 設定和可移植性規則位於 [Database](/docs/database) 中。 +所有應用程式狀態都透過 Drizzle ORM 存放在 SQL 資料庫中。結構描述與提供者無關；支援的資料庫、`DATABASE_URL` 設定，以及可移植性規則，都記載於 [Database](/docs/database)。 + +Core 的 SQL 儲存區會自動建立，並在每個範本中都可使用： -核心 SQL 商店是自動建立的，並且在每個範本中都可用： +- `application_state`：短暫的 UI 狀態（導覽、草稿、選取項目） +- `settings`：持久性的鍵值設定 +- `oauth_tokens`：OAuth 憑證 +- `sessions`：驗證工作階段 -- `application_state` - 短暫的 UI 狀態（導覽、草稿、選取） -- `settings` — 持久鍵值設定 -- `oauth_tokens` — OAuth 憑證 -- `sessions` — 驗證工作階段 +以下每一列都可展開以顯示其欄位： +若要新增你自己的領域資料，請使用與上述核心儲存區相同的結構描述輔助工具來定義資料表： + ```ts // Drizzle schema for domain data import { table, text, integer } from "@agent-native/core/db/schema"; @@ -243,26 +270,30 @@ export const forms = table("forms", { }); ``` +你和代理都可以直接從終端機檢查該資料，不需要額外的 SQL 用戶端： + ```bash -# 資料庫快速檢查的核心動作 +# 用於快速檢查資料庫的 Core actions pnpm action db-schema # show all tables pnpm action db-query --sql "SELECT * FROM forms" ``` -正式環境代理聊天外掛預設將原始 SQL 工具設為唯讀 -(`frameworkTools: { database: "read" }`)，因此代理使用 `db-schema` / `db-query` 檢查應用程式擁有的資料， -並透過型別化應用程式 actions 執行寫入。只有在刻意的維護介面也需要公開具範圍限制的 -`db-exec` / `db-patch` 時，才設定 `database: "write"`（或 `true`）； -設定 `database: "off"` / `false` 可要求所有資料存取都透過型別化應用程式 actions。 +`db-schema` 會印出每個資料表的欄位與型別。`db-query` 會直接執行唯讀 SQL，這對於在不開啟資料庫用戶端的情況下檢查某個 action 的寫入結果很有用。 + + + +正式環境代理聊天外掛預設將原始 SQL 工具設為唯讀（`frameworkTools: { database: "read" }`），因此代理使用 `db-schema` / `db-query` 檢查應用程式擁有的資料，並透過型別化應用程式 actions 執行寫入。只有在刻意的維護介面也需要公開具範圍限制的 `db-exec` / `db-patch` 時，才設定 `database: "write"`（或 `true`）；設定 `database: "off"` / `false` 可要求所有資料存取都透過型別化應用程式 actions。 `frameworkTools` 以同樣的方式管理框架自帶的其餘工具：分享、審閱留言、版本歷史、feature flags、本地化、稽核、Context X-Ray、個人資料、自動化、docs、resources、web、跨應用委派、聊天與郵件。完整清單、`"minimal"` 預設，以及為什麼關閉分組仍保留其 HTTP 路由，請參見 [Production Agent Tools](/docs/deployment#production-agent-tools)。 -## 代理聊天橋 {#agent-chat-bridge} + -UI 從不直接呼叫 LLM。當使用者點選“產生圖表”或“寫入摘要”時，UI 透過 `postMessage` 向代理傳送訊息。代理完成工作 - 具有完整的對話歷史紀錄、skills、指令和迭代能力。 +## 代理聊天橋接 {#agent-chat-bridge} + +UI 從不直接呼叫 LLM。當使用者點擊「Generate chart」或「Write summary」時，UI 會透過 `postMessage` 向代理傳送一則訊息。代理負責完成工作，它擁有完整的對話歷史、skills、指令，以及反覆迭代的能力。 ```ts -// In a React component — delegate AI work to the agent +// Delegate AI work to the agent from a React component import { sendToAgentChat } from "@agent-native/core/client/agent-chat"; sendToAgentChat({ message: "Generate a chart showing signups by source", @@ -271,16 +302,19 @@ sendToAgentChat({ }); ``` -為什麼不呼叫 LLM 行內？ +簡而言之： + +- **AI 是非確定性的**：你需要對話流程來提供意見回饋並反覆迭代，而不是一次性的按鈕。 +- **脈絡很重要**：代理擁有應用程式的指令、skills 和歷史紀錄。行內呼叫則完全沒有這些。 +- **代理能做更多事**：它可以執行 actions、瀏覽網頁，並將多個步驟串連在一起。 -- **人工智慧是不確定的。**您需要對話流來提供意見回饋和迭代——而不是一次性按鈕。 -- **脈絡很重要。**代理擁有您的完整程式碼庫、說明、skills 和歷史紀錄。行內呼叫則沒有這些。 -- **代理可以做更多事情。**它可以執行 actions、瀏覽網頁以及將多個步驟連結在一起。 -- **無頭執行。**因為一切都透過代理進行，所以任何應用程式都可以完全由 Slack、Telegram 或其他代理透過 [A2A](/docs/a2a-protocol) 驅動。 +**[外部執行](/docs/a2a-protocol)** -## Actions系統 {#actions-system} +因為一切都會經過代理和 actions，任何應用程式都可以由 Slack、Telegram、排程工作、腳本，或透過 A2A 的另一個代理來驅動。 -當代理需要做一些複雜的事情時——呼叫 API、處理資料、查詢資料庫——它會執行一個**操作**。 Actions 是 `actions/` 中的 TypeScript 檔案，匯出預設的 `defineAction()`： +## Actions 系統 {#actions-system} + +當代理需要做一些複雜的事，例如呼叫 API、處理資料或查詢資料庫時，它會執行一個**動作**。Actions 是 `actions/` 中匯出預設 `defineAction()` 的 TypeScript 檔案： ```ts filename="actions/fetch-data.ts" import { defineAction } from "@agent-native/core/action"; @@ -298,19 +332,30 @@ export default defineAction({ }); ``` -一次 `defineAction()` 呼叫將為您提供： +這個 action 會從來源 API 擷取 JSON 並回傳它。`defineAction()` 會用一個 zod schema 包裝這個函式來驗證其輸入（`source`），因此框架可以驗證該輸入、產生代理可以呼叫的 JSON Schema，並為前端 hook 推斷型別，這一切都來自這單一個定義。 + +一次 `defineAction()` 呼叫會自動觸及五種不同的消費者。下圖顯示了單一 action 的扇出；下方的清單則說明每個消費者各自獲得什麼： -- **代理工具** — 代理透過 zod 派生的 JSON 架構看到它並可以呼叫它。 -- **前端鉤子** - `useActionMutation("fetch-data")` 具有完整的 TypeScript 推理。 -- **框架傳輸** - 自動安裝在用戶端掛鉤後面。 -- **CLI** — `pnpm action fetch-data --source=signups` 用於指令碼和代理開發迴圈。 -- **MCP 工具/A2A 工具** — 當啟用 MCP 伺服器或 A2A 時，也會顯示相同的操作。 +```mermaid +graph LR + A[defineAction] --> B[Agent tool] + A --> C[Frontend hook] + A --> D[Framework transport] + A --> E[CLI command] + A --> F[MCP or A2A tool] +``` -相同的邏輯，一個定義，自動連線到每個消費者。請參閱 [Actions](/docs/actions) 取得完整參考。 +- **代理工具：** 代理會透過 zod 衍生的 JSON Schema 看到它，並可以呼叫它。 +- **前端 hook：** `useActionMutation("fetch-data")`，具有完整的 TypeScript 推斷。 +- **框架傳輸：** 自動掛載於用戶端 hooks 之後。 +- **CLI：** `pnpm action fetch-data --source=signups`，用於腳本撰寫和代理開發迴圈。 +- **MCP 工具 / A2A 工具：** 當啟用 MCP 伺服器或 A2A 時，同一個 action 也會出現在那裡。 + +每個消費者都呼叫相同的底層函式，因此只需要撰寫和維護一份實作。完整參考資料請見 [Actions](/docs/actions)。 ## 即時同步 {#polling-sync} -資料庫更改透過`useDbSync()`同步到 UI。同行程透過`/_agent-native/events`寫流； `/_agent-native/poll` 仍然是跨行程和無伺服器的後備方案。當代理寫入資料庫（應用程式狀態、設定或域資料）時，版本計數器會遞增，並且用戶端會使相關的 React 查詢快取無效。 +當代理變更資料時，UI 需要在不手動重新整理的情況下反映出來。`useDbSync()` 就是讓這件事自動發生的機制。同行程的寫入會透過 `/_agent-native/events` 串流；`/_agent-native/poll` 仍然是跨行程和無伺服器情境下的回退方案。當代理寫入資料庫（應用程式狀態、設定或領域資料）時，版本計數器會遞增，用戶端也會讓相關的 React Query 快取失效。 ```ts // Client: subscribe to agent/UI data changes once near the app shell @@ -318,33 +363,37 @@ import { useDbSync } from "@agent-native/core/client/hooks"; useDbSync({ queryClient }); ``` -流程是： +在應用程式的根部附近呼叫一次即可。它會讓整個應用程式訂閱變更事件，因此任何使用 `useActionQuery` 或具有來源版本的 `useQuery` 的元件，都會在其讀取的資料變更時自動重新取得。 + +流程如下： -1. 代理執行寫入資料庫的操作 -2. 伺服器使用 `"action"` 或 `"settings"` 等來源發出更改事件 -3. `useDbSync` 透過 SSE 或輪詢回退接收它 -4. `useActionQuery` 掛鉤和來源版本 `useQuery` 掛鉤重新取得 -5. 元件無需重新載入頁面即可呈現新資料 +1. 代理執行一個會寫入資料庫的 action +2. 伺服器會發出一個變更事件，附帶像 `"action"` 或 `"settings"` 這樣的來源 +3. `useDbSync` 透過 SSE 或輪詢回退接收該事件 +4. `useActionQuery` hooks 和具有來源版本的 `useQuery` hooks 重新取得資料 +5. 元件在不重新載入頁面的情況下渲染新資料 - +下圖從頭到尾追蹤了相同的順序： + + ```html
- Agent 操作
寫入資料庫 + 代理動作
寫入資料庫
- 變更事件
source: action / settings + 變更事件
來源：action / settings
useDbSyncSSE · poll fallback + >SSE · 輪詢回退
- 重新取得查詢
渲染，無需重載 + 查詢重新取得
渲染，無需重新載入
``` @@ -371,88 +420,95 @@ useDbSync({ queryClient }); -這適用於所有部署環境（包括無伺服器和邊緣），因為它使用資料庫，而不是記憶狀態或檔案系統觀察器。 +這在所有部署環境中都能運作，包括無伺服器和邊緣環境，因為它使用資料庫，而不是記憶體內狀態或檔案系統監看器。 -## 框架 {#frames} +## Frames {#frames} -_frame_ 是在您的應用程式旁邊託管代理的環境 - 在本機是嵌入式面板；在雲端端，它是 Builder.io 的託管表面。參見[Frames](/docs/frames)。 +_frame_ 是在你的應用程式旁託管代理的環境。在本機，它是嵌入式面板；在雲端，它是 Builder.io 的託管介面。請參閱 [Frames](/docs/frames)。 -Agent-Native 應用程式包括一個嵌入式代理面板，該面板與應用程式 UI 一起提供 AI 代理。這就是架構發揮作用的原因：代理需要電腦（資料庫、瀏覽器、程式碼執行），而應用程式需要代理來進行 AI 工作。 +Agent-native 應用程式包含一個嵌入式代理面板，會在應用程式 UI 旁邊提供 AI 代理。這正是讓這個架構得以運作的關鍵：代理需要一台電腦（資料庫、瀏覽器、程式碼執行），而應用程式則需要代理來完成 AI 工作。 -- **嵌入式代理面板** - 每個應用程式中內建聊天和可選的 CLI 終端。支援 Claude 程式碼、Codex、Gemini、OpenCode 和 Builder.io。在本機執行。免費且開放原始碼。 -- **雲端** — 透過即時協作、視覺化編輯、角色和權限部署到任何雲端。最適合團隊。 +- **嵌入式代理面板：** 每個應用程式都內建聊天和可選的 CLI 終端機。支援 Claude Code、Codex、Gemini、OpenCode 和 Builder.io。在本機執行，免費且開放原始碼。 +- **雲端：** 部署到任何雲端，具備即時協作、視覺化編輯、角色與權限。最適合團隊使用。 ## 情境感知 {#context-awareness} -代理始終知道使用者在看什麼。 UI 在每次路由更改時將 `navigation` 金鑰寫入應用程式狀態。代理在執行操作之前透過 `view-screen` 操作讀取它。 +代理隨時都知道使用者正在看什麼。UI 會在每次路由變更時，將一個 `navigation` 鍵寫入 application-state。代理會在採取行動之前，透過 `view-screen` action 讀取它。 -例如，當您開啟電子郵件對話串時，UI 會插入一行，例如： +舉例來說，當你開啟一個電子郵件對話串時，UI 會 upsert 一列像這樣的資料： ```json { "key": "navigation", "value": { "view": "thread", "threadId": "th_abc123" } } ``` -UI 在路由變更時寫入此資訊；代理在採取任何操作之前都會讀取它（透過 `view-screen`），因此它始終知道您關注的是哪個對話串 - 或圖表或幻燈片。 + + +UI 會在路由變更時寫入這筆資料；代理會在採取任何行動之前（透過 `view-screen`）讀取它，因此它隨時都知道你正專注於哪個對話串、圖表或投影片。 + + + +完整模式請參閱 [情境意識](/docs/context-awareness)：導覽狀態、view-screen、navigate 指令，以及抖動防止機制。 + +## 一個 action，多個表面 {#protocols} + +將一個領域操作實作為一個 action，只需要一次；框架會將它公開給每一個消費者。同一個 `defineAction()` 會成為代理工具、型別安全的 UI hook、HTTP 端點、CLI 指令、MCP 工具和 A2A 工具，只有在某個表面需要更豐富的互動時，才會加上可選的 `link`、`mcpApp`、原生小工具中繼資料或 Generative UI 包裝器。Skills 和指令則涵蓋行為。 + +完整的協定/表面矩陣（MCP 伺服器與 OAuth、MCP Apps、A2A、深層連結、原生聊天小工具、Generative UI、AgentChatRuntime 連接器、Agent Web，以及 ACP 和 A2UI 的轉接器展望），以及如何選擇產品形態（聊天、行內 UI、完整應用程式頁面、嵌入式 sidecar、自動化，或外部代理存取），請參閱 [Agent 介面](/docs/agent-surfaces)。 + +## 應用程式程式碼與客製化 {#agent-modifies-code} + +框架不會賦予嵌入式代理對應用程式原始碼的環境級存取權限。在已部署的 +應用程式中，代理通常透過 actions、SQL 支援的狀態和已設定的整合來運作。只有當其 +frame 被刻意授予工作區和寫入工具時，它才能編輯元件、路由、 +樣式和 actions。Templates 是完整的應用程式，無論如何你都可以在自己的儲存庫 +和開發流程中 fork 並客製化它們。若要在不變更原始碼的情況下進行執行階段 +客製化，請使用 [Extensions](/docs/extensions)。 + +## 預設具備可移植性 {#hosting-agnostic} + +兩項架構規則讓應用程式能夠跨資料庫和主機移植： + +- **與資料庫無關。** 使用 `@agent-native/core/db/schema` 撰寫結構描述，並使用 Drizzle 的可移植查詢 DSL 進行讀寫，讓相同的程式碼可以在任何支援的提供者上執行。只在附加性遷移或一次性維護時使用原始 SQL，並保持參數化且與方言無關。請參閱 [Database](/docs/database)。 +- **與主機無關。** 伺服器執行於 Nitro 之上，並可編譯為任何部署目標。切勿在伺服器路由或外掛程式中使用 Node 特有的 API（`fs`、`child_process`、`path`），也切勿假設有一個持續存在的伺服器行程。無伺服器和邊緣環境都是無狀態的，因此請將所有狀態保留在 SQL 中。請參閱 [Deployment](/docs/deployment)。 -請參閱 [Context Awareness](/docs/context-awareness) 了解完整模式：導覽狀態、檢視螢幕、導覽指令和抖動預防。 +## 代理資源 {#workspace} -## 一個動作，多個表面 {#protocols} +每位使用者都會獲得一組個人的**代理資源**：指令、skills、記憶、自訂子代理、排程工作，以及已連接的 MCP 伺服器，全部都儲存在 SQL 中而不是檔案裡。這讓 Claude-Code 等級的客製化，得以在多租戶 SaaS 中實現，而不需要為每位使用者啟動一個容器。請參閱 [Agent Resources](/docs/agent-resources)。 -將一個域操作作為一個動作執行一次；此框架將其暴露給每個消費者。相同的 `defineAction()` 成為代理工具、型別安全 UI 掛鉤、HTTP 端點、CLI 指令、MCP 工具和 A2A 工具，並且僅在表面需要時新增可選的 `link`、`mcpApp` 或顯式本機小工具中繼資料。 Skills 和說明涵蓋行為。 +## 相關建置區塊 {#building-blocks} -有關完整的協議/表面矩陣（MCP 伺服器和 OAuth、MCP 應用程式、A2A、深層連結、本機聊天小工具、AgentChatRuntime 連線器、Agent Web 以及 ACP 和 A2UI 的轉接器範圍），以及選取產品形狀（無頭、豐富聊天、嵌入式邊車或完整應用程式），請參閱[Agent Surfaces](/docs/agent-surfaces)。 +以下這些都建立在同一份合約之上，並且各有自己的深入探討： -## 應用程式程式碼與自訂 {#agent-modifies-code} +- **[Dispatch](/docs/dispatch)：** 工作區控制平面，具備共用收件匣、機密保管庫、排程工作，以及一個透過 A2A 委派給專門應用程式的協調器。 +- **[Extensions](/docs/extensions)：** 代理在執行階段建立的沙盒化 Alpine.js 迷你應用程式，不需要變更原始碼或執行遷移。 +- **[A2A 協議](/docs/a2a-protocol)：** 同一個工作區中的應用程式如何透過 JSON-RPC 互相發現並呼叫彼此。 -嵌入式代理預設不會編輯應用程式原始碼。只有當主機有意授予 -repository/workspace 寫入工具時，它才能編輯原始碼。在一般已部署的 -應用程式中，代理透過 actions、SQL 支援的狀態和已設定的整合來工作。 -Templates 是完整的應用程式，您可以在自己的程式碼庫和開發流程中 fork -並自訂它們。 +## 接下來呢 {#deep-dives} -## 預設為便攜式 {#hosting-agnostic} + -兩條架構規則使應用程式可以跨資料庫和主機移植： +### [什麼是 Agent-Native？](/docs/what-is-agent-native) -- **與資料庫無關。** 使用 `@agent-native/core/db/schema` 寫入模式並使用 Drizzle 的可移植查詢 DSL 進行讀/寫，因此相同的程式碼可以在任何支援的提供者上執行。僅將原始 SQL 用於附加遷移或一次性維護，保持參數化且與方言無關。參見[Database](/docs/database)。 -- **與主機無關。** 伺服器在 Nitro 上執行並編譯為任何部署目標。切勿在伺服器路由或外掛中使用特定於節點的 API（`fs`、`child_process`、`path`），並且切勿假設持久伺服器行程 - 無伺服器和邊緣是無狀態的，因此將所有狀態保留在 SQL 中。參見[Deployment](/docs/deployment)。 +這些規則背後的願景與理念。 -## 工作區 {#workspace} +### [情境意識](/docs/context-awareness) -每個使用者都會獲得一個個人**工作空間** - 指令、skills、記憶、自訂子代理、計畫作業和連線的 MCP 伺服器 - 全部儲存在 SQL 而不是檔案中。這使得 Claude 程式碼級定制可以在多租戶 SaaS 中實現，而無需為每個使用者啟動一個容器。參見[代理資源](/docs/agent-resources)。 +深入探討導覽狀態、view-screen 和 navigate 指令。 -## 相關建置塊 {#building-blocks} +### [Skills指南](/docs/skills-guide) -這些位於同一個合約之上，並且有自己的深入研究： +框架 skills、領域 skills，以及建立自訂 skills。 -- **[Dispatch](/docs/dispatch)** — 工作區控制平面：共用收件箱、機密庫、計畫作業以及透過 A2A 委托給專業應用程式的編排器。 -- **[Extensions](/docs/extensions)** — 代理在執行時建立的沙盒 Alpine.js 迷你應用，無需更改來源或遷移。 -- **[資料程式](/docs/data-programs)** — 由 agent 撰寫並儲存的 `run-code` 腳本，為 dashboard 面板提供快取的、可更新的結果，而非硬編碼的 provider action。 -- **[A2A Protocol](/docs/a2a-protocol)** — 同一工作區中的應用如何透過 JSON-RPC 發現並相互呼叫。 +### [原生聊天 UI](/docs/native-chat-ui) -## 您免費獲得的東西 {#what-you-get-for-free} +以 action 宣告的表格、圖表，以及自帶執行環境（BYO）的姿態。 -采用此框架很有價值，主要是因為您不再需要建置什麼。一旦您的應用遵循這五個規則，您就繼承了： +### [Agent 介面](/docs/agent-surfaces) -- **一個操作 = 每個表面。** 使用 `defineAction()` 定義的每個操作同時是一個代理工具、型別安全前端掛鉤 (`useActionQuery` / `useActionMutation`)、框架擁有的 HTTP 傳輸、CLI 指令、用於外部用戶端的 MCP 工具以及用於其他 Agent-Native 應用程式的 A2A 工具。可選的 `link` 和 `mcpApp` 中繼資料新增深層連結和 MCP 應用 UI，無需第二次實現。 -- **每個使用者一個完整的工作區。** Skills、共用 `LEARNINGS.md`、個人 `memory/MEMORY.md`、`AGENTS.md`、自訂子代理、計畫作業、連線的 MCP 伺服器 — 所有 SQL 支援，無需開發盒。參見[代理資源](/docs/agent-resources)。 -- **插入 React 元件。** `` 和 `` 在應用程式中的任何位置呈現聊天 + 工作區。參見[Drop-in Agent](/docs/drop-in-agent)。 -- **BYO 代理聊天執行時。** 相同的聊天 UI 可以位於 OpenAI 代理、OpenAI 回應、Claude 代理 SDK、Vercel AI SDK、AG-UI 或您自己的規範化 HTTP 流之上。參見[Native 聊天介面](/docs/native-chat-ui#byo-agent-runtimes)。 -- **代理和 UI 之間的即時同步。**同一行程立即透過 `/_agent-native/events` 寫入流；輕量級輪詢使無伺服器、cron 和跨行程寫入保持收斂。改變 actions 會自動使操作支援的查詢失效，因此無需手動重新整理即可顯示代理建立的紀錄。請參閱下面的 [Live Sync](#polling-sync)。 -- **Auth、orgs、RBAC。** 每個範本都內建了帶有 orgs/members/roles 的更好的驗證。參見[Authentication](/docs/authentication)。 -- **脈絡感知。**代理始終透過 `navigation` 應用狀態鍵了解使用者正在檢視的內容。參見[Context Awareness](/docs/context-awareness)。 -- **MCP 用戶端 + 伺服器，雙向。** 應用程式攝取 MCP 伺服器（本機、遠端、集線器共用）*並且*將其自己的 actions 公開為 MCP 伺服器。請參閱 [MCP Clients](/docs/mcp-clients) 和 [MCP Protocol](/docs/mcp-protocol)。 -- **應用程式間委托。**不同應用程式中的代理透過 [A2A](/docs/a2a-protocol) 進行通信。同來源部署跳過 JWT；跨域使用共用的`A2A_SECRET`。 -- **子代理團隊。** 產生一個具有自己的對話串和工具的子代理，以聊天中行內的標籤形式出現。參見[Agent Teams](/docs/agent-teams)。 -- **可移植性。**任何 Drizzle 支援的 SQL 資料庫、任何 Nitro 相容的主機（Node、Workers、Netlify、Vercel、Deno、Lambda、Bun）。 +聊天、原生行內 UI、完整應用程式頁面、嵌入式 sidecar、自動化，以及外部代理路徑。 -這就是“以及其他所有東西”，否則你需要自己將它們粘合在一起。 +### [A2A 協議](/docs/a2a-protocol) -## 下一步 {#deep-dives} +代理與代理之間的通訊。 -- [**What Is Agent-Native?**](/docs/what-is-agent-native) — 這些規則背後的願景和理念 -- [**Context Awareness**](/docs/context-awareness) — 深入了解導覽狀態、view-screen 和 navigate 指令 -- [**Skills Guide**](/docs/skills-guide) — 框架 skills、領域 skills 以及建立自訂 skills -- [**Native Chat UI**](/docs/native-chat-ui) — action 宣告的表格、圖表和自備執行階段支援 -- [**Agent Surfaces**](/docs/agent-surfaces) — 聊天、原生行內 UI、完整應用頁面、嵌入式 sidecar、自動化和外部代理路徑 -- [**A2A Protocol**](/docs/a2a-protocol) — 代理間通訊 +