From aa492e143789faaa1558f880e99318237ff5dbbf Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Mon, 3 Aug 2026 15:47:07 -0700 Subject: [PATCH 1/5] docs: update Agent Surfaces doc --- packages/core/docs/content/agent-surfaces.mdx | 603 +++++++++--------- packages/docs/app/components/docsNavItems.ts | 2 +- 2 files changed, 314 insertions(+), 291 deletions(-) diff --git a/packages/core/docs/content/agent-surfaces.mdx b/packages/core/docs/content/agent-surfaces.mdx index 009d9aff4c..751f98b408 100644 --- a/packages/core/docs/content/agent-surfaces.mdx +++ b/packages/core/docs/content/agent-surfaces.mdx @@ -6,73 +6,13 @@ search: "agentic app rich chat native chat UI full app automation headless BYO a # Agent Surfaces -Agent-Native is deliberately composable. Most apps start with chat, add actions, -render structured results inline, and then grow durable pages around the same -SQL state. The same action surface can also power embedded sidecars, -automation-first jobs, external agents, and custom chat runtimes. - -The useful way to choose is not by protocol first. Choose the product surface -you want, then use the matching primitive. New here? Read -[Key Concepts](/docs/key-concepts) first — it defines the actions, SQL, and -agent-loop vocabulary this page assumes. - -| Surface | Use it when | Start with | -| ----------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **Rich chat on Agent-Native** | You want a standalone or embedded chat backed by the built-in agent loop. | [Chat template](/docs/template-chat), ``, `` | -| **Native inline UI** | Action results should render as first-party tables, charts, cards, approvals, or compact reports in chat. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer`, data widget helpers | -| **Generated inline UI** | The agent should create temporary or reusable controls, pickers, calculators, or visualizers inside chat. | [Generative UI](/docs/generative-ui), `render-inline-extension`, `create-extension` | -| **Full application** | Humans and agents should share durable screens, data, navigation, and collaboration. | Templates, actions, SQL state, context awareness | -| **Embedded sidecar** | You already have a SaaS app and want an agent beside it with page context and host commands. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **Automation-first app** | Jobs, scripts, another app, or another agent should call the work directly without a browser UI. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Rich chat on your agent** | You built the agent elsewhere and want Agent-Native's composer, transcript, tool cards, and native widgets. | `AgentChatRuntime`, `` | - -Those are stages and deployment shapes, not separate products. A workflow can -start in chat, appear as a native table or chart, become a durable page in the -app, and still run from jobs, scripts, MCP, or A2A without changing the operation -the agent calls. - -## Full-page Manage Agent {#agent-page} - -When a full application needs a durable place to inspect and configure its -agent, mount `AgentTabsPage` at `/agent`. Current templates pair that route -with an app-navigation entry and pass `agentPageHref="/agent"` to -`AgentSidebar`; the sidebar's Resources and Settings modes can then link to the -full page without duplicating those flows. +A **surface** is the way users (or other systems) interact with your app: a chat window, a dashboard page, a background job, an API call from another agent. Agent-Native lets you mix and match these without rebuilding your core logic, because every surface runs the same underlying actions. If you're new to Agent-Native, read [Key Concepts](/docs/key-concepts) first. -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` +## How surfaces relate to each other -The shared page currently provides twelve tabs across two groups: +The four main product shapes sit on a spectrum from most interactive to fully headless. What makes them composable is that the foundation stays the same throughout: the same actions, the same SQL database, and the same agent loop power every shape. Adding a new surface doesn't mean rewriting what's underneath — you're just adding a new way to reach the same operations. -| Group | Tab | Shows | -| --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Resources | **Files** | The existing `ResourcesPanel` for personal or organization files | -| Resources | **Instructions** | Always-on AGENTS.md-style rules | -| Resources | **Agents** | Custom sub-agent profiles | -| Resources | **Memory** | Long-term recall notes | -| Resources | **Skills** | Reusable workflows | -| Resources | **Learnings** | Corrections and patterns captured over time | -| Resources | **Remote agents** | A2A connections to other agent-native apps — this replaces what the Connections tab used to also show | -| Agent | **Snapshots** | A scope preview, token budget, ordered system sections grouped by provenance/governance/source, and the latest live-thread snapshot. Renamed from "Context"; old `#context` links redirect here. | -| Agent | **Connections** | MCP server management only | -| Agent | **Automations** | Personal and organization Scheduled/Event automations with pause/resume, details, and delete flows. The stable compatibility URL remains `/agent#jobs`. | -| Agent | **Settings** | Agent model, API keys, limits, voice, and automation settings | -| Agent | **Access** | The app MCP URL, an A2A agent card when available, and shared setup guides for Claude, ChatGPT, Cursor, Claude Code, Codex, and other clients. Links to `/mcp/connect` for the full connect flow and token fallback. | - -The page currently shows personal (`user`-scope) data only — there is no -page-level Personal/Organization toggle today. The design goal is inspectable, -attributable, governable context, with capability separated from access: -Connections describes what the app can call; Access describes how external -clients connect to it. The page is a thin shell over existing components, -actions, and access checks—not a new admin console. An organization-scoped -view, grants, scope editing, revocation UI, and per-iteration provenance -history are not provided by this page yet. - - + ```html
@@ -130,176 +70,19 @@ history are not provided by this page yet. -## Automation-first app {#headless} - -Use the automation-first path when no one needs a custom browser screen while -the work runs: scheduled jobs, integrations, backend workflows, CLI loops, -another agent, or an existing product calling into Agent-Native. - -This is the shape to reach for when automation is the product surface. You send -a request from the terminal, Slack, email, a scheduled job, another agent, or -Chat — "summarize my unread emails," "post the daily metrics to Slack," "find -the candidates who replied last week" — and the agent acts and returns the -result wherever it belongs. It is still a real app, not a stateless prompt: -actions, auth sessions, app state, thread/run history, settings, credentials, -and share records all live in SQL. - -Pick this pattern when: - -- **The work happens in the background.** Most of the value is created while the user isn't looking — triage agents, daily-report agents, on-call responders. -- **The output leaves the app.** The agent posts to Slack, sends email, or updates a third-party system; there's nothing to browse in-app. -- **The domain is one-shot.** Research bot, summary generator, report writer — no persistent object that needs a list view. -- **You're prototyping an automation.** Ship the operation now; add chat or app pages when users need to inspect and steer it. - -If your product is built around persistent objects users browse, pivot, and -share — emails, events, documents, charts — pick a [full application](#full-application) -or a [template](/docs/cloneable-saas) instead; those add a full UI _plus_ the agent. - -### What ships in the box {#in-the-box} - -An automation-first app skips dashboard work, and it is channel-agnostic from -day one — the same agent runs from the web, Slack, Telegram, email, and other -agents because everything goes through the same actions. The trade-off is there -is no "browse-everything-at-a-glance" view; if users need that, start from -[Chat](/docs/template-chat) or add a small status page or list view. - -When you add the built-in Chat shell, the framework provides five management -surfaces you don't have to build: **Chat** (the main input), **Resources** -(skills, memory, instructions, sub-agents, and connected MCP servers), -**Automations**, **Thread history**, and **Settings**. Those are usually enough -— talk to it, see what it's done, configure how it behaves. Reach for -[Chat](/docs/template-chat) when you're ready to add that browser UI, or the -[Dispatch template](/docs/template-dispatch) for a workspace-style starting -point with Slack/Telegram, scheduled jobs, and shared secrets out of the box. - -The smallest no-browser local path is a scaffold plus one action: - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -Then define the durable operation: - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -One action is then callable as: - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **App-agent CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts -- **A2A** — from another agent-native app or agent peer -- **UI** — through `useActionQuery`, `useActionMutation`, or `callAction` -- **Agent tool** — from the built-in chat loop - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. To call it from an external system with a long-lived bearer token, see [HTTP API](/docs/http-api). - - - -This is not a no-database or stateless mode. The app-agent loop stores sessions, -threads, runs, settings, credentials, application state, and share records in -SQL. Local development defaults to SQLite; hosted automation-first apps should -use a persistent SQL database. - -If you need the whole agent loop headlessly from the project folder, use: - -```bash -pnpm agent "Summarize this week's forms." -``` - -If another app or script needs to call the whole agent, use -`agentNative.invoke("analytics", "...")` or the `agent-native invoke` CLI. That -keeps cross-app work on the A2A path while local work stays on actions. - -Workers, jobs, integration webhooks, and custom hosts can drive the agent loop -directly through the server API. This is lower-level than actions — you provide -the engine, model, messages, tools, actions, an event sink, and an abort signal -yourself: - -```ts -import { runAgentLoop } from "@agent-native/core/server"; +## Choose a starting point -await runAgentLoop({ - engine, - model, - systemPrompt, - tools, - actions, - messages, - send, - signal, -}); -``` - -For most apps, scheduled prompts and integration webhooks already call this loop -for you. Reach for it directly only when building a custom no-browser host, eval -runner, or server-side orchestration surface — see [Server — Production agent -handler](/docs/server#agent-handler) for the full signature. - -### Running against a folder {#folder-loop} +Chat is the most common entry point. Apps typically grow inline UI as output gets richer, then add full app pages when users need persistent objects to browse and share. The same actions power the buttons, scheduled jobs, and external agents that come later. Use the Embedded sidecar when adding an agent to a product you already own, or Automation-first for work that runs without a browser. Here's the full picture: -If your goal is "run an agent against this folder," start with the app-agent -loop in that folder: scaffold the automation-first app, add actions/instructions, run -`pnpm agent "..."`. That keeps the work inside the same action/runtime/state -contract the app will use in production. - -External coding harnesses are a separate product surface for embedding Claude -Code, Codex, Pi, Cursor, Mastra, or similar runtimes inside an Agent-Native app. -Use them when you are building a coding-agent product, not as the default way to -start a local agent-native workflow. - -### Cloud repo access {#cloud-repo-access} - -For cloud automation-first apps that need repository access, use the GitHub connector -plus token CRUD model: list repositories, search files, read files, create or -edit files, delete files, and revoke access through provider-scoped -credentials. In local development, set the target repository explicitly: - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -Do not treat a VM clone or long-lived sandbox checkout as the primary cloud -repo-access model. Sandboxes still matter for isolated code execution, but -repository access should be explicit, permissioned, auditable, and revocable -through the connector layer. - -### Sharing sessions and runs {#sharing-runs} - -Automation-first sessions and runs are durable objects. Shareability should be -phased: read/share links first, so teammates can inspect sanitized prompts, -outputs, and run status; permissioned writable collaboration later, so -continuing a run, approving actions, editing schedules, or changing -configuration goes through explicit access checks. +| Surface | Use it when | Start with | +| --- | --- | --- | +| **[Rich chat](#rich-chat)** | Users talk to the agent, see tool calls, and keep a thread history. | [Chat template](/docs/template-chat), `` | +| **[Native inline UI](#native-inline-ui)** | Action results should render as tables, charts, cards, or approvals in chat. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[Generated inline UI](#generated-inline-ui)** | The agent should create temporary or reusable controls inside chat on the fly. | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[Full application](#full-application)** | Users need durable screens, shared data, navigation, and collaboration. | Templates, actions, SQL state, context awareness | +| **[Embedded sidecar](#embedded-sidecar)** | You already have a SaaS app and want an agent beside it with page context. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[Automation-first](#headless)** | Jobs, scripts, or other agents call the work directly with no browser UI. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[Rich chat on your agent](#byo-agent)** | You built the agent elsewhere and want Agent-Native's chat UI around it. | `AgentChatRuntime`, `` | ## Rich chat on Agent-Native {#rich-chat} @@ -382,39 +165,99 @@ React widget, use [Generative UI](/docs/generative-ui): it renders sandboxed Alpine/Tailwind UI inline, can read app state and slot context, and can send selected values back to chat. -## Rich chat on your agent {#byo-agent} +## Native inline UI {#native-inline-ui} -Use this path when your agent is already built with another framework or -runtime and you want Agent-Native's chat UI around it. `AgentChatRuntime` is the -boundary: your runtime streams normalized events, and Agent-Native renders the -composer, transcript, tool calls, approvals, native widgets, and app layout. +Use this when your actions return structured data — a list of records, a chart dataset, a status summary — that should render as a real UI component inside the chat thread rather than a plain text description. You define a `chatUI` renderer on the action, and Agent-Native renders it as a first-party React component: no iframes, no separate rendering path. -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +This is the right choice when the output has a clear, reusable shape that you'd design once and use across many agent responses. For controls the agent needs to create dynamically at runtime, see [Generated inline UI](#generated-inline-ui) instead. -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +See [Native Chat UI](/docs/native-chat-ui) for the full renderer API, widget library, and BYO agent runtime integration. -export function SupportAgentChat() { - return ; +## Generated inline UI {#generated-inline-ui} + +Use this when the agent needs to create a control that doesn't exist yet as a pre-built widget — a custom form, a picker built around the current context, a one-off calculator. Unlike native widgets, generated UI is composed by the agent at runtime from Alpine.js and Tailwind, runs sandboxed in an iframe, and can send selected values back into the chat thread. + +Generated UI can be transient (rendered once and discarded) or saved as a reusable extension that persists for the user. + +See [Generative UI](/docs/generative-ui) for the full API, sandbox constraints, and extension persistence model. + +## Full application {#full-application} + +Use the full app path when users need durable objects and workflows: forms, +dashboards, calendars, inboxes, editors, documents, assets, or reports. + +Full apps add product UI around the same action and agent contract: + + + +### SQL state + +App data, navigation, settings, and chat history are all durable. The agent reads and writes the same rows the UI does. + +### Context awareness + +The agent knows the current route, selection, and focused object, so "edit this" always means the right thing. + +### Live sync + +Agent changes update the UI in real time, and UI changes update the agent's context. No polling, no refresh. + +### Deep links + +Action results can open the right app view directly: a chart links to the dashboard, a draft links to the inbox. + +### Native chat widgets + +Tables, charts, cards, approvals, and typed results render as first-party React components inline in chat. + +### Generative UI and extensions + +The agent can create inline controls on the fly, and save reusable mini-apps when a workflow needs to persist. + + + +Start from the [Chat template](/docs/template-chat) when you want a minimal app +around your actions, or from a domain [template](/docs/cloneable-saas) when you +want a complete product shape. + +### Full-page Manage Agent {#agent-page} + +Every Agent-Native app eventually needs a place where users can configure their agent: set standing instructions, review what it's done, connect MCP servers, manage automations, and control access. Building that UI from scratch is a lot of work. Agent-Native ships a pre-built full-page component, `AgentTabsPage`, that covers all of it across twelve tabs. + +Mount it at `/agent` in your app. Current templates pair that route with an app-navigation entry and pass `agentPageHref="/agent"` to `AgentSidebar`, so the sidebar's Resources and Settings modes can link to the full page without duplicating those flows. + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -Ready-made runtime helpers exist for OpenAI Agents, OpenAI Responses, the Claude -Agent SDK, the Vercel AI SDK, and AG-UI, plus the normalized HTTP runtime above -for any other agent (Mastra, Flue, Eve, LangGraph, or a custom service). ACP is -not the end-user app chat or A2A transport, and Agent-Native does not currently -claim A2UI support. ACP is supported in one specific place — driving a local -coding agent (Gemini CLI, Claude Code, …) through the -[harness layer](/docs/harness-agents#acp), not as the chat runtime here. +The shared page currently provides twelve tabs across two groups: -[Native Chat UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -is the canonical home for the event shapes, the runtime helpers, and `chatUI` -tool-result metadata. Start there when wiring an external agent into the chat. +| Group | Tab | Shows | +| --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | The existing `ResourcesPanel` for personal or organization files | +| Resources | **Instructions** | Always-on AGENTS.md-style rules | +| Resources | **Agents** | Custom sub-agent profiles | +| Resources | **Memory** | Long-term recall notes | +| Resources | **Skills** | Reusable workflows | +| Resources | **Learnings** | Corrections and patterns captured over time | +| Resources | **Remote agents** | A2A connections to other agent-native apps (replaces what the Connections tab used to show) | +| Agent | **Snapshots** | A scope preview, token budget, ordered system sections grouped by provenance/governance/source, and the latest live-thread snapshot. Renamed from "Context"; old `#context` links redirect here. | +| Agent | **Connections** | MCP server management only | +| Agent | **Automations** | Personal and organization Scheduled/Event automations with pause/resume, details, and delete flows. The stable compatibility URL remains `/agent#jobs`. | +| Agent | **Settings** | Agent model, API keys, limits, voice, and automation settings | +| Agent | **Access** | The app MCP URL, an A2A agent card when available, and shared setup guides for Claude, ChatGPT, Cursor, Claude Code, Codex, and other clients. Links to `/mcp/connect` for the full connect flow and token fallback. | + +The page shows personal (`user`-scope) data only. There is no org-level toggle today. It is a thin shell over existing components and access checks, not a new admin console: Connections describes what the app can call; Access describes how external clients connect to it. + +Not yet included: + +- Organization-scoped view +- Grants and scope editing +- Revocation UI +- Per-iteration provenance history ## Embedded sidecar {#embedded-sidecar} @@ -456,6 +299,10 @@ export function AppShell({ children }) { } ``` +### How it connects + +The two pieces work as a bridge: the host app passes page context (current route, selected text, focused object) into `AgentNativeEmbedded`, and the agent sends commands back out through `onNavigate` and `onRefresh`. The server plugin handles identity — it resolves the host session so the agent acts as the right user without a separate login. Nothing in the host app needs to change; the plugin attaches Agent-Native's routes alongside your existing ones. + ```html @@ -518,46 +365,222 @@ export function AppShell({ children }) { See [Embedding SDK](/docs/embedding-sdk) for host auth, database isolation, iframe/picker mode, and lower-level bridge APIs. -## Full application {#full-application} +## Automation-first app {#headless} -Use the full app path when users need durable objects and workflows: forms, -dashboards, calendars, inboxes, editors, documents, assets, or reports. +Use the automation-first path when no one needs a custom browser screen while +the work runs: scheduled jobs, integrations, backend workflows, CLI loops, +another agent, or an existing product calling into Agent-Native. -Full apps add product UI around the same action and agent contract: +This is the shape to reach for when automation is the product surface. You send a request from the terminal, Slack, email, a scheduled job, another agent, or Chat ("summarize my unread emails," "post the daily metrics to Slack," "find the candidates who replied last week") and the agent acts and returns the result wherever it belongs. It is still a real app, not a stateless prompt: +actions, auth sessions, app state, thread/run history, settings, credentials, +and share records all live in SQL. -- **SQL state** — app data, navigation, settings, and chat history are durable. -- **Context awareness** — the agent knows the current route, selection, and focused object. -- **Live sync** — agent changes update the UI, and UI changes update the agent's context. -- **Deep links** — action results can open the right app view. -- **Native chat widgets** — tables, charts, cards, approvals, and typed results appear inline. -- **Generative UI and extensions** — the agent can create inline controls now - and save reusable mini-apps when the workflow needs to persist. +Pick this pattern when: -Start from the [Chat template](/docs/template-chat) when you want a minimal app -around your actions, or from a domain [template](/docs/cloneable-saas) when you -want a complete product shape. +- **The work happens in the background.** Most of the value is created while the user isn't looking: triage agents, daily-report agents, on-call responders. +- **The output leaves the app.** The agent posts to Slack, sends email, or updates a third-party system; there's nothing to browse in-app. +- **The domain is one-shot.** Research bot, summary generator, report writer with no persistent object that needs a list view. +- **You're prototyping an automation.** Ship the operation now; add chat or app pages when users need to inspect and steer it. + +If your product is built around persistent objects users browse, pivot, and share (emails, events, documents, charts), pick a [full application](#full-application) or a [template](/docs/cloneable-saas) instead; those add a full UI _plus_ the agent. + +### What ships in the box {#in-the-box} + +An automation-first app skips dashboard work, and it is channel-agnostic from day one. The same agent runs from the web, Slack, Telegram, email, and other agents because everything goes through the same actions. The trade-off is there is no "browse-everything-at-a-glance" view; if users need that, start from [Chat](/docs/template-chat) or add a small status page or list view. + +When you add the built-in Chat shell, the framework provides five management surfaces you don't have to build: **Chat** (the main input), **Resources** (skills, memory, instructions, sub-agents, and connected MCP servers), **Automations**, **Thread history**, and **Settings**. Those are usually enough: talk to it, see what it's done, configure how it behaves. Reach for +[Chat](/docs/template-chat) when you're ready to add that browser UI, or the +[Dispatch template](/docs/template-dispatch) for a workspace-style starting +point with Slack/Telegram, scheduled jobs, and shared secrets out of the box. + +The smallest no-browser local path is a scaffold plus one action: + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +Then define the durable operation: + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +One action is then callable as: + +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **App-agent CLI:** `pnpm agent "Summarize form_123"` +- **MCP:** from Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, and other MCP hosts +- **A2A:** from another agent-native app or agent peer +- **UI:** through `useActionQuery`, `useActionMutation`, or `callAction` +- **Agent tool:** from the built-in chat loop + + + +Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. To call it from an external system with a long-lived bearer token, see [HTTP API](/docs/http-api). + + + +This is not a no-database or stateless mode. The app-agent loop stores sessions, +threads, runs, settings, credentials, application state, and share records in +SQL. Local development defaults to SQLite; hosted automation-first apps should +use a persistent SQL database. + +If you need the whole agent loop headlessly from the project folder, use: + +```bash +pnpm agent "Summarize this week's forms." +``` + +If another app or script needs to call the whole agent, use +`agentNative.invoke("analytics", "...")` or the `agent-native invoke` CLI. That +keeps cross-app work on the A2A path while local work stays on actions. + +Workers, jobs, integration webhooks, and custom hosts can drive the agent loop +directly through the server API. This is lower-level than actions — you provide +the engine, model, messages, tools, actions, an event sink, and an abort signal +yourself: + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +For most apps, scheduled prompts and integration webhooks already call this loop +for you. Reach for it directly only when building a custom no-browser host, eval +runner, or server-side orchestration surface. See [Server: Production agent handler](/docs/server#agent-handler) for the full signature. + +### Running against a folder {#folder-loop} + +If your goal is "run an agent against this folder," start with the app-agent +loop in that folder: scaffold the automation-first app, add actions/instructions, run +`pnpm agent "..."`. That keeps the work inside the same action/runtime/state +contract the app will use in production. + +External coding harnesses are a separate product surface for embedding Claude +Code, Codex, Pi, Cursor, Mastra, or similar runtimes inside an Agent-Native app. +Use them when you are building a coding-agent product, not as the default way to +start a local agent-native workflow. + +### Cloud repo access {#cloud-repo-access} + +For cloud automation-first apps that need repository access, use the GitHub connector +plus token CRUD model: list repositories, search files, read files, create or +edit files, delete files, and revoke access through provider-scoped +credentials. In local development, set the target repository explicitly: + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +Do not treat a VM clone or long-lived sandbox checkout as the primary cloud +repo-access model. Sandboxes still matter for isolated code execution, but +repository access should be explicit, permissioned, auditable, and revocable +through the connector layer. -## How to choose {#how-to-choose} +### Sharing sessions and runs {#sharing-runs} -| If you are thinking... | Choose | -| ---------------------------------------------------------------- | ------------------------- | -| "I want the framework's agent, but chat should be the main UI." | Rich chat on Agent-Native | -| "The action result should be a chart, table, or typed card." | Native inline UI | -| "I want the agent to make an interactive control right now." | Generated inline UI | -| "The agent and UI should evolve together as the product." | Full application | -| "I already have a SaaS app; add an agent beside it." | Embedded sidecar | -| "I need a callable workflow for jobs, scripts, or other agents." | Automation-first app | -| "I already have an agent; I need a polished chat UI for it." | Rich chat on your agent | +Automation-first sessions and runs are durable objects. Shareability should be +phased: read/share links first, so teammates can inspect sanitized prompts, +outputs, and run status; permissioned writable collaboration later, so +continuing a run, approving actions, editing schedules, or changing +configuration goes through explicit access checks. -Keep the contract small: define durable operations as actions, return explicit -widget results when chat needs rich UI, and add full screens only when users -need to browse, compare, configure, or collaborate over persistent objects. +## Rich chat on your agent {#byo-agent} + +Use this path when your agent is already built with another framework or +runtime and you want Agent-Native's chat UI around it. `AgentChatRuntime` is the +boundary: your runtime streams normalized events, and Agent-Native renders the +composer, transcript, tool calls, approvals, native widgets, and app layout. + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` + +Ready-made runtime helpers exist for OpenAI Agents, OpenAI Responses, the Claude +Agent SDK, the Vercel AI SDK, and AG-UI, plus the normalized HTTP runtime above +for any other agent (Mastra, Flue, Eve, LangGraph, or a custom service). ACP is +not the end-user app chat or A2A transport, and Agent-Native does not currently +claim A2UI support. ACP is supported in one specific place: driving a local +coding agent (Gemini CLI, Claude Code, …) through the +[harness layer](/docs/harness-agents#acp), not as the chat runtime here. + +[Native Chat UI: BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) +is the canonical home for the event shapes, the runtime helpers, and `chatUI` +tool-result metadata. Start there when wiring an external agent into the chat. ## What's next {#related-docs} -- [**Actions**](/docs/actions) — define the operation once; every surface above calls the same one -- [**Native Chat UI**](/docs/native-chat-ui) — render typed action results as tables, charts, and cards in chat -- [**Generative UI**](/docs/generative-ui) — generate transient or persisted sandboxed UI inline in chat -- [**Automation-First Apps**](/docs/pure-agent-apps) — the full no-browser pattern for jobs, queues, scripts, and external agents -- [**External Agents**](/docs/external-agents) — connect MCP-compatible hosts to an app -- [**A2A Protocol**](/docs/a2a-protocol) — call agents from other agent-native apps + + +### [Actions](/docs/actions) + +Define the operation once. Every surface above calls the same one. + +### [Native Chat UI](/docs/native-chat-ui) + +Render typed action results as tables, charts, and cards directly in chat. + +### [Generative UI](/docs/generative-ui) + +Generate transient or persisted sandboxed UI inline in chat. + +### [Automation-First Apps](/docs/pure-agent-apps) + +The full no-browser pattern for jobs, queues, scripts, and external agents. + +### [External Agents](/docs/external-agents) + +Connect MCP-compatible hosts to your app as a tool server. + +### [A2A Protocol](/docs/a2a-protocol) + +Call agents from other agent-native apps over the A2A standard. + + diff --git a/packages/docs/app/components/docsNavItems.ts b/packages/docs/app/components/docsNavItems.ts index e1c1148817..1880ce73e8 100644 --- a/packages/docs/app/components/docsNavItems.ts +++ b/packages/docs/app/components/docsNavItems.ts @@ -60,12 +60,12 @@ const NAV_SECTION_CONFIG: NavSectionConfig[] = [ labelKey: "whatIsAgentNative", slug: "what-is-agent-native", }, + { id: "key-concepts", labelKey: "keyConcepts", slug: "key-concepts" }, { id: "agent-surfaces", labelKey: "agentSurfaces", slug: "agent-surfaces", }, - { id: "key-concepts", labelKey: "keyConcepts", slug: "key-concepts" }, { id: "cloneable-saas", labelKey: "templatesOverview", From 62e4e797aa473787b64c034571d98f99817564f4 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Mon, 3 Aug 2026 16:34:58 -0700 Subject: [PATCH 2/5] update to pass checks --- .changeset/agent-surfaces.md | 5 +++ packages/core/docs/content/agent-surfaces.mdx | 18 ++++---- scripts/i18n-localized-docs-baseline.txt | 42 +++++++++++++++++++ 3 files changed, 56 insertions(+), 9 deletions(-) create mode 100644 .changeset/agent-surfaces.md diff --git a/.changeset/agent-surfaces.md b/.changeset/agent-surfaces.md new file mode 100644 index 0000000000..c533df2813 --- /dev/null +++ b/.changeset/agent-surfaces.md @@ -0,0 +1,5 @@ +--- +"@agent-native/core": patch +--- + +Restructure agent-surfaces doc to match table order, add Native inline UI and Generated inline UI sections diff --git a/packages/core/docs/content/agent-surfaces.mdx b/packages/core/docs/content/agent-surfaces.mdx index 751f98b408..71fa65dee5 100644 --- a/packages/core/docs/content/agent-surfaces.mdx +++ b/packages/core/docs/content/agent-surfaces.mdx @@ -74,15 +74,15 @@ The four main product shapes sit on a spectrum from most interactive to fully he Chat is the most common entry point. Apps typically grow inline UI as output gets richer, then add full app pages when users need persistent objects to browse and share. The same actions power the buttons, scheduled jobs, and external agents that come later. Use the Embedded sidecar when adding an agent to a product you already own, or Automation-first for work that runs without a browser. Here's the full picture: -| Surface | Use it when | Start with | -| --- | --- | --- | -| **[Rich chat](#rich-chat)** | Users talk to the agent, see tool calls, and keep a thread history. | [Chat template](/docs/template-chat), `` | -| **[Native inline UI](#native-inline-ui)** | Action results should render as tables, charts, cards, or approvals in chat. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | -| **[Generated inline UI](#generated-inline-ui)** | The agent should create temporary or reusable controls inside chat on the fly. | [Generative UI](/docs/generative-ui), `render-inline-extension` | -| **[Full application](#full-application)** | Users need durable screens, shared data, navigation, and collaboration. | Templates, actions, SQL state, context awareness | -| **[Embedded sidecar](#embedded-sidecar)** | You already have a SaaS app and want an agent beside it with page context. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **[Automation-first](#headless)** | Jobs, scripts, or other agents call the work directly with no browser UI. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | -| **[Rich chat on your agent](#byo-agent)** | You built the agent elsewhere and want Agent-Native's chat UI around it. | `AgentChatRuntime`, `` | +| Surface | Use it when | Start with | +| ----------------------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------------------- | +| **[Rich chat](#rich-chat)** | Users talk to the agent, see tool calls, and keep a thread history. | [Chat template](/docs/template-chat), `` | +| **[Native inline UI](#native-inline-ui)** | Action results should render as tables, charts, cards, or approvals in chat. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[Generated inline UI](#generated-inline-ui)** | The agent should create temporary or reusable controls inside chat on the fly. | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[Full application](#full-application)** | Users need durable screens, shared data, navigation, and collaboration. | Templates, actions, SQL state, context awareness | +| **[Embedded sidecar](#embedded-sidecar)** | You already have a SaaS app and want an agent beside it with page context. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[Automation-first](#headless)** | Jobs, scripts, or other agents call the work directly with no browser UI. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[Rich chat on your agent](#byo-agent)** | You built the agent elsewhere and want Agent-Native's chat UI around it. | `AgentChatRuntime`, `` | ## Rich chat on Agent-Native {#rich-chat} diff --git a/scripts/i18n-localized-docs-baseline.txt b/scripts/i18n-localized-docs-baseline.txt index 64a2270ec9..98fb285e15 100644 --- a/scripts/i18n-localized-docs-baseline.txt +++ b/scripts/i18n-localized-docs-baseline.txt @@ -1,6 +1,11 @@ # Existing localized docs strings that still match English source. # Keep this file sorted. Remove entries as translated docs improve. # Format: relative/localized/path.md|English source string +packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/ar-SA/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/ar-SA/frames.mdx|type: \"code\" packages/core/docs/content/locales/ar-SA/messaging.mdx|Microsoft Teams @@ -15,6 +20,10 @@ packages/core/docs/content/locales/ar-SA/toolkit-capability-packages.mdx|Creativ packages/core/docs/content/locales/ar-SA/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/ar-SA/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. packages/core/docs/content/locales/ar-SA/what-is-agent-native.mdx|Agent Surfaces +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/de-DE/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/de-DE/frames.mdx|type: \"code\" packages/core/docs/content/locales/de-DE/messaging.mdx|Microsoft Teams @@ -27,6 +36,10 @@ packages/core/docs/content/locales/de-DE/template-forms.mdx|"add an NPS question packages/core/docs/content/locales/de-DE/template-slides.mdx|"10-slide pitch deck" packages/core/docs/content/locales/de-DE/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/de-DE/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. +packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/es-ES/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/es-ES/frames.mdx|type: \"code\" packages/core/docs/content/locales/es-ES/messaging.mdx|Microsoft Teams @@ -40,6 +53,10 @@ packages/core/docs/content/locales/es-ES/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/es-ES/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/es-ES/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/es-ES/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. +packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/fr-FR/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/fr-FR/frames.mdx|type: \"code\" packages/core/docs/content/locales/fr-FR/messaging.mdx|Microsoft Teams @@ -54,6 +71,10 @@ packages/core/docs/content/locales/fr-FR/toolkit-capability-packages.mdx|Creativ packages/core/docs/content/locales/fr-FR/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/fr-FR/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. packages/core/docs/content/locales/fr-FR/what-is-agent-native.mdx|Agent Surfaces +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/hi-IN/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/hi-IN/frames.mdx|type: \"code\" packages/core/docs/content/locales/hi-IN/messaging.mdx|Microsoft Teams @@ -77,6 +98,10 @@ packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|Team-wide rule packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|Tool surface packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|Typed contract packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|`/slash` commands +packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/ja-JP/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/ja-JP/frames.mdx|type: \"code\" packages/core/docs/content/locales/ja-JP/messaging.mdx|Microsoft Teams @@ -90,6 +115,11 @@ packages/core/docs/content/locales/ja-JP/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/ja-JP/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/ja-JP/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/ja-JP/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. +packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|SQL state packages/core/docs/content/locales/ko-KR/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/ko-KR/frames.mdx|type: \"code\" packages/core/docs/content/locales/ko-KR/messaging.mdx|Microsoft Teams @@ -104,6 +134,10 @@ packages/core/docs/content/locales/ko-KR/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/ko-KR/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/ko-KR/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/ko-KR/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. +packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/pt-BR/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/pt-BR/frames.mdx|type: \"code\" packages/core/docs/content/locales/pt-BR/messaging.mdx|Microsoft Teams @@ -117,6 +151,10 @@ packages/core/docs/content/locales/pt-BR/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/pt-BR/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/pt-BR/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/pt-BR/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. +packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/zh-CN/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/zh-CN/frames.mdx|type: \"code\" packages/core/docs/content/locales/zh-CN/messaging.mdx|Microsoft Teams @@ -130,6 +168,10 @@ packages/core/docs/content/locales/zh-CN/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/zh-CN/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/zh-CN/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/zh-CN/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. +packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|Generative UI packages/core/docs/content/locales/zh-TW/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/zh-TW/frames.mdx|type: \"code\" packages/core/docs/content/locales/zh-TW/messaging.mdx|Microsoft Teams From de0eb9ce68cfff14c2b1ca72d5399dc6e0c5a9c8 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Tue, 4 Aug 2026 15:17:35 -0700 Subject: [PATCH 3/5] add translations --- .../content/locales/ar-SA/agent-surfaces.mdx | 647 +++++++++-------- .../content/locales/de-DE/agent-surfaces.mdx | 661 +++++++++-------- .../content/locales/es-ES/agent-surfaces.mdx | 653 +++++++++-------- .../content/locales/fr-FR/agent-surfaces.mdx | 651 +++++++++-------- .../content/locales/hi-IN/agent-surfaces.mdx | 600 ++++++++-------- .../content/locales/ja-JP/agent-surfaces.mdx | 595 ++++++++-------- .../content/locales/ko-KR/agent-surfaces.mdx | 655 +++++++++-------- .../content/locales/pt-BR/agent-surfaces.mdx | 602 ++++++++-------- .../content/locales/zh-CN/agent-surfaces.mdx | 589 ++++++++-------- .../content/locales/zh-TW/agent-surfaces.mdx | 664 +++++++++--------- scripts/i18n-localized-docs-baseline.txt | 54 +- scripts/template-standard-baseline.json | 60 -- 12 files changed, 3304 insertions(+), 3127 deletions(-) diff --git a/packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx b/packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx index 6e341d6c79..521b684c68 100644 --- a/packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx @@ -1,83 +1,39 @@ --- -title: "أسطح الوكيل" -description: "استخدم Agent-Native بشكل مستقل، كدردشة غنية، داخل تطبيق موجود، أو كتطبيق أصلي كامل للوكيل." -search: "التطبيق الكامل للدردشة الغنية للوكيل مقطوع الرأس BYO وقت تشغيل الوكيل AgentChatRuntime تضمين actions MCP A2A HTTP CLI" +title: "واجهات الوكيل" +description: "اختر كيف ينمو تطبيق الوكيل من المحادثة إلى واجهة المستخدم المضمّنة، وصفحات التطبيق الدائمة، والشرائط الجانبية المضمّنة، والأتمتة، والوصول الخارجي للوكيل." +search: "تطبيق وكيل محادثة غنية واجهة مستخدم محادثة أصلية تطبيق كامل أتمتة بلا رأس وكيل BYO وقت تشغيل AgentChatRuntime تضمين إجراءات MCP A2A HTTP CLI" --- -# أسطح الوكيل +# واجهات الوكيل -## مساحة عمل Agent الكاملة {#agent-page} +**الواجهة** هي الطريقة التي يتفاعل بها المستخدمون (أو الأنظمة الأخرى) مع تطبيقك: نافذة محادثة، أو صفحة لوحة تحكم، أو مهمة تعمل في الخلفية، أو استدعاء API من وكيل آخر. يتيح لك Agent-Native دمج هذه الواجهات وتنسيقها دون إعادة بناء منطقك الأساسي، لأن كل واجهة تُشغّل نفس الإجراءات الأساسية. إذا كنت جديدًا على Agent-Native، اقرأ [المفاهيم الأساسية](/docs/key-concepts) أولاً. -عندما يحتاج التطبيق الكامل إلى مكان دائم لفحص وكيله وتهيئته، اربط -`AgentTabsPage` بالمسار `/agent`. أضف المسار إلى تنقل التطبيق ومرر -`agentPageHref="/agent"` إلى `AgentSidebar` كي تصل وضعيّتا Resources وSettings -إلى الصفحة الكاملة من دون تكرار التدفقات. +## كيف ترتبط الواجهات ببعضها -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -تحتوي الصفحة المشتركة حاليًا على خمس علامات تبويب: - -- **Context** — معاينة النطاق، وميزانية الرموز، وأقسام النظام المرتبة مع مصدرها وحوكمتها، وعرض القائمة أو الخريطة، وأحدث لقطة للمحادثة الحية. -- **Files** — يعيد استخدام `ResourcesPanel` للموارد الشخصية أو الخاصة بالمؤسسة. -- **Connections** — إدارة خوادم MCP وقائمة الوكلاء البعيدين عبر A2A؛ أي ما يستطيع وكيل التطبيق استدعاءه. -- **Automations** — أتمتة Scheduled وEvent الشخصية وأتمتة المؤسسة مع الإيقاف والاستئناف والتفاصيل والحذف. يبقى عنوان التوافق `/agent#jobs`. -- **Access** — عنوان MCP وبطاقة وكيل A2A عند توفرها وتعليمات إعداد العملاء الخارجيين؛ ويربط بالمسار `/mcp/connect` للتدفق الكامل والرمز الاحتياطي. +تقع الأشكال الأربعة الرئيسية للمنتج على طيف يمتد من الأكثر تفاعلاً إلى الأكثر تجريدًا. ما يجعلها قابلة للتركيب هو أن الأساس يبقى ثابتاً طوال الوقت: نفس الإجراءات، ونفس قاعدة بيانات SQL، ونفس حلقة الوكيل تشغّل كل شكل. إضافة واجهة جديدة لا تعني إعادة كتابة ما هو موجود — بل تضيف فقط طريقة جديدة للوصول إلى نفس العمليات. -تعمل الصفحة حاليًا بالنطاق الشخصي ولا تعرض مفتاح **Personal / Organization** -على مستوى الصفحة. قد تعرض علامة تبويب قدرات محددة بالمؤسسة عندما تدعمها -الإجراءات الأساسية؛ تعرض **Automations** أقسامًا شخصية وأقسام المؤسسة لكل من -Scheduled وEvent. تعمل أتمتة أحداث المؤسسة دائمًا بهوية منشئها. الصفحة غلاف رقيق للمكونات والإجراءات -وفحوصات الوصول الموجودة، وليست لوحة إدارة جديدة. - -Agent-Native قابل للتأليف بشكل متعمد. يمكنك استخدام الوكيل بدون الكثير من UI، -استخدم UI بدون وقت تشغيل الوكيل المضمن، أو استخدمهما معًا بشكل كامل -التطبيق. - -الطريقة المفيدة للاختيار ليست عن طريق البروتوكول أولاً. اختر سطح المنتج -الذي تريده، ثم استخدم البدائية المطابقة. - -| السطح | استخدمه عندما | ابدأ بـ | -| ------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | -| **العميل مقطوع الرأس** | يجب على التعليمات البرمجية أو الوظائف أو البرامج النصية أو تطبيق آخر أو وكيل آخر استدعاء العمل مباشرة. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **دردشة غنية على Agent-Native** | تريد دردشة مستقلة أو مضمنة مدعومة بحلقة الوكيل المضمنة. | [Chat template](/docs/template-chat), ``, `` | -| **دردشة غنية مع وكيلك** | لقد أنشأت الوكيل في مكان آخر وتريد مؤلف Agent-Native والنص وبطاقات الأدوات والأدوات الأصلية. | `AgentChatRuntime`, `` | -| **عربة جانبية مضمنة** | لديك بالفعل تطبيق SaaS وتريد وكيلًا بجانبه يتضمن سياق الصفحة وأوامر المضيف. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **الطلب الكامل** | يجب على البشر والوكلاء مشاركة الشاشات والبيانات والتنقل والتعاون الدائم. | النماذج، actions، حالة SQL، الوعي بالسياق | - -تلك مراحل وليست منتجات منفصلة. يمكن أن يبدأ سير العمل بدون رأس -وكيل بإجراء واحد، يظهر في الدردشة كجدول أو مخطط، ويصبح فيما بعد -ملء الشاشة في التطبيق دون تغيير العملية التي يستدعيها الوكيل. - - + ```html
- مقطوعة الرأسالإجراءات والوظائف والبرامج النصية والوكلاء الآخرين + محادثةمحرر، سجل، استدعاءات الأدوات
- دردشة غنيةالملحن، النص، بطاقات الأدوات + واجهة مستخدم مضمّنةجداول، مخططات، بطاقات
- عربة جانبية مدمجةالوكيل بجانب تطبيق موجود + صفحة التطبيقشاشات دائمة، بيانات SQL
- معظم واجهة المستخدمالتطبيق الكاملشاشات متينة، بيانات، تعاون + headlessأتمتةمهام، نصوص برمجية، وكلاء خارجيون
@@ -114,180 +70,32 @@ Agent-Native قابل للتأليف بشكل متعمد. يمكنك استخد -## عميل بلا رأس {#headless} +## اختر نقطة البداية -استخدم المسار بدون رأس عندما لا يحتاج أحد إلى التحديق في شاشة التطبيق المخصصة أثناء -تشغيل العمل: المهام المجدولة، وعمليات التكامل، وسير عمل الواجهة الخلفية، وحلقات CLI، -وكيل آخر، أو منتج موجود يتصل بـ Agent-Native. +المحادثة هي نقطة الدخول الأكثر شيوعًا. تنمو التطبيقات عادةً لتضم واجهة مستخدم مضمّنة مع ازدياد ثراء المخرجات، ثم تُضاف صفحات تطبيق كاملة عندما يحتاج المستخدمون إلى كائنات دائمة للتصفح والمشاركة. نفس الإجراءات تشغّل الأزرار والمهام المجدولة والوكلاء الخارجيين التي تأتي لاحقًا. استخدم الشريط الجانبي المضمّن عند إضافة وكيل إلى منتج تمتلكه بالفعل، أو الأتمتة أولاً للعمل الذي يعمل بدون متصفح. إليك الصورة الكاملة: -هذا أيضًا هو الشكل الذي يجب الوصول إليه عندما يكون **الوكيل*هو*المنتج** — -حلقة وكيل التطبيق هي الباب الأمامي، وليست لوحة القيادة. قمت بإرسال طلب من -المحطة الطرفية، أو Slack، أو البريد الإلكتروني، أو مهمة مجدولة، أو وكيل آخر، أو الدردشة - "تلخيص -رسائل البريد الإلكتروني غير المقروءة"، "انشر المقاييس اليومية على Slack"، "ابحث عن المرشحين الذين -أجاب الأسبوع الماضي" - ويعمل الوكيل ويعيد النتيجة أينما كانت -ينتمي. لا يزال تطبيقًا حقيقيًا، وليس مطالبة عديمة الحالة: actions، جلسات المصادقة، -حالة التطبيق، وسجل سلسلة المحادثات/التشغيل، والإعدادات، وبيانات الاعتماد، وسجلات المشاركة كلها مباشرة -في SQL. +| الواجهة | استخدمها عندما | ابدأ بـ | +| ------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | +| **[محادثة غنية](#rich-chat)** | يتحدث المستخدمون مع الوكيل، ويرون استدعاءات الأدوات، ويحتفظون بسجل الخيط. | [قالب المحادثة](/docs/template-chat)، `` | +| **[واجهة مستخدم مضمّنة أصلية](#native-inline-ui)** | يجب أن تُعرض نتائج الإجراءات كجداول أو مخططات أو بطاقات أو موافقات في المحادثة. | [واجهة المحادثة الأصلية](/docs/native-chat-ui)، `chatUI.renderer` | +| **[واجهة مستخدم مضمّنة مولَّدة](#generated-inline-ui)** | يجب أن يُنشئ الوكيل عناصر تحكم مؤقتة أو قابلة لإعادة الاستخدام داخل المحادثة أثناء التشغيل. | [واجهة مستخدم توليدية](/docs/generative-ui)، `render-inline-extension` | +| **[تطبيق كامل](#full-application)** | يحتاج المستخدمون إلى شاشات دائمة وبيانات مشتركة وتنقل وتعاون. | القوالب، الإجراءات، حالة SQL، الوعي بالسياق | +| **[شريط جانبي مضمّن](#embedded-sidecar)** | لديك تطبيق SaaS بالفعل وتريد وكيلاً بجانبه مع سياق الصفحة. | `createAgentNativeEmbeddedPlugin()`، `AgentNativeEmbedded` | +| **[الأتمتة أولاً](#headless)** | تستدعي المهام أو النصوص أو الوكلاء الآخرون العمل مباشرة بدون واجهة متصفح. | `agent-native create --headless`، `defineAction`، HTTP، CLI، MCP، A2A | +| **[محادثة غنية على وكيلك](#byo-agent)** | لقد بنيت الوكيل في مكان آخر وتريد واجهة محادثة Agent-Native حوله. | `AgentChatRuntime`، `` | -اختر هذا النمط عندما: +## محادثة غنية على Agent-Native {#rich-chat} -- **يتم العمل في الخلفية.** يتم إنشاء معظم القيمة دون أن يراقب المستخدم — وكلاء الفرز، ووكلاء التقارير اليومية، والمستجيبون عند الطلب. -- **الإخراج يغادر التطبيق.** يقوم الوكيل بالنشر على Slack، أو يرسل بريدًا إلكترونيًا، أو يقوم بتحديث نظام تابع لجهة خارجية؛ لا يوجد شيء لتصفحه داخل التطبيق. -- **المجال عبارة عن طلقة واحدة.** روبوت البحث، ومولد الملخص، وكاتب التقارير — لا يوجد كائن ثابت يحتاج إلى عرض القائمة. -- **أنت تقوم بإعداد النماذج الأولية.** اشحن الوكيل الآن؛ قم بإضافة UI الأكثر ثراءً لاحقًا إذا أراد المستخدمون واحدًا. +استخدم المحادثة المدمجة عندما يجب أن يتحدث المستخدم مع الوكيل، ويرى استدعاءات الأدوات، +ويوافق على العمل، ويفحص النتائج الأصلية، ويحتفظ بسجل خيط دائم. -إذا كان منتجك مبنيًا على كائنات ثابتة يتصفحها المستخدمون ويدورون حولها -المشاركة - رسائل البريد الإلكتروني، والأحداث، والمستندات، والمخططات - اختر [full application](#full-application) -أو [template](/docs/cloneable-saas) بدلاً من ذلك؛ يضيف هؤلاء UI _plus_ الوكيل الكامل. - -### ما الذي يأتي في الصندوق {#in-the-box} - -يتخطى التطبيق بدون مراقبة أسابيع من عمل لوحة التحكم، وهو لا يلتزم بالقناة منذ اليوم -واحد — يتم تشغيل نفس الوكيل من الويب وSlack وTelegram والبريد الإلكتروني والوكلاء الآخرين -لأن كل شيء يمر عبر الوكيل، وليس UI. المقايضة موجودة -لا يوجد عرض "تصفح كل شيء بلمحة سريعة"؛ إذا احتاج المستخدمون إلى ذلك، فامزج الأنماط و -أضف صفحة حالة صغيرة أو عرض قائمة. - -عند إضافة Chat Shell المضمن، يوفر إطار العمل خمس إدارة -الأسطح التي لا يتعين عليك إنشاؤها: **الدردشة** (الإدخال الرئيسي)، **مساحة العمل** -(skills، الذاكرة، التعليمات، الوكلاء الفرعيون، خوادم MCP المتصلة، مجدولة -الوظائف)، **سجل الوظائف**، **سجل سلسلة المحادثات**، و **الإعدادات**. تلك عادة -كافي — تحدث معه، وشاهد ما تم إنجازه، وقم بتكوين كيفية تصرفه. الوصول إلى -[Chat](/docs/template-chat) عندما تكون مستعدًا لإضافة هذا المتصفح UI، أو -[Dispatch template](/docs/template-dispatch) لبدء نمط مساحة العمل -أشر باستخدام Slack/Telegram والمهام المجدولة والأسرار المشتركة خارج الصندوق. - -أصغر مسار محلي هو سقالة وكيل مقطوعة الرأس بالإضافة إلى إجراء واحد: - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -ثم حدد العملية الدائمة: - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -يمكن بعد ذلك استدعاء إجراء واحد كـ: - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **وكيل التطبيق CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — من Claude، وChatGPT، وCodex، وCursor، وOpenCode، وCopilot، ومضيفي MCP الآخرين -- **A2A** — من تطبيق وكيل آخر أو نظير وكيل -- **UI** — من خلال `useActionQuery` أو `useActionMutation` أو `callAction` -- **أداة الوكيل** — من حلقة الدردشة المضمنة - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -هذا ليس وضعًا بلا قاعدة بيانات أو عديم الحالة. تقوم حلقة وكيل التطبيق بتخزين الجلسات -سلاسل المحادثات، وعمليات التشغيل، والإعدادات، وبيانات الاعتماد، وحالة التطبيق، ومشاركة السجلات في -زكسق0قكسز. التطوير المحلي الافتراضي هو SQLite؛ يجب أن تستخدم التطبيقات مقطوعة الرأس المستضافة -قاعدة بيانات SQL المستمرة. - -إذا كنت بحاجة إلى تكرار حلقة الوكيل بالكامل من مجلد المشروع، فاستخدم: - -```bash -pnpm agent "Summarize this week's forms." -``` - -إذا احتاج تطبيق أو برنامج نصي آخر إلى استدعاء الوكيل بالكامل، فاستخدم -`agentNative.invoke("analytics", "...")` أو `agent-native invoke` CLI. ذلك -يحتفظ بالعمل عبر التطبيقات على مسار A2A بينما يظل العمل المحلي على actions. - -يمكن للعمال والوظائف والتكامل webhooks والمضيفين المخصصين قيادة حلقة الوكيل -مباشرة من خلال الخادم API. وهذا مستوى أقل من actions — الذي تقدمه -المحرك والنموذج والرسائل وactions ومخزن الحدث بنفسك: - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -بالنسبة لمعظم التطبيقات، تستدعي المطالبات المجدولة والتكامل webhooks هذه الحلقة بالفعل -لك. يمكنك الوصول إليه مباشرةً فقط عند إنشاء مضيف مخصص بدون رأس، بالتقييم -المشغل، أو سطح التنسيق من جانب الخادم - راجع [الخادم - وكيل الإنتاج -المعالج](/docs/server#agent-handler) للتوقيع الكامل. - -### التشغيل ضد مجلد {#folder-loop} - -إذا كان هدفك هو "تشغيل وكيل ضد هذا المجلد"، فابدأ بوكيل التطبيق -قم بالتكرار في هذا المجلد: قم بتركيب التطبيق بدون رأس، وأضف actions/التعليمات، وقم بتشغيل -`pnpm agent "..."`. وهذا يبقي العمل داخل نفس الإجراء/وقت التشغيل/الحالة -العقد الذي سيستخدمه التطبيق في الإنتاج. - -تعد أدوات الترميز الخارجية بمثابة سطح منتج منفصل لتضمين Claude -الرمز أو Codex أو Pi أو Cursor أو Mastra أو أوقات التشغيل المماثلة داخل تطبيق Agent-Native. -استخدمها عند إنشاء منتج وكيل ترميز، وليس كطريقة افتراضية -ابدأ سير عمل الوكيل المحلي الأصلي. - -### الوصول إلى الريبو السحابي {#cloud-repo-access} - -بالنسبة للتطبيقات السحابية بدون رأس والتي تحتاج إلى الوصول إلى المستودع، استخدم موصل GitHub -نموذج الرمز المميز CRUD: سرد المستودعات أو البحث في الملفات أو قراءة الملفات أو إنشاءها أو -تحرير الملفات، وحذف الملفات، وإبطال الوصول من خلال نطاق الموفر -بيانات الاعتماد. في التطوير المحلي، قم بتعيين المستودع المستهدف بشكل صريح: - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -لا تعامل استنساخ VM أو الخروج المعزول طويل الأمد باعتباره السحابة الأساسية -نموذج الوصول إلى الريبو. لا تزال صناديق الحماية مهمة لتنفيذ التعليمات البرمجية المعزولة، ولكن -يجب أن يكون الوصول إلى المستودع صريحًا ومرخصًا وقابلاً للتدقيق وقابلاً للإلغاء -من خلال طبقة الموصل. - -### مشاركة الجلسات والتشغيل {#sharing-runs} - -الجلسات والجري بدون رأس هي أشياء متينة. يجب أن تتم إمكانية المشاركة على مراحل: -قراءة/مشاركة الروابط أولاً، حتى يتمكن أعضاء الفريق من فحص المطالبات والمخرجات المعقمة -وحالة التشغيل؛ يُسمح بالتعاون القابل للكتابة لاحقًا، لذا استمر في التشغيل، -الموافقة على actions أو تعديل الجداول الزمنية أو تغيير التكوين -فحوصات الوصول الصريحة. - -## دردشة غنية على Agent-Native {#rich-chat} - -استخدم الدردشة المضمنة عندما يتعين على المستخدم التحدث إلى الوكيل، راجع استدعاءات الأداة، -الموافقة على العمل، وفحص النتائج الأصلية، والاحتفاظ بسجل سلاسل المحادثات الدائم. - -للحصول على نقطة بداية كاملة للتطبيق، استخدم [Chat template](/docs/template-chat): +لنقطة بداية تطبيق كاملة، استخدم [قالب المحادثة](/docs/template-chat): ```bash npx @agent-native/core@latest create my-chat-app --template chat ``` -أبسط دردشة بصفحة كاملة: +أبسط محادثة على صفحة كاملة: ```tsx import { AgentChatSurface } from "@agent-native/core/client/chat"; @@ -297,11 +105,10 @@ export default function ChatRoute() { } ``` -عندما يحتوي التطبيق على علامة تبويب دردشة بملء الصفحة و`AgentSidebar`، استخدم نفس الشيء -`storageKey` على كلا السطحين، قم بتمكين `chatViewTransition`، ثم قم بتثبيت -مساعدو تسليم الدردشة الرئيسية في التخطيط. روابط عادية داخل التطبيق خارج الدردشة -بعد ذلك تحويل الدردشة الكاملة إلى الشريط الجانبي مع الحفاظ على نشاطها -الخيط: +عندما يحتوي التطبيق على تبويب محادثة بصفحة كاملة و`AgentSidebar`، استخدم نفس +`storageKey` على كلتا الواجهتين، وفعّل `chatViewTransition`، وثبّت +مساعدي التسليم لصفحة المحادثة الرئيسية في التخطيط. يمكن للروابط العادية داخل التطبيق الخارجة من صفحة المحادثة +أن تحوّل المحادثة الكاملة إلى الشريط الجانبي مع الحفاظ على الخيط النشط: ```tsx import { @@ -339,7 +146,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -أبسط دردشة مضمنة مع الكروم الخاص بك: +أبسط محادثة مضمّنة مع إطارك الخاص: ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -349,51 +156,115 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -يمكن لـ Actions عرض نتائج عناصر واجهة مستخدم أصلية صريحة، لذا لا يقتصر الأمر على إخراج الدردشة -نص. يتم عرض الجداول والمخططات وبطاقات المنتجات المكتوبة كـ React للطرف الأول -مكونات في الدردشة، بدون إطارات iframe. انظر [Native واجهة الدردشة](/docs/native-chat-ui). +يمكن للإجراءات إرجاع نتائج عناصر واجهة أصلية صريحة بحيث لا يكون مخرج المحادثة مجرد +نص. تُعرض الجداول والمخططات وبطاقات المنتج المكتوبة كمكونات React من الدرجة الأولى +في المحادثة، بدون iframes. انظر [واجهة المحادثة الأصلية](/docs/native-chat-ui). +عندما يحتاج الوكيل إلى عناصر تحكم مولَّدة عشوائية بدلاً من عنصر واجهة +React محدد مسبقًا، استخدم [واجهة المستخدم التوليدية](/docs/generative-ui): تُعرض واجهة +Alpine/Tailwind المحمية مضمّنةً، ويمكنها قراءة حالة التطبيق وسياق الفتحة، وإرسال +القيم المحددة مرة أخرى إلى المحادثة. -## دردشة غنية مع وكيلك {#byo-agent} +## واجهة مستخدم مضمّنة أصلية {#native-inline-ui} -استخدم هذا المسار عندما يكون وكيلك مبنيًا بالفعل باستخدام إطار عمل آخر أو -وقت التشغيل وتريد دردشة Agent-Native UI حوله. `AgentChatRuntime` هو -الحدود: يقوم وقت التشغيل الخاص بك ببث الأحداث الطبيعية، ويعرض Agent-Native -الملحن والنص واستدعاءات الأدوات والموافقات والأدوات الأصلية وتخطيط التطبيق. +استخدم هذا عندما تُرجع إجراءاتك بيانات منظمة — قائمة سجلات، أو مجموعة بيانات مخطط، أو ملخص حالة — يجب أن تُعرض كمكوّن واجهة مستخدم حقيقي داخل خيط المحادثة بدلاً من وصف نصي بسيط. تُعرّف مُصيِّر `chatUI` على الإجراء، ويُعرضه Agent-Native كمكوّن React من الدرجة الأولى: بدون iframes، بدون مسار عرض منفصل. -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +هذا هو الخيار الصحيح عندما يكون للمخرج شكل واضح وقابل لإعادة الاستخدام يمكنك تصميمه مرة واحدة واستخدامه عبر ردود الوكيل المتعددة. للعناصر التي يحتاج الوكيل إلى إنشائها ديناميكيًا أثناء التشغيل، انظر [واجهة مستخدم مضمّنة مولَّدة](#generated-inline-ui) بدلاً من ذلك. -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +انظر [واجهة المحادثة الأصلية](/docs/native-chat-ui) للاطلاع على واجهة API الكاملة للمُصيِّر، ومكتبة العناصر، وتكامل وقت تشغيل وكيل BYO. -export function SupportAgentChat() { - return ; +## واجهة مستخدم مضمّنة مولَّدة {#generated-inline-ui} + +استخدم هذا عندما يحتاج الوكيل إلى إنشاء عنصر تحكم غير موجود بعد كعنصر واجهة مبني مسبقًا — نموذج مخصص، أو أداة انتقاء مبنية حول السياق الحالي، أو آلة حاسبة لمرة واحدة. على عكس العناصر الأصلية، تُركَّب واجهة المستخدم المولَّدة من قِبل الوكيل أثناء التشغيل من Alpine.js وTailwind، وتعمل محمية في iframe، ويمكنها إرسال القيم المحددة مرة أخرى إلى خيط المحادثة. + +يمكن أن تكون واجهة المستخدم المولَّدة عابرة (تُعرض مرة واحدة وتُهمل) أو محفوظة كامتداد قابل لإعادة الاستخدام يستمر للمستخدم. + +انظر [واجهة المستخدم التوليدية](/docs/generative-ui) للاطلاع على واجهة API الكاملة، وقيود الحماية، ونموذج استمرارية الامتداد. + +## تطبيق كامل {#full-application} + +استخدم مسار التطبيق الكامل عندما يحتاج المستخدمون إلى كائنات وسير عمل دائمة: نماذج، +ولوحات تحكم، وتقاويم، وصناديق وارد، ومحررات، ومستندات، وأصول، أو تقارير. + +تضيف التطبيقات الكاملة واجهة مستخدم للمنتج حول نفس عقد الإجراءات والوكيل: + + + +### حالة SQL + +بيانات التطبيق والتنقل والإعدادات وسجل المحادثة كلها دائمة. يقرأ الوكيل ويكتب نفس الصفوف التي تفعلها واجهة المستخدم. + +### الوعي بالسياق + +يعرف الوكيل المسار الحالي والاختيار والكائن المركّز، لذا فإن "تعديل هذا" يعني دائمًا الشيء الصحيح. + +### المزامنة الحية + +تُحدّث تغييرات الوكيل واجهة المستخدم في الوقت الفعلي، وتُحدّث تغييرات واجهة المستخدم سياق الوكيل. لا استطلاع، لا تحديث. + +### الروابط العميقة + +يمكن لنتائج الإجراءات فتح العرض الصحيح للتطبيق مباشرة: يرتبط المخطط بلوحة التحكم، ويرتبط المسودة بصندوق الوارد. + +### عناصر المحادثة الأصلية + +تُعرض الجداول والمخططات والبطاقات والموافقات والنتائج المكتوبة كمكونات React من الدرجة الأولى مضمّنةً في المحادثة. + +### واجهة مستخدم توليدية وامتدادات + +يمكن للوكيل إنشاء عناصر تحكم مضمّنة أثناء التشغيل، وحفظ تطبيقات مصغّرة قابلة لإعادة الاستخدام عندما يحتاج سير العمل إلى الاستمرار. + + + +ابدأ من [قالب المحادثة](/docs/template-chat) عندما تريد تطبيقًا بسيطًا +حول إجراءاتك، أو من [قالب](/docs/cloneable-saas) نطاق معين عندما تريد +شكل منتج كاملاً. + +### إدارة الوكيل بصفحة كاملة {#agent-page} + +كل تطبيق Agent-Native يحتاج في نهاية المطاف إلى مكان يمكن للمستخدمين من خلاله تهيئة وكيلهم: وضع تعليمات دائمة، ومراجعة ما قام به، وتوصيل خوادم MCP، وإدارة الأتمتة، والتحكم في الوصول. بناء هذه الواجهة من الصفر يستلزم الكثير من العمل. يُشحن Agent-Native مع مكوّن بصفحة كاملة مبني مسبقًا، `AgentTabsPage`، يغطي كل ذلك عبر اثني عشر تبويبًا. + +ثبّته في `/agent` في تطبيقك. تقوم القوالب الحالية بإقران هذا المسار بمدخل تنقل التطبيق وتمرير `agentPageHref="/agent"` إلى `AgentSidebar`، بحيث يمكن لأوضاع الموارد والإعدادات في الشريط الجانبي الارتباط بالصفحة الكاملة دون تكرار تلك التدفقات. + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -توجد مساعدات وقت التشغيل الجاهزة لوكلاء OpenAI واستجابات OpenAI وClaude -الوكيل SDK، وVercel AI SDK، وAG-UI، بالإضافة إلى وقت تشغيل HTTP الذي تمت تسويته أعلاه -لأي وكيل آخر (Mastra، أو Flue، أو Eve، أو LangGraph، أو خدمة مخصصة). ACP هو -ليست دردشة تطبيق المستخدم النهائي أو نقل A2A، ولا Agent-Native حاليًا -المطالبة بدعم A2UI. يتم دعم ACP في مكان واحد محدد - قيادة سيارة محلية -وكيل الترميز (Gemini CLI، Claude Code، ...) من خلال -[harness layer](/docs/harness-agents#acp)، وليس وقت تشغيل الدردشة هنا. +توفر الصفحة المشتركة حاليًا اثني عشر تبويبًا عبر مجموعتين: + +| المجموعة | التبويب | يعرض | +| -------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| الموارد | **Files** | لوحة `ResourcesPanel` الحالية للملفات الشخصية أو التنظيمية | +| الموارد | **Instructions** | قواعد دائمة التشغيل بأسلوب AGENTS.md | +| الموارد | **Agents** | ملفات تعريف الوكلاء الفرعيين المخصصة | +| الموارد | **Memory** | ملاحظات الاستدعاء طويل الأمد | +| الموارد | **Skills** | سير عمل قابلة لإعادة الاستخدام | +| الموارد | **Learnings** | التصحيحات والأنماط المُلتقطة بمرور الوقت | +| الموارد | **Remote agents** | اتصالات A2A بتطبيقات agent-native الأخرى (يحل محل ما كان يعرضه تبويب Connections سابقًا) | +| الوكيل | **Snapshots** | معاينة نطاق، وميزانية رموز، وأقسام نظام مرتبة مجمّعة حسب المصدر/الحوكمة/المرجع، وأحدث لقطة خيط حي. تمت إعادة تسميتها من "Context"؛ تُعيد روابط `#context` القديمة التوجيه إلى هنا. | +| الوكيل | **Connections** | إدارة خادم MCP فقط | +| الوكيل | **Automations** | أتمتة مجدولة/أحداث شخصية وتنظيمية مع تدفقات إيقاف مؤقت/استئناف وتفاصيل وحذف. يبقى عنوان URL للتوافق الثابت `/agent#jobs`. | +| الوكيل | **Settings** | نموذج الوكيل، ومفاتيح API، والحدود، والصوت، وإعدادات الأتمتة | +| الوكيل | **Access** | عنوان URL لـ MCP للتطبيق، وبطاقة وكيل A2A عند الإتاحة، وأدلة الإعداد المشتركة لـ Claude وChatGPT وCursor وClaude Code وCodex وعملاء آخرين. روابط إلى `/mcp/connect` لتدفق الاتصال الكامل واحتياطي الرمز المميز. | + +تعرض الصفحة بيانات شخصية (نطاق `user`) فقط. لا يوجد تبديل على مستوى المؤسسة اليوم. إنها غلاف رقيق على المكونات والفحوصات الموجودة، وليست وحدة تحكم إدارية جديدة: يصف Connections ما يمكن للتطبيق استدعاؤه؛ يصف Access كيفية اتصال العملاء الخارجيين به. -[Native واجهة الدردشة — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -هو الموطن الأساسي لأشكال الأحداث، ومساعدي وقت التشغيل، و`chatUI` -البيانات التعريفية لنتيجة الأداة. ابدأ من هنا عند توصيل وكيل خارجي بالدردشة. +غير مدرج بعد: -## عربة جانبية مضمنة {#embedded-sidecar} +- عرض على نطاق المؤسسة +- تحرير المنح والنطاق +- واجهة مستخدم الإلغاء +- سجل المصدر لكل تكرار -استخدم العربة الجانبية المضمنة عندما يكون المنتج الرئيسي موجودًا بالفعل وتريد -الوكيل بجانبه. +## الشريط الجانبي المضمّن {#embedded-sidecar} -يقوم المكون الإضافي للخادم بتوصيل مسارات Agent-Native إلى تطبيقك المضيف ويحلها -جانب خادم هوية المضيف: +استخدم الشريط الجانبي المضمّن عندما يكون المنتج الرئيسي موجودًا بالفعل وتريد +وكيلاً بجانبه. + +يُثبّت المكوّن الإضافي للخادم مسارات Agent-Native في تطبيقك المضيف ويحل +هوية المضيف من جانب الخادم: ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -405,7 +276,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -يقوم الجانب React بتمرير سياق الصفحة وأوامر المضيف: +يمرر الشريط الجانبي React سياق الصفحة وأوامر المضيف: ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -427,18 +298,22 @@ export function AppShell({ children }) { } ``` - +### كيف يتصل + +يعمل الجزءان كجسر: يمرر تطبيق المضيف سياق الصفحة (المسار الحالي، والنص المحدد، والكائن المركّز) إلى `AgentNativeEmbedded`، ويُرسل الوكيل الأوامر مرة أخرى من خلال `onNavigate` و`onRefresh`. يتعامل المكوّن الإضافي للخادم مع الهوية — يحل جلسة المضيف بحيث يتصرف الوكيل كمستخدم صحيح بدون تسجيل دخول منفصل. لا يحتاج أي شيء في تطبيق المضيف إلى التغيير؛ يُرفق المكوّن الإضافي مسارات Agent-Native بجانب المسارات الموجودة لديك. + + ```html
- التطبيق المضيفSaaS الموجودة لديك + تطبيق المضيفتطبيق SaaS الحالي لديك
- getContext()
الطريق · الاختيار + getContext()
المسار · التحديد
- على التنقل / على التحديث
أوامر المضيف
@@ -449,10 +324,10 @@ export function AppShell({ children }) {
AgentNativeEmbeddedوكيل + مساحة عمل + >الوكيل + الموارد
- Agent-Native الطرق
التي تم تركيبها بواسطة البرنامج المساعد للخادممُثبَّتة بواسطة المكوّن الإضافي للخادم
@@ -486,45 +361,209 @@ export function AppShell({ children }) { -راجع [Embedding SDK](/docs/embedding-sdk) للتعرف على مصادقة المضيف وعزل قاعدة البيانات -وضع iframe/المنتقي وجسر المستوى الأدنى API. +انظر [SDK التضمين](/docs/embedding-sdk) للاطلاع على مصادقة المضيف وعزل قاعدة البيانات +ووضع iframe/المنتقي وواجهات برمجة الجسر ذات المستوى الأدنى. + +## تطبيق الأتمتة أولاً {#headless} + +استخدم مسار الأتمتة أولاً عندما لا يحتاج أحد إلى شاشة متصفح مخصصة بينما +يعمل العمل: المهام المجدولة، والتكاملات، وسير العمل الخلفية، وحلقات CLI، +ووكيل آخر، أو منتج موجود يستدعي Agent-Native. + +هذا هو الشكل الذي يجب اللجوء إليه عندما تكون الأتمتة هي واجهة المنتج. ترسل طلبًا من الطرفية، أو Slack، أو البريد الإلكتروني، أو مهمة مجدولة، أو وكيل آخر، أو محادثة ("لخّص رسائلي الإلكترونية غير المقروءة"، "انشر المقاييس اليومية على Slack"، "ابحث عن المرشحين الذين ردوا الأسبوع الماضي") ويتصرف الوكيل ويُرجع النتيجة إلى حيث تنتمي. إنه لا يزال تطبيقًا حقيقيًا، وليس موجهًا عديم الحالة: +تعيش الإجراءات وجلسات المصادقة وحالة التطبيق وسجل الخيط/التشغيل والإعدادات وبيانات الاعتماد +وسجلات المشاركة في SQL. + +اختر هذا النمط عندما: + +- **يحدث العمل في الخلفية.** تُنشأ معظم القيمة بينما لا ينظر المستخدم: وكلاء الفرز، ووكلاء التقارير اليومية، والمستجيبون للمناوبة. +- **يغادر المخرج التطبيق.** ينشر الوكيل على Slack، أو يرسل بريدًا إلكترونيًا، أو يحدّث نظامًا خارجيًا؛ لا يوجد شيء للتصفح داخل التطبيق. +- **النطاق لقطة واحدة.** روبوت بحث، أو مولّد ملخصات، أو كاتب تقارير بدون كائن دائم يحتاج إلى عرض قائمة. +- **أنت تنشئ نموذجًا أوليًا للأتمتة.** أشحن العملية الآن؛ أضف المحادثة أو صفحات التطبيق عندما يحتاج المستخدمون إلى فحصها وتوجيهها. + +إذا كان منتجك مبنيًا حول كائنات دائمة يتصفح المستخدمون فيها ويتمحور حولها ويشاركونها (رسائل إلكترونية، أحداث، مستندات، مخططات)، اختر [تطبيقًا كاملاً](#full-application) أو [قالبًا](/docs/cloneable-saas) بدلاً من ذلك؛ تلك تضيف واجهة مستخدم كاملة _بالإضافة إلى_ الوكيل. + +### ما يأتي في الصندوق {#in-the-box} + +يتخطى تطبيق الأتمتة أولاً عمل لوحة التحكم، وهو مستقل عن القناة منذ اليوم الأول. يعمل نفس الوكيل من الويب وSlack وTelegram والبريد الإلكتروني والوكلاء الآخرين لأن كل شيء يمر بنفس الإجراءات. المقايضة هي أنه لا يوجد عرض "تصفح كل شيء في لمحة"؛ إذا احتاج المستخدمون إلى ذلك، ابدأ من [المحادثة](/docs/template-chat) أو أضف صفحة حالة صغيرة أو عرض قائمة. + +عند إضافة غلاف المحادثة المدمج، يوفر الإطار خمس واجهات إدارة لا يتعين عليك بناؤها: **المحادثة** (المدخل الرئيسي)، **الموارد** (المهارات والذاكرة والتعليمات والوكلاء الفرعيون وخوادم MCP المتصلة)، **الأتمتة**، **سجل الخيط**، و**الإعدادات**. هذه عادةً كافية: تحدث إليه، وانظر ما فعله، وهيّئ كيفية تصرفه. العب إلى [المحادثة](/docs/template-chat) عندما تكون مستعدًا لإضافة تلك الواجهة المتصفح، أو [قالب الإرسال](/docs/template-dispatch) كنقطة بداية بأسلوب مساحة العمل مع Slack/Telegram والمهام المجدولة والأسرار المشتركة خارج الصندوق. + +أصغر مسار محلي بدون متصفح هو سقالة بالإضافة إلى إجراء واحد: + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +ثم عرّف العملية الدائمة: + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +إجراء واحد يمكن استدعاؤه كـ: + +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **App-agent CLI:** `pnpm agent "Summarize form_123"` +- **MCP:** من Claude وChatGPT وCodex وCursor وOpenCode وCopilot ومضيفي MCP الآخرين +- **A2A:** من تطبيق agent-native آخر أو نظير وكيل +- **واجهة المستخدم:** من خلال `useActionQuery` أو `useActionMutation` أو `callAction` +- **أداة الوكيل:** من حلقة المحادثة المدمجة + + + +كل `defineAction` يُثبَّت تلقائيًا في `/_agent-native/actions/`. يُتحقق من صحة نص JSON وفق مخطط zod الخاص بالإجراء قبل تنفيذ `run`. لاستدعائه من نظام خارجي برمز حامل طويل الأمد، انظر [HTTP API](/docs/http-api). + + + +هذا ليس وضع بلا قاعدة بيانات أو وضع عديم الحالة. تخزّن حلقة تطبيق-الوكيل الجلسات +والخيوط والتشغيلات والإعدادات وبيانات الاعتماد وحالة التطبيق وسجلات المشاركة في +SQL. يعتمد التطوير المحلي على SQLite بشكل افتراضي؛ يجب على تطبيقات الأتمتة أولاً المستضافة +استخدام قاعدة بيانات SQL ثابتة. + +إذا كنت بحاجة إلى حلقة الوكيل بالكامل بدون واجهة من مجلد المشروع، استخدم: + +```bash +pnpm agent "Summarize this week's forms." +``` + +إذا احتاج تطبيق أو نص برمجي آخر إلى استدعاء الوكيل بالكامل، استخدم +`agentNative.invoke("analytics", "...")` أو واجهة CLI `agent-native invoke`. يبقي ذلك +العمل عبر التطبيقات على مسار A2A بينما يبقى العمل المحلي على الإجراءات. + +يمكن للعمال والمهام وخطافات الويب للتكامل والمضيفين المخصصين تشغيل حلقة الوكيل +مباشرة من خلال واجهة برمجة تطبيقات الخادم. هذا أكثر انخفاضًا في المستوى من الإجراءات — تُوفّر +المحرك والنموذج والرسائل والأدوات والإجراءات وبالوعة الأحداث وإشارة الإلغاء +بنفسك: + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +بالنسبة لمعظم التطبيقات، تستدعي الموجهات المجدولة وخطافات الويب للتكامل هذه الحلقة +بالفعل نيابةً عنك. العب إليها مباشرة فقط عند بناء مضيف مخصص بدون متصفح، أو مُشغّل تقييم، +أو سطح تنسيق من جانب الخادم. انظر [الخادم: معالج الوكيل في الإنتاج](/docs/server#agent-handler) للاطلاع على التوقيع الكامل. + +### التشغيل على مجلد {#folder-loop} + +إذا كان هدفك "تشغيل وكيل على هذا المجلد"، ابدأ بحلقة تطبيق-الوكيل +في ذلك المجلد: قم بسقالة تطبيق الأتمتة أولاً، وأضف الإجراءات/التعليمات، وشغّل +`pnpm agent "..."`. يبقي ذلك العمل داخل نفس عقد الإجراء/وقت التشغيل/الحالة الذي سيستخدمه التطبيق في الإنتاج. + +تسخيرات الترميز الخارجية هي سطح منتج منفصل لتضمين Claude +Code وCodex وPi وCursor وMastra أو أوقات تشغيل مماثلة داخل تطبيق Agent-Native. +استخدمها عندما تبني منتج وكيل ترميز، وليس كالطريقة الافتراضية +لبدء سير عمل agent-native محلي. + +### وصول المستودع السحابي {#cloud-repo-access} + +بالنسبة لتطبيقات الأتمتة أولاً السحابية التي تحتاج إلى وصول المستودع، استخدم موصّل GitHub +بالإضافة إلى نموذج CRUD للرمز المميز: سرد المستودعات، والبحث في الملفات، وقراءة الملفات، وإنشاء أو +تعديل الملفات، وحذف الملفات، وإلغاء الوصول من خلال بيانات الاعتماد المحددة بالمزود. في التطوير المحلي، حدد المستودع الهدف صراحةً: + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +لا تتعامل مع استنساخ VM أو سحب صندوق رمل طويل الأمد كنموذج وصول المستودع السحابي الأساسي. لا تزال صناديق الرمل مهمة للتنفيذ المعزول للكود، لكن يجب أن يكون وصول المستودع صريحًا ومُذن به وقابل للتدقيق وقابل للإلغاء من خلال طبقة الموصّل. + +### مشاركة الجلسات والتشغيلات {#sharing-runs} + +جلسات وتشغيلات الأتمتة أولاً هي كائنات دائمة. يجب أن تكون إمكانية المشاركة مرحلية: روابط القراءة/المشاركة أولاً، حتى يتمكن أعضاء الفريق من فحص الموجهات المُعقّمة والمخرجات وحالة التشغيل؛ والتعاون القابل للكتابة بالإذن لاحقًا، بحيث يمر الاستمرار في التشغيل والموافقة على الإجراءات وتعديل الجداول الزمنية أو تغيير التهيئة من خلال فحوصات وصول صريحة. + +## محادثة غنية على وكيلك {#byo-agent} + +استخدم هذا المسار عندما يكون وكيلك مبنيًا بالفعل بإطار عمل أو +وقت تشغيل آخر وتريد واجهة محادثة Agent-Native حوله. `AgentChatRuntime` هو +الحد الفاصل: يبث وقت تشغيلك أحداثًا موحدة، ويُعرض Agent-Native المحرر +وسجل النسخ واستدعاءات الأدوات والموافقات والعناصر الأصلية وتخطيط التطبيق. + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` + +توجد مساعدات وقت تشغيل جاهزة لـ OpenAI Agents وOpenAI Responses وClaude +Agent SDK وVercel AI SDK وAG-UI، بالإضافة إلى وقت تشغيل HTTP الموحد أعلاه +لأي وكيل آخر (Mastra، Flue، Eve، LangGraph، أو خدمة مخصصة). ACP ليس محادثة التطبيق للمستخدم النهائي أو نقل A2A، ولا يدّعي Agent-Native حاليًا دعم A2UI. ACP مدعوم في مكان واحد محدد: تشغيل وكيل ترميز محلي (Gemini CLI، Claude Code، ...) من خلال +[طبقة التسخير](/docs/harness-agents#acp)، وليس كوقت تشغيل المحادثة هنا. + +[واجهة المحادثة الأصلية: أوقات تشغيل وكيل BYO](/docs/native-chat-ui#byo-agent-runtimes) +هو المرجع الرسمي لأشكال الأحداث ومساعدات وقت التشغيل وبيانات تعريف نتيجة أداة `chatUI`. ابدأ هناك عند توصيل وكيل خارجي بالمحادثة. + +## ما التالي {#related-docs} + + + +### [الإجراءات](/docs/actions) + +عرّف العملية مرة واحدة. كل واجهة أعلاه تستدعي نفسها. + +### [واجهة المحادثة الأصلية](/docs/native-chat-ui) -## التطبيق الكامل {#full-application} +اعرض نتائج الإجراءات المكتوبة كجداول ومخططات وبطاقات مباشرة في المحادثة. -استخدم مسار التطبيق الكامل عندما يحتاج المستخدمون إلى كائنات ومهام سير عمل متينة: النماذج، -لوحات التحكم، أو التقويمات، أو صناديق البريد الوارد، أو برامج التحرير، أو المستندات، أو الأصول، أو التقارير. +### [واجهة المستخدم التوليدية](/docs/generative-ui) -تضيف التطبيقات الكاملة المنتج UI حول نفس الإجراء وعقد الوكيل: +أنشئ واجهة مستخدم محمية عابرة أو ثابتة مضمّنة في المحادثة. -- **حالة SQL** — بيانات التطبيق، والتنقل، والإعدادات، وسجل الدردشة دائمة. -- **الوعي بالسياق** — يعرف الوكيل المسار الحالي والتحديد والكائن الذي يتم التركيز عليه. -- **المزامنة المباشرة** — تعمل تغييرات الوكيل على تحديث UI، كما تعمل تغييرات UI على تحديث سياق الوكيل. -- **روابط لمواضع معينة** — يمكن لنتائج الإجراء فتح عرض التطبيق المناسب. -- **أدوات الدردشة الأصلية** — تظهر الجداول والمخططات والبطاقات والموافقات والنتائج المكتوبة مضمنة. +### [تطبيقات الأتمتة أولاً](/docs/pure-agent-apps) -ابدأ من [Chat template](/docs/template-chat) عندما تريد تطبيقًا بسيطًا -حول actions، أو من النطاق [template](/docs/cloneable-saas) عندما -تريد شكلًا كاملاً للمنتج. +النمط الكامل بدون متصفح للمهام والطوابير والنصوص البرمجية والوكلاء الخارجيين. -## كيفية الاختيار {#how-to-choose} +### [الوكلاء الخارجيون](/docs/external-agents) -| إذا كنت تفكر... | اختر | -| ---------------------------------------------------------------- | --------------------------- | -| "أحتاج فقط إلى أداة قابلة للاستدعاء أو سير عمل." | عميل مقطوع الرأس | -| "أريد وكيل إطار العمل، ولكن يجب أن تكون الدردشة هي UI الرئيسية." | دردشة غنية على Agent-Native | -| "لدي وكيل بالفعل؛ وأحتاج إلى دردشة مصقولة UI من أجل ذلك." | دردشة غنية مع وكيلك | -| "لدي بالفعل تطبيق SaaS؛ أضف وكيلًا بجانبه." | عربة جانبية مضمنة | -| "يجب أن يتطور الوكيل وUI معًا ليكونا المنتج." | التطبيق الكامل | +اتصل بمضيفي MCP المتوافقين بتطبيقك كخادم أدوات. -اجعل العقد صغيرًا: حدد العمليات الدائمة كـ actions، وإرجاع صريح -نتائج الأدوات عندما تحتاج الدردشة إلى UI، وإضافة شاشات كاملة فقط عند المستخدمين -تحتاج إلى تصفح الكائنات الثابتة أو مقارنتها أو تكوينها أو التعاون عليها. +### [بروتوكول A2A](/docs/a2a-protocol) -## الخطوات التالية {#related-docs} +استدع الوكلاء من تطبيقات agent-native الأخرى عبر معيار A2A. -- [**Actions**](/docs/actions) — عرّف العملية مرة واحدة؛ كل سطح أعلاه يستدعي العملية نفسها -- [**Native Chat UI**](/docs/native-chat-ui) — اعرض نتائج actions كجداول ومخططات وبطاقات في الدردشة -- [**Generative UI**](/docs/generative-ui) — أنشئ واجهة مستخدم مؤقتة أو دائمة ضمن بيئة معزولة داخل الدردشة -- [**Automation-First Apps**](/docs/pure-agent-apps) — النمط الكامل دون متصفح للوظائف وقوائم الانتظار والبرامج النصية والوكلاء الخارجيين -- [**External Agents**](/docs/external-agents) — صِل المضيفين المتوافقين مع MCP بتطبيق -- [**A2A Protocol**](/docs/a2a-protocol) — استدعِ الوكلاء من تطبيقات Agent-Native أخرى + diff --git a/packages/core/docs/content/locales/de-DE/agent-surfaces.mdx b/packages/core/docs/content/locales/de-DE/agent-surfaces.mdx index 0e88075635..b18027a55c 100644 --- a/packages/core/docs/content/locales/de-DE/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/de-DE/agent-surfaces.mdx @@ -1,92 +1,44 @@ --- -title: "Agentenoberflächen" -description: "Verwenden Sie Agent-Native kopflos, als Rich-Chat, in einer vorhandenen App oder als vollständig agentennative Anwendung." -search: "Headless Agent Rich Chat, vollständige App BYO Agent Runtime AgentChatRuntime Embed actions MCP A2A HTTP CLI" +title: "Agent-Oberflächen" +description: "Wählen Sie, wie eine agentische App von Chat zu Inline-UI, dauerhaften App-Seiten, eingebetteten Sidecars, Automatisierung und externem Agentenzugriff wächst." +search: "agentische App Rich-Chat native Chat-UI vollständige App Automatisierung headless BYO Agent-Runtime AgentChatRuntime einbetten Aktionen MCP A2A HTTP CLI" --- -# Agentenoberflächen +# Agent-Oberflächen -## Vollständiger Agent-Arbeitsbereich {#agent-page} +Eine **Oberfläche** ist die Art und Weise, wie Benutzer (oder andere Systeme) mit Ihrer App interagieren: ein Chat-Fenster, eine Dashboard-Seite, ein Hintergrundjob, ein API-Aufruf von einem anderen Agenten. Agent-Native ermöglicht es Ihnen, diese zu kombinieren, ohne Ihre Kernlogik neu zu schreiben, da jede Oberfläche dieselben zugrunde liegenden Aktionen ausführt. Wenn Sie neu bei Agent-Native sind, lesen Sie zuerst [Schlüsselkonzepte](/docs/key-concepts). -Wenn eine vollständige Anwendung einen dauerhaften Ort zum Prüfen und -Konfigurieren ihres Agents braucht, binde `AgentTabsPage` unter `/agent` ein. -Füge die Route zur App-Navigation hinzu und übergib `agentPageHref="/agent"` an -`AgentSidebar`, damit die Modi Resources und Settings auf die vollständige -Seite verweisen können, ohne diese Abläufe zu duplizieren. +## Wie Oberflächen miteinander zusammenhängen -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -Die gemeinsame Seite bietet derzeit fünf Tabs: - -- **Context** — Bereichsvorschau, Tokenbudget, geordnete Systemabschnitte mit Herkunft und Governance, Listen-/Treemap-Ansicht und der aktuelle Live-Thread-Snapshot. -- **Files** — verwendet `ResourcesPanel` für persönliche oder organisationsweite Ressourcen wieder. -- **Connections** — MCP-Serververwaltung und A2A-Liste entfernter Agents: was der Agent dieser App aufrufen kann. -- **Automations** — persönliche und Organisations-Automatisierungen für Scheduled und Event mit Pausieren/Fortsetzen, Details und Löschen. Die Kompatibilitäts-URL bleibt `/agent#jobs`. -- **Access** — MCP-URL, eine A2A-Agent-Card wenn verfügbar, und gemeinsame Einrichtungsanleitungen; die vollständige Verbindung und den Token-Fallback gibt es unter `/mcp/connect`. +Die vier wichtigsten Produktformen liegen auf einem Spektrum von höchst interaktiv bis vollständig headless. Was sie kombinierbar macht, ist, dass das Fundament durchgehend gleich bleibt: dieselben Aktionen, dieselbe SQL-Datenbank und dieselbe Agentenschleife treiben jede Form an. Das Hinzufügen einer neuen Oberfläche bedeutet nicht, das Darunter liegende neu zu schreiben — Sie fügen lediglich einen neuen Weg hinzu, dieselben Operationen zu erreichen. -Die Seite verwendet derzeit den persönlichen Bereich und hat keinen -seitenweiten Umschalter **Personal / Organization**. Ein Tab kann eigene -Organisationsbereiche anzeigen, wenn die zugrunde liegenden Actions sie -unterstützen: **Automations** zeigt persönliche und Organisationsbereiche für -Scheduled und Event. Organisations-Event-Automatisierungen laufen immer als ihr Ersteller. Die Seite -ist eine dünne Hülle um vorhandene Komponenten, Actions und -Zugriffskontrollen, keine neue Admin-Konsole. - -Agent-Native ist bewusst zusammensetzbar. Sie können den Agenten ohne großen Aufwand verwenden UI, -Verwenden Sie UI ohne die integrierte Agent-Laufzeit oder verwenden Sie beide zusammen als Vollversion -Anwendung. - -Der sinnvolle Weg zur Auswahl besteht nicht zuerst nach dem Protokoll. Wählen Sie die Produktoberfläche -Sie möchten, dann verwenden Sie das passende Grundelement. - -| Oberfläche | Verwenden Sie es, wenn | Beginnen Sie mit | -| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- | -| **Kopfloser Agent** | Code, Jobs, Skripte, eine andere App oder ein anderer Agent sollten die Arbeit direkt aufrufen. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Rich-Chat auf Agent-Native** | Sie möchten einen eigenständigen oder eingebetteten Chat, der durch die integrierte Agentenschleife unterstützt wird. | [Chat template](/docs/template-chat), ``, `` | -| **Rich-Chat auf Ihrem Agenten** | Sie haben den Agent woanders erstellt und möchten den Verfassenr, das Transkript, die Toolkarten und die nativen Widgets von Agent-Native. | `AgentChatRuntime`, `` | -| **Eingebetteter Sidecar** | Sie haben bereits eine SaaS-App und möchten daneben einen Agenten mit Seitenkontext und Hostbefehlen. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **Vollständige Bewerbung** | Menschen und Agenten sollten robuste Bildschirme, Daten, Navigation und Zusammenarbeit gemeinsam nutzen. | Vorlagen, actions, SQL-Status, Kontextbewusstsein | - -Das sind Stufen, keine separaten Produkte. Ein Workflow kann als Headless starten -Agent mit einer Aktion, erscheint im Chat als Tabelle oder Diagramm und wird später zum -Vollbild in einer App, ohne den vom Agenten aufgerufenen Vorgang zu ändern. - - + ```html
- Headlessactions, Jobs, Skripte, andere Agenten + ChatEingabefeld, Verlauf, Tool-Aufrufe
- Rich ChatComposer, Transkript, Tool-Karten + Inline-UITabellen, Diagramme, Karten
- Eingebetteter Sidecaragent beside an existing app + App-Seitedauerhafte Ansichten, SQL-Daten
- meiste UIVollständige Anwendungdauerhafte Screens, Daten, Zusammenarbeit + headlessAutomatisierungJobs, Skripte, externe Agenten
- gleiche actions · gleiches SQL · gleiche Agentenschleife + same actions · same SQL · same agent loop
``` @@ -119,174 +71,26 @@ Vollbild in einer App, ohne den vom Agenten aufgerufenen Vorgang zu ändern. -## Kopfloser Agent {#headless} - -Verwenden Sie den Headless-Pfad, wenn niemand dabei auf den Bildschirm einer benutzerdefinierten App starren muss -die Arbeit läuft: geplante Jobs, Integrationen, Backend-Workflows, CLI-Schleifen, -ein anderer Agent oder ein vorhandenes Produkt, das Agent-Native aufruft. - -Dies ist auch die Form, nach der man greifen sollte, wenn **der Agent _das Produkt_ ist** – das -App-Agent-Schleife ist die Haustür, kein Dashboard. Sie senden eine Anfrage vom -Terminal, Slack, E-Mail, ein geplanter Job, ein anderer Agent oder Chat – „meine zusammenfassen -Ungelesene E-Mails“, „Posten Sie die täglichen Kennzahlen an Slack“, „Finden Sie die Kandidaten, die -letzte Woche geantwortet“ – und der Agent handelt und gibt das Ergebnis an jedem beliebigen Ort zurück -gehört. Es handelt sich immer noch um eine echte App und nicht um eine zustandslose Eingabeaufforderung: actions, Authentifizierungssitzungen, -App-Status, Thread-/Ausführungsverlauf, Einstellungen, Anmeldeinformationen und Freigabedatensätze sind alle live -in SQL. - -Wählen Sie dieses Muster, wenn: - -- **Die Arbeit findet im Hintergrund statt.** Der größte Teil des Werts wird geschaffen, während der Benutzer nicht hinschaut – Triage-Agenten, Agenten für tägliche Berichte, Bereitschaftsdienstmitarbeiter. -- **Die Ausgabe verlässt die App.** Der Agent postet an Slack, sendet E-Mails oder aktualisiert ein Drittsystem; In der App gibt es nichts zum Durchsuchen. -- **Die Domain ist einmalig.** Forschungsbot, Zusammenfassungsgenerator, Berichtersteller – kein persistentes Objekt, das eine Listenansicht benötigt. -- **Sie erstellen Prototypen.** Versenden Sie den Agenten jetzt; Fügen Sie später das reichhaltigere UI hinzu, wenn Benutzer eines wünschen. - -Wenn Ihr Produkt auf persistenten Objekten basiert, durchsuchen, schwenken und navigieren Benutzer -Teilen – E-Mails, Ereignisse, Dokumente, Diagramme – wählen Sie einen [full application](#full-application) -oder stattdessen ein [template](/docs/cloneable-saas); diese fügen ein vollständiges UI _plus_ den Agenten hinzu. - -### Was im Lieferumfang enthalten ist {#in-the-box} - -Eine Headless-App überspringt wochenlange Dashboard-Arbeit und ist von Tag zu Tag kanalunabhängig -eins – derselbe Agent läuft über das Web, Slack, Telegram, E-Mail und andere Agenten -weil alles über den Agenten läuft, nicht über UI. Der Kompromiss besteht darin, dass es -keine Ansicht „Alles auf einen Blick durchsuchen“; Wenn Benutzer dies benötigen, mischen Sie Muster und -Fügen Sie eine kleine Statusseite oder Listenansicht hinzu. - -Wenn Sie die integrierte Chat-Shell hinzufügen, bietet das Framework fünf Verwaltungsfunktionen -Oberflächen, die Sie nicht erstellen müssen: **Chat** (die Haupteingabe), **Workspace** -(skills, Speicher, Anweisungen, Subagenten, verbundene MCP-Server, geplant -Jobs), **Jobverlauf**, **Threadverlauf** und **Einstellungen**. Das sind normalerweise -genug – sprechen Sie mit ihm, sehen Sie, was er tut, konfigurieren Sie, wie er sich verhält. Greifen Sie nach -[Chat](/docs/template-chat), wenn Sie bereit sind, diesen Browser hinzuzufügen, UI, oder -[Dispatch template](/docs/template-dispatch) für einen Anfang im Workspace-Stil -Punkt mit Slack/Telegram, geplanten Jobs und Shared Secrets sofort einsatzbereit. - -Der kleinste lokale Pfad ist ein Headless-Agent-Gerüst plus einer Aktion: - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -Definieren Sie dann den dauerhaften Betrieb: - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -Eine Aktion ist dann aufrufbar als: - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **App-Agent CLI** – `pnpm agent "Summarize form_123"` -- **MCP** – von Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot und anderen MCP-Hosts -- **A2A** – von einer anderen agentennativen App oder einem Agent-Peer -- **UI** – bis `useActionQuery`, `useActionMutation` oder `callAction` -- **Agent-Tool** – aus der integrierten Chat-Schleife - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -Dies ist kein datenbankloser oder zustandsloser Modus. Die App-Agent-Schleife speichert Sitzungen -Threads, Ausführungen, Einstellungen, Anmeldeinformationen, Anwendungsstatus und Freigabedatensätze in -SQL. Die lokale Entwicklung ist standardmäßig SQLite; Gehostete Headless-Apps sollten ein -persistente SQL-Datenbank. - -Wenn Sie die gesamte Agentenschleife kopflos aus dem Projektordner benötigen, verwenden Sie: - -```bash -pnpm agent "Summarize this week's forms." -``` - -Wenn eine andere App oder ein anderes Skript den gesamten Agenten aufrufen muss, verwenden Sie -`agentNative.invoke("analytics", "...")` oder `agent-native invoke` CLI. Das -App-übergreifende Arbeit bleibt auf dem A2A-Pfad, während lokale Arbeit auf actions verbleibt. - -Worker, Jobs, Integration webhooks und benutzerdefinierte Hosts können die Agentenschleife steuern -direkt über den Server API. Dies ist eine niedrigere Ebene als actions – Sie stellen -Die Engine, das Modell, die Nachrichten, actions und die Ereignissenke selbst: - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -Bei den meisten Apps rufen geplante Eingabeaufforderungen und Integration webhooks diese Schleife bereits auf -für Sie. Greifen Sie direkt danach zu, nur wenn Sie einen benutzerdefinierten Headless-Host erstellen, eval -Runner oder serverseitige Orchestrierungsoberfläche – siehe [Server – Produktionsagent -handler](/docs/server#agent-handler) für die vollständige Signatur. +## Einen Startpunkt wählen -### Wird für einen Ordner ausgeführt {#folder-loop} +Chat ist der häufigste Einstiegspunkt. Apps entwickeln typischerweise Inline-UI, wenn die Ausgaben reichhaltiger werden, und fügen dann vollständige App-Seiten hinzu, wenn Benutzer persistente Objekte zum Durchsuchen und Teilen benötigen. Dieselben Aktionen treiben Schaltflächen, geplante Jobs und externe Agenten an, die später hinzukommen. Verwenden Sie den Embedded Sidecar, wenn Sie einem Produkt, das Sie bereits besitzen, einen Agenten hinzufügen, oder Automation-first für Arbeiten, die ohne Browser ausgeführt werden. Hier ist das vollständige Bild: -Wenn Ihr Ziel darin besteht, „einen Agenten für diesen Ordner auszuführen“, beginnen Sie mit dem App-Agenten -Schleife in diesem Ordner: Erstellen Sie ein Gerüst für die Headless-App, fügen Sie actions/instructions hinzu und führen Sie es aus -`pnpm agent "..."`. Dadurch bleibt die Arbeit innerhalb derselben Aktion/Laufzeit/Status -Vertrag, den die App in der Produktion verwenden wird. - -Externe Codierkabelbäume sind eine separate Produktoberfläche zum Einbetten von Claude -Code, Codex, Pi, Cursor, Mastra oder ähnliche Laufzeiten innerhalb einer Agent-Native-App. -Verwenden Sie sie, wenn Sie ein Coding-Agent-Produkt erstellen, und nicht als Standardmethode -Starten Sie einen lokalen Agent-nativen Workflow. - -### Cloud-Repo-Zugriff {#cloud-repo-access} - -Für Cloud-Headless-Apps, die Repository-Zugriff benötigen, verwenden Sie den GitHub-Connector -plus Token CRUD-Modell: Repositorys auflisten, Dateien durchsuchen, Dateien lesen, erstellen oder -Dateien bearbeiten, Dateien löschen und Zugriff über den Anbieterbereich widerrufen -Anmeldeinformationen. Legen Sie bei der lokalen Entwicklung das Ziel-Repository explizit fest: - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -Behandeln Sie einen VM-Klon oder einen langlebigen Sandbox-Checkout nicht als primäre Cloud -Repo-Zugriffsmodell. Sandboxes sind für die isolierte Codeausführung immer noch wichtig, aber -Der Repository-Zugriff sollte explizit, berechtigt, überprüfbar und widerrufbar sein -durch die Verbindungsschicht. - -### Sitzungen und Läufe teilen {#sharing-runs} - -Headless-Sitzungen und -Läufe sind dauerhafte Objekte. Die Teilbarkeit sollte schrittweise erfolgen: -Lesen/teilen Sie zuerst die Links, damit Teamkollegen bereinigte Eingabeaufforderungen und Ausgaben überprüfen können -und Laufstatus; Berechtigte beschreibbare Zusammenarbeit später, also Fortsetzung eines Laufs, -Das Genehmigen von actions, das Bearbeiten von Zeitplänen oder das Ändern der Konfiguration erfolgt durch -Explizite Zugriffsprüfungen. +| Oberfläche | Verwenden Sie diese, wenn | Starten mit | +| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **[Rich-Chat](#rich-chat)** | Benutzer mit dem Agenten sprechen, Tool-Aufrufe sehen und einen Thread-Verlauf behalten. | [Chat-Template](/docs/template-chat), `` | +| **[Native Inline-UI](#native-inline-ui)** | Aktionsergebnisse als Tabellen, Diagramme, Karten oder Genehmigungen im Chat gerendert werden sollen. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[Generierte Inline-UI](#generated-inline-ui)** | Der Agent temporäre oder wiederverwendbare Steuerelemente im Chat dynamisch erstellen soll. | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[Vollständige Anwendung](#full-application)** | Benutzer dauerhafte Ansichten, gemeinsame Daten, Navigation und Zusammenarbeit benötigen. | Templates, Aktionen, SQL-Zustand, Kontextbewusstsein | +| **[Embedded Sidecar](#embedded-sidecar)** | Sie bereits eine SaaS-App haben und einen Agenten daneben mit Seitenkontext hinzufügen möchten. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[Automation-first](#headless)** | Jobs, Skripte oder andere Agenten die Arbeit direkt ohne Browser-UI aufrufen. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[Rich-Chat auf Ihrem Agenten](#byo-agent)** | Sie den Agenten anderswo erstellt haben und die Chat-UI von Agent-Native drumherum möchten. | `AgentChatRuntime`, `` | ## Rich-Chat auf Agent-Native {#rich-chat} -Verwenden Sie den integrierten Chat, wenn der Benutzer mit dem Agenten sprechen soll, siehe Tool-Aufrufe -Arbeiten genehmigen, native Ergebnisse überprüfen und einen dauerhaften Thread-Verlauf führen. +Verwenden Sie den integrierten Chat, wenn der Benutzer mit dem Agenten sprechen, Tool-Aufrufe sehen, +Arbeiten genehmigen, native Ergebnisse prüfen und einen dauerhaften Thread-Verlauf behalten soll. -Für einen vollständigen App-Startpunkt verwenden Sie [Chat template](/docs/template-chat): +Für einen vollständigen App-Startpunkt verwenden Sie das [Chat-Template](/docs/template-chat): ```bash npx @agent-native/core@latest create my-chat-app --template chat @@ -302,11 +106,10 @@ export default function ChatRoute() { } ``` -Wenn eine App sowohl über eine ganzseitige Chat-Registerkarte als auch über ein `AgentSidebar` verfügt, verwenden Sie dasselbe -`storageKey` auf beiden Oberflächen, aktivieren Sie `chatViewTransition` und installieren Sie -Chat-Home-Übergabe-Helfer im Layout. Gewöhnliche In-App-Links aus dem Chat -Seite kann dann den gesamten Chat in die Seitenleiste umwandeln, während der Chat aktiv bleibt -Thread: +Wenn eine App sowohl einen ganzseitigen Chat-Tab als auch eine `AgentSidebar` hat, verwenden Sie denselben +`storageKey` auf beiden Oberflächen, aktivieren Sie `chatViewTransition` und installieren Sie die +Chat-Home-Handoff-Helfer im Layout. Gewöhnliche In-App-Links aus der Chat-Seite können dann +den vollständigen Chat in die Sidebar überblenden, während der aktive Thread beibehalten wird: ```tsx import { @@ -344,7 +147,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -Der einfachste eingebettete Chat mit Ihrem eigenen Chrome: +Der einfachste eingebettete Chat mit Ihrer eigenen Chrome-Umgebung: ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -354,51 +157,115 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -Actions kann explizite native Widget-Ergebnisse zurückgeben, sodass die Chat-Ausgabe nicht einfach ist -Text. Tabellen, Diagramme und getippte Produktkarten werden als Erstanbieter-React -Komponenten im Chat, ohne Iframes. Siehe [Native Chat-Oberfläche](/docs/native-chat-ui). +Aktionen können explizite native Widget-Ergebnisse zurückgeben, sodass die Chat-Ausgabe nicht nur +Text ist. Tabellen, Diagramme und typisierte Produktkarten werden als First-Party-React-Komponenten im Chat +gerendert, ohne iFrames. Siehe [Native Chat UI](/docs/native-chat-ui). +Wenn der Agent beliebige generierte Steuerelemente anstelle eines vordefinierten +React-Widgets benötigt, verwenden Sie [Generative UI](/docs/generative-ui): Es rendert sandgeboxtes +Alpine/Tailwind-UI inline, kann App-Zustand und Slot-Kontext lesen und ausgewählte Werte an den Chat +zurückschicken. -## Rich-Chat auf Ihrem Agenten {#byo-agent} +## Native Inline-UI {#native-inline-ui} -Verwenden Sie diesen Pfad, wenn Ihr Agent bereits mit einem anderen Framework erstellt wurde oder -Laufzeit und Sie möchten Agent-Natives Chat-Oberfläche darum herum. `AgentChatRuntime` ist der -Grenze: Ihre Laufzeit streamt normalisierte Ereignisse und Agent-Native rendert die -Komponist, Transkript, Toolaufrufe, Genehmigungen, native Widgets und App-Layout. +Verwenden Sie diese, wenn Ihre Aktionen strukturierte Daten zurückgeben — eine Liste von Einträgen, einen Diagramm-Datensatz, eine Statuszusammenfassung — die als echte UI-Komponente im Chat-Thread gerendert werden sollen, anstatt als reine Textbeschreibung. Sie definieren einen `chatUI`-Renderer auf der Aktion, und Agent-Native rendert ihn als First-Party-React-Komponente: keine iFrames, kein separater Rendering-Pfad. -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +Dies ist die richtige Wahl, wenn die Ausgabe eine klare, wiederverwendbare Form hat, die Sie einmal entwerfen und über viele Agentenantworten hinweg verwenden würden. Für Steuerelemente, die der Agent zur Laufzeit dynamisch erstellen muss, siehe stattdessen [Generierte Inline-UI](#generated-inline-ui). -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +Siehe [Native Chat UI](/docs/native-chat-ui) für die vollständige Renderer-API, Widget-Bibliothek und BYO-Agent-Runtime-Integration. -export function SupportAgentChat() { - return ; +## Generierte Inline-UI {#generated-inline-ui} + +Verwenden Sie diese, wenn der Agent ein Steuerelement erstellen muss, das noch nicht als vorgefertigtes Widget existiert — ein benutzerdefiniertes Formular, ein Picker, der auf den aktuellen Kontext zugeschnitten ist, ein einmaliger Rechner. Im Gegensatz zu nativen Widgets wird die generierte UI vom Agenten zur Laufzeit aus Alpine.js und Tailwind zusammengesetzt, läuft sandgeboxed in einem iFrame und kann ausgewählte Werte zurück in den Chat-Thread senden. + +Generierte UI kann transient (einmal gerendert und verworfen) oder als wiederverwendbare Erweiterung gespeichert sein, die für den Benutzer persistent ist. + +Siehe [Generative UI](/docs/generative-ui) für die vollständige API, Sandbox-Einschränkungen und das Erweiterungspersistenzmodell. + +## Vollständige Anwendung {#full-application} + +Verwenden Sie den vollständigen App-Pfad, wenn Benutzer dauerhafte Objekte und Workflows benötigen: Formulare, +Dashboards, Kalender, Posteingänge, Editoren, Dokumente, Assets oder Berichte. + +Vollständige Apps fügen Produkt-UI um denselben Aktions- und Agentenvertrag herum hinzu: + + + +### SQL-Zustand + +App-Daten, Navigation, Einstellungen und Chat-Verlauf sind alle dauerhaft. Der Agent liest und schreibt dieselben Zeilen wie die UI. + +### Kontextbewusstsein + +Der Agent kennt die aktuelle Route, Auswahl und das fokussierte Objekt, sodass „bearbeite das" immer das Richtige meint. + +### Live-Sync + +Agentenänderungen aktualisieren die UI in Echtzeit, und UI-Änderungen aktualisieren den Kontext des Agenten. Kein Polling, kein Neu laden. + +### Deeplinks + +Aktionsergebnisse können die richtige App-Ansicht direkt öffnen: Ein Diagramm verlinkt zum Dashboard, ein Entwurf zum Posteingang. + +### Native Chat-Widgets + +Tabellen, Diagramme, Karten, Genehmigungen und typisierte Ergebnisse werden als First-Party-React-Komponenten direkt im Chat gerendert. + +### Generative UI und Erweiterungen + +Der Agent kann Inline-Steuerelemente spontan erstellen und wiederverwendbare Mini-Apps speichern, wenn ein Workflow persistieren muss. + + + +Starten Sie vom [Chat-Template](/docs/template-chat), wenn Sie eine minimale App +um Ihre Aktionen herum möchten, oder von einem Domain-[Template](/docs/cloneable-saas), wenn Sie +eine vollständige Produktform möchten. + +### Ganzseitige Manage-Agent-Seite {#agent-page} + +Jede Agent-Native-App braucht früher oder später einen Ort, an dem Benutzer ihren Agenten konfigurieren können: dauerhafte Anweisungen festlegen, überprüfen was er getan hat, MCP-Server verbinden, Automatisierungen verwalten und den Zugriff steuern. Diese UI von Grund auf zu bauen ist viel Arbeit. Agent-Native liefert eine vorgefertigte ganzseitige Komponente, `AgentTabsPage`, die alles über zwölf Tabs abdeckt. + +Binden Sie sie unter `/agent` in Ihrer App ein. Aktuelle Templates kombinieren diese Route mit einem App-Navigationseintrag und übergeben `agentPageHref="/agent"` an `AgentSidebar`, sodass die Ressourcen- und Einstellungsmodi der Sidebar auf die vollständige Seite verlinken können, ohne diese Abläufe zu duplizieren. + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -Für OpenAI Agents, OpenAI Responses und Claude gibt es vorgefertigte Laufzeithelfer -Agent SDK, Vercel AI SDK und AG-UI sowie die normalisierte HTTP-Laufzeit oben -für jeden anderen Agenten (Mastra, Flue, Eve, LangGraph oder ein benutzerdefinierter Dienst). ACP ist -nicht der Endbenutzer-App-Chat oder A2A-Transport, und Agent-Native derzeit nicht -Beanspruchen Sie A2UI-Unterstützung. ACP wird an einer bestimmten Stelle unterstützt – beim Fahren eines lokalen -Kodierungsagent (Gemini CLI, Claude Code, …) über den -[harness layer](/docs/harness-agents#acp), nicht als Chat-Laufzeit hier. +Die gemeinsame Seite bietet derzeit zwölf Tabs in zwei Gruppen: + +| Gruppe | Tab | Zeigt | +| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | Das bestehende `ResourcesPanel` für persönliche oder organisationsweite Dateien | +| Resources | **Instructions** | Immer aktive AGENTS.md-ähnliche Regeln | +| Resources | **Agents** | Benutzerdefinierte Sub-Agenten-Profile | +| Resources | **Memory** | Langzeiterinnerungsnotizen | +| Resources | **Skills** | Wiederverwendbare Workflows | +| Resources | **Learnings** | Im Laufe der Zeit erfasste Korrekturen und Muster | +| Resources | **Remote agents** | A2A-Verbindungen zu anderen agent-native Apps (ersetzt was der Connections-Tab früher zeigte) | +| Agent | **Snapshots** | Eine Scope-Vorschau, Token-Budget, geordnete Systemabschnitte gruppiert nach Herkunft/Governance/Quelle und der neueste Live-Thread-Snapshot. Umbenannt von „Context"; alte `#context`-Links leiten hierher weiter. | +| Agent | **Connections** | Nur MCP-Server-Verwaltung | +| Agent | **Automations** | Persönliche und organisationsweite geplante/ereignisbasierte Automatisierungen mit Pause/Fortsetzen, Details und Löschvorgängen. Die stabile Kompatibilitäts-URL bleibt `/agent#jobs`. | +| Agent | **Settings** | Agentenmodell, API-Schlüssel, Limits, Sprache und Automatisierungseinstellungen | +| Agent | **Access** | Die App-MCP-URL, eine A2A-Agentencard wenn verfügbar, und gemeinsame Einrichtungsanleitungen für Claude, ChatGPT, Cursor, Claude Code, Codex und andere Clients. Verlinkt zu `/mcp/connect` für den vollständigen Verbindungsablauf und Token-Fallback. | + +Die Seite zeigt nur persönliche (`user`-Scope) Daten. Es gibt heute keinen org-weiten Umschalter. Sie ist eine dünne Hülle über bestehenden Komponenten und Zugriffsüberprüfungen, keine neue Admin-Konsole: Connections beschreibt, was die App aufrufen kann; Access beschreibt, wie externe Clients sich damit verbinden. -[Native Chat-Oberfläche — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -ist das kanonische Zuhause für die Ereignisformen, die Laufzeithelfer und `chatUI` -Tool-Ergebnis-Metadaten. Beginnen Sie dort, wenn Sie einen externen Agenten in den Chat einbinden. +Noch nicht enthalten: -## Eingebetteter Sidecar {#embedded-sidecar} +- Organisationsweite Ansicht +- Berechtigungen und Scope-Bearbeitung +- Widerrufs-UI +- Herkunftsverlauf pro Iteration -Verwenden Sie den eingebetteten Sidecar, wenn das Hauptprodukt bereits vorhanden ist und Sie ein möchten -Agent daneben. +## Embedded Sidecar {#embedded-sidecar} -Das Server-Plugin stellt Agent-Native-Routen in Ihre Host-App ein und löst sie auf -Hostidentität serverseitig: +Verwenden Sie den Embedded Sidecar, wenn das Hauptprodukt bereits existiert und Sie einen +Agenten daneben haben möchten. + +Das Server-Plugin bindet Agent-Native-Routen in Ihre Host-App ein und löst +Host-Identität serverseitig auf: ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -410,7 +277,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -Der Sidecar React übergibt Seitenkontext und Hostbefehle: +Der React-Sidecar übergibt Seitenkontext und Host-Befehle: ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -432,19 +299,23 @@ export function AppShell({ children }) { } ``` - +### Wie es sich verbindet + +Die zwei Teile arbeiten als Brücke: Die Host-App übergibt Seitenkontext (aktuelle Route, ausgewählter Text, fokussiertes Objekt) an `AgentNativeEmbedded`, und der Agent sendet Befehle über `onNavigate` und `onRefresh` zurück. Das Server-Plugin übernimmt die Identität — es löst die Host-Session auf, damit der Agent als der richtige Benutzer agiert, ohne separaten Login. Nichts in der Host-App muss geändert werden; das Plugin bindet Agent-Native-Routen neben Ihren bestehenden ein. + + ```html
- Host-AppIhr vorhandenes SaaS + Host appyour existing SaaS
- getContext()
Route · Auswahl + getContext()
route · selection
onNavigate / onRefresh
Host-Befehlehost commands
@@ -454,9 +325,9 @@ export function AppShell({ children }) {
AgentNativeEmbeddedagent + workspace + >agent + resources
- Agent-Native-Routen
mounted by the server plugin
@@ -491,45 +362,221 @@ export function AppShell({ children }) { -Informationen zur Hostauthentifizierung, Datenbankisolation finden Sie unter [Embedding SDK](/docs/embedding-sdk). -Iframe/Picker-Modus und untergeordnete Bridge APIs. +Siehe [Embedding SDK](/docs/embedding-sdk) für Host-Authentifizierung, Datenbankisolation, +iFrame/Picker-Modus und niederstufigere Bridge-APIs. -## Vollständige Bewerbung {#full-application} +## Automation-first-App {#headless} -Verwenden Sie den vollständigen App-Pfad, wenn Benutzer dauerhafte Objekte und Arbeitsabläufe benötigen: Formulare, -Dashboards, Kalender, Posteingänge, Editoren, Dokumente, Assets oder Berichte. +Verwenden Sie den Automation-first-Pfad, wenn niemand einen benutzerdefinierten Browser-Bildschirm benötigt, während +die Arbeit läuft: geplante Jobs, Integrationen, Backend-Workflows, CLI-Schleifen, +ein anderer Agent oder ein bestehendes Produkt, das Agent-Native aufruft. + +Dies ist das Muster für den Fall, dass Automatisierung die Produktoberfläche ist. Sie senden eine Anfrage vom Terminal, Slack, E-Mail, einem geplanten Job, einem anderen Agenten oder Chat („fasse meine ungelesenen E-Mails zusammen", „poste die täglichen Metriken zu Slack", „finde die Kandidaten, die letzte Woche geantwortet haben") und der Agent handelt und gibt das Ergebnis zurück, wo es hingehört. Es ist immer noch eine echte App, kein zustandsloser Prompt: +Aktionen, Auth-Sessions, App-Zustand, Thread-/Run-Verlauf, Einstellungen, Anmeldeinformationen +und Share-Einträge leben alle in SQL. + +Wählen Sie dieses Muster, wenn: + +- **Die Arbeit im Hintergrund stattfindet.** Der Großteil des Wertes wird geschaffen, während der Benutzer nicht schaut: Triage-Agenten, tägliche Berichts-Agenten, Bereitschafts-Responder. +- **Die Ausgabe die App verlässt.** Der Agent postet zu Slack, sendet E-Mails oder aktualisiert ein Drittanbietersystem; es gibt nichts In-App zu durchsuchen. +- **Die Domäne einmalig ist.** Recherche-Bot, Zusammenfassungs-Generator, Berichtsschreiber ohne dauerhaftes Objekt, das eine Listenansicht braucht. +- **Sie eine Automatisierung prototypisieren.** Liefern Sie die Operation jetzt; fügen Sie Chat oder App-Seiten hinzu, wenn Benutzer sie inspizieren und steuern müssen. + +Wenn Ihr Produkt rund um persistente Objekte aufgebaut ist, die Benutzer durchsuchen, pivotieren und teilen (E-Mails, Ereignisse, Dokumente, Diagramme), wählen Sie stattdessen eine [vollständige Anwendung](#full-application) oder ein [Template](/docs/cloneable-saas); diese fügen eine vollständige UI _plus_ den Agenten hinzu. + +### Was im Lieferumfang enthalten ist {#in-the-box} + +Eine Automation-first-App überspringt Dashboard-Arbeit und ist von Anfang an kanalunabhängig. Derselbe Agent läuft vom Web, Slack, Telegram, E-Mail und anderen Agenten aus, weil alles durch dieselben Aktionen geht. Der Kompromiss ist, dass es keine „Alles-auf-einen-Blick"-Ansicht gibt; wenn Benutzer das benötigen, starten Sie von [Chat](/docs/template-chat) oder fügen Sie eine kleine Status-Seite oder Listenansicht hinzu. + +Wenn Sie die integrierte Chat-Hülle hinzufügen, bietet das Framework fünf Verwaltungsoberflächen, die Sie nicht selbst bauen müssen: **Chat** (die Haupteingabe), **Resources** (Skills, Speicher, Anweisungen, Sub-Agenten und verbundene MCP-Server), **Automations**, **Thread-Verlauf** und **Settings**. Das ist normalerweise genug: mit ihm sprechen, sehen was er getan hat, konfigurieren wie er sich verhält. Greifen Sie auf [Chat](/docs/template-chat) zurück, wenn Sie bereit sind, diese Browser-UI hinzuzufügen, oder das [Dispatch-Template](/docs/template-dispatch) für einen workspace-ähnlichen Startpunkt mit Slack/Telegram, geplanten Jobs und gemeinsamen Secrets out of the box. + +Der kleinste No-Browser-Lokalpfad ist ein Scaffold plus eine Aktion: + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +Dann die dauerhafte Operation definieren: + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +Eine Aktion ist dann aufrufbar als: + +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **App-Agenten-CLI:** `pnpm agent "Summarize form_123"` +- **MCP:** von Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot und anderen MCP-Hosts +- **A2A:** von einer anderen agent-native App oder einem Agent-Peer +- **UI:** über `useActionQuery`, `useActionMutation` oder `callAction` +- **Agenten-Tool:** aus der integrierten Chat-Schleife + + + +Jedes `defineAction` wird automatisch unter `/_agent-native/actions/` eingebunden. Der JSON-Body wird gegen das Zod-Schema der Aktion validiert, bevor `run` ausgeführt wird. Um es von einem externen System mit einem langlebigen Bearer-Token aufzurufen, siehe [HTTP API](/docs/http-api). + + + +Dies ist kein datenbankloser oder zustandsloser Modus. Die App-Agenten-Schleife speichert Sessions, +Threads, Runs, Einstellungen, Anmeldeinformationen, Anwendungszustand und Share-Einträge in +SQL. Die lokale Entwicklung verwendet standardmäßig SQLite; gehostete Automation-first-Apps sollten +eine persistente SQL-Datenbank verwenden. + +Wenn Sie die gesamte Agentenschleife headless aus dem Projektordner benötigen, verwenden Sie: + +```bash +pnpm agent "Summarize this week's forms." +``` + +Wenn eine andere App oder ein Skript die gesamte Agentenschleife aufrufen muss, verwenden Sie +`agentNative.invoke("analytics", "...")` oder die `agent-native invoke`-CLI. Das +hält cross-App-Arbeit auf dem A2A-Pfad, während lokale Arbeit bei Aktionen bleibt. + +Worker, Jobs, Integrations-Webhooks und benutzerdefinierte Hosts können die Agentenschleife +direkt über die Server-API steuern. Dies ist niederstufiger als Aktionen — Sie stellen +Engine, Modell, Nachrichten, Tools, Aktionen, einen Event-Sink und ein Abbruchsignal +selbst bereit: + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +Für die meisten Apps rufen geplante Prompts und Integrations-Webhooks diese Schleife bereits +für Sie auf. Greifen Sie direkt darauf zurück nur beim Bauen eines benutzerdefinierten No-Browser-Hosts, Eval- +Runners oder einer serverseitigen Orchestrierungsoberfläche. Siehe [Server: Produktions-Agenten-Handler](/docs/server#agent-handler) für die vollständige Signatur. + +### Gegen einen Ordner ausführen {#folder-loop} + +Wenn Ihr Ziel ist „einen Agenten gegen diesen Ordner ausführen", starten Sie mit der App-Agenten- +Schleife in diesem Ordner: erstellen Sie das Automation-first-App-Scaffold, fügen Sie Aktionen/Anweisungen hinzu, führen Sie +`pnpm agent "..."` aus. Das hält die Arbeit im selben Aktions-/Runtime-/Zustandsvertrag, +den die App in der Produktion verwenden wird. + +Externe Coding-Harnesses sind eine separate Produktoberfläche zum Einbetten von Claude +Code, Codex, Pi, Cursor, Mastra oder ähnlichen Runtimes in eine Agent-Native-App. +Verwenden Sie sie, wenn Sie ein Coding-Agenten-Produkt bauen, nicht als Standardweg zum +Starten eines lokalen agent-native-Workflows. + +### Cloud-Repository-Zugriff {#cloud-repo-access} + +Für Cloud-Automation-first-Apps, die Repository-Zugriff benötigen, verwenden Sie den GitHub-Connector +plus Token-CRUD-Modell: Repositories auflisten, Dateien suchen, Dateien lesen, Dateien erstellen oder +bearbeiten, Dateien löschen und Zugriff durch anbieterspezifische +Anmeldeinformationen widerrufen. In der lokalen Entwicklung legen Sie das Ziel-Repository explizit fest: + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +Behandeln Sie keinen VM-Klon oder eine langlebige Sandbox-Checkout als primäres Cloud- +Repository-Zugriffsmodell. Sandboxes sind weiterhin wichtig für isolierte Code-Ausführung, aber +Repository-Zugriff sollte explizit, berechtigt, nachvollziehbar und widerrufbar durch +die Connector-Schicht sein. + +### Sessions und Runs teilen {#sharing-runs} + +Automation-first-Sessions und Runs sind dauerhafte Objekte. Teilbarkeit sollte +phasenweise erfolgen: zuerst Lese-/Share-Links, damit Teammitglieder bereinigte Prompts, +Ausgaben und Run-Status inspizieren können; später berechtigte beschreibbare Zusammenarbeit, damit +das Fortsetzen eines Runs, Genehmigen von Aktionen, Bearbeiten von Zeitplänen oder Ändern von +Konfigurationen explizite Zugriffsüberprüfungen durchlaufen. + +## Rich-Chat auf Ihrem Agenten {#byo-agent} + +Verwenden Sie diesen Pfad, wenn Ihr Agent bereits mit einem anderen Framework oder +einer anderen Runtime erstellt wurde und Sie die Chat-UI von Agent-Native drumherum möchten. `AgentChatRuntime` ist die +Grenze: Ihre Runtime streamt normalisierte Events, und Agent-Native rendert den +Eingabebereich, Transkript, Tool-Aufrufe, Genehmigungen, native Widgets und das App-Layout. + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` + +Fertige Runtime-Helfer existieren für OpenAI Agents, OpenAI Responses, das Claude +Agent SDK, das Vercel AI SDK und AG-UI, sowie die oben genannte normalisierte HTTP-Runtime +für jeden anderen Agenten (Mastra, Flue, Eve, LangGraph oder einen benutzerdefinierten Service). ACP ist +nicht der Endbenutzer-App-Chat oder A2A-Transport, und Agent-Native behauptet derzeit keine A2UI-Unterstützung. ACP wird an einem spezifischen Ort unterstützt: das Steuern eines lokalen +Coding-Agenten (Gemini CLI, Claude Code, …) über die +[Harness-Schicht](/docs/harness-agents#acp), nicht als Chat-Runtime hier. + +[Native Chat UI: BYO-Agent-Runtimes](/docs/native-chat-ui#byo-agent-runtimes) +ist das kanonische Zuhause für die Event-Formen, die Runtime-Helfer und `chatUI` +Tool-Ergebnis-Metadaten. Beginnen Sie dort beim Verdrahten eines externen Agenten in den Chat. + +## Was als nächstes kommt {#related-docs} + + + +### [Aktionen](/docs/actions) + +Die Operation einmal definieren. Jede obige Oberfläche ruft dieselbe auf. + +### [Native Chat UI](/docs/native-chat-ui) + +Typisierte Aktionsergebnisse als Tabellen, Diagramme und Karten direkt im Chat rendern. + +### [Generative UI](/docs/generative-ui) -Vollständige Apps fügen das Produkt UI mit derselben Aktion und demselben Agentenvertrag hinzu: +Transiente oder persistierte sandgeboxte UI inline im Chat generieren. -- **SQL-Status** – App-Daten, Navigation, Einstellungen und Chat-Verlauf sind dauerhaft. -- **Kontextbewusstsein** – der Agent kennt die aktuelle Route, Auswahl und das fokussierte Objekt. -- **Live-Synchronisierung** – Agentenänderungen aktualisieren den UI, und UI-Änderungen aktualisieren den Kontext des Agenten. -- **Deep Links** – Aktionsergebnisse können die richtige App-Ansicht öffnen. -- **Native Chat-Widgets** – Tabellen, Diagramme, Karten, Genehmigungen und eingegebene Ergebnisse werden inline angezeigt. +### [Automation-First-Apps](/docs/pure-agent-apps) -Beginnen Sie mit [Chat template](/docs/template-chat), wenn Sie eine minimale App wünschen -um Ihr actions oder von einer Domäne [template](/docs/cloneable-saas), wenn Sie -Sie möchten eine vollständige Produktform. +Das vollständige No-Browser-Muster für Jobs, Queues, Skripte und externe Agenten. -## So wählen Sie aus {#how-to-choose} +### [Externe Agenten](/docs/external-agents) -| Wenn Sie denken... | Auswählen | -| --------------------------------------------------------------------------------------- | ---------------------------- | -| „Ich brauche nur ein aufrufbares Tool oder einen Workflow.“ | Kopfloser Agent | -| „Ich möchte den Agenten des Frameworks, aber Chat sollte der Haupt-UI sein.“ | Rich-Chat auf Agent-Native | -| „Ich habe bereits einen Agenten; dafür brauche ich einen ausgefeilten Chat-Oberfläche.“ | Rich-Chat über Ihren Agenten | -| „Ich habe bereits eine SaaS-App. Fügen Sie daneben einen Agenten hinzu.“ | Eingebetteter Sidecar | -| „Der Agent und UI sollten sich gemeinsam als Produkt weiterentwickeln.“ | Vollständige Bewerbung | +MCP-kompatible Hosts als Tool-Server mit Ihrer App verbinden. -Halten Sie den Vertrag klein: Definieren Sie dauerhafte Operationen als actions, geben Sie explizit zurück -Widget-Ergebnisse, wenn der Chat umfangreiches UI benötigt, und Vollbildanzeigen nur hinzufügen, wenn Benutzer -müssen persistente Objekte durchsuchen, vergleichen, konfigurieren oder zusammenarbeiten. +### [A2A-Protokoll](/docs/a2a-protocol) -## Wie geht es weiter? {#related-docs} +Agenten von anderen agent-native Apps über den A2A-Standard aufrufen. -- [**Actions**](/docs/actions) – Definieren Sie den Vorgang einmal; jede Oberfläche oben ruft denselben auf -- [**Native Chat-Oberfläche**](/docs/native-chat-ui) – Typisierte Aktionsergebnisse als Tabellen, Diagramme und Karten im Chat rendern -- [**Generative UI**](/docs/generative-ui) – Temporäre oder persistierte Sandbox-UI direkt im Chat generieren -- [**Automation-First Apps**](/docs/pure-agent-apps) – Das vollständige browserlose Muster für Jobs, Warteschlangen, Skripte und externe Agenten -- [**External Agents**](/docs/external-agents) – MCP-kompatible Hosts mit einer App verbinden -- [**A2A Protocol**](/docs/a2a-protocol) – Agenten aus anderen Agent-Native-Apps aufrufen + diff --git a/packages/core/docs/content/locales/es-ES/agent-surfaces.mdx b/packages/core/docs/content/locales/es-ES/agent-surfaces.mdx index 9e5ae98f46..b93b420ca8 100644 --- a/packages/core/docs/content/locales/es-ES/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/es-ES/agent-surfaces.mdx @@ -1,95 +1,47 @@ --- title: "Superficies del agente" -description: "Utilice Agent-Native sin cabeza, como chat enriquecido, dentro de una aplicación existente o como una aplicación nativa completa del agente." -search: "aplicación completa de chat enriquecido de agente sin cabeza BYO tiempo de ejecución del agente AgentChatRuntime incrustado actions MCP A2A HTTP CLI" +description: "Elige cómo una aplicación agéntica crece desde el chat hacia la interfaz de usuario integrada, páginas de aplicación duraderas, sidecars embebidos, automatización y acceso de agentes externos." +search: "aplicación agéntica chat enriquecido chat nativo interfaz de usuario completa automatización headless BYO agent runtime AgentChatRuntime embeber acciones MCP A2A HTTP CLI" --- -# Superficies de agentes +# Superficies del agente -## Espacio de trabajo completo del agente {#agent-page} +Una **superficie** es la forma en que los usuarios (u otros sistemas) interactúan con tu aplicación: una ventana de chat, una página de panel, un trabajo en segundo plano, una llamada a la API desde otro agente. Agent-Native te permite combinar estas superficies sin reconstruir la lógica central, porque cada superficie ejecuta las mismas acciones subyacentes. Si eres nuevo en Agent-Native, lee primero [Conceptos clave](/docs/key-concepts). -Cuando una aplicación completa necesita un lugar permanente para inspeccionar y -configurar su agente, monta `AgentTabsPage` en `/agent`. Añade la ruta a la -navegación de la aplicación y pasa `agentPageHref="/agent"` a `AgentSidebar` para -que los modos Resources y Settings enlacen a la página completa sin duplicar -estos flujos. +## Cómo se relacionan las superficies entre sí -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -La página compartida ofrece actualmente cinco pestañas: - -- **Context** — vista previa del ámbito, presupuesto de tokens, secciones de sistema ordenadas con procedencia y gobierno, vista de lista/treemap y la instantánea del hilo activo más reciente. -- **Files** — vuelve a alojar `ResourcesPanel` para recursos personales o de la organización. -- **Connections** — gestión de servidores MCP y lista de agentes remotos A2A: lo que puede llamar el agente de esta aplicación. -- **Automations** — automatizaciones personales y de organización Scheduled y Event con pausa/reanudación, detalles y eliminación. La URL de compatibilidad sigue siendo `/agent#jobs`. -- **Access** — URL de MCP, tarjeta de agente A2A cuando existe y guías de configuración compartidas; el flujo completo y el token alternativo están en `/mcp/connect`. +Las cuatro formas principales de producto se sitúan en un espectro que va desde lo más interactivo hasta completamente headless. Lo que las hace componibles es que la base permanece igual en todo momento: las mismas acciones, la misma base de datos SQL y el mismo bucle del agente impulsan cada forma. Añadir una nueva superficie no significa reescribir lo que hay debajo — solo estás añadiendo una nueva forma de acceder a las mismas operaciones. -La página usa actualmente el ámbito personal y no ofrece un selector -**Personal / Organization** para toda la página. Una pestaña puede mostrar sus -propias secciones de organización cuando las acciones subyacentes las admiten: -**Automations** muestra secciones personales y de organización para Scheduled -y Event. Las automatizaciones Event de la organización siempre se ejecutan -como su creador. La página es una capa fina sobre componentes, acciones y -comprobaciones existentes, no una nueva consola de administración. - -Agent-Native es deliberadamente componible. Puedes utilizar el agente sin mucho UI, -use el UI sin el tiempo de ejecución del agente integrado, o use ambos juntos como un completo -solicitud. - -La forma útil de elegir no es primero mediante el protocolo. Elige la superficie del producto -lo que quieras, entonces usa la primitiva coincidente. - -| Superficie | Úselo cuando | Empezar con | -| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **Agente sin cabeza** | El código, los trabajos, los scripts, otra aplicación u otro agente deben llamar al trabajo directamente. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Chat enriquecido en Agent-Native** | Quiere un chat independiente o integrado respaldado por el bucle de agente integrado. | [Chat template](/docs/template-chat), ``, `` | -| **Chat enriquecido con tu agente** | Creaste el agente en otro lugar y quieres el compositor, la transcripción, las tarjetas de herramientas y los widgets nativos de Agent-Native. | `AgentChatRuntime`, `` | -| **Sidecar integrado** | Ya tienes una aplicación SaaS y quieres un agente junto a ella con contexto de página y comandos de host. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **Solicitud completa** | Los seres humanos y los agentes deben compartir pantallas, datos, navegación y colaboración duraderos. | Plantillas, estado actions, estado SQL, conocimiento del contexto | - -Esas son etapas, no productos separados. Un flujo de trabajo puede comenzar sin cabeza -agente con una acción, aparece en el chat como una tabla o gráfico y luego se convierte en -pantalla completa en una aplicación sin cambiar la operación que llama el agente. - - + ```html
- HeadlessChatactions, trabajos, scripts, otros agentescompositor, transcripción, llamadas a herramientas
- Chat enriquecidocompositor, transcripción, tarjetas de herramientas + Interfaz de usuario integradatablas, gráficos, tarjetas
- Sidecar integradoagent beside an existing app + Página de aplicaciónpantallas duraderas, datos SQL
- la mayor parte del UIAplicación completapantallas duraderas, datos, colaboración + headlessAutomatizacióntrabajos, scripts, agentes externos
mismas actions · mismo SQL · mismo bucle de agentemismas acciones · mismo SQL · mismo bucle del agente
``` @@ -123,180 +75,32 @@ pantalla completa en una aplicación sin cambiar la operación que llama el agen -## Agente sin cabeza {#headless} - -Utilice la ruta sin cabeza cuando nadie necesite mirar la pantalla de una aplicación personalizada mientras -el trabajo se ejecuta: trabajos programados, integraciones, flujos de trabajo backend, bucles CLI, -otro agente o un producto existente llamando a Agent-Native. - -Esta es también la forma a adoptar cuando **el agente _es_ el producto**: el -El bucle aplicación-agente es la puerta de entrada, no un tablero. Envías una solicitud desde el -terminal, Slack, correo electrónico, un trabajo programado, otro agente o Chat — "resumir mi -correos electrónicos no leídos", "publicar las métricas diarias en Slack", "encontrar los candidatos que -respondió la semana pasada" — y el agente actúa y devuelve el resultado dondequiera que esté -pertenece. Sigue siendo una aplicación real, no un mensaje sin estado: actions, sesiones de autenticación, -Estado de la aplicación, historial de subprocesos/ejecuciones, configuración, credenciales y registros compartidos, todo en vivo -en SQL. - -Elija este patrón cuando: - -- **El trabajo se realiza en segundo plano.** La mayor parte del valor se crea mientras el usuario no está mirando: agentes de clasificación, agentes de informes diarios, socorristas de guardia. -- **El resultado sale de la aplicación.** El agente publica en Slack, envía correo electrónico o actualiza un sistema de terceros; no hay nada para explorar en la aplicación. -- **El dominio es de una sola vez.** Bot de investigación, generador de resúmenes, redactor de informes: no hay ningún objeto persistente que necesite una vista de lista. -- **Estás creando un prototipo.** Envíe el agente ahora; agregue un UI más rico más adelante si los usuarios lo desean. - -Si su producto se basa en objetos persistentes, los usuarios exploran, pivotan y -compartir: correos electrónicos, eventos, documentos, gráficos: elija un [full application](#full-application) -o un [template](/docs/cloneable-saas) en su lugar; estos agregan un UI completo _más_ el agente. - -### Qué se envía en la caja {#in-the-box} - -Una aplicación headless evita semanas de trabajo en el panel y es independiente del canal desde el día -uno: el mismo agente se ejecuta desde la web, Slack, Telegram, correo electrónico y otros agentes -porque todo pasa por el agente, no por el UI. La contrapartida es que -sin vista para "navegar todo de un vistazo"; si los usuarios lo necesitan, mezcle patrones y -agregue una pequeña página de estado o vista de lista. - -Cuando agrega el shell de Chat integrado, el marco proporciona cinco funciones de administración -superficies que no tienes que construir: **Chat** (la entrada principal), **Espacio de trabajo** -(skills, memoria, instrucciones, subagentes, servidores MCP conectados, programados -trabajos), **Historial de trabajos**, **Historial de subprocesos** y **Configuración**. Esos suelen ser -suficiente: habla con él, mira qué hace, configura cómo se comporta. Alcanzar -[Chat](/docs/template-chat) cuando esté listo para agregar ese navegador UI, o el -[Dispatch template](/docs/template-dispatch) para un inicio estilo espacio de trabajo -punto con Slack/Telegram, trabajos programados y secretos compartidos listos para usar. - -La ruta local más pequeña es una estructura de agente sin cabeza más una acción: - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -Luego defina la operación duradera: - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -Una acción es entonces invocable como: +## Elige un punto de partida -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **Agente de aplicaciones CLI** — `pnpm agent "Summarize form_123"` -- **MCP**: de Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot y otros hosts MCP -- **A2A**: desde otra aplicación nativa del agente o agente igual -- **UI**: hasta `useActionQuery`, `useActionMutation` o `callAction` -- **Herramienta de agente**: desde el bucle de chat integrado +El chat es el punto de entrada más común. Las aplicaciones suelen añadir interfaz de usuario integrada a medida que el resultado se enriquece, y luego añaden páginas de aplicación completas cuando los usuarios necesitan objetos persistentes para explorar y compartir. Las mismas acciones impulsan los botones, los trabajos programados y los agentes externos que vienen después. Usa el sidecar embebido cuando añadas un agente a un producto que ya posees, o el modo Automatización-primero para trabajos que se ejecutan sin un navegador. Aquí está el panorama completo: - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -Este no es un modo sin base de datos ni sin estado. El bucle app-agent almacena sesiones, -procesos, ejecuciones, configuraciones, credenciales, estado de la aplicación y registros compartidos en -SQL. El desarrollo local por defecto es SQLite; las aplicaciones sin cabeza alojadas deben utilizar un -base de datos persistente SQL. - -Si necesita todo el bucle del agente sin cabeza desde la carpeta del proyecto, utilice: - -```bash -pnpm agent "Summarize this week's forms." -``` - -Si otra aplicación o script necesita llamar a todo el agente, utilice -`agentNative.invoke("analytics", "...")` o `agent-native invoke` CLI. Eso -mantiene el trabajo entre aplicaciones en la ruta A2A mientras que el trabajo local permanece en actions. - -Los trabajadores, los trabajos, la integración webhooks y los hosts personalizados pueden impulsar el ciclo del agente -directamente a través del servidor API. Este es un nivel inferior al de actions: usted proporciona -el motor, el modelo, los mensajes, actions y el receptor de eventos usted mismo: - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -Para la mayoría de las aplicaciones, las indicaciones programadas y la integración webhooks ya llaman a este bucle -para ti. Consíguelo directamente solo cuando crees un host sin cabeza personalizado, eval -ejecutor o superficie de orquestación del lado del servidor; consulte [Servidor: agente de producción -handler](/docs/server#agent-handler) para obtener la firma completa. - -### Ejecutando en una carpeta {#folder-loop} - -Si su objetivo es "ejecutar un agente en esta carpeta", comience con el agente de aplicación -bucle en esa carpeta: cree scaffolding en la aplicación headless, agregue actions/instrucciones, ejecute -`pnpm agent "..."`. Eso mantiene el trabajo dentro de la misma acción/tiempo de ejecución/estado -contrato que la aplicación utilizará en producción. - -Los arneses de codificación externos son una superficie de producto separada para incrustar Claude -Código, Codex, Pi, Cursor, Mastra o tiempos de ejecución similares dentro de una aplicación Agent-Native. -Utilízalos cuando estés creando un producto de agente de codificación, no como forma predeterminada -iniciar un flujo de trabajo nativo del agente local. - -### Acceso al repositorio en la nube {#cloud-repo-access} - -Para aplicaciones headless en la nube que necesitan acceso al repositorio, utilice el conector GitHub -Modelo plus token CRUD: enumerar repositorios, buscar archivos, leer archivos, crear o -editar archivos, eliminar archivos y revocar el acceso a través del ámbito del proveedor -credenciales. En desarrollo local, establezca el repositorio de destino explícitamente: - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -No trate un clon de VM o un checkout de zona de pruebas de larga duración como la nube principal -modelo de acceso al repositorio. Los entornos sandbox siguen siendo importantes para la ejecución de código aislado, pero -el acceso al repositorio debe ser explícito, autorizado, auditable y revocable -a través de la capa del conector. - -### Compartir sesiones y ejecuciones {#sharing-runs} - -Las sesiones y ejecuciones sin cabeza son objetos duraderos. La compartibilidad debe realizarse por etapas: -leer/compartir enlaces primero, para que los compañeros de equipo puedan inspeccionar mensajes y resultados desinfectados -y estado de ejecución; colaboración con permiso de escritura más adelante, por lo que continuaremos ejecutando, -aprobar actions, editar horarios o cambiar la configuración pasa por el proceso -comprobaciones de acceso explícitas. +| Superficie | Úsala cuando | Comienza con | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | +| **[Chat enriquecido](#rich-chat)** | Los usuarios hablan con el agente, ven las llamadas a herramientas y mantienen un historial de hilo. | [Plantilla de chat](/docs/template-chat), `` | +| **[Interfaz de usuario nativa integrada](#native-inline-ui)** | Los resultados de las acciones deben renderizarse como tablas, gráficos, tarjetas o aprobaciones en el chat. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[Interfaz de usuario generada integrada](#generated-inline-ui)** | El agente debe crear controles temporales o reutilizables dentro del chat sobre la marcha. | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[Aplicación completa](#full-application)** | Los usuarios necesitan pantallas duraderas, datos compartidos, navegación y colaboración. | Plantillas, acciones, estado SQL, reconocimiento de contexto | +| **[Sidecar embebido](#embedded-sidecar)** | Ya tienes una aplicación SaaS y quieres un agente junto a ella con contexto de página. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[Automatización-primero](#headless)** | Trabajos, scripts u otros agentes llaman al trabajo directamente sin interfaz de usuario en el navegador. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[Chat enriquecido sobre tu agente](#byo-agent)** | Construiste el agente en otro lugar y quieres la interfaz de chat de Agent-Native a su alrededor. | `AgentChatRuntime`, `` | ## Chat enriquecido en Agent-Native {#rich-chat} -Utilice el chat integrado cuando el usuario deba hablar con el agente, consulte llamadas a herramientas, -aprobar el trabajo, inspeccionar los resultados nativos y mantener un historial duradero de los hilos. +Usa el chat integrado cuando el usuario deba hablar con el agente, ver las llamadas a herramientas, +aprobar trabajo, inspeccionar resultados nativos y mantener un historial de hilo duradero. -Para obtener un punto de partida completo de la aplicación, utilice [Chat template](/docs/template-chat): +Para un punto de partida de aplicación completa, usa la [Plantilla de chat](/docs/template-chat): ```bash npx @agent-native/core@latest create my-chat-app --template chat ``` -El chat de página completa más simple: +El chat de página completa más sencillo: ```tsx import { AgentChatSurface } from "@agent-native/core/client/chat"; @@ -306,11 +110,10 @@ export default function ChatRoute() { } ``` -Cuando una aplicación tiene una pestaña de chat de página completa y un `AgentSidebar`, usa lo mismo -`storageKey` en ambas superficies, habilite `chatViewTransition` e instale -ayudantes de transferencia de chat a casa en el diseño. Enlaces normales dentro de la aplicación fuera del chat -La página puede transformar el chat completo en la barra lateral mientras mantiene activo -tema: +Cuando una aplicación tiene tanto una pestaña de chat de página completa como un `AgentSidebar`, usa la misma +`storageKey` en ambas superficies, habilita `chatViewTransition` e instala los +asistentes de transferencia chat-home en el diseño. Los enlaces normales dentro de la aplicación fuera de la página +de chat pueden entonces transformar el chat completo en la barra lateral mientras mantienen el hilo activo: ```tsx import { @@ -348,7 +151,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -El chat integrado más simple con tu propio Chrome: +El chat embebido más sencillo con tu propio chrome: ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -358,51 +161,115 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -Actions puede devolver resultados explícitos del widget nativo para que la salida del chat no sea solo -texto. Las tablas, gráficos y tarjetas de productos escritas se representan como React propio -componentes en el chat, sin iframes. Ver [Native Interfaz de chat](/docs/native-chat-ui). +Las acciones pueden devolver resultados de widgets nativos explícitos para que la salida del chat no sea solo +texto. Tablas, gráficos y tarjetas de producto tipadas se renderizan como componentes React de primera clase +en el chat, sin iframes. Consulta [Native Chat UI](/docs/native-chat-ui). +Cuando el agente necesita controles generados arbitrariamente en lugar de un +widget React predefinido, usa [Generative UI](/docs/generative-ui): renderiza interfaz de usuario Alpine/Tailwind +aislada en línea, puede leer el estado de la aplicación y el contexto del slot, y puede enviar +los valores seleccionados de vuelta al chat. -## Chat enriquecido con tu agente {#byo-agent} +## Interfaz de usuario nativa integrada {#native-inline-ui} -Utilice esta ruta cuando su agente ya esté creado con otro marco o -tiempo de ejecución y desea que el chat UI de Agent-Native lo rodee. `AgentChatRuntime` es el -límite: su tiempo de ejecución transmite eventos normalizados y Agent-Native representa el -compositor, transcripción, llamadas de herramientas, aprobaciones, widgets nativos y diseño de aplicaciones. +Úsala cuando tus acciones devuelvan datos estructurados — una lista de registros, un conjunto de datos de gráfico, un resumen de estado — que deban renderizarse como un componente de interfaz de usuario real dentro del hilo de chat en lugar de una descripción de texto simple. Defines un renderizador `chatUI` en la acción, y Agent-Native lo renderiza como un componente React de primera clase: sin iframes, sin ruta de renderizado separada. -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +Esta es la elección correcta cuando la salida tiene una forma clara y reutilizable que diseñarías una vez y usarías en muchas respuestas del agente. Para controles que el agente necesita crear dinámicamente en tiempo de ejecución, consulta [Interfaz de usuario generada integrada](#generated-inline-ui) en su lugar. -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +Consulta [Native Chat UI](/docs/native-chat-ui) para la API completa del renderizador, la biblioteca de widgets y la integración del runtime de agente BYO. -export function SupportAgentChat() { - return ; +## Interfaz de usuario generada integrada {#generated-inline-ui} + +Úsala cuando el agente necesite crear un control que aún no existe como widget preconstruido — un formulario personalizado, un selector construido alrededor del contexto actual, una calculadora de uso único. A diferencia de los widgets nativos, la interfaz de usuario generada es compuesta por el agente en tiempo de ejecución usando Alpine.js y Tailwind, se ejecuta aislada en un iframe y puede enviar los valores seleccionados de vuelta al hilo de chat. + +La interfaz de usuario generada puede ser transitoria (renderizada una vez y descartada) o guardada como una extensión reutilizable que persiste para el usuario. + +Consulta [Generative UI](/docs/generative-ui) para la API completa, las restricciones del sandbox y el modelo de persistencia de extensiones. + +## Aplicación completa {#full-application} + +Usa la ruta de aplicación completa cuando los usuarios necesiten objetos y flujos de trabajo duraderos: formularios, +paneles, calendarios, bandejas de entrada, editores, documentos, activos o informes. + +Las aplicaciones completas añaden interfaz de usuario de producto alrededor del mismo contrato de acción y agente: + + + +### Estado SQL + +Los datos de la aplicación, la navegación, la configuración y el historial de chat son todos duraderos. El agente lee y escribe las mismas filas que hace la interfaz de usuario. + +### Reconocimiento de contexto + +El agente conoce la ruta actual, la selección y el objeto enfocado, por lo que "editar esto" siempre significa lo correcto. + +### Sincronización en vivo + +Los cambios del agente actualizan la interfaz de usuario en tiempo real, y los cambios de la interfaz de usuario actualizan el contexto del agente. Sin sondeo, sin actualización. + +### Vínculos profundos + +Los resultados de las acciones pueden abrir directamente la vista correcta de la aplicación: un gráfico enlaza al panel, un borrador enlaza a la bandeja de entrada. + +### Widgets de chat nativos + +Tablas, gráficos, tarjetas, aprobaciones y resultados tipados se renderizan como componentes React de primera clase en línea en el chat. + +### Interfaz de usuario generativa y extensiones + +El agente puede crear controles en línea sobre la marcha y guardar mini-aplicaciones reutilizables cuando un flujo de trabajo necesita persistir. + + + +Comienza desde la [Plantilla de chat](/docs/template-chat) cuando quieras una aplicación mínima +alrededor de tus acciones, o desde una [plantilla](/docs/cloneable-saas) de dominio cuando quieras +una forma de producto completa. + +### Gestión del agente en página completa {#agent-page} + +Toda aplicación Agent-Native eventualmente necesita un lugar donde los usuarios puedan configurar su agente: establecer instrucciones permanentes, revisar lo que ha hecho, conectar servidores MCP, gestionar automatizaciones y controlar el acceso. Construir esa interfaz de usuario desde cero es mucho trabajo. Agent-Native incluye un componente de página completa preconstruido, `AgentTabsPage`, que cubre todo esto en doce pestañas. + +Móntalo en `/agent` en tu aplicación. Las plantillas actuales emparejan esa ruta con una entrada de navegación de la aplicación y pasan `agentPageHref="/agent"` a `AgentSidebar`, para que los modos Recursos y Configuración de la barra lateral puedan enlazar a la página completa sin duplicar esos flujos. + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -Existen ayudas de tiempo de ejecución listas para usar para los agentes OpenAI, las respuestas de OpenAI y el Claude -Agent SDK, Vercel AI SDK y AG-UI, además del tiempo de ejecución normalizado de HTTP anterior -para cualquier otro agente (Mastra, Flue, Eve, LangGraph o un servicio personalizado). ACP es -no es el chat de la aplicación del usuario final ni el transporte A2A, y Agent-Native no lo hace actualmente -reclama soporte para A2UI. ACP se admite en un lugar específico: conducir un local -agente de codificación (Código Gemini CLI, Claude,…) a través del -[harness layer](/docs/harness-agents#acp), no como tiempo de ejecución del chat aquí. +La página compartida actualmente proporciona doce pestañas en dos grupos: + +| Grupo | Pestaña | Muestra | +| -------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Recursos | **Files** | El `ResourcesPanel` existente para archivos personales o de la organización | +| Recursos | **Instructions** | Reglas de estilo AGENTS.md siempre activas | +| Recursos | **Agents** | Perfiles de subagentes personalizados | +| Recursos | **Memory** | Notas de memoria a largo plazo | +| Recursos | **Skills** | Flujos de trabajo reutilizables | +| Recursos | **Learnings** | Correcciones y patrones capturados a lo largo del tiempo | +| Recursos | **Remote agents** | Conexiones A2A a otras aplicaciones agent-native (reemplaza lo que la pestaña Connections solía mostrar) | +| Agente | **Snapshots** | Una vista previa del alcance, presupuesto de tokens, secciones del sistema ordenadas agrupadas por procedencia/gobernanza/fuente, y la última instantánea de hilo en vivo. Renombrada desde "Context"; los enlaces antiguos `#context` redirigen aquí. | +| Agente | **Connections** | Solo gestión de servidores MCP | +| Agente | **Automations** | Automatizaciones Programadas/por Evento personales y de la organización con flujos de pausa/reanudación, detalles y eliminación. La URL de compatibilidad estable permanece en `/agent#jobs`. | +| Agente | **Settings** | Modelo del agente, claves de API, límites, voz y configuración de automatización | +| Agente | **Access** | La URL MCP de la aplicación, una tarjeta de agente A2A cuando esté disponible, y guías de configuración compartidas para Claude, ChatGPT, Cursor, Claude Code, Codex y otros clientes. Enlaza a `/mcp/connect` para el flujo de conexión completo y el respaldo de token. | -[Native Interfaz de chat — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -es el hogar canónico de las formas de eventos, los ayudantes de tiempo de ejecución y `chatUI` -metadatos de resultados de herramientas. Empiece por ahí cuando conecte a un agente externo al chat. +La página muestra datos solo de ámbito personal (`user`). No hay un interruptor a nivel de organización hoy. Es una envoltura delgada sobre componentes existentes y verificaciones de acceso, no una nueva consola de administración: Connections describe lo que la aplicación puede llamar; Access describe cómo los clientes externos se conectan a ella. -## Sidecar integrado {#embedded-sidecar} +Aún no incluido: -Utilice el sidecar integrado cuando el producto principal ya exista y desee un -agente al lado. +- Vista con ámbito de organización +- Concesiones y edición de alcance +- Interfaz de usuario de revocación +- Historial de procedencia por iteración -El complemento del servidor monta rutas Agent-Native en su aplicación host y las resuelve -lado del servidor de identidad del host: +## Sidecar embebido {#embedded-sidecar} + +Usa el sidecar embebido cuando el producto principal ya existe y quieres un +agente junto a él. + +El plugin del servidor monta las rutas de Agent-Native en tu aplicación host y resuelve +la identidad del host en el lado del servidor: ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -414,7 +281,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -El sidecar React pasa el contexto de la página y los comandos del host: +El sidecar React pasa el contexto de página y los comandos del host: ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -436,7 +303,11 @@ export function AppShell({ children }) { } ``` - +### Cómo se conecta + +Las dos piezas funcionan como un puente: la aplicación host pasa el contexto de página (ruta actual, texto seleccionado, objeto enfocado) a `AgentNativeEmbedded`, y el agente envía comandos de vuelta a través de `onNavigate` y `onRefresh`. El plugin del servidor gestiona la identidad — resuelve la sesión del host para que el agente actúe como el usuario correcto sin un inicio de sesión separado. Nada en la aplicación host necesita cambiar; el plugin adjunta las rutas de Agent-Native junto a las tuyas existentes. + + ```html
@@ -458,10 +329,10 @@ export function AppShell({ children }) {
AgentNativeEmbeddedagent + workspace + >agente + recursos
- rutas Agent-Native
mounted by the server pluginmontadas por el plugin del servidor
@@ -495,45 +366,221 @@ export function AppShell({ children }) { -Consulte [Embedding SDK](/docs/embedding-sdk) para autenticación de host y aislamiento de bases de datos -modo iframe/selector y puente de nivel inferior API. +Consulta [SDK de Embedding](/docs/embedding-sdk) para autenticación del host, aislamiento de base de datos, +modo iframe/selector y APIs de puente de nivel inferior. + +## Aplicación Automatización-primero {#headless} + +Usa la ruta de automatización-primero cuando nadie necesite una pantalla de navegador personalizada mientras +el trabajo se ejecuta: trabajos programados, integraciones, flujos de trabajo de backend, bucles de CLI, +otro agente, o un producto existente que llama a Agent-Native. + +Esta es la forma a elegir cuando la automatización es la superficie del producto. Envías una solicitud desde la terminal, Slack, correo electrónico, un trabajo programado, otro agente, o el Chat ("resume mis correos electrónicos no leídos," "publica las métricas diarias en Slack," "encuentra los candidatos que respondieron la semana pasada") y el agente actúa y devuelve el resultado donde corresponda. Sigue siendo una aplicación real, no un prompt sin estado: +las acciones, las sesiones de autenticación, el estado de la aplicación, el historial de hilo/ejecución, la configuración, las credenciales +y los registros de compartición todos viven en SQL. + +Elige este patrón cuando: + +- **El trabajo ocurre en segundo plano.** La mayor parte del valor se crea mientras el usuario no está mirando: agentes de clasificación, agentes de informes diarios, respondedores de guardia. +- **La salida sale de la aplicación.** El agente publica en Slack, envía correo electrónico o actualiza un sistema de terceros; no hay nada que explorar dentro de la aplicación. +- **El dominio es de un solo uso.** Bot de investigación, generador de resúmenes, escritor de informes sin objeto persistente que necesite una vista de lista. +- **Estás prototipando una automatización.** Lanza la operación ahora; añade chat o páginas de aplicación cuando los usuarios necesiten inspeccionarla y dirigirla. + +Si tu producto está construido alrededor de objetos persistentes que los usuarios exploran, pivotean y comparten (correos electrónicos, eventos, documentos, gráficos), elige una [aplicación completa](#full-application) o una [plantilla](/docs/cloneable-saas) en su lugar; esas añaden una interfaz de usuario completa _más_ el agente. + +### Qué viene incluido {#in-the-box} + +Una aplicación de automatización-primero omite el trabajo de panel, y es agnóstica al canal desde el primer día. El mismo agente se ejecuta desde la web, Slack, Telegram, correo electrónico y otros agentes porque todo pasa por las mismas acciones. La contrapartida es que no hay una vista de "ver-todo-de-un-vistazo"; si los usuarios necesitan eso, comienza desde [Chat](/docs/template-chat) o añade una pequeña página de estado o vista de lista. + +Cuando añades el shell de Chat integrado, el framework proporciona cinco superficies de gestión que no tienes que construir: **Chat** (la entrada principal), **Resources** (habilidades, memoria, instrucciones, subagentes y servidores MCP conectados), **Automations**, **Thread history** y **Settings**. Esas suelen ser suficientes: hablar con él, ver lo que ha hecho, configurar cómo se comporta. Ve a [Chat](/docs/template-chat) cuando estés listo para añadir esa interfaz de usuario en el navegador, o a la [plantilla Dispatch](/docs/template-dispatch) para un punto de partida estilo espacio de trabajo con Slack/Telegram, trabajos programados y secretos compartidos listos para usar. + +La ruta local más pequeña sin navegador es un scaffold más una acción: + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +Luego define la operación duradera: + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +Una acción es entonces invocable como: + +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **CLI del agente de la aplicación:** `pnpm agent "Summarize form_123"` +- **MCP:** desde Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot y otros hosts MCP +- **A2A:** desde otra aplicación agent-native o par de agente +- **Interfaz de usuario:** a través de `useActionQuery`, `useActionMutation` o `callAction` +- **Herramienta del agente:** desde el bucle de chat integrado + + + +Cada `defineAction` se monta automáticamente en `/_agent-native/actions/`. El cuerpo JSON se valida contra el esquema zod de la acción antes de que se ejecute `run`. Para llamarlo desde un sistema externo con un token de portador de larga duración, consulta [API HTTP](/docs/http-api). + + + +Este no es un modo sin base de datos ni sin estado. El bucle de agente de la aplicación almacena sesiones, +hilos, ejecuciones, configuración, credenciales, estado de la aplicación y registros de compartición en +SQL. El desarrollo local usa SQLite por defecto; las aplicaciones de automatización-primero alojadas deben +usar una base de datos SQL persistente. + +Si necesitas todo el bucle del agente sin navegador desde la carpeta del proyecto, usa: + +```bash +pnpm agent "Summarize this week's forms." +``` + +Si otra aplicación o script necesita llamar a todo el agente, usa +`agentNative.invoke("analytics", "...")` o la CLI `agent-native invoke`. Eso +mantiene el trabajo entre aplicaciones en la ruta A2A mientras el trabajo local permanece en las acciones. + +Los workers, trabajos, webhooks de integración y hosts personalizados pueden dirigir el bucle del agente +directamente a través de la API del servidor. Esto es de nivel más bajo que las acciones — tú proporcionas +el motor, el modelo, los mensajes, las herramientas, las acciones, un sumidero de eventos y una señal de aborto +tú mismo: + +```ts +import { runAgentLoop } from "@agent-native/core/server"; -## Solicitud completa {#full-application} +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` -Utilice la ruta completa de la aplicación cuando los usuarios necesiten objetos y flujos de trabajo duraderos: formularios -paneles de control, calendarios, bandejas de entrada, editores, documentos, activos o informes. +Para la mayoría de las aplicaciones, los prompts programados y los webhooks de integración ya llaman a este bucle +por ti. Úsalo directamente solo cuando construyas un host personalizado sin navegador, un ejecutor de evaluaciones +o una superficie de orquestación del lado del servidor. Consulta [Servidor: Manejador de agente en producción](/docs/server#agent-handler) para la firma completa. -Las aplicaciones completas agregan el producto UI alrededor de la misma acción y contrato de agente: +### Ejecutar contra una carpeta {#folder-loop} -- **Estado SQL**: los datos de la aplicación, la navegación, la configuración y el historial de chat son duraderos. -- **Conciencia del contexto**: el agente conoce la ruta actual, la selección y el objeto enfocado. -- **Sincronización en vivo**: los cambios del agente actualizan el UI y los cambios del UI actualizan el contexto del agente. -- **Enlaces profundos**: los resultados de la acción pueden abrir la vista correcta de la aplicación. -- **Widgets de chat nativos**: tablas, gráficos, tarjetas, aprobaciones y resultados escritos aparecen en línea. +Si tu objetivo es "ejecutar un agente contra esta carpeta," comienza con el bucle del agente de la aplicación +en esa carpeta: crea el scaffold de la aplicación de automatización-primero, añade acciones/instrucciones, ejecuta +`pnpm agent "..."`. Eso mantiene el trabajo dentro del mismo contrato de acción/runtime/estado +que la aplicación usará en producción. -Comienza desde [Chat template](/docs/template-chat) cuando quieras una aplicación mínima -alrededor de tu actions, o desde un dominio [template](/docs/cloneable-saas) cuando -quiero una forma de producto completa. +Los arneses de codificación externos son una superficie de producto separada para embeber Claude +Code, Codex, Pi, Cursor, Mastra o runtimes similares dentro de una aplicación Agent-Native. +Úsalos cuando estés construyendo un producto de agente de codificación, no como la forma predeterminada de +iniciar un flujo de trabajo agent-native local. -## Cómo elegir {#how-to-choose} +### Acceso a repositorios en la nube {#cloud-repo-access} -| Si estás pensando... | Elegir | -| --------------------------------------------------------------------------- | -------------------------------- | -| "Solo necesito una herramienta o un flujo de trabajo que se pueda llamar". | Agente sin cabeza | -| "Quiero el agente del framework, pero el chat debería ser el UI principal." | Chat enriquecido en Agent-Native | -| "Ya tengo un agente; necesito un chat pulido UI para ello." | Chat enriquecido con tu agente | -| "Ya tengo una aplicación SaaS; agregue un agente al lado." | Sidecar integrado | -| "El agente y UI deben evolucionar juntos como producto." | Solicitud completa | +Para aplicaciones de automatización-primero en la nube que necesiten acceso a repositorios, usa el conector de GitHub +más el modelo CRUD de tokens: listar repositorios, buscar archivos, leer archivos, crear o +editar archivos, eliminar archivos y revocar el acceso a través de credenciales con ámbito de proveedor. +En el desarrollo local, establece el repositorio destino explícitamente: -Mantenga el contrato pequeño: defina operaciones duraderas como actions, devuelva explícito -resultados del widget cuando el chat necesita UI enriquecido y agrega pantallas completas solo cuando los usuarios -necesita explorar, comparar, configurar o colaborar en objetos persistentes. +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +No trates un clon de VM o un checkout de sandbox de larga duración como el modelo principal de +acceso a repositorios en la nube. Los sandboxes siguen siendo importantes para la ejecución aislada de código, pero +el acceso al repositorio debe ser explícito, con permisos, auditable y revocable +a través de la capa del conector. + +### Compartir sesiones y ejecuciones {#sharing-runs} + +Las sesiones y ejecuciones de automatización-primero son objetos duraderos. La capacidad de compartición debe ser +escalonada: primero los enlaces de lectura/compartición, para que los compañeros de equipo puedan inspeccionar los prompts saneados, +las salidas y el estado de ejecución; luego la colaboración de escritura con permisos, para que +continuar una ejecución, aprobar acciones, editar horarios o cambiar la +configuración pase a través de verificaciones de acceso explícitas. + +## Chat enriquecido sobre tu agente {#byo-agent} + +Usa esta ruta cuando tu agente ya esté construido con otro framework o +runtime y quieras la interfaz de chat de Agent-Native a su alrededor. `AgentChatRuntime` es el +límite: tu runtime transmite eventos normalizados, y Agent-Native renderiza el +compositor, la transcripción, las llamadas a herramientas, las aprobaciones, los widgets nativos y el diseño de la aplicación. + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` + +Existen asistentes de runtime listos para OpenAI Agents, OpenAI Responses, el SDK de agente de Claude, +el SDK de IA de Vercel y AG-UI, además del runtime HTTP normalizado anterior +para cualquier otro agente (Mastra, Flue, Eve, LangGraph o un servicio personalizado). ACP no es +el chat de aplicación para el usuario final ni el transporte A2A, y Agent-Native actualmente no +reclama compatibilidad con A2UI. ACP está soportado en un lugar específico: dirigir un agente de codificación +local (Gemini CLI, Claude Code, ...) a través de la +[capa de arnés](/docs/harness-agents#acp), no como el runtime de chat aquí. + +[Native Chat UI: Runtimes de agente BYO](/docs/native-chat-ui#byo-agent-runtimes) +es el lugar canónico para las formas de eventos, los asistentes de runtime y los metadatos de resultado de herramienta `chatUI`. Comienza allí al conectar un agente externo al chat. ## Qué sigue {#related-docs} -- [**Actions**](/docs/actions): define la operación una vez; todas las superficies anteriores llaman a la misma -- [**Native Interfaz de chat**](/docs/native-chat-ui): representa resultados tipados como tablas, gráficos y tarjetas en el chat -- [**Generative UI**](/docs/generative-ui): genera UI aislada, temporal o persistente, dentro del chat -- [**Automation-First Apps**](/docs/pure-agent-apps): el patrón completo sin navegador para trabajos, colas, scripts y agentes externos -- [**External Agents**](/docs/external-agents): conecta hosts compatibles con MCP a una aplicación -- [**A2A Protocol**](/docs/a2a-protocol): llama a agentes desde otras aplicaciones Agent-Native + + +### [Acciones](/docs/actions) + +Define la operación una vez. Cada superficie anterior llama a la misma. + +### [Native Chat UI](/docs/native-chat-ui) + +Renderiza resultados de acciones tipados como tablas, gráficos y tarjetas directamente en el chat. + +### [Generative UI](/docs/generative-ui) + +Genera interfaz de usuario aislada transitoria o persistida en línea en el chat. + +### [Aplicaciones Automatización-Primero](/docs/pure-agent-apps) + +El patrón completo sin navegador para trabajos, colas, scripts y agentes externos. + +### [Agentes externos](/docs/external-agents) + +Conecta hosts compatibles con MCP a tu aplicación como servidor de herramientas. + +### [Protocolo A2A](/docs/a2a-protocol) + +Llama a agentes desde otras aplicaciones agent-native a través del estándar A2A. + + diff --git a/packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx b/packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx index 751dda6513..5582503405 100644 --- a/packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx @@ -1,93 +1,47 @@ --- title: "Surfaces d'agent" -description: "Utilisez Agent-Native sans tête, en tant que chat enrichi, dans une application existante ou en tant qu'application native d'agent complète." -search: "Application complète de chat enrichi d'agent sans tête BYO runtime d'agent AgentChatRuntime intégré actions MCP A2A HTTP CLI" +description: "Choisissez comment une application agentique évolue du chat vers une interface utilisateur intégrée, des pages d'application durables, des sidecars embarqués, de l'automatisation et un accès agent externe." +search: "application agentique chat enrichi interface utilisateur native application complète automatisation sans interface BYO agent runtime AgentChatRuntime intégration actions MCP A2A HTTP CLI" --- -# Surfaces des agents +# Surfaces d'agent -## Espace de travail Agent complet {#agent-page} +Une **surface** désigne la façon dont les utilisateurs (ou d'autres systèmes) interagissent avec votre application : une fenêtre de chat, une page de tableau de bord, une tâche en arrière-plan, un appel API depuis un autre agent. Agent-Native vous permet de combiner ces surfaces sans reconstruire votre logique centrale, car chaque surface exécute les mêmes actions sous-jacentes. Si vous découvrez Agent-Native, commencez par lire [Concepts clés](/docs/key-concepts). -Lorsqu'une application complète a besoin d'un endroit durable pour inspecter et -configurer son agent, montez `AgentTabsPage` sur `/agent`. Ajoutez la route à la -navigation de l'application et passez `agentPageHref="/agent"` à -`AgentSidebar` afin que les modes Resources et Settings puissent ouvrir la page -complète sans dupliquer ces flux. +## Comment les surfaces s'articulent entre elles -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -La page partagée propose actuellement cinq onglets : - -- **Context** — aperçu du périmètre, budget de tokens, sections système ordonnées avec provenance et gouvernance, vue liste/treemap et dernière capture du fil actif. -- **Files** — réutilise `ResourcesPanel` pour les ressources personnelles ou de l'organisation. -- **Connections** — gestion des serveurs MCP et liste des agents distants A2A : ce que l'agent de l'application peut appeler. -- **Automations** — automatisations personnelles et d'organisation Scheduled et Event avec pause/reprise, détails et suppression. L'URL de compatibilité reste `/agent#jobs`. -- **Access** — URL MCP, fiche d'agent A2A si disponible et guides de configuration partagés ; le flux complet et le repli par jeton sont disponibles sur `/mcp/connect`. +Les quatre formes de produit principales s'inscrivent sur un spectre allant de la plus interactive à la totalement sans interface. Ce qui les rend composables, c'est que la fondation reste la même tout au long : les mêmes actions, la même base de données SQL et la même boucle d'agent alimentent chaque forme. Ajouter une nouvelle surface ne signifie pas réécrire ce qui se trouve en dessous — vous ajoutez simplement une nouvelle façon d'atteindre les mêmes opérations. -La page utilise actuellement le périmètre personnel et ne propose pas de -sélecteur **Personal / Organization** global. Un onglet peut afficher ses -propres sections d'organisation lorsque les actions sous-jacentes les prennent -en charge : **Automations** affiche des sections personnelles et d'organisation -pour Scheduled et Event. Les automatisations Event d'organisation s'exécutent -toujours en tant que leur créateur. La page est une fine enveloppe autour des composants, -actions et contrôles existants, pas une nouvelle console d'administration. - -Agent-Native est délibérément composable. Vous pouvez utiliser l'agent sans trop dépenser UI, -utilisez le UI sans le runtime d'agent intégré, ou utilisez les deux ensemble comme un ensemble complet -application. - -La manière utile de choisir n'est pas d'abord par protocole. Choisissez la surface du produit -vous voulez, puis utilisez la primitive correspondante. - -| Surface | Utilisez-le quand | Commencer par | -| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **Agent sans tête** | Le code, les tâches, les scripts, une autre application ou un autre agent doivent appeler le travail directement. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Chat enrichi sur Agent-Native** | Vous souhaitez un chat autonome ou intégré soutenu par la boucle d'agent intégrée. | [Chat template](/docs/template-chat), ``, `` | -| **Chat enrichi sur votre agent** | Vous avez créé l'agent ailleurs et souhaitez le compositeur, la transcription, les fiches outils et les widgets natifs de Agent-Native. | `AgentChatRuntime`, `` | -| **Side-car intégré** | Vous disposez déjà d'une application SaaS et souhaitez un agent à côté avec le contexte de la page et les commandes d'hôte. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **Application complète** | Les humains et les agents doivent partager des écrans, des données, une navigation et une collaboration durables. | Modèles, état actions, SQL, connaissance du contexte | - -Ce sont des étapes, pas des produits séparés. Un workflow peut démarrer sans tête -agent avec une seule action, apparaît dans le chat sous forme de tableau ou de graphique, et devient plus tard un -plein écran dans une application sans modifier l'opération appelée par l'agent. - - + ```html
- Headlessactions, jobs, scripts, autres agents + Chatcompositeur, transcription, appels d'outils
- Chat enrichiéditeur, transcription, cartes d’outils + Interface intégréetableaux, graphiques, cartes
- Sidecar intégréagent beside an existing app + Page d'applicationécrans durables, données SQL
- la majeure partie du UIApplication complèteécrans durables, données, collaboration + sans interfaceAutomatisationtâches, scripts, agents externes
mêmes actions · même SQL · même boucle agentmêmes actions · même SQL · même boucle d'agent
``` @@ -121,180 +75,32 @@ plein écran dans une application sans modifier l'opération appelée par l'agen -## Agent sans tête {#headless} - -Utilisez le chemin sans tête lorsque personne n'a besoin de regarder l'écran d'une application personnalisée pendant -le travail s'exécute : tâches planifiées, intégrations, workflows backend, boucles CLI, -un autre agent ou un produit existant appelant Agent-Native. - -C'est aussi la forme à atteindre lorsque **l'agent _est_ le produit** — le -la boucle app-agent est la porte d'entrée, pas un tableau de bord. Vous envoyez une demande depuis le -terminal, Slack, e-mail, une tâche planifiée, un autre agent ou Chat – "résumer mon -e-mails non lus", "publier les statistiques quotidiennes sur Slack", "trouver les candidats qui -a répondu la semaine dernière" — et l'agent agit et renvoie le résultat partout où il se trouve -appartient. Il s'agit toujours d'une véritable application, pas d'une invite sans état : actions, sessions d'authentification, -L'état de l'application, l'historique des threads/exécutions, les paramètres, les informations d'identification et les enregistrements de partage sont tous en ligne -dans SQL. - -Choisissez ce modèle lorsque : - -- **Le travail s'effectue en arrière-plan.** La majeure partie de la valeur est créée lorsque l'utilisateur ne regarde pas : agents de tri, agents chargés des rapports quotidiens, intervenants de garde. -- **La sortie quitte l'application.** L'agent publie sur Slack, envoie un e-mail ou met à jour un système tiers ; il n'y a rien à parcourir dans l'application. -- **Le domaine est unique.** Bot de recherche, générateur de résumés, rédacteur de rapports : aucun objet persistant nécessitant une vue de liste. -- **Vous êtes en train de créer un prototype.** Expédiez l'agent maintenant ; ajoutez un UI plus riche plus tard si les utilisateurs le souhaitent. - -Si votre produit est construit autour d'objets persistants, les utilisateurs parcourent, pivotent et -Partager – e-mails, événements, documents, graphiques – choisissez un [full application](#full-application) -ou un [template](/docs/cloneable-saas) à la place ; ceux-ci ajoutent un UI complet _plus_ l'agent. - -### Ce qui est livré dans la boîte {#in-the-box} - -Une application headless évite des semaines de travail sur le tableau de bord et est indépendante des canaux dès le jour. -un – le même agent s'exécute à partir du Web, de Slack, de Telegram, de la messagerie électronique et d'autres agents -car tout passe par l'agent, pas le UI. Le compromis est qu'il y a -pas de vue « parcourir tout en un coup d’œil » ; si les utilisateurs en ont besoin, mélangez les modèles et -Ajoutez une petite page d'état ou une vue de liste. - -Lorsque vous ajoutez le shell Chat intégré, le framework propose cinq gestions -surfaces que vous n'avez pas besoin de créer : **Chat** (l'entrée principale), **Espace de travail** -(skills, mémoire, instructions, sous-agents, serveurs MCP connectés, planifiés -tâches), **Historique des tâches**, **Historique des threads** et **Paramètres**. Ce sont généralement -assez – parlez-lui, voyez ce qu'il fait, configurez son comportement. Atteindre -[Chat](/docs/template-chat) lorsque vous êtes prêt à ajouter ce navigateur UI, ou le -[Dispatch template](/docs/template-dispatch) pour un démarrage de style espace de travail -pointez avec Slack/Telegram, les tâches planifiées et les secrets partagés prêts à l'emploi. - -Le plus petit chemin local est un échafaudage d'agents sans tête plus une action : - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -Définissez ensuite l’opération durable : - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -Une action peut alors être appelée comme : - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **Agent d'application CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — à partir de Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot et d'autres hôtes MCP -- **A2A** – à partir d'une autre application native d'agent ou d'un homologue d'agent -- **UI** — via `useActionQuery`, `useActionMutation` ou `callAction` -- **Outil d'agent** – à partir de la boucle de discussion intégrée - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -Il ne s'agit pas d'un mode sans base de données ou sans état. La boucle app-agent stocke les sessions, -threads, exécutions, paramètres, informations d'identification, état de l'application et enregistrements de partage dans -SQL. Le développement local est par défaut SQLite ; les applications sans tête hébergées doivent utiliser un -Base de données SQL persistante. - -Si vous avez besoin de l'intégralité de la boucle de l'agent sans tête à partir du dossier du projet, utilisez : - -```bash -pnpm agent "Summarize this week's forms." -``` - -Si une autre application ou un autre script doit appeler l'ensemble de l'agent, utilisez -`agentNative.invoke("analytics", "...")` ou `agent-native invoke` CLI. Cela -conserve le travail inter-applications sur le chemin A2A tandis que le travail local reste sur actions. - -Les travailleurs, les tâches, l'intégration webhooks et les hôtes personnalisés peuvent piloter la boucle d'agent -directement via le serveur API. Il s'agit d'un niveau inférieur à actions — vous fournissez -le moteur, le modèle, les messages, le actions et le récepteur d'événements vous-même : - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -Pour la plupart des applications, les invites planifiées et l'intégration webhooks appellent déjà cette boucle -pour vous. Accédez-y directement uniquement lors de la création d'un hôte sans tête personnalisé, évaluez -runner ou surface d'orchestration côté serveur – voir [Serveur – Agent de production -handler](/docs/server#agent-handler) pour la signature complète. +## Choisir un point de départ -### Exécuter sur un dossier {#folder-loop} +Le chat est le point d'entrée le plus courant. Les applications développent généralement une interface intégrée à mesure que les sorties s'enrichissent, puis ajoutent des pages d'application complètes lorsque les utilisateurs ont besoin d'objets persistants à parcourir et partager. Les mêmes actions alimentent les boutons, les tâches planifiées et les agents externes qui viennent ensuite. Utilisez le sidecar embarqué lorsque vous ajoutez un agent à un produit que vous possédez déjà, ou l'approche Automatisation-d'abord pour les tâches qui s'exécutent sans navigateur. Voici la vue d'ensemble : -Si votre objectif est "exécuter un agent sur ce dossier", commencez par l'agent d'application -boucle dans ce dossier : échafaudez l'application sans tête, ajoutez actions/instructions, exécutez -`pnpm agent "..."`. Cela maintient le travail dans la même action/exécution/état -contrat que l'application utilisera en production. - -Les faisceaux de codage externes constituent une surface de produit distincte pour l'intégration de Claude -Code, Codex, Pi, Cursor, Mastra ou environnements d'exécution similaires dans une application Agent-Native. -Utilisez-les lorsque vous créez un produit d'agent de codage, et non comme méthode par défaut -démarrez un workflow natif d'agent local. - -### Accès au dépôt cloud {#cloud-repo-access} - -Pour les applications cloud sans interface graphique qui nécessitent un accès au référentiel, utilisez le connecteur GitHub -Modèle de jeton plus CRUD : répertorier les référentiels, rechercher des fichiers, lire des fichiers, créer ou -modifier des fichiers, supprimer des fichiers et révoquer l'accès via le niveau du fournisseur -informations d'identification. En développement local, définissez explicitement le référentiel cible : - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -Ne traitez pas un clone de VM ou une extraction sandbox de longue durée comme cloud principal -modèle d'accès au dépôt. Les bacs à sable sont toujours importants pour l'exécution de code isolé, mais -L'accès au référentiel doit être explicite, autorisé, vérifiable et révocable -via la couche de connecteur. - -### Partage de sessions et d'exécutions {#sharing-runs} - -Les sessions et exécutions sans tête sont des objets durables. Le partage doit être progressif : -lisez/partagez d'abord les liens afin que vos coéquipiers puissent inspecter les invites et les sorties nettoyées -et état d'exécution ; collaboration en écriture autorisée plus tard, donc poursuite d'une exécution, -l'approbation de actions, la modification des horaires ou la modification de la configuration sont effectuées -vérifications d'accès explicites. +| Surface | Utilisez-la quand | Commencer avec | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **[Chat enrichi](#rich-chat)** | Les utilisateurs parlent à l'agent, voient les appels d'outils et conservent un historique de fil de discussion. | [Modèle Chat](/docs/template-chat), `` | +| **[Interface utilisateur native intégrée](#native-inline-ui)** | Les résultats des actions doivent s'afficher sous forme de tableaux, graphiques, cartes ou approbations dans le chat. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[Interface utilisateur intégrée générée](#generated-inline-ui)** | L'agent doit créer des contrôles temporaires ou réutilisables dans le chat à la volée. | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[Application complète](#full-application)** | Les utilisateurs ont besoin d'écrans durables, de données partagées, de navigation et de collaboration. | Modèles, actions, état SQL, prise de conscience du contexte | +| **[Sidecar embarqué](#embedded-sidecar)** | Vous avez déjà une application SaaS et souhaitez y adjoindre un agent avec le contexte de la page. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[Automatisation-d'abord](#headless)** | Des tâches, scripts ou autres agents appellent le travail directement sans interface navigateur. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[Chat enrichi sur votre agent](#byo-agent)** | Vous avez créé l'agent ailleurs et souhaitez y intégrer l'interface chat d'Agent-Native. | `AgentChatRuntime`, `` | ## Chat enrichi sur Agent-Native {#rich-chat} Utilisez le chat intégré lorsque l'utilisateur doit parler à l'agent, voir les appels d'outils, -approuvez le travail, inspectez les résultats natifs et conservez un historique de thread durable. +approuver les actions, inspecter les résultats natifs et conserver un historique de fil de discussion durable. -Pour un point de départ complet de l'application, utilisez [Chat template](/docs/template-chat) : +Pour un point de départ d'application complète, utilisez le [modèle Chat](/docs/template-chat) : ```bash npx @agent-native/core@latest create my-chat-app --template chat ``` -Le chat pleine page le plus simple : +Le chat pleine page le plus simple : ```tsx import { AgentChatSurface } from "@agent-native/core/client/chat"; @@ -304,11 +110,10 @@ export default function ChatRoute() { } ``` -Lorsqu'une application dispose à la fois d'un onglet de discussion pleine page et d'un `AgentSidebar`, utilisez le même -`storageKey` sur les deux surfaces, activez `chatViewTransition` et installez le -assistants de transfert de chat-home dans la mise en page. Liens ordinaires dans l'application hors du chat -la page peut ensuite transformer le chat complet en barre latérale tout en gardant l'actif -thème : +Lorsqu'une application dispose à la fois d'un onglet chat pleine page et d'un `AgentSidebar`, utilisez la même +`storageKey` sur les deux surfaces, activez `chatViewTransition` et installez les +assistants de transfert chat-home dans la mise en page. Les liens ordinaires dans l'application hors de la page +chat peuvent alors faire passer le chat complet dans la barre latérale tout en conservant le fil actif : ```tsx import { @@ -346,7 +151,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -Le chat intégré le plus simple avec votre propre chrome : +Le chat embarqué le plus simple avec votre propre chrome : ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -356,51 +161,114 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -Actions peut renvoyer des résultats de widget natifs explicites afin que la sortie du chat ne soit pas simplement -texte. Les tableaux, graphiques et fiches produits saisies s'affichent sous la forme React propriétaire -composants dans le chat, sans iframes. Voir [Native Interface de chat](/docs/native-chat-ui). +Les actions peuvent renvoyer des résultats de widget natif explicites afin que la sortie du chat ne soit pas uniquement +du texte. Les tableaux, graphiques et cartes de produit typées s'affichent en tant que composants React de premier niveau +dans le chat, sans iframe. Voir [Native Chat UI](/docs/native-chat-ui). +Lorsque l'agent a besoin de contrôles générés arbitraires plutôt qu'un +widget React prédéfini, utilisez [Generative UI](/docs/generative-ui) : il affiche une interface Alpine/Tailwind +dans un bac à sable intégré, peut lire l'état de l'application et le contexte de l'emplacement, et peut renvoyer +les valeurs sélectionnées vers le chat. -## Chat enrichi sur votre agent {#byo-agent} +## Interface utilisateur native intégrée {#native-inline-ui} -Utilisez ce chemin lorsque votre agent est déjà construit avec un autre framework ou -runtime et vous voulez que le chat UI de Agent-Native l'entoure. `AgentChatRuntime` est le -limite : votre runtime diffuse les événements normalisés et Agent-Native restitue le -compositeur, transcription, appels d'outils, approbations, widgets natifs et mise en page de l'application. +Utilisez cette surface lorsque vos actions renvoient des données structurées — une liste d'enregistrements, un jeu de données de graphique, un résumé d'état — qui doivent s'afficher en tant que vrai composant d'interface dans le fil de chat plutôt qu'une simple description textuelle. Vous définissez un renderer `chatUI` sur l'action, et Agent-Native l'affiche en tant que composant React de premier niveau : pas d'iframe, pas de chemin de rendu séparé. -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +C'est le bon choix lorsque la sortie a une forme claire et réutilisable que vous concevriez une fois et utiliseriez dans de nombreuses réponses d'agent. Pour les contrôles que l'agent doit créer dynamiquement à l'exécution, consultez [Interface utilisateur intégrée générée](#generated-inline-ui) à la place. -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +Consultez [Native Chat UI](/docs/native-chat-ui) pour l'API de renderer complète, la bibliothèque de widgets et l'intégration du runtime BYO agent. -export function SupportAgentChat() { - return ; +## Interface utilisateur intégrée générée {#generated-inline-ui} + +Utilisez cette surface lorsque l'agent doit créer un contrôle qui n'existe pas encore en tant que widget prédéfini — un formulaire personnalisé, un sélecteur construit autour du contexte actuel, une calculatrice ponctuelle. Contrairement aux widgets natifs, l'interface générée est composée par l'agent à l'exécution à partir d'Alpine.js et Tailwind, s'exécute dans un bac à sable dans une iframe et peut renvoyer les valeurs sélectionnées dans le fil de chat. + +L'interface générée peut être transitoire (affichée une fois puis supprimée) ou enregistrée en tant qu'extension réutilisable qui persiste pour l'utilisateur. + +Consultez [Generative UI](/docs/generative-ui) pour l'API complète, les contraintes du bac à sable et le modèle de persistance des extensions. + +## Application complète {#full-application} + +Utilisez le chemin d'application complète lorsque les utilisateurs ont besoin d'objets et de flux de travail durables : formulaires, +tableaux de bord, calendriers, boîtes de réception, éditeurs, documents, ressources ou rapports. + +Les applications complètes ajoutent une interface produit autour du même contrat d'action et d'agent : + + + +### État SQL + +Les données de l'application, la navigation, les paramètres et l'historique du chat sont tous durables. L'agent lit et écrit les mêmes lignes que l'interface utilisateur. + +### Prise de conscience du contexte + +L'agent connaît la route actuelle, la sélection et l'objet ciblé, de sorte que « modifier ceci » signifie toujours la bonne chose. + +### Synchronisation en direct + +Les modifications de l'agent mettent à jour l'interface en temps réel, et les modifications de l'interface mettent à jour le contexte de l'agent. Pas de polling, pas de rechargement. + +### Liens profonds + +Les résultats des actions peuvent ouvrir directement la bonne vue de l'application : un graphique renvoie au tableau de bord, un brouillon renvoie à la boîte de réception. + +### Widgets de chat natifs + +Les tableaux, graphiques, cartes, approbations et résultats typés s'affichent en tant que composants React de premier niveau intégrés dans le chat. + +### Interface générative et extensions + +L'agent peut créer des contrôles intégrés à la volée et enregistrer des mini-applications réutilisables lorsqu'un flux de travail doit persister. + + + +Commencez par le [modèle Chat](/docs/template-chat) si vous souhaitez une application minimale +autour de vos actions, ou par un [modèle](/docs/cloneable-saas) de domaine lorsque vous +souhaitez une forme de produit complète. + +### Agent Manager pleine page {#agent-page} + +Chaque application Agent-Native finit par avoir besoin d'un endroit où les utilisateurs peuvent configurer leur agent : définir des instructions permanentes, consulter ce qu'il a fait, connecter des serveurs MCP, gérer des automatisations et contrôler l'accès. Construire cette interface de zéro représente beaucoup de travail. Agent-Native propose un composant pleine page préconfiguré, `AgentTabsPage`, qui couvre tout cela sur douze onglets. + +Montez-le à `/agent` dans votre application. Les modèles actuels associent cette route à une entrée de navigation de l'application et transmettent `agentPageHref="/agent"` à `AgentSidebar`, afin que les modes Ressources et Paramètres de la barre latérale puissent renvoyer vers la page complète sans dupliquer ces flux. + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -Des assistants d'exécution prêts à l'emploi existent pour les agents OpenAI, les réponses OpenAI et le Claude -Agent SDK, Vercel AI SDK et AG-UI, ainsi que le moteur d'exécution normalisé HTTP ci-dessus -pour tout autre agent (Mastra, Flue, Eve, LangGraph ou un service personnalisé). ACP est -pas le chat de l'application utilisateur final ni le transport A2A, et Agent-Native ne le fait pas actuellement -réclamez la prise en charge de A2UI. ACP est pris en charge à un endroit spécifique : conduire un local -Agent de codage (Gemini CLI, Claude Code, …) via le -[harness layer](/docs/harness-agents#acp), pas comme environnement d'exécution de chat ici. +La page partagée propose actuellement douze onglets répartis en deux groupes : + +| Groupe | Onglet | Affiche | +| ---------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Ressources | **Files** | Le `ResourcesPanel` existant pour les fichiers personnels ou d'organisation | +| Ressources | **Instructions** | Règles permanentes de type AGENTS.md | +| Ressources | **Agents** | Profils de sous-agents personnalisés | +| Ressources | **Memory** | Notes de rappel à long terme | +| Ressources | **Skills** | Flux de travail réutilisables | +| Ressources | **Learnings** | Corrections et modèles capturés au fil du temps | +| Ressources | **Remote agents** | Connexions A2A vers d'autres applications agent-native (remplace ce que l'onglet Connections affichait auparavant) | +| Agent | **Snapshots** | Un aperçu de portée, un budget de tokens, des sections système ordonnées regroupées par provenance/gouvernance/source, et le dernier snapshot de fil en direct. Renommé depuis « Context » ; les anciens liens `#context` redirigent ici. | +| Agent | **Connections** | Gestion des serveurs MCP uniquement | +| Agent | **Automations** | Automatisations Planifiées/Événementielles personnelles et d'organisation avec des flux de pause/reprise, détails et suppression. L'URL de compatibilité stable reste `/agent#jobs`. | +| Agent | **Settings** | Modèle d'agent, clés API, limites, voix et paramètres d'automatisation | +| Agent | **Access** | L'URL MCP de l'application, une carte d'agent A2A si disponible, et des guides de configuration partagés pour Claude, ChatGPT, Cursor, Claude Code, Codex et d'autres clients. Liens vers `/mcp/connect` pour le flux de connexion complet et le repli de token. | + +La page affiche uniquement les données personnelles (portée `user`). Il n'existe pas de bascule au niveau organisation aujourd'hui. Il s'agit d'une fine couche sur les composants existants et les vérifications d'accès, et non d'une nouvelle console d'administration : Connections décrit ce que l'application peut appeler ; Access décrit comment les clients externes s'y connectent. + +Non encore inclus : -[Native Interface de chat — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -est la maison canonique pour les formes d'événements, les assistants d'exécution et `chatUI` -métadonnées des résultats de l'outil. Commencez par là lorsque vous connectez un agent externe au chat. +- Vue avec portée organisation +- Modification des grants et des portées +- Interface de révocation +- Historique de provenance par itération -## Side-car intégré {#embedded-sidecar} +## Sidecar embarqué {#embedded-sidecar} -Utilisez le side-car intégré lorsque le produit principal existe déjà et que vous souhaitez un -agent à côté. +Utilisez le sidecar embarqué lorsque le produit principal existe déjà et que vous souhaitez y adjoindre un agent. Le plugin serveur monte les routes Agent-Native dans votre application hôte et résout -Identité de l'hôte côté serveur : +l'identité hôte côté serveur : ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -412,7 +280,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -Le side-car React transmet le contexte de la page et les commandes de l'hôte : +Le sidecar React transmet le contexte de la page et les commandes hôtes : ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -434,7 +302,11 @@ export function AppShell({ children }) { } ``` - +### Comment ça se connecte + +Les deux éléments fonctionnent comme un pont : l'application hôte transmet le contexte de la page (route actuelle, texte sélectionné, objet ciblé) dans `AgentNativeEmbedded`, et l'agent renvoie des commandes via `onNavigate` et `onRefresh`. Le plugin serveur gère l'identité — il résout la session hôte afin que l'agent agisse en tant que le bon utilisateur sans connexion séparée. Rien dans l'application hôte n'a besoin de changer ; le plugin attache les routes d'Agent-Native aux côtés de vos routes existantes. + + ```html
@@ -446,7 +318,7 @@ export function AppShell({ children }) {
onNavigate / onRefresh
commandes hôtecommandes hôtes
@@ -456,10 +328,10 @@ export function AppShell({ children }) {
AgentNativeEmbeddedagent + workspace + >agent + ressources
- routes Agent-Native
mounted by the server pluginmontées par le plugin serveur
@@ -493,45 +365,220 @@ export function AppShell({ children }) { -Voir [Embedding SDK](/docs/embedding-sdk) pour l'authentification de l'hôte, l'isolation de la base de données, -mode iframe/picker et pont de niveau inférieur API. +Consultez [Embedding SDK](/docs/embedding-sdk) pour l'authentification hôte, l'isolation de la base de données, +le mode iframe/sélecteur et les API de pont de niveau inférieur. -## Application complète {#full-application} +## Application automatisation-d'abord {#headless} + +Utilisez le chemin automatisation-d'abord lorsque personne n'a besoin d'un écran de navigateur personnalisé pendant +l'exécution du travail : tâches planifiées, intégrations, flux de travail backend, boucles CLI, +un autre agent ou un produit existant appelant Agent-Native. + +C'est la forme à privilégier lorsque l'automatisation est la surface du produit. Vous envoyez une requête depuis le terminal, Slack, l'e-mail, une tâche planifiée, un autre agent ou le Chat (« résume mes e-mails non lus », « publie les métriques quotidiennes sur Slack », « trouve les candidats qui ont répondu la semaine dernière ») et l'agent agit et renvoie le résultat là où il doit aller. Il s'agit toujours d'une vraie application, et non d'un prompt sans état : +les actions, les sessions d'authentification, l'état de l'application, l'historique des fils/exécutions, les paramètres, les identifiants +et les enregistrements de partage vivent tous en SQL. + +Choisissez ce modèle lorsque : + +- **Le travail se déroule en arrière-plan.** L'essentiel de la valeur est créé pendant que l'utilisateur ne regarde pas : agents de triage, agents de rapport quotidien, agents de permanence. +- **La sortie quitte l'application.** L'agent publie sur Slack, envoie des e-mails ou met à jour un système tiers ; il n'y a rien à parcourir dans l'application. +- **Le domaine est ponctuel.** Bot de recherche, générateur de résumés, rédacteur de rapports sans objet persistant nécessitant une vue de liste. +- **Vous prototypez une automatisation.** Déployez l'opération maintenant ; ajoutez le chat ou des pages d'application lorsque les utilisateurs ont besoin de l'inspecter et de la piloter. + +Si votre produit est construit autour d'objets persistants que les utilisateurs parcourent, pivotent et partagent (e-mails, événements, documents, graphiques), choisissez plutôt une [application complète](#full-application) ou un [modèle](/docs/cloneable-saas) ; ceux-ci ajoutent une interface complète _en plus_ de l'agent. + +### Ce qui est inclus dans la boîte {#in-the-box} + +Une application automatisation-d'abord ignore le travail de tableau de bord et est agnostique aux canaux dès le premier jour. Le même agent s'exécute depuis le web, Slack, Telegram, l'e-mail et d'autres agents parce que tout passe par les mêmes actions. La contrepartie est qu'il n'existe pas de vue « tout-en-un » ; si les utilisateurs en ont besoin, commencez par [Chat](/docs/template-chat) ou ajoutez une petite page de statut ou vue de liste. + +Lorsque vous ajoutez le shell Chat intégré, le framework fournit cinq surfaces de gestion que vous n'avez pas à construire : **Chat** (l'entrée principale), **Ressources** (compétences, mémoire, instructions, sous-agents et serveurs MCP connectés), **Automatisations**, **Historique des fils** et **Paramètres**. Celles-ci sont généralement suffisantes : parlez-lui, voyez ce qu'il a fait, configurez son comportement. Utilisez [Chat](/docs/template-chat) lorsque vous êtes prêt à ajouter cette interface navigateur, ou le [modèle Dispatch](/docs/template-dispatch) pour un point de départ de type espace de travail avec Slack/Telegram, tâches planifiées et secrets partagés prêts à l'emploi. + +Le plus petit chemin local sans navigateur est un scaffold plus une action : + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +Définissez ensuite l'opération durable : + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +Une action est ensuite appelable via : + +- **HTTP :** `POST /_agent-native/actions/summarize-week` +- **CLI :** `pnpm action summarize-week --formId form_123` +- **CLI app-agent :** `pnpm agent "Summarize form_123"` +- **MCP :** depuis Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot et d'autres hôtes MCP +- **A2A :** depuis une autre application agent-native ou un pair agent +- **Interface :** via `useActionQuery`, `useActionMutation` ou `callAction` +- **Outil d'agent :** depuis la boucle de chat intégrée + + -Utilisez le chemin complet de l'application lorsque les utilisateurs ont besoin d'objets et de flux de travail durables : formulaires, -Tableaux de bord, calendriers, boîtes de réception, éditeurs, documents, éléments ou rapports. +Chaque `defineAction` est automatiquement monté à `/_agent-native/actions/`. Le corps JSON est validé par rapport au schéma zod de l'action avant l'exécution de `run`. Pour l'appeler depuis un système externe avec un token bearer de longue durée, consultez [HTTP API](/docs/http-api). -Les applications complètes ajoutent le produit UI autour de la même action et du même contrat d'agent : + + +Il ne s'agit pas d'un mode sans base de données ou sans état. La boucle app-agent stocke les sessions, +les fils, les exécutions, les paramètres, les identifiants, l'état de l'application et les enregistrements de partage en +SQL. Le développement local utilise SQLite par défaut ; les applications automatisation-d'abord hébergées doivent +utiliser une base de données SQL persistante. + +Si vous avez besoin de toute la boucle d'agent sans interface depuis le dossier du projet, utilisez : + +```bash +pnpm agent "Summarize this week's forms." +``` + +Si une autre application ou un script doit appeler toute la boucle d'agent, utilisez +`agentNative.invoke("analytics", "...")` ou le CLI `agent-native invoke`. Cela +maintient le travail inter-applications sur le chemin A2A tandis que le travail local reste sur les actions. + +Les workers, tâches, webhooks d'intégration et hôtes personnalisés peuvent piloter la boucle d'agent +directement via l'API serveur. C'est un niveau plus bas que les actions — vous fournissez +vous-même le moteur, le modèle, les messages, les outils, les actions, un collecteur d'événements et un signal d'abandon : + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +Pour la plupart des applications, les prompts planifiés et les webhooks d'intégration appellent déjà cette boucle +pour vous. Utilisez-la directement uniquement lorsque vous construisez un hôte personnalisé sans navigateur, un exécuteur d'évaluation +ou une surface d'orchestration côté serveur. Consultez [Serveur : Gestionnaire d'agent en production](/docs/server#agent-handler) pour la signature complète. + +### Exécution sur un dossier {#folder-loop} + +Si votre objectif est « exécuter un agent sur ce dossier », commencez par la boucle +app-agent dans ce dossier : scaffoldez l'application automatisation-d'abord, ajoutez des actions/instructions, exécutez +`pnpm agent "..."`. Cela maintient le travail dans le même contrat action/runtime/état +que l'application utilisera en production. + +Les harnais de codage externes sont une surface de produit séparée pour intégrer Claude +Code, Codex, Pi, Cursor, Mastra ou des runtimes similaires dans une application Agent-Native. +Utilisez-les lorsque vous construisez un produit agent de codage, et non comme la façon par défaut de +démarrer un flux de travail agent-native local. + +### Accès au dépôt cloud {#cloud-repo-access} + +Pour les applications automatisation-d'abord cloud nécessitant un accès au dépôt, utilisez le connecteur GitHub +plus le modèle CRUD de token : lister les dépôts, rechercher des fichiers, lire des fichiers, créer ou +modifier des fichiers, supprimer des fichiers et révoquer l'accès via des +identifiants à portée de fournisseur. En développement local, définissez explicitement le dépôt cible : + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +Ne traitez pas un clone de VM ou un checkout de bac à sable de longue durée comme le modèle principal d'accès +au dépôt cloud. Les bacs à sable restent importants pour l'exécution de code isolé, mais +l'accès au dépôt doit être explicite, autorisé, auditable et révocable +via la couche de connecteur. + +### Partage des sessions et des exécutions {#sharing-runs} -- **État SQL** : les données de l'application, la navigation, les paramètres et l'historique des discussions sont durables. -- **Conscience du contexte** : l'agent connaît l'itinéraire actuel, la sélection et l'objet ciblé. -- **Synchronisation en direct** : les modifications de l'agent mettent à jour le UI et les modifications de UI mettent à jour le contexte de l'agent. -- **Liens profonds** : les résultats de l'action peuvent ouvrir la bonne vue de l'application. -- **Widgets de discussion natifs** : les tableaux, graphiques, cartes, approbations et résultats saisis apparaissent en ligne. +Les sessions et les exécutions automatisation-d'abord sont des objets durables. La partageabilité doit être +progressive : d'abord des liens de lecture/partage, afin que les coéquipiers puissent inspecter les prompts assainis, +les sorties et l'état d'exécution ; ensuite une collaboration en écriture avec permissions, afin que +la continuation d'une exécution, l'approbation des actions, la modification des planifications ou le changement de +configuration passe par des vérifications d'accès explicites. -Démarrez à partir du [Chat template](/docs/template-chat) lorsque vous souhaitez une application minimale -autour de votre actions, ou depuis un domaine [template](/docs/cloneable-saas) lorsque vous -vous voulez une forme complète du produit. +## Chat enrichi sur votre agent {#byo-agent} + +Utilisez ce chemin lorsque votre agent est déjà construit avec un autre framework ou +runtime et que vous souhaitez y intégrer l'interface chat d'Agent-Native. `AgentChatRuntime` est la +frontière : votre runtime diffuse des événements normalisés, et Agent-Native affiche le +compositeur, la transcription, les appels d'outils, les approbations, les widgets natifs et la mise en page de l'application. -## Comment choisir {#how-to-choose} +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` -| Si vous pensez... | Choisir | -| -------------------------------------------------------------------------- | ----------------------------- | -| "J'ai juste besoin d'un outil ou d'un workflow appelable." | Agent sans tête | -| "Je veux l'agent du framework, mais le chat devrait être le UI principal." | Chat enrichi sur Agent-Native | -| "J'ai déjà un agent ; j'ai besoin d'un chat UI soigné pour cela." | Chat enrichi sur votre agent | -| "J'ai déjà une application SaaS ; ajoutez un agent à côté." | Side-car intégré | -| "L'agent et UI devraient évoluer ensemble en tant que produit." | Application complète | +Des assistants de runtime prêts à l'emploi existent pour OpenAI Agents, OpenAI Responses, le Claude +Agent SDK, le Vercel AI SDK et AG-UI, ainsi que le runtime HTTP normalisé ci-dessus +pour tout autre agent (Mastra, Flue, Eve, LangGraph ou un service personnalisé). ACP n'est pas +le chat de l'application pour l'utilisateur final ou le transport A2A, et Agent-Native ne revendique pas actuellement le support A2UI. ACP est pris en charge dans un endroit spécifique : piloter un +agent de codage local (Gemini CLI, Claude Code, …) via la +[couche harnais](/docs/harness-agents#acp), et non comme le runtime de chat ici. -Gardez le contrat petit : définissez les opérations durables comme actions, renvoyez-le explicitement -résultats du widget lorsque le chat a besoin de UI riche et ajout d'écrans pleins uniquement lorsque les utilisateurs -besoin de parcourir, comparer, configurer ou collaborer sur des objets persistants. +[Native Chat UI : Runtimes BYO agent](/docs/native-chat-ui#byo-agent-runtimes) +est la référence canonique pour les formes d'événements, les assistants de runtime et les +métadonnées de résultat d'outil `chatUI`. Commencez là lors du câblage d'un agent externe dans le chat. ## Et ensuite {#related-docs} -- [**Actions**](/docs/actions) — définissez l’opération une fois ; toutes les surfaces ci-dessus appellent la même -- [**Native Interface de chat**](/docs/native-chat-ui) — affichez les résultats typés sous forme de tableaux, graphiques et cartes dans le chat -- [**Generative UI**](/docs/generative-ui) — générez une UI en bac à sable, temporaire ou persistante, dans le chat -- [**Automation-First Apps**](/docs/pure-agent-apps) — le modèle complet sans navigateur pour les tâches, files d’attente, scripts et agents externes -- [**External Agents**](/docs/external-agents) — connectez des hôtes compatibles MCP à une application -- [**A2A Protocol**](/docs/a2a-protocol) — appelez des agents depuis d’autres applications Agent-Native + + +### [Actions](/docs/actions) + +Définissez l'opération une fois. Chaque surface ci-dessus appelle la même. + +### [Native Chat UI](/docs/native-chat-ui) + +Affichez les résultats d'actions typés sous forme de tableaux, graphiques et cartes directement dans le chat. + +### [Generative UI](/docs/generative-ui) + +Générez une interface sandbox transitoire ou persistante intégrée dans le chat. + +### [Applications automatisation-d'abord](/docs/pure-agent-apps) + +Le modèle complet sans navigateur pour les tâches, files d'attente, scripts et agents externes. + +### [Agents externes](/docs/external-agents) + +Connectez des hôtes compatibles MCP à votre application en tant que serveur d'outils. + +### [Protocole A2A](/docs/a2a-protocol) + +Appelez des agents depuis d'autres applications agent-native via le standard A2A. + + 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 f79ea4d144..8a1d9850cc 100644 --- a/packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx @@ -1,86 +1,43 @@ --- -title: "एजेंट सतह" -description: "Agent-Native का उपयोग बिना सोचे-समझे, रिच चैट के रूप में, किसी मौजूदा ऐप के अंदर, या पूर्ण एजेंट-नेटिव एप्लिकेशन के रूप में करें।" -search: "हेडलेस एजेंट रिच चैट पूर्ण ऐप BYO एजेंट रनटाइम एजेंटचैटरनटाइम एम्बेड actions MCP A2A HTTP CLI" +title: "Agent 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 -## पूरा Agent कार्यक्षेत्र {#agent-page} +एक **surface** वह तरीका है जिससे उपयोगकर्ता (या अन्य सिस्टम) आपके ऐप के साथ इंटरैक्ट करते हैं: एक चैट विंडो, एक डैशबोर्ड पेज, एक बैकग्राउंड जॉब, किसी अन्य एजेंट से एक API कॉल। Agent-Native आपको इन्हें बिना अपनी मूल लॉजिक को फिर से बनाए मिक्स और मैच करने देता है, क्योंकि हर surface एक ही अंतर्निहित actions चलाता है। यदि आप Agent-Native में नए हैं, तो पहले [Key Concepts](/docs/key-concepts) पढ़ें। -जब किसी पूर्ण ऐप को अपने एजेंट को देखने और कॉन्फ़िगर करने के लिए स्थायी स्थान -चाहिए, तो `/agent` पर `AgentTabsPage` माउंट करें। ऐप नेविगेशन में यह रूट जोड़ें -और `AgentSidebar` को `agentPageHref="/agent"` दें, ताकि Resources और Settings -मोड इन प्रवाहों को दोहराए बिना पूरे पेज पर जा सकें। +## Surfaces एक-दूसरे से कैसे संबंधित हैं -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -साझा पेज में अभी पाँच टैब हैं: - -- **Context** — स्कोप प्रीव्यू, टोकन बजट, provenance और governance के साथ क्रमबद्ध सिस्टम सेक्शन, सूची/treemap दृश्य और नवीनतम live-thread snapshot। -- **Files** — व्यक्तिगत या संगठन संसाधनों के लिए मौजूदा `ResourcesPanel` को फिर से उपयोग करता है। -- **Connections** — MCP सर्वर प्रबंधन और A2A remote-agent सूची: यह ऐप का एजेंट क्या बुला सकता है। -- **Automations** — pause/resume, विवरण और delete प्रवाहों के साथ व्यक्तिगत और संगठन Scheduled व Event ऑटोमेशन। संगतता URL `/agent#jobs` ही रहता है। -- **Access** — MCP URL, उपलब्ध होने पर A2A agent card और साझा client setup guides; पूरा flow और token fallback `/mcp/connect` पर है। +चार मुख्य उत्पाद आकार सबसे इंटरैक्टिव से पूरी तरह headless तक एक स्पेक्ट्रम पर हैं। जो चीज़ उन्हें composable बनाती है वह यह है कि नींव पूरे समय एक ही रहती है: समान actions, समान SQL डेटाबेस, और समान agent loop हर आकार को शक्ति देता है। एक नई surface जोड़ने का मतलब यह नहीं है कि नीचे की चीज़ों को फिर से लिखना होगा — आप बस उसी operations तक पहुंचने का एक नया तरीका जोड़ रहे हैं। -पेज अभी व्यक्तिगत scope का उपयोग करता है और पूरे पेज के लिए -**Personal / Organization** टॉगल नहीं देता। underlying actions समर्थन करें तो -कोई टैब अपने संगठन सेक्शन दिखा सकता है: **Automations** Scheduled और Event -दोनों के व्यक्तिगत और संगठन सेक्शन दिखाता है। संगठन Event ऑटोमेशन हमेशा अपने -निर्माता के रूप में चलते हैं। यह पेज मौजूदा -components, actions और access checks की पतली shell है, नई admin console नहीं। - -Agent-Native जानबूझकर रचना योग्य है। आप एजेंट का उपयोग बहुत अधिक UI के बिना कर सकते हैं, -अंतर्निहित एजेंट रनटाइम के बिना UI का उपयोग करें, या दोनों को पूर्ण रूप में एक साथ उपयोग करें -आवेदन. - -चुनने का उपयोगी तरीका पहले प्रोटोकॉल नहीं है। उत्पाद की सतह चुनें -आप चाहें, तो मेल खाने वाले प्रिमिटिव का उपयोग करें। - -| सतह | इसका उपयोग तब करें जब | से प्रारंभ करें | -| ---------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **नेतृत्वहीन एजेंट** | कोड, जॉब, स्क्रिप्ट, अन्य ऐप, या किसी अन्य एजेंट को कार्य को सीधे कॉल करना चाहिए। | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Agent-Native पर रिच चैट** | आप अंतर्निहित एजेंट लूप द्वारा समर्थित एक स्टैंडअलोन या एम्बेडेड चैट चाहते हैं। | [Chat template](/docs/template-chat), ``, `` | -| **आपके एजेंट पर समृद्ध चैट** | आपने एजेंट कहीं और बनाया है और Agent-Native का कंपोजर, ट्रांसक्रिप्ट, टूल कार्ड और नेटिव विजेट चाहते हैं। | `AgentChatRuntime`, `` | -| **एंबेडेड साइडकार** | आपके पास पहले से ही एक SaaS ऐप है और आप उसके पास पेज संदर्भ और होस्ट कमांड के साथ एक एजेंट चाहते हैं। | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **पूर्ण आवेदन** | मनुष्यों और एजेंटों को टिकाऊ स्क्रीन, डेटा, नेविगेशन और सहयोग साझा करना चाहिए। | टेम्पलेट्स, actions, SQL स्थिति, संदर्भ जागरूकता | - -वे चरण हैं, अलग-अलग उत्पाद नहीं। एक वर्कफ़्लो बिना नेतृत्व -एक कार्रवाई के साथ एजेंट, चैट में एक तालिका या चार्ट के रूप में दिखाई देता है, और बाद में एक बन जाता है -एजेंट द्वारा कॉल किए जाने वाले ऑपरेशन को बदले बिना किसी ऐप में पूर्ण स्क्रीन। - - + ```html
- Headlessactions, jobs, scripts, दूसरे agents + Chatcomposer, transcript, tool calls
- rich chatकंपोजर, ट्रांसक्रिप्ट, टूल कार्ड + Inline UItables, charts, cards
- embedded sidecaragent beside an existing app + App pagedurable screens, SQL data
- अधिकांश UIपूर्ण applicationस्थायी स्क्रीन, डेटा, सहयोग + headlessAutomationjobs, scripts, external agents
- वही actions · वही SQL · वही एजेंट लूप + same actions · same SQL · same agent loop
``` @@ -113,180 +70,31 @@ Agent-Native जानबूझकर रचना योग्य है। आ -## नेतृत्वहीन एजेंट {#headless} - -जब किसी को कस्टम ऐप स्क्रीन को घूरने की आवश्यकता न हो तो हेडलेस पथ का उपयोग करें -कार्य चलता है: निर्धारित कार्य, एकीकरण, बैकएंड वर्कफ़्लो, CLI लूप, -कोई अन्य एजेंट, या कोई मौजूदा उत्पाद जो Agent-Native पर कॉल कर रहा है। - -जब **एजेंट *उत्पाद*है** - तब तक पहुंचने के लिए यह आकार भी है - -ऐप-एजेंट लूप सामने का दरवाजा है, डैशबोर्ड नहीं। आप -टर्मिनल, Slack, ईमेल, एक निर्धारित नौकरी, अन्य एजेंट, या चैट - "मेरा सारांश प्रस्तुत करें -अपठित ईमेल," "दैनिक मेट्रिक्स को Slack पर पोस्ट करें," "उन उम्मीदवारों को ढूंढें जो -पिछले सप्ताह उत्तर दिया गया" - और एजेंट कार्य करता है और जहां कहीं भी परिणाम देता है -के अंतर्गत आता है। यह अभी भी एक वास्तविक ऐप है, कोई स्टेटलेस प्रॉम्प्ट नहीं: actions, प्रमाणीकरण सत्र, -ऐप स्थिति, थ्रेड/रन इतिहास, सेटिंग्स, क्रेडेंशियल और शेयर रिकॉर्ड सभी लाइव -SQL में। - -यह पैटर्न तब चुनें जब: - -- **कार्य पृष्ठभूमि में होता है।** अधिकांश मान तब निर्मित होता है जब उपयोगकर्ता नहीं देख रहा होता है - ट्राइएज एजेंट, दैनिक-रिपोर्ट एजेंट, ऑन-कॉल उत्तरदाता। -- **आउटपुट ऐप छोड़ देता है।** एजेंट Slack पर पोस्ट करता है, ईमेल भेजता है, या तीसरे पक्ष के सिस्टम को अपडेट करता है; ऐप में ब्राउज़ करने के लिए कुछ भी नहीं है। -- **डोमेन एक-शॉट है।** अनुसंधान बॉट, सारांश जनरेटर, रिपोर्ट लेखक - कोई स्थायी वस्तु नहीं है जिसके लिए सूची दृश्य की आवश्यकता हो। -- **आप प्रोटोटाइप कर रहे हैं।** एजेंट को अभी भेजें; यदि उपयोगकर्ता चाहें तो बाद में अधिक समृद्ध UI जोड़ें। - -यदि आपका उत्पाद उपयोगकर्ताओं द्वारा ब्राउज़, पिवोट और लगातार उपयोग की जाने वाली वस्तुओं के आधार पर बनाया गया है -साझा करें - ईमेल, ईवेंट, दस्तावेज़, चार्ट - एक [full application](#full-application) चुनें -या इसके बजाय एक [template](/docs/cloneable-saas); वे एक पूर्ण UI _प्लस_ एजेंट जोड़ते हैं। - -### बॉक्स में क्या भेजा जाता है {#in-the-box} - -एक हेडलेस ऐप कई हफ्तों तक डैशबोर्ड पर काम नहीं करता है, और यह दिन से चैनल-अज्ञेयवादी हो जाता है -एक - एक ही एजेंट वेब, Slack, टेलीग्राम, ईमेल और अन्य एजेंटों से चलता है -क्योंकि सब कुछ एजेंट के माध्यम से जाता है, UI के माध्यम से नहीं। समझौता वहीं है -कोई "हर चीज़-एक-नज़र में ब्राउज़ करें" दृश्य नहीं; यदि उपयोगकर्ताओं को इसकी आवश्यकता है, तो पैटर्न मिलाएं और -एक छोटा स्थिति पृष्ठ या सूची दृश्य जोड़ें। - -जब आप अंतर्निहित चैट शेल जोड़ते हैं, तो फ्रेमवर्क पांच प्रबंधन प्रदान करता है -ऐसी सतहें जिन्हें आपको बनाने की ज़रूरत नहीं है: **चैट** (मुख्य इनपुट), **कार्यस्थान** -(skills, मेमोरी, निर्देश, उप-एजेंट, कनेक्टेड MCP सर्वर, शेड्यूल किया गया -नौकरियाँ), **कार्य इतिहास**, **थ्रेड इतिहास**, और **सेटिंग्स**। वे आमतौर पर -पर्याप्त - उससे बात करें, देखें कि उसने क्या किया है, कॉन्फ़िगर करें कि वह कैसा व्यवहार करता है। के लिए पहुंचें -[Chat](/docs/template-chat) जब आप उस ब्राउज़र को जोड़ने के लिए तैयार हों UI, या -कार्यस्थान-शैली की शुरुआत के लिए [Dispatch template](/docs/template-dispatch) -Slack/टेलीग्राम, निर्धारित नौकरियों और बॉक्स से बाहर साझा रहस्यों के साथ बिंदु। - -सबसे छोटा स्थानीय पथ एक हेडलेस एजेंट मचान और एक क्रिया है: - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -फिर टिकाऊ संचालन को परिभाषित करें: - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -तब एक क्रिया को इस प्रकार कॉल किया जा सकता है: - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **ऐप-एजेंट CLI** — `pnpm agent "Summarize form_123"` -- **MCP** - Claude, ChatGPT, Codex, कर्सर, ओपनकोड, कोपायलट और अन्य MCP होस्ट से -- **A2A** - किसी अन्य एजेंट-मूल ऐप या एजेंट सहकर्मी से -- **UI** — `useActionQuery`, `useActionMutation`, या `callAction` के माध्यम से -- **एजेंट टूल** - अंतर्निहित चैट लूप से - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -यह नो-डेटाबेस या स्टेटलेस मोड नहीं है। ऐप-एजेंट लूप सत्र संग्रहीत करता है, -थ्रेड्स, रन, सेटिंग्स, क्रेडेंशियल्स, एप्लिकेशन स्थिति और शेयर रिकॉर्ड -SQL. स्थानीय विकास SQLite पर डिफ़ॉल्ट होता है; होस्ट किए गए हेडलेस ऐप्स को a -लगातार SQL डेटाबेस। +## एक शुरुआती बिंदु चुनें -यदि आपको प्रोजेक्ट फ़ोल्डर से संपूर्ण एजेंट लूप को बिना किसी प्रयास के चाहिए, तो इसका उपयोग करें: +Chat सबसे सामान्य प्रवेश बिंदु है। जब आउटपुट समृद्ध होता है तो ऐप्स आमतौर पर इनलाइन UI बढ़ाते हैं, फिर जब उपयोगकर्ताओं को ब्राउज़ और शेयर करने के लिए स्थायी ऑब्जेक्ट की आवश्यकता होती है तो पूर्ण ऐप पेज जोड़ते हैं। वही actions बाद में आने वाले बटन, शेड्यूल की गई jobs, और बाहरी agents को शक्ति देते हैं। Embedded sidecar का उपयोग तब करें जब किसी ऐसे product में एजेंट जोड़ना हो जो आपके पास पहले से है, या बिना ब्राउज़र के चलने वाले काम के लिए Automation-first का उपयोग करें। यहाँ पूरी तस्वीर है: -```bash -pnpm agent "Summarize this week's forms." -``` - -यदि किसी अन्य ऐप या स्क्रिप्ट को पूरे एजेंट को कॉल करने की आवश्यकता है, तो इसका उपयोग करें -`agentNative.invoke("analytics", "...")` या `agent-native invoke` CLI। वह -क्रॉस-ऐप कार्य को A2A पथ पर रखता है जबकि स्थानीय कार्य actions पर रहता है। - -कर्मचारी, नौकरियां, एकीकरण webhooks और कस्टम होस्ट एजेंट लूप चला सकते हैं -सीधे सर्वर API के माध्यम से। यह actions से निम्न-स्तर है - आप प्रदान करते हैं -इंजन, मॉडल, संदेश, actions, और ईवेंट स्वयं सिंक हो जाते हैं: - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` +| Surface | इसका उपयोग कब करें | इससे शुरू करें | +| ----------------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **[Rich chat](#rich-chat)** | उपयोगकर्ता एजेंट से बात करते हैं, tool calls देखते हैं, और thread history रखते हैं। | [Chat template](/docs/template-chat), `` | +| **[Native inline UI](#native-inline-ui)** | Action परिणाम चैट में tables, charts, cards, या approvals के रूप में रेंडर होने चाहिए। | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[Generated inline UI](#generated-inline-ui)** | एजेंट को चैट के अंदर तुरंत temporary या reusable controls बनाने चाहिए। | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[Full application](#full-application)** | उपयोगकर्ताओं को टिकाऊ screens, shared data, navigation, और collaboration चाहिए। | Templates, actions, SQL state, context awareness | +| **[Embedded sidecar](#embedded-sidecar)** | आपके पास पहले से SaaS ऐप है और उसके साथ page context वाला एजेंट चाहिए। | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[Automation-first](#headless)** | Jobs, scripts, या अन्य agents बिना ब्राउज़र UI के सीधे काम करते हैं। | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[Rich chat on your agent](#byo-agent)** | आपने एजेंट कहीं और बनाया है और Agent-Native का chat UI उसके चारों ओर चाहते हैं। | `AgentChatRuntime`, `` | -अधिकांश ऐप्स के लिए, निर्धारित संकेत और एकीकरण webhooks पहले से ही इस लूप को कॉल करते हैं -आपके लिए। कस्टम हेडलेस होस्ट बनाते समय ही सीधे उस तक पहुंचें, eval -रनर, या सर्वर-साइड ऑर्केस्ट्रेशन सतह - [सर्वर - प्रोडक्शन एजेंट -हैंडलर](/docs/server#agent-handler) पूर्ण हस्ताक्षर के लिए। +## Agent-Native पर Rich chat {#rich-chat} -### फ़ोल्डर के विरुद्ध चल रहा है {#folder-loop} +बिल्ट-इन chat का उपयोग तब करें जब उपयोगकर्ता को एजेंट से बात करनी हो, tool calls देखनी हों, काम approve करना हो, native results inspect करने हों, और एक टिकाऊ thread history रखनी हो। -यदि आपका लक्ष्य "इस फ़ोल्डर के विरुद्ध एक एजेंट चलाना" है, तो ऐप-एजेंट से शुरुआत करें -उस फ़ोल्डर में लूप करें: हेडलेस ऐप को स्कैफोल्ड करें, actions/निर्देश जोड़ें, चलाएं -`pnpm agent "..."`. यह कार्य को उसी क्रिया/रनटाइम/स्थिति में रखता है -ऐप अनुबंध का उपयोग उत्पादन में करेगा। - -बाहरी कोडिंग हार्नेस Claude को एम्बेड करने के लिए एक अलग उत्पाद सतह है -कोड, Codex, Pi, कर्सर, मास्ट्रा, या Agent-Native ऐप के अंदर समान रनटाइम। -जब आप कोडिंग-एजेंट उत्पाद बना रहे हों तो उनका उपयोग करें, डिफ़ॉल्ट तरीके के रूप में नहीं -एक स्थानीय एजेंट-मूल वर्कफ़्लो प्रारंभ करें। - -### क्लाउड रेपो एक्सेस {#cloud-repo-access} - -क्लाउड हेडलेस ऐप्स के लिए जिन्हें रिपॉजिटरी एक्सेस की आवश्यकता है, GitHub कनेक्टर का उपयोग करें -प्लस टोकन CRUD मॉडल: रिपॉजिटरी की सूची बनाएं, फ़ाइलें खोजें, फ़ाइलें पढ़ें, बनाएं या -फ़ाइलें संपादित करें, फ़ाइलें हटाएं, और प्रदाता-दायरे के माध्यम से पहुंच रद्द करें -प्रमाणपत्र. स्थानीय विकास में, लक्ष्य भंडार को स्पष्ट रूप से सेट करें: - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -VM क्लोन या लंबे समय तक चलने वाले सैंडबॉक्स चेकआउट को प्राथमिक क्लाउड न मानें -रेपो-एक्सेस मॉडल। पृथक कोड निष्पादन के लिए सैंडबॉक्स अभी भी मायने रखते हैं, लेकिन -रिपोजिटरी पहुंच स्पष्ट, अनुमति प्राप्त, ऑडिट योग्य और प्रतिसंहरणीय होनी चाहिए -कनेक्टर परत के माध्यम से। - -### सत्र और रन साझा करना {#sharing-runs} - -बिना सोचे-समझे सत्र और रन टिकाऊ वस्तुएं हैं। साझाकरण को चरणबद्ध किया जाना चाहिए: -पहले लिंक पढ़ें/साझा करें, ताकि टीम के साथी स्वच्छ संकेतों, आउटपुट का निरीक्षण कर सकें -और रन स्थिति; बाद में लिखने योग्य सहयोग की अनुमति दी गई, इसलिए एक रन जारी रखें, -actions को मंजूरी देना, शेड्यूल संपादित करना, या कॉन्फ़िगरेशन बदलना -स्पष्ट पहुंच जांच। - -## Agent-Native पर रिच चैट {#rich-chat} - -जब उपयोगकर्ता को एजेंट से बात करनी हो, टूल कॉल देखें, तो अंतर्निहित चैट का उपयोग करें -कार्य को मंजूरी दें, मूल परिणामों का निरीक्षण करें, और एक टिकाऊ थ्रेड इतिहास रखें। - -पूर्ण ऐप शुरुआती बिंदु के लिए, [Chat template](/docs/template-chat) का उपयोग करें: +एक पूर्ण ऐप शुरुआती बिंदु के लिए, [Chat template](/docs/template-chat) का उपयोग करें: ```bash npx @agent-native/core@latest create my-chat-app --template chat ``` -सबसे सरल पूर्ण-पृष्ठ चैट: +सबसे सरल full-page chat: ```tsx import { AgentChatSurface } from "@agent-native/core/client/chat"; @@ -296,11 +104,7 @@ export default function ChatRoute() { } ``` -जब किसी ऐप में पूर्ण-पृष्ठ चैट टैब और `AgentSidebar` दोनों हों, तो इसका उपयोग करें -दोनों सतहों पर `storageKey`, `chatViewTransition` सक्षम करें, और इंस्टॉल करें -लेआउट में चैट-होम हैंडऑफ़ हेल्पर्स। सामान्य इन-ऐप लिंक चैट से बाहर -पेज फिर सक्रिय रहते हुए पूरी चैट को साइडबार में रूपांतरित कर सकता है -थ्रेड: +जब किसी ऐप में full-page chat tab और `AgentSidebar` दोनों हों, तो दोनों surfaces पर एक ही `storageKey` का उपयोग करें, `chatViewTransition` सक्षम करें, और layout में chat-home handoff helpers इंस्टॉल करें। chat पेज से बाहर के सामान्य in-app links तब full chat को sidebar में morph कर सकते हैं जबकि active thread बनाए रखते हैं: ```tsx import { @@ -338,7 +142,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -आपके अपने क्रोम के साथ सबसे सरल एम्बेडेड चैट: +अपने chrome के साथ सबसे सरल embedded chat: ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -348,51 +152,104 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -Actions स्पष्ट देशी विजेट परिणाम लौटा सकता है इसलिए चैट आउटपुट सिर्फ -पाठ. तालिकाएँ, चार्ट और टाइप किए गए उत्पाद कार्ड प्रथम-पक्ष React -चैट में घटक, आईफ्रेम के बिना। [Native चैट UI](/docs/native-chat-ui) देखें. +Actions स्पष्ट native widget results वापस कर सकते हैं ताकि chat आउटपुट केवल टेक्स्ट न हो। Tables, charts, और typed product cards iframes के बिना chat में first-party React components के रूप में रेंडर होते हैं। [Native Chat UI](/docs/native-chat-ui) देखें। जब एजेंट को पूर्वनिर्धारित React widget के बजाय arbitrary generated controls की आवश्यकता हो, तो [Generative UI](/docs/generative-ui) का उपयोग करें: यह sandboxed Alpine/Tailwind UI इनलाइन रेंडर करता है, app state और slot context पढ़ सकता है, और चुने गए values को chat में वापस भेज सकता है। -## अपने एजेंट पर रिच चैट {#byo-agent} +## Native inline UI {#native-inline-ui} -इस पथ का उपयोग तब करें जब आपका एजेंट पहले से ही किसी अन्य ढांचे के साथ बना हो या -रनटाइम और आप इसके आसपास Agent-Native की चैट UI चाहते हैं। `AgentChatRuntime` है -सीमा: आपका रनटाइम सामान्यीकृत घटनाओं को स्ट्रीम करता है, और Agent-Native रेंडर करता है -कंपोजर, ट्रांसक्रिप्ट, टूल कॉल, अनुमोदन, मूल विजेट और ऐप लेआउट। +इसका उपयोग तब करें जब आपके actions structured data वापस करते हैं — records की एक list, एक chart dataset, एक status summary — जो plain text विवरण के बजाय chat thread के अंदर एक वास्तविक UI component के रूप में रेंडर होनी चाहिए। आप action पर एक `chatUI` renderer परिभाषित करते हैं, और Agent-Native इसे एक first-party React component के रूप में रेंडर करता है: कोई iframes नहीं, कोई अलग rendering path नहीं। -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +यह सही विकल्प है जब आउटपुट का एक स्पष्ट, reusable आकार हो जिसे आप एक बार डिज़ाइन करेंगे और कई agent responses में उपयोग करेंगे। उन controls के लिए जिन्हें एजेंट को runtime पर dynamically बनाने की आवश्यकता है, इसके बजाय [Generated inline UI](#generated-inline-ui) देखें। -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +पूर्ण renderer API, widget library, और BYO agent runtime integration के लिए [Native Chat UI](/docs/native-chat-ui) देखें। -export function SupportAgentChat() { - return ; +## Generated inline UI {#generated-inline-ui} + +इसका उपयोग तब करें जब एजेंट को ऐसा control बनाना हो जो अभी तक pre-built widget के रूप में मौजूद नहीं है — एक custom form, वर्तमान context के आधार पर बना picker, एक बार का calculator। native widgets के विपरीत, generated UI को एजेंट runtime पर Alpine.js और Tailwind से compose करता है, iframe में sandboxed चलता है, और चुने गए values को chat thread में वापस भेज सकता है। + +Generated UI transient (एक बार रेंडर होकर हटाई गई) या एक reusable extension के रूप में saved हो सकती है जो उपयोगकर्ता के लिए persist करती है। + +पूर्ण API, sandbox constraints, और extension persistence model के लिए [Generative UI](/docs/generative-ui) देखें। + +## Full application {#full-application} + +full app path का उपयोग तब करें जब उपयोगकर्ताओं को टिकाऊ objects और workflows की आवश्यकता हो: forms, dashboards, calendars, inboxes, editors, documents, assets, या reports। + +Full apps उसी action और agent contract के चारों ओर product UI जोड़ते हैं: + + + +### SQL state + +App data, navigation, settings, और chat history सभी टिकाऊ हैं। एजेंट उन्हीं rows को पढ़ता और लिखता है जो UI करता है। + +### Context awareness + +एजेंट वर्तमान route, selection, और focused object जानता है, इसलिए "इसे edit करें" का मतलब हमेशा सही चीज़ होती है। + +### Live sync + +एजेंट के बदलाव UI को real time में अपडेट करते हैं, और UI के बदलाव एजेंट के context को अपडेट करते हैं। कोई polling नहीं, कोई refresh नहीं। + +### Deep links + +Action परिणाम सीधे सही app view खोल सकते हैं: एक chart dashboard से link करता है, एक draft inbox से link करता है। + +### Native chat widgets + +Tables, charts, cards, approvals, और typed results chat में first-party React components के रूप में इनलाइन रेंडर होते हैं। + +### Generative UI and extensions + +एजेंट तुरंत inline controls बना सकता है, और reusable mini-apps save कर सकता है जब किसी workflow को persist करना हो। + + + +[Chat template](/docs/template-chat) से शुरू करें जब आप अपने actions के चारों ओर एक minimal app चाहते हों, या किसी domain [template](/docs/cloneable-saas) से जब आप एक complete product shape चाहते हों। + +### Full-page Manage Agent {#agent-page} + +हर Agent-Native ऐप को अंततः एक ऐसी जगह की आवश्यकता होती है जहाँ उपयोगकर्ता अपने एजेंट को configure कर सकें: standing instructions सेट करना, क्या हुआ है यह review करना, MCP servers connect करना, automations manage करना, और access control करना। उस UI को scratch से बनाना बहुत काम है। Agent-Native एक pre-built full-page component, `AgentTabsPage`, ship करता है जो बारह tabs में यह सब cover करता है। + +इसे अपने ऐप में `/agent` पर mount करें। वर्तमान templates उस route को app-navigation entry के साथ pair करते हैं और `AgentSidebar` को `agentPageHref="/agent"` पास करते हैं, ताकि sidebar के Resources और Settings modes उन flows को duplicate किए बिना पूर्ण पेज से link कर सकें। + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -OpenAI एजेंटों, OpenAI प्रतिक्रियाओं, Claude के लिए तैयार रनटाइम सहायक मौजूद हैं -एजेंट SDK, वर्सेल AI SDK, और AG-UI, साथ ही उपरोक्त सामान्यीकृत HTTP रनटाइम -किसी अन्य एजेंट के लिए (मास्ट्रा, फ़्लू, ईव, लैंगग्राफ, या एक कस्टम सेवा)। ACP है -अंतिम-उपयोगकर्ता ऐप चैट या A2A ट्रांसपोर्ट नहीं, और Agent-Native वर्तमान में नहीं है -A2UI समर्थन का दावा करें। ACP एक विशिष्ट स्थान पर समर्थित है - लोकल ड्राइविंग -कोडिंग एजेंट (मिथुन CLI, Claude कोड,…) के माध्यम से -[harness layer](/docs/harness-agents#acp), यहां चैट रनटाइम के रूप में नहीं। +साझा पेज वर्तमान में दो groups में बारह tabs प्रदान करता है: + +| Group | Tab | दिखाता है | +| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | व्यक्तिगत या organization files के लिए मौजूदा `ResourcesPanel` | +| Resources | **Instructions** | हमेशा-चालू AGENTS.md-style rules | +| Resources | **Agents** | Custom sub-agent profiles | +| Resources | **Memory** | Long-term recall notes | +| Resources | **Skills** | Reusable workflows | +| Resources | **Learnings** | समय के साथ captured corrections और patterns | +| Resources | **Remote agents** | अन्य agent-native apps से A2A connections (Connections tab जो पहले दिखाता था उसे replace करता है) | +| Agent | **Snapshots** | एक scope preview, token budget, provenance/governance/source के अनुसार grouped ordered system sections, और नवीनतम live-thread snapshot। "Context" से renamed; पुराने `#context` links यहाँ redirect होते हैं। | +| Agent | **Connections** | केवल MCP server management | +| Agent | **Automations** | pause/resume, details, और delete flows के साथ Personal और organization Scheduled/Event automations। stable compatibility URL `/agent#jobs` रहता है। | +| Agent | **Settings** | Agent model, API keys, limits, voice, और automation settings | +| Agent | **Access** | App MCP URL, उपलब्ध होने पर A2A agent card, और Claude, ChatGPT, Cursor, Claude Code, Codex, और अन्य clients के लिए shared setup guides। पूर्ण connect flow और token fallback के लिए `/mcp/connect` से links। | + +पेज केवल personal (`user`-scope) data दिखाता है। आज कोई org-level toggle नहीं है। यह मौजूदा components और access checks पर एक thin shell है, कोई नया admin console नहीं: Connections बताता है कि ऐप क्या call कर सकता है; Access बताता है कि बाहरी clients इससे कैसे connect होते हैं। + +अभी तक शामिल नहीं: -[Native चैट UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -इवेंट आकृतियों, रनटाइम हेल्पर्स और `chatUI` के लिए विहित घर है -टूल-परिणाम मेटाडेटा। किसी बाहरी एजेंट को चैट में शामिल करते समय वहीं से शुरुआत करें। +- Organization-scoped view +- Grants और scope editing +- Revocation UI +- Per-iteration provenance history -## एंबेडेड साइडकार {#embedded-sidecar} +## Embedded sidecar {#embedded-sidecar} -जब मुख्य उत्पाद पहले से मौजूद हो और आप चाहते हों तो एम्बेडेड साइडकार का उपयोग करें -इसके बगल में एजेंट। +Embedded sidecar का उपयोग तब करें जब मुख्य product पहले से मौजूद हो और आप उसके साथ एजेंट चाहते हों। -सर्वर प्लगइन आपके होस्ट ऐप में Agent-Native रूट्स को माउंट करता है और हल करता है -होस्ट पहचान सर्वर-साइड: +Server plugin आपके host app में Agent-Native routes mount करता है और host identity server-side resolve करता है: ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -404,7 +261,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -React साइडकार पेज संदर्भ और होस्ट कमांड पास करता है: +React sidecar page context और host commands पास करता है: ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -426,19 +283,23 @@ export function AppShell({ children }) { } ``` - +### यह कैसे connect होता है + +दो टुकड़े एक bridge के रूप में काम करते हैं: host app page context (current route, selected text, focused object) को `AgentNativeEmbedded` में पास करता है, और एजेंट `onNavigate` और `onRefresh` के माध्यम से commands वापस भेजता है। Server plugin identity handle करता है — यह host session को resolve करता है ताकि एजेंट एक अलग login के बिना सही उपयोगकर्ता के रूप में कार्य करे। Host app में कुछ भी बदलने की आवश्यकता नहीं है; plugin Agent-Native के routes को आपके मौजूदा routes के साथ attach करता है। + + ```html
- host appHost appआपका मौजूदा SaaS
- getContext()
रूट · चयन + getContext()
route · selection
onNavigate / onRefresh
होस्ट commandshost commands
@@ -448,10 +309,10 @@ export function AppShell({ children }) {
AgentNativeEmbeddedagent + workspace + >agent + resources
- Agent-Native रूट
mounted by the server pluginserver plugin द्वारा mounted
@@ -485,45 +346,180 @@ export function AppShell({ children }) { -होस्ट ऑथ, डेटाबेस आइसोलेशन के लिए [Embedding SDK](/docs/embedding-sdk) देखें -आईफ्रेम/पिकर मोड, और निचले स्तर का ब्रिज APIs। +Host auth, database isolation, iframe/picker mode, और lower-level bridge APIs के लिए [Embedding SDK](/docs/embedding-sdk) देखें। + +## Automation-first app {#headless} + +Automation-first path का उपयोग तब करें जब काम चलते समय किसी को custom browser screen की आवश्यकता न हो: scheduled jobs, integrations, backend workflows, CLI loops, दूसरा एजेंट, या कोई मौजूदा product जो Agent-Native को call करता हो। + +यह वह आकार है जो तब उपयोग करना चाहिए जब automation product surface हो। आप terminal, Slack, email, scheduled job, दूसरे एजेंट, या Chat से एक request भेजते हैं ("मेरे unread emails summarize करो," "Slack पर daily metrics post करो," "पिछले हफ्ते reply करने वाले candidates ढूंढो") और एजेंट कार्य करता है और परिणाम जहाँ वह होना चाहिए वहाँ वापस करता है। यह अभी भी एक वास्तविक ऐप है, कोई stateless prompt नहीं: actions, auth sessions, app state, thread/run history, settings, credentials, और share records सभी SQL में रहते हैं। + +इस pattern को तब चुनें जब: + +- **काम background में होता है।** अधिकांश value तब बनाई जाती है जब उपयोगकर्ता नहीं देख रहा: triage agents, daily-report agents, on-call responders। +- **आउटपुट ऐप से बाहर जाता है।** एजेंट Slack पर post करता है, email भेजता है, या third-party system अपडेट करता है; ऐप में browse करने के लिए कुछ नहीं है। +- **Domain one-shot है।** Research bot, summary generator, report writer जिसमें कोई persistent object नहीं है जिसे list view की आवश्यकता हो। +- **आप एक automation prototype कर रहे हैं।** अभी operation ship करें; जब उपयोगकर्ताओं को inspect और steer करने की आवश्यकता हो तो chat या app pages जोड़ें। + +यदि आपका product persistent objects के चारों ओर बना है जिन्हें उपयोगकर्ता browse, pivot, और share करते हैं (emails, events, documents, charts), तो इसके बजाय [full application](#full-application) या [template](/docs/cloneable-saas) चुनें; वे पूर्ण UI _plus_ एजेंट जोड़ते हैं। + +### बॉक्स में क्या आता है {#in-the-box} + +एक automation-first ऐप dashboard काम छोड़ देता है, और यह day one से channel-agnostic है। वही एजेंट web, Slack, Telegram, email, और अन्य agents से चलता है क्योंकि सब कुछ उन्हीं actions के माध्यम से जाता है। trade-off यह है कि कोई "सब कुछ एक नज़र में" view नहीं है; यदि उपयोगकर्ताओं को इसकी आवश्यकता है, तो [Chat](/docs/template-chat) से शुरू करें या एक छोटा status page या list view जोड़ें। + +जब आप built-in Chat shell जोड़ते हैं, तो framework पाँच management surfaces प्रदान करता है जिन्हें आपको बनाना नहीं है: **Chat** (मुख्य input), **Resources** (skills, memory, instructions, sub-agents, और connected MCP servers), **Automations**, **Thread history**, और **Settings**। वे आमतौर पर पर्याप्त हैं: इससे बात करें, देखें क्या हुआ है, configure करें यह कैसे behave करता है। [Chat](/docs/template-chat) के लिए पहुंचें जब आप वह browser UI जोड़ने के लिए तैयार हों, या Slack/Telegram, scheduled jobs, और shared secrets के साथ workspace-style शुरुआती बिंदु के लिए [Dispatch template](/docs/template-dispatch) के लिए। + +सबसे छोटा no-browser local path एक scaffold plus एक action है: + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +फिर टिकाऊ operation परिभाषित करें: -## पूर्ण आवेदन {#full-application} +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; -जब उपयोगकर्ताओं को टिकाऊ ऑब्जेक्ट और वर्कफ़्लो की आवश्यकता हो तो पूर्ण ऐप पथ का उपयोग करें: फ़ॉर्म, -डैशबोर्ड, कैलेंडर, इनबॉक्स, संपादक, दस्तावेज़, संपत्ति, या रिपोर्ट। +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` -पूर्ण ऐप्स समान क्रिया और एजेंट अनुबंध के आसपास उत्पाद UI जोड़ते हैं: +एक action को इस प्रकार call किया जा सकता है: -- **SQL स्थिति** — ऐप डेटा, नेविगेशन, सेटिंग्स और चैट इतिहास टिकाऊ हैं। -- **संदर्भ जागरूकता** - एजेंट वर्तमान मार्ग, चयन और केंद्रित वस्तु को जानता है। -- **लाइव सिंक** - एजेंट परिवर्तन UI को अपडेट करते हैं, और UI परिवर्तन एजेंट के संदर्भ को अपडेट करते हैं। -- **डीप लिंक** — कार्रवाई के परिणाम सही ऐप दृश्य खोल सकते हैं। -- **मूल चैट विजेट** — टेबल, चार्ट, कार्ड, अनुमोदन और टाइप किए गए परिणाम इनलाइन दिखाई देते हैं। +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **App-agent CLI:** `pnpm agent "Summarize form_123"` +- **MCP:** Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot, और अन्य MCP hosts से +- **A2A:** किसी अन्य agent-native app या agent peer से +- **UI:** `useActionQuery`, `useActionMutation`, या `callAction` के माध्यम से +- **Agent tool:** built-in chat loop से -जब आपको न्यूनतम ऐप चाहिए तो [Chat template](/docs/template-chat) से प्रारंभ करें -आपके actions के आसपास, या किसी डोमेन [template](/docs/cloneable-saas) से जब आप -एक संपूर्ण उत्पाद आकार चाहते हैं। + + +हर `defineAction` `/_agent-native/actions/` पर auto-mount होता है। `run` execute होने से पहले JSON body को action के zod schema के विरुद्ध validate किया जाता है। इसे long-lived bearer token के साथ external system से call करने के लिए, [HTTP API](/docs/http-api) देखें। -## कैसे चुनें {#how-to-choose} + -| अगर आप सोच रहे हैं... | चुनें | -| -------------------------------------------------------------------------------- | ----------------------- | -| "मुझे बस एक कॉल करने योग्य टूल या वर्कफ़्लो की आवश्यकता है।" | नेतृत्वहीन एजेंट | -| "मुझे फ़्रेमवर्क का एजेंट चाहिए, लेकिन चैट मुख्य UI होनी चाहिए।" | Agent-Native पर रिच चैट | -| "मेरे पास पहले से ही एक एजेंट है; मुझे इसके लिए एक बेहतर चैट UI की आवश्यकता है।" | अपने एजेंट पर रिच चैट | -| "मेरे पास पहले से ही एक SaaS ऐप है; इसके बगल में एक एजेंट जोड़ें।" | एम्बेडेड साइडकार | -| "एजेंट और UI को उत्पाद के रूप में एक साथ विकसित होना चाहिए।" | पूर्ण आवेदन | +यह no-database या stateless mode नहीं है। App-agent loop SQL में sessions, threads, runs, settings, credentials, application state, और share records store करता है। Local development defaults SQLite पर; hosted automation-first apps को persistent SQL database का उपयोग करना चाहिए। -अनुबंध को छोटा रखें: टिकाऊ संचालन को actions के रूप में परिभाषित करें, स्पष्ट वापसी करें -विजेट परिणाम जब चैट को समृद्ध UI की आवश्यकता होती है, और पूर्ण स्क्रीन केवल तभी जोड़ते हैं जब उपयोगकर्ता -लगातार वस्तुओं को ब्राउज़ करने, तुलना करने, कॉन्फ़िगर करने या सहयोग करने की आवश्यकता है। +यदि आपको project folder से पूरे agent loop को headlessly चलाने की आवश्यकता है, तो उपयोग करें: + +```bash +pnpm agent "Summarize this week's forms." +``` + +यदि किसी अन्य ऐप या script को पूरे एजेंट को call करने की आवश्यकता है, तो `agentNative.invoke("analytics", "...")` या `agent-native invoke` CLI का उपयोग करें। यह cross-app काम को A2A path पर रखता है जबकि local काम actions पर रहता है। + +Workers, jobs, integration webhooks, और custom hosts server API के माध्यम से agent loop को सीधे drive कर सकते हैं। यह actions से lower-level है — आप engine, model, messages, tools, actions, एक event sink, और एक abort signal खुद प्रदान करते हैं: + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +अधिकांश apps के लिए, scheduled prompts और integration webhooks पहले से ही इस loop को आपके लिए call करते हैं। इसे सीधे तभी उपयोग करें जब custom no-browser host, eval runner, या server-side orchestration surface बना रहे हों। पूर्ण signature के लिए [Server: Production agent handler](/docs/server#agent-handler) देखें। + +### एक folder के विरुद्ध चलाना {#folder-loop} + +यदि आपका लक्ष्य "इस folder के विरुद्ध एजेंट चलाना" है, तो उस folder में app-agent loop से शुरू करें: automation-first app scaffold करें, actions/instructions जोड़ें, `pnpm agent "..."` चलाएं। यह काम को उसी action/runtime/state contract के अंदर रखता है जो ऐप production में उपयोग करेगा। + +External coding harnesses एक अलग product surface हैं जो Claude Code, Codex, Pi, Cursor, Mastra, या इसी तरह के runtimes को Agent-Native ऐप के अंदर embed करने के लिए हैं। इनका उपयोग तब करें जब आप coding-agent product बना रहे हों, न कि local agent-native workflow शुरू करने के default तरीके के रूप में। + +### Cloud repo access {#cloud-repo-access} + +Cloud automation-first apps के लिए जिन्हें repository access की आवश्यकता है, GitHub connector plus token CRUD model का उपयोग करें: repositories list करना, files search करना, files read करना, files create या edit करना, files delete करना, और provider-scoped credentials के माध्यम से access revoke करना। Local development में, target repository को explicitly set करें: + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +VM clone या long-lived sandbox checkout को primary cloud repo-access model के रूप में treat न करें। Sandboxes isolated code execution के लिए अभी भी महत्वपूर्ण हैं, लेकिन repository access connector layer के माध्यम से explicit, permissioned, auditable, और revocable होनी चाहिए। + +### Sessions और runs share करना {#sharing-runs} + +Automation-first sessions और runs टिकाऊ objects हैं। Shareability को phased होना चाहिए: पहले read/share links, ताकि teammates sanitized prompts, outputs, और run status inspect कर सकें; बाद में permissioned writable collaboration, ताकि run continue करना, actions approve करना, schedules edit करना, या configuration बदलना explicit access checks के माध्यम से जाए। + +## अपने एजेंट पर Rich chat {#byo-agent} + +इस path का उपयोग तब करें जब आपका एजेंट किसी अन्य framework या runtime के साथ पहले से बना हो और आप उसके चारों ओर Agent-Native का chat UI चाहते हों। `AgentChatRuntime` boundary है: आपका runtime normalized events stream करता है, और Agent-Native composer, transcript, tool calls, approvals, native widgets, और app layout render करता है। + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` + +OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, और AG-UI के लिए ready-made runtime helpers मौजूद हैं, plus किसी भी अन्य एजेंट (Mastra, Flue, Eve, LangGraph, या custom service) के लिए ऊपर normalized HTTP runtime। ACP end-user app chat या A2A transport नहीं है, और Agent-Native वर्तमान में A2UI support का दावा नहीं करता। ACP एक specific जगह में support किया जाता है: [harness layer](/docs/harness-agents#acp) के माध्यम से local coding agent (Gemini CLI, Claude Code, ...) को drive करना, यहाँ chat runtime के रूप में नहीं। + +[Native Chat UI: BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) event shapes, runtime helpers, और `chatUI` tool-result metadata का canonical home है। External एजेंट को chat में wire करते समय वहाँ से शुरू करें। ## आगे क्या है {#related-docs} -- [**Actions**](/docs/actions) — ऑपरेशन को एक बार परिभाषित करें; ऊपर की हर सतह उसी को कॉल करती है -- [**Native चैट UI**](/docs/native-chat-ui) — टाइप किए गए action परिणामों को चैट में टेबल, चार्ट और कार्ड के रूप में दिखाएँ -- [**Generative UI**](/docs/generative-ui) — चैट में अस्थायी या सहेजी गई sandbox UI बनाएँ -- [**Automation-First Apps**](/docs/pure-agent-apps) — jobs, queues, scripts और बाहरी agents के लिए पूरा बिना-ब्राउज़र पैटर्न -- [**External Agents**](/docs/external-agents) — MCP-संगत hosts को ऐप से जोड़ें -- [**A2A Protocol**](/docs/a2a-protocol) — अन्य Agent-Native ऐप्स से agents को कॉल करें + + +### [Actions](/docs/actions) + +Operation एक बार परिभाषित करें। ऊपर की हर surface एक ही को call करती है। + +### [Native Chat UI](/docs/native-chat-ui) + +Typed action results को tables, charts, और cards के रूप में सीधे chat में render करें। + +### [Generative UI](/docs/generative-ui) + +Chat में transient या persisted sandboxed UI इनलाइन generate करें। + +### [Automation-First Apps](/docs/pure-agent-apps) + +Jobs, queues, scripts, और external agents के लिए पूर्ण no-browser pattern। + +### [External Agents](/docs/external-agents) + +MCP-compatible hosts को आपके ऐप से tool server के रूप में connect करें। + +### [A2A Protocol](/docs/a2a-protocol) + +A2A standard पर अन्य agent-native apps के agents को call करें। + + diff --git a/packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx b/packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx index e6e9599e7d..47198315cf 100644 --- a/packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx @@ -1,89 +1,46 @@ --- -title: "エージェント サーフェス" -description: "Agent-Native をヘッドレスで、リッチ チャットとして、既存のアプリ内で、または完全なエージェント ネイティブ アプリケーションとして使用します。" -search: "ヘッドレス エージェント リッチ チャット フル アプリ BYO エージェント ランタイム AgentChatRuntime 埋め込み actions MCP A2A HTTP CLI" +title: "エージェントサーフェス" +description: "チャットからインラインUI、永続的なアプリページ、埋め込みサイドカー、自動化、外部エージェントアクセスまで、エージェントアプリの拡張方法を選択してください。" +search: "エージェントアプリ リッチチャット ネイティブチャットUI フルアプリ 自動化 ヘッドレス BYO エージェントランタイム AgentChatRuntime 埋め込み アクション MCP A2A HTTP CLI" --- -# エージェント サーフェス +# エージェントサーフェス -## フルページの Agent ワークスペース {#agent-page} +**サーフェス**とは、ユーザー（または他のシステム）がアプリと対話する方法のことです。チャットウィンドウ、ダッシュボードページ、バックグラウンドジョブ、他のエージェントからのAPIコールなどがあります。Agent-Native では、コアロジックを作り直すことなく、これらを自由に組み合わせることができます。すべてのサーフェスが同じ基盤となるアクションを実行するためです。Agent-Native を初めて使う場合は、まず[キーコンセプト](/docs/key-concepts)をお読みください。 -完全なアプリケーションでエージェントを確認・設定する常設の場所が必要な -場合は、`/agent` に `AgentTabsPage` をマウントします。アプリのナビゲーション -にこのルートを追加し、`AgentSidebar` に `agentPageHref="/agent"` を渡すと、 -Resources と Settings から同じフローを重複させずにフルページへ移動できます。 +## サーフェスの相互関係 -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -共有ページには現在、5 つのタブがあります。 - -- **Context** — スコープのプレビュー、トークン予算、provenance・governance・source で整理された順序付きシステムセクション、リスト/treemap 表示、最新の live thread スナップショット。 -- **Files** — 個人または組織のリソース用に既存の `ResourcesPanel` を再ホストします。 -- **Connections** — MCP サーバー管理と A2A リモートエージェント一覧。アプリのエージェントが呼び出せるものを示します。 -- **Automations** — 一時停止/再開、詳細、削除に対応した個人および組織の Scheduled/Event 自動化。互換 URL は `/agent#jobs` のままです。 -- **Access** — MCP URL、利用可能なら A2A エージェントカード、共通のクライアント設定ガイドを表示します。完全な接続フローとトークンのフォールバックは `/mcp/connect` にあります。 +4つの主要なプロダクト形態は、最もインタラクティブなものから完全なヘッドレスまでのスペクトラム上に位置します。それらが組み合わせ可能なのは、基盤が常に同じであるためです。同じアクション、同じSQLデータベース、同じエージェントループがすべての形態を支えています。新しいサーフェスを追加しても、その下にあるものを書き直す必要はありません。同じ操作に到達する新しい方法を追加するだけです。 -ページは現在、個人スコープを使用し、ページ全体の -**Personal / Organization** 切り替えは提供していません。基盤のアクションが -対応する場合、タブは独自の組織セクションを表示できます。**Automations** は -Scheduled と Event の個人および組織セクションを表示します。組織の Event 自動化は -常に作成者として実行されます。このページは既存のコンポーネント、アクション、アクセスチェックを -再利用する薄いシェルであり、新しい管理コンソールではありません。 - -Agent-Native は意図的に構成可能です。 UI をあまり必要とせずにエージェントを使用できます。 -組み込みエージェント ランタイムなしで UI を使用するか、両方を完全なものとして一緒に使用します -アプリケーション。 - -選択する便利な方法は、最初にプロトコルに基づいて選択することではありません。製品の表面を選択してください -必要に応じて、一致するプリミティブを使用します。 - -| 表面 | 次の場合に使用します | から始めましょう | -| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **ヘッドレス エージェント** | コード、ジョブ、スクリプト、別のアプリ、または別のエージェントは、作業を直接呼び出す必要があります。 | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Agent-Native でのリッチなチャット** | 組み込みエージェント ループを利用したスタンドアロン チャットまたは埋め込みチャットが必要です。 | [Chat template](/docs/template-chat), ``, `` | -| **エージェントでのリッチ チャット** | 他の場所でエージェントを構築し、Agent-Native のコンポーザー、トランスクリプト、ツール カード、ネイティブ ウィジェットが必要です。 | `AgentChatRuntime`, `` | -| **埋め込みサイドカー** | あなたはすでに SaaS アプリを持っており、ページ コンテキストとホスト コマンドを備えたエージェントを必要としています。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **完全なアプリケーション** | 人間とエージェントは、耐久性のある画面、データ、ナビゲーション、コラボレーションを共有する必要があります。 | テンプレート、actions、SQL 状態、コンテキスト認識 | - -これらは段階であり、個別の製品ではありません。ワークフローはヘッドレスとして開始できます -エージェントは 1 つのアクションを持ち、表またはグラフとしてチャットに表示され、後にエージェントになります -エージェントが呼び出す操作を変更せずにアプリを全画面表示します。 - - + ```html
- Headlessチャットactions、ジョブ、スクリプト、他のエージェントコンポーザー、トランスクリプト、ツールコール
- リッチチャットコンポーザー、文字起こし、ツールカード + インラインUIテーブル、チャート、カード
- 埋め込み sidecaragent beside an existing app + アプリページ永続的な画面、SQLデータ
- ほとんどの UI完全なアプリケーション永続画面、データ、コラボレーション + ヘッドレス自動化ジョブ、スクリプト、外部エージェント
同じ actions · 同じ SQL · 同じエージェントループ同じアクション · 同じSQL · 同じエージェントループ
``` @@ -117,180 +74,31 @@ Agent-Native は意図的に構成可能です。 UI をあまり必要とせず -## ヘッドレスエージェント {#headless} - -カスタム アプリ画面を見つめる必要がない場合は、ヘッドレス パスを使用します。 -作業の実行: スケジュールされたジョブ、統合、バックエンド ワークフロー、CLI ループ -別のエージェント、または Agent-Native を呼び出す既存の製品。 - -これは、**エージェントが製品である**場合に到達する形状でもあります。 -app-agent ループはダッシュボードではなくフロントドアです。 -ターミナル、Slack、電子メール、スケジュールされたジョブ、別のエージェント、またはチャット - 「私の要約 -未読メール」、「日々の指標を Slack に投稿」、「候補者を見つける -先週返信しました」 - エージェントが動作し、どこにいても結果を返します -に属します。これはステートレス プロンプトではなく実際のアプリです: actions、認証セッション -アプリの状態、スレッド/実行履歴、設定、認証情報、共有レコードはすべてライブです -SQL にあります。 - -次の場合にこのパターンを選択してください。 - -- **作業はバックグラウンドで行われます。** 価値のほとんどは、トリアージ エージェント、日次レポート エージェント、オンコール対応者など、ユーザーが見ていない間に作成されます。 -- **出力はアプリから出ます。** エージェントは Slack に投稿するか、電子メールを送信するか、サードパーティ システムを更新します。アプリ内で閲覧できるものは何もありません。 -- **ドメインはワンショットです。** リサーチ ボット、概要ジェネレーター、レポート ライター — リスト ビューを必要とする永続的なオブジェクトはありません。 -- **プロトタイピング中です。** 今すぐエージェントを出荷してください。ユーザーが必要に応じて、後でよりリッチな UI を追加します。 - -製品が永続オブジェクトを中心に構築されている場合、ユーザーは参照、ピボット、および -共有 — 電子メール、イベント、ドキュメント、グラフ — [full application](#full-application) を選択 -または代わりに [template](/docs/cloneable-saas);これらは完全な UI に加えてエージェントを追加します。 - -### 同梱品 {#in-the-box} - -ヘッドレス アプリは数週間にわたるダッシュボード作業を省略し、一日中チャネルに依存しません -1 つ - 同じエージェントが Web、Slack、テレグラム、電子メール、その他のエージェントから実行されます -すべてが UI ではなくエージェントを経由するためです。トレードオフは次のとおりです -「一目ですべてを参照」ビューはありません。ユーザーがそれを必要とする場合は、パターンを組み合わせて -小さなステータス ページまたはリスト ビューを追加します。 - -組み込みのチャット シェルを追加すると、フレームワークによって 5 つの管理が提供されます -構築する必要のないサーフェス: **チャット** (メイン入力)、**ワークスペース** -(skills、メモリ、命令、サブエージェント、接続された MCP サーバー、スケジュール済み -ジョブ)、**ジョブ履歴**、**スレッド履歴**、**設定**。それらは通常 -十分です — 話しかけて、何が行われるかを確認し、どのように動作するかを設定してください。手を伸ばして -ブラウザ UI を追加する準備ができたら [Chat](/docs/template-chat)、または -ワークスペース スタイルで開始する場合は [Dispatch template](/docs/template-dispatch) -Slack/テレグラム、スケジュールされたジョブ、すぐに使用できる共有シークレットをポイントします。 - -最小のローカル パスは、ヘッドレス エージェント スキャフォールドと 1 つのアクションです。 - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -次に、永続的な操作を定義します。 +## 出発点の選択 -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; +チャットは最も一般的なエントリーポイントです。出力が豊かになるにつれてインラインUIを追加し、ユーザーが参照・共有できる永続的なオブジェクトが必要になったときにフルアプリページを追加するのが典型的な成長パターンです。同じアクションが、後から追加するボタン、スケジュールジョブ、外部エージェントを動かします。すでに所有しているプロダクトにエージェントを追加する場合は埋め込みサイドカーを、ブラウザなしで動作するワークには自動化ファーストを使用してください。全体像は次のとおりです： -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` +| サーフェス | 使用場面 | 開始方法 | +| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | +| **[リッチチャット](#rich-chat)** | ユーザーがエージェントと会話し、ツールコールを確認し、スレッド履歴を保持する場合。 | [Chat template](/docs/template-chat), `` | +| **[ネイティブインラインUI](#native-inline-ui)** | アクション結果をチャット内のテーブル、チャート、カード、または承認として表示する場合。 | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[生成インラインUI](#generated-inline-ui)** | エージェントがチャット内に一時的または再利用可能なコントロールをその場で作成する必要がある場合。 | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[フルアプリケーション](#full-application)** | ユーザーが永続的な画面、共有データ、ナビゲーション、コラボレーションを必要とする場合。 | テンプレート、アクション、SQLステート、コンテキスト認識 | +| **[埋め込みサイドカー](#embedded-sidecar)** | 既存のSaaSアプリがあり、ページコンテキストを持つエージェントをその隣に配置したい場合。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[自動化ファースト](#headless)** | ジョブ、スクリプト、または他のエージェントがブラウザUIなしで直接ワークを呼び出す場合。 | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[自作エージェントへのリッチチャット](#byo-agent)** | 別の場所でエージェントを構築済みで、Agent-Native のチャットUIをその周りに使いたい場合。 | `AgentChatRuntime`, `` | -1 つのアクションは次のように呼び出し可能です。 +## Agent-Native のリッチチャット {#rich-chat} -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **アプリエージェント CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot、およびその他の MCP ホストから -- **A2A** — 別のエージェント ネイティブ アプリまたはエージェント ピアから -- **UI** — `useActionQuery`、`useActionMutation`、または `callAction` 経由 -- **エージェント ツール** — 組み込みチャット ループから +ユーザーがエージェントと会話し、ツールコールを確認し、ワークを承認し、ネイティブ結果を調べ、永続的なスレッド履歴を保持する必要がある場合は、組み込みのチャットを使用してください。 - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -これはデータベースなしモードやステートレス モードではありません。アプリとエージェントのループはセッションを保存します。 -スレッド、実行、設定、資格情報、アプリケーションの状態、および共有レコード -SQL。ローカル開発のデフォルトは SQLite です。ホストされているヘッドレス アプリは、 -永続的な SQL データベース。 - -プロジェクト フォルダーからエージェント全体をヘッドレスでループする必要がある場合は、次を使用します。 - -```bash -pnpm agent "Summarize this week's forms." -``` - -別のアプリまたはスクリプトがエージェント全体を呼び出す必要がある場合は、 -`agentNative.invoke("analytics", "...")` または `agent-native invoke` CLI。それ -ローカル作業は actions に維持されますが、クロスアプリ作業は A2A パスに維持されます。 - -ワーカー、ジョブ、統合 webhooks、およびカスタム ホストがエージェント ループを駆動できる -サーバー API 経由で直接。これは actions よりも低レベルです。 -エンジン、モデル、メッセージ、actions、イベント シンクを自分で作成します: - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -ほとんどのアプリでは、スケジュールされたプロンプトと統合 webhooks がすでにこのループを呼び出しています -あなたのために。カスタム ヘッドレス ホスト eval -ランナー、またはサーバー側のオーケストレーション サーフェス — 「サーバー — 実稼働エージェント -handler](/docs/server#agent-handler)。 - -### フォルダに対して実行中 {#folder-loop} - -目標が「このフォルダに対してエージェントを実行する」ことである場合は、app-agent から始めます -そのフォルダー内をループします: ヘッドレス アプリをスキャフォールディングし、actions/instructions を追加し、実行します -`pnpm agent "..."`。これにより、同じアクション/ランタイム/状態内での作業が維持されます -アプリが運用環境で使用する契約。 - -外部コーディング ハーネスは、Claude を組み込むための別の製品表面です -Agent-Native アプリ内のコード、Codex、Pi、Cursor、Mastra、または同様のランタイム。 -デフォルトの方法としてではなく、コーディング エージェント製品を構築するときに使用してください。 -ローカル エージェント ネイティブ ワークフローを開始します。 - -### クラウド リポジトリへのアクセス {#cloud-repo-access} - -リポジトリ アクセスが必要なクラウド ヘッドレス アプリの場合は、GitHub コネクタを使用します -プラストークン CRUD モデル: リポジトリの一覧表示、ファイルの検索、ファイルの読み取り、作成、または -プロバイダー スコープによるファイルの編集、ファイルの削除、アクセスの取り消し -資格情報。ローカル開発では、ターゲット リポジトリを明示的に設定します。 - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -VM クローンまたは長期存続するサンドボックス チェックアウトをプライマリ クラウドとして扱わないでください -リポジトリ アクセス モデル。サンドボックスは分離されたコードの実行には依然として重要ですが、 -リポジトリへのアクセスは明示的で、権限があり、監査可能で、取り消し可能である必要があります -コネクタ層を経由します。 - -### セッションと実行の共有 {#sharing-runs} - -ヘッドレス セッションと実行は耐久性のあるオブジェクトです。共有性は段階的に行う必要があります: -チームメイトがサニタイズされたプロンプトや出力を検査できるように、最初にリンクを読み取り/共有します。 -および実行ステータス。後で許可された書き込み可能なコラボレーションのため、実行を続行します。 -actions の承認、スケジュールの編集、または構成の変更が完了します -明示的なアクセス チェック。 - -## Agent-Native での充実したチャット {#rich-chat} - -ユーザーがエージェントと話す必要がある場合は、組み込みチャットを使用します。ツールの呼び出しを参照してください。 -作業を承認し、ネイティブ結果を検査し、永続的なスレッド履歴を保存します。 - -完全なアプリの開始点については、[Chat template](/docs/template-chat) を使用します。 +フルアプリの出発点として、[Chat template](/docs/template-chat) を使用してください： ```bash npx @agent-native/core@latest create my-chat-app --template chat ``` -最も単純な全ページチャット: +最もシンプルなフルページチャット： ```tsx import { AgentChatSurface } from "@agent-native/core/client/chat"; @@ -300,11 +108,7 @@ export default function ChatRoute() { } ``` -アプリにフルページ チャット タブと `AgentSidebar` の両方がある場合は、同じものを使用します -両方の表面で `storageKey` を有効にし、`chatViewTransition` を有効にして、 -レイアウト内のチャット ホーム ハンドオフ ヘルパー。チャット外の通常のアプリ内リンク -ページでは、アクティブな状態を維持したまま、チャット全体をサイドバーにモーフィングできます -スレッド: +アプリにフルページのチャットタブと `AgentSidebar` の両方がある場合は、両方のサーフェスで同じ `storageKey` を使用し、`chatViewTransition` を有効にして、レイアウトにチャットホームハンドオフヘルパーをインストールしてください。チャットページからの通常のアプリ内リンクは、アクティブなスレッドを維持しながら、フルチャットをサイドバーに変形させることができます： ```tsx import { @@ -342,7 +146,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -独自の Chrome を使用した最も単純な埋め込みチャット: +独自のクロームを持つ最もシンプルな埋め込みチャット： ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -352,51 +156,104 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -Actions は明示的なネイティブ ウィジェット結果を返すことができるため、チャット出力は単なるものではありません -テキスト。表、グラフ、および型指定された製品カードは、ファーストパーティ React としてレンダリングされます -コンポーネント (iframe なし)。 [Native チャット UI](/docs/native-chat-ui) を参照してください。 +アクションは明示的なネイティブウィジェット結果を返せるため、チャットの出力はテキストだけではありません。テーブル、チャート、型付きプロダクトカードは、iframeなしでチャット内のファーストパーティReactコンポーネントとしてレンダリングされます。[Native Chat UI](/docs/native-chat-ui) を参照してください。エージェントが事前定義されたReactウィジェットの代わりに任意の生成コントロールを必要とする場合は、[Generative UI](/docs/generative-ui) を使用してください。これはサンドボックス化されたAlpine/Tailwind UIをインラインでレンダリングし、アプリの状態とスロットコンテキストを読み取り、選択した値をチャットに送り返すことができます。 -## エージェントとのリッチなチャット {#byo-agent} +## ネイティブインラインUI {#native-inline-ui} -エージェントがすでに別のフレームワークで構築されている場合、または -ランタイムで、Agent-Native のチャット UI が必要です。 `AgentChatRuntime` は -境界: ランタイムは正規化されたイベントをストリームし、Agent-Native は -作曲者、トランスクリプト、ツール呼び出し、承認、ネイティブ ウィジェット、アプリ レイアウト。 +アクションが構造化データ（レコードのリスト、チャートデータセット、ステータスサマリーなど）を返し、プレーンテキストの説明ではなく、チャットスレッド内の実際のUIコンポーネントとしてレンダリングする必要がある場合に使用してください。アクションに `chatUI` レンダラーを定義すると、Agent-Native はそれをファーストパーティのReactコンポーネントとしてレンダリングします。iframeも別のレンダリングパスも不要です。 -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +これは、出力に明確で再利用可能な形状があり、一度デザインして多くのエージェントレスポンスで使用する場合に適しています。エージェントが実行時に動的に作成する必要があるコントロールについては、代わりに[生成インラインUI](#generated-inline-ui)を参照してください。 -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +完全なレンダラーAPI、ウィジェットライブラリ、およびBYOエージェントランタイム統合については、[Native Chat UI](/docs/native-chat-ui) を参照してください。 -export function SupportAgentChat() { - return ; +## 生成インラインUI {#generated-inline-ui} + +エージェントが事前構築されたウィジェットとしてまだ存在しないコントロール（カスタムフォーム、現在のコンテキストに基づいたピッカー、ワンオフの計算機など）を作成する必要がある場合に使用してください。ネイティブウィジェットとは異なり、生成UIはエージェントが実行時にAlpine.jsとTailwindから構成し、iframeでサンドボックス化されて実行され、選択した値をチャットスレッドに送り返すことができます。 + +生成UIは一時的（一度レンダリングして破棄）にも、ユーザーのために永続する再利用可能な拡張機能として保存することもできます。 + +完全なAPI、サンドボックスの制約、および拡張機能の永続化モデルについては、[Generative UI](/docs/generative-ui) を参照してください。 + +## フルアプリケーション {#full-application} + +ユーザーがフォーム、ダッシュボード、カレンダー、受信トレイ、エディター、ドキュメント、アセット、レポートなど、永続的なオブジェクトとワークフローを必要とする場合は、フルアプリのパスを使用してください。 + +フルアプリは、同じアクションとエージェントコントラクトの周りにプロダクトUIを追加します： + + + +### SQLステート + +アプリデータ、ナビゲーション、設定、チャット履歴はすべて永続化されます。エージェントはUIと同じ行を読み書きします。 + +### コンテキスト認識 + +エージェントは現在のルート、選択、フォーカスされたオブジェクトを把握しているため、「これを編集して」は常に正しいものを意味します。 + +### ライブ同期 + +エージェントの変更はリアルタイムでUIを更新し、UIの変更はエージェントのコンテキストを更新します。ポーリングも更新も不要です。 + +### ディープリンク + +アクション結果は正しいアプリビューを直接開けます。チャートはダッシュボードにリンクし、下書きは受信トレイにリンクします。 + +### ネイティブチャットウィジェット + +テーブル、チャート、カード、承認、型付き結果は、チャット内のファーストパーティのReactコンポーネントとしてインラインでレンダリングされます。 + +### 生成UIと拡張機能 + +エージェントはその場でインラインコントロールを作成でき、ワークフローを永続化する必要がある場合は再利用可能なミニアプリを保存できます。 + + + +アクションの周りに最小限のアプリが必要な場合は[Chat template](/docs/template-chat)から、完全なプロダクト形態が必要な場合はドメイン[テンプレート](/docs/cloneable-saas)から始めてください。 + +### フルページ管理エージェント {#agent-page} + +すべてのAgent-Nativeアプリは最終的に、ユーザーがエージェントを設定できる場所が必要になります。常時指示の設定、実行内容の確認、MCPサーバーの接続、自動化の管理、アクセスの制御などです。そのUIをゼロから構築するのは大変な作業です。Agent-Nativeには、12タブにわたってすべてをカバーする事前構築済みのフルページコンポーネント `AgentTabsPage` が搭載されています。 + +アプリの `/agent` にマウントしてください。現在のテンプレートはそのルートをアプリナビゲーションエントリーと組み合わせ、`AgentSidebar` に `agentPageHref="/agent"` を渡すため、サイドバーのリソースと設定モードはそれらのフローを複製することなくフルページにリンクできます。 + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -OpenAI エージェント、OpenAI レスポンス、Claude 用の既製のランタイム ヘルパーが存在します -エージェント SDK、Vercel AI SDK、AG-UI、および上記の正規化された HTTP ランタイム -他のエージェント (Mastra、Flue、Eve、LangGraph、またはカスタム サービス) 用。 ACP は -エンドユーザー アプリのチャットや A2A トランスポートではなく、Agent-Native は現在サポートされていません -A2UI サポートを主張します。 ACP は 1 つの特定の場所でサポートされています - ローカルの運転 -コーディング エージェント (Gemini CLI、Claude コードなど) -[harness layer](/docs/harness-agents#acp)、ここではチャット ランタイムとしては使用しません。 +共有ページは現在、2つのグループにわたって12タブを提供しています： + +| グループ | タブ | 表示内容 | +| --------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | 個人またはorganizationファイル用の既存の `ResourcesPanel` | +| Resources | **Instructions** | 常時有効なAGENTS.mdスタイルのルール | +| Resources | **Agents** | カスタムサブエージェントプロファイル | +| Resources | **Memory** | 長期記憶ノート | +| Resources | **Skills** | 再利用可能なワークフロー | +| Resources | **Learnings** | 時間をかけて記録された修正とパターン | +| Resources | **Remote agents** | 他のagent-nativeアプリへのA2A接続（Connectionsタブに表示されていたものを置き換え） | +| Agent | **Snapshots** | スコーププレビュー、トークンバジェット、出所/ガバナンス/ソース別にグループ化された順序付きシステムセクション、および最新のライブスレッドスナップショット。「Context」から改名。古い `#context` リンクはここにリダイレクト。 | +| Agent | **Connections** | MCPサーバー管理のみ | +| Agent | **Automations** | 一時停止/再開、詳細、削除フローを備えた個人およびorganizationのスケジュール/イベント自動化。安定した互換性URLは `/agent#jobs` のまま。 | +| Agent | **Settings** | エージェントモデル、APIキー、制限、音声、自動化設定 | +| Agent | **Access** | アプリのMCP URL、利用可能な場合のA2Aエージェントカード、Claude、ChatGPT、Cursor、Claude Code、Codex、その他のクライアントの共有セットアップガイド。完全な接続フローとトークンフォールバックの `/mcp/connect` へのリンク。 | + +このページは個人（`user`スコープ）データのみを表示します。現時点ではorgレベルのトグルはありません。既存のコンポーネントとアクセスチェックの薄いシェルであり、新しい管理コンソールではありません。Connectionsはアプリが呼び出せるものを示し、Accessは外部クライアントがどのように接続するかを示します。 + +まだ含まれていないもの： -[Native チャット UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -は、イベント シェイプ、ランタイム ヘルパー、および `chatUI` の正規のホームです -ツール結果のメタデータ。外部エージェントをチャットに接続するときは、そこから始めてください。 +- organizationスコープビュー +- グラントとスコープ編集 +- 失効UI +- イテレーション別の出所履歴 ## 埋め込みサイドカー {#embedded-sidecar} -メイン製品がすでに存在しており、必要な場合は埋め込みサイドカーを使用します -その隣にエージェントがいます。 +メインプロダクトが既に存在し、その隣にエージェントを配置したい場合は、埋め込みサイドカーを使用してください。 -サーバー プラグインは、Agent-Native ルートをホスト アプリにマウントし、解決します -ホスト ID サーバー側: +サーバープラグインはAgent-Nativeのルートをホストアプリにマウントし、サーバー側でホストのアイデンティティを解決します： ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -408,7 +265,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -React サイドカーは、ページ コンテキストとホスト コマンドを渡します。 +Reactサイドカーはページコンテキストとホストコマンドを渡します： ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -430,13 +287,16 @@ export function AppShell({ children }) { } ``` - +### 接続の仕組み + +2つのピースはブリッジとして機能します。ホストアプリはページコンテキスト（現在のルート、選択されたテキスト、フォーカスされたオブジェクト）を `AgentNativeEmbedded` に渡し、エージェントは `onNavigate` と `onRefresh` を通してコマンドを送り返します。サーバープラグインはアイデンティティを処理します。ホストセッションを解決して、エージェントが別のログインなしに正しいユーザーとして動作できるようにします。ホストアプリ内で変更する必要は何もありません。プラグインはAgent-Nativeのルートを既存のルートの横に追加します。 + + ```html
- ホストアプリ既存の SaaS + ホストアプリ既存のSaaS
getContext()
ルート · 選択
@@ -452,10 +312,10 @@ export function AppShell({ children }) {
AgentNativeEmbeddedagent + workspace + >エージェント + リソース
- Agent-Native ルート
mounted by the server pluginサーバープラグインによってマウント
@@ -489,45 +349,180 @@ export function AppShell({ children }) { -ホスト認証、データベース分離については、[Embedding SDK](/docs/embedding-sdk) を参照してください。 -iframe/ピッカー モード、および下位レベルのブリッジ API。 +ホスト認証、データベース分離、iframe/ピッカーモード、下位レベルのブリッジAPIについては、[Embedding SDK](/docs/embedding-sdk) を参照してください。 + +## 自動化ファーストアプリ {#headless} + +ワークの実行中に誰もカスタムブラウザ画面を必要としない場合（スケジュールジョブ、インテグレーション、バックエンドワークフロー、CLIループ、別のエージェント、またはAgent-Nativeを呼び出す既存プロダクト）は、自動化ファーストのパスを使用してください。 + +これは自動化がプロダクトサーフェスである場合に選ぶ形態です。ターミナル、Slack、メール、スケジュールジョブ、別のエージェント、またはChat（「未読メールを要約して」「日次メトリクスをSlackに投稿して」「先週返信した候補者を見つけて」）からリクエストを送ると、エージェントが作業して結果を適切な場所に返します。これはステートレスなプロンプトではなく、実際のアプリです。アクション、認証セッション、アプリ状態、スレッド/実行履歴、設定、クレデンシャル、共有レコードがすべてSQLに格納されます。 + +このパターンを選ぶ場合： + +- **ワークがバックグラウンドで発生する場合。** ユーザーが見ていない間に価値の大部分が生まれます。トリアージエージェント、日次レポートエージェント、オンコールレスポンダー。 +- **出力がアプリの外に出る場合。** エージェントがSlackに投稿したり、メールを送ったり、サードパーティシステムを更新したりする。アプリ内で参照するものはない。 +- **ドメインが一回限りの場合。** リサーチボット、サマリージェネレーター、リストビューを必要とする永続的なオブジェクトのないレポートライター。 +- **自動化をプロトタイピングしている場合。** 今すぐ操作をリリースし、ユーザーが検査・操作する必要があるときにチャットやアプリページを追加する。 + +ユーザーが閲覧、ピボット、共有する永続的なオブジェクト（メール、イベント、ドキュメント、チャート）を中心にプロダクトが構築されている場合は、代わりに[フルアプリケーション](#full-application)または[テンプレート](/docs/cloneable-saas)を選んでください。それらはエージェントに加えて完全なUIを提供します。 + +### 最初から含まれているもの {#in-the-box} + +自動化ファーストアプリはダッシュボード作業をスキップし、最初からチャンネル非依存です。同じエージェントがウェブ、Slack、Telegram、メール、他のエージェントから実行されます。すべてが同じアクションを通るためです。トレードオフとして「一目ですべてを参照」するビューがありません。ユーザーにそれが必要な場合は、[Chat](/docs/template-chat)から始めるか、小さなステータスページやリストビューを追加してください。 + +組み込みのChatシェルを追加すると、フレームワークは自分で構築する必要のない5つの管理サーフェスを提供します。**Chat**（メイン入力）、**Resources**（スキル、メモリ、指示、サブエージェント、接続されたMCPサーバー）、**Automations**、**Thread history**、**Settings**。これらは通常十分です。それと会話し、何をしたかを確認し、どのように動作するかを設定する。ブラウザUIを追加する準備ができたら[Chat](/docs/template-chat)を、SlackやTelegram、スケジュールジョブ、共有シークレットを備えたワークスペーススタイルの出発点には[Dispatch template](/docs/template-dispatch)を使用してください。 + +最小のブラウザなしローカルパスは、スキャフォールドと1つのアクションです： + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +次に永続的な操作を定義します： + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +1つのアクションは次の方法で呼び出せます： + +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **App-agent CLI:** `pnpm agent "Summarize form_123"` +- **MCP:** Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot、その他のMCPホストから +- **A2A:** 別のagent-nativeアプリまたはエージェントピアから +- **UI:** `useActionQuery`、`useActionMutation`、または `callAction` 経由 +- **エージェントツール:** 組み込みのチャットループから + + + +すべての `defineAction` は `/_agent-native/actions/` に自動マウントされます。JSONボディは `run` が実行される前にアクションのzodスキーマに対して検証されます。長期間有効なベアラートークンを使用して外部システムから呼び出すには、[HTTP API](/docs/http-api) を参照してください。 + + -## 完全なアプリケーション {#full-application} +これはデータベースなし、またはステートレスモードではありません。app-agentループはセッション、スレッド、実行、設定、クレデンシャル、アプリケーション状態、共有レコードをSQLに格納します。ローカル開発はデフォルトでSQLiteを使用します。ホストされた自動化ファーストアプリは永続的なSQLデータベースを使用する必要があります。 -ユーザーが耐久性のあるオブジェクトやワークフローを必要とする場合は、完全なアプリ パスを使用します: フォーム -ダッシュボード、カレンダー、受信トレイ、エディタ、ドキュメント、アセット、またはレポート。 +プロジェクトフォルダからエージェントループ全体をヘッドレスで必要とする場合は、以下を使用してください： -完全なアプリは、同じアクションとエージェント契約に基づいて製品 UI を追加します: +```bash +pnpm agent "Summarize this week's forms." +``` -- **SQL 状態** — アプリのデータ、ナビゲーション、設定、チャット履歴は永続的です。 -- **コンテキスト認識** — エージェントは現在のルート、選択内容、およびフォーカスされているオブジェクトを認識します。 -- **ライブ同期** — エージェントの変更により UI が更新され、UI の変更によりエージェントのコンテキストが更新されます。 -- **ディープリンク** — アクションの結果により適切なアプリビューを開くことができます。 -- **ネイティブ チャット ウィジェット** — 表、グラフ、カード、承認、入力された結果がインラインで表示されます。 +別のアプリやスクリプトがエージェント全体を呼び出す必要がある場合は、`agentNative.invoke("analytics", "...")` または `agent-native invoke` CLIを使用してください。これにより、クロスアプリワークはA2Aパスを維持し、ローカルワークはアクションにとどまります。 + +ワーカー、ジョブ、インテグレーションウェブフック、カスタムホストはサーバーAPIを通じてエージェントループを直接駆動できます。これはアクションよりも低レベルです。エンジン、モデル、メッセージ、ツール、アクション、イベントシンク、アボートシグナルを自分で提供します： + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` -最小限のアプリが必要な場合は、[Chat template](/docs/template-chat) から始めてください -actions の周囲、またはドメイン [template](/docs/cloneable-saas) から -完全な製品形状が必要です。 +ほとんどのアプリでは、スケジュールされたプロンプトとインテグレーションウェブフックが既にこのループを呼び出しています。カスタムのブラウザなしホスト、評価ランナー、またはサーバーサイドのオーケストレーションサーフェスを構築する場合にのみ直接使用してください。完全なシグネチャについては、[Server: Production agent handler](/docs/server#agent-handler) を参照してください。 -## 選び方 {#how-to-choose} +### フォルダに対して実行する {#folder-loop} -| 考えているなら... | 選択 | -| ------------------------------------------------------------------------------------------ | --------------------------------- | -| 「呼び出し可能なツールまたはワークフローが必要なだけです。」 | ヘッドレスエージェント | -| 「フレームワークのエージェントが必要ですが、チャットをメインの UI にする必要があります。」 | Agent-Native での充実したチャット | -| 「すでにエージェントがいます。そのエージェントには洗練されたチャット UI が必要です。」 | エージェントとのリッチなチャット | -| 「すでに SaaS アプリを持っています。その横にエージェントを追加してください。」 | 埋め込みサイドカー | -| 「エージェントと UI は製品として一緒に進化する必要があります。」 | 完全なアプリケーション | +「このフォルダに対してエージェントを実行する」が目標の場合は、そのフォルダ内のapp-agentループから始めてください。自動化ファーストアプリをスキャフォールドし、アクション/指示を追加し、`pnpm agent "..."` を実行します。これにより、ワークはアプリが本番環境で使用するのと同じアクション/ランタイム/ステートコントラクト内に保たれます。 -コントラクトを小さく保ちます: 永続的な操作を actions として定義し、明示的に返します -チャットにリッチな UI が必要な場合はウィジェットの結果が表示され、ユーザーがいる場合にのみ全画面が追加されます -永続オブジェクトを参照、比較、構成、または共同作業する必要があります。 +外部コーディングハーネスは、Claude Code、Codex、Pi、Cursor、Mastra、または同様のランタイムをAgent-Nativeアプリ内に埋め込むための別のプロダクトサーフェスです。コーディングエージェントプロダクトを構築する場合に使用してください。ローカルのagent-nativeワークフローを開始するデフォルトの方法としてではありません。 + +### クラウドリポジトリアクセス {#cloud-repo-access} + +リポジトリアクセスが必要なクラウド自動化ファーストアプリでは、GitHubコネクターとトークンCRUDモデルを使用してください。プロバイダースコープのクレデンシャルを通じて、リポジトリの一覧表示、ファイルの検索、ファイルの読み取り、ファイルの作成または編集、ファイルの削除、アクセスの失効ができます。ローカル開発では、ターゲットリポジトリを明示的に設定してください： + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +VMクローンや長期間のサンドボックスチェックアウトをプライマリのクラウドリポジトリアクセスモデルとして扱わないでください。サンドボックスは分離されたコード実行には引き続き重要ですが、リポジトリアクセスはコネクターレイヤーを通じて明示的、許可済み、監査可能、かつ失効可能であるべきです。 + +### セッションと実行の共有 {#sharing-runs} + +自動化ファーストのセッションと実行は永続的なオブジェクトです。共有機能は段階的に実装すべきです。まず読み取り/共有リンクで、チームメートがサニタイズされたプロンプト、出力、実行ステータスを検査できるようにし、次に許可された書き込み可能なコラボレーションで、実行の継続、アクションの承認、スケジュールの編集、設定の変更が明示的なアクセスチェックを通じて行われるようにします。 + +## 自作エージェントへのリッチチャット {#byo-agent} + +エージェントが別のフレームワークまたはランタイムで既に構築されており、その周りにAgent-NativeのチャットUIを使いたい場合は、このパスを使用してください。`AgentChatRuntime` が境界です。あなたのランタイムが正規化されたイベントをストリームし、Agent-Nativeがコンポーザー、トランスクリプト、ツールコール、承認、ネイティブウィジェット、アプリレイアウトをレンダリングします。 + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` + +OpenAI Agents、OpenAI Responses、Claude Agent SDK、Vercel AI SDK、AG-UI向けの既製ランタイムヘルパーと、他のエージェント（Mastra、Flue、Eve、LangGraph、またはカスタムサービス）向けの上記の正規化されたHTTPランタイムが存在します。ACPはエンドユーザーアプリのチャットやA2Aトランスポートではなく、Agent-Nativeは現在A2UIサポートを主張していません。ACPは1つの特定の場所でサポートされています。[ハーネスレイヤー](/docs/harness-agents#acp)を通じたローカルコーディングエージェント（Gemini CLI、Claude Codeなど）の駆動であり、ここでのチャットランタイムとしてではありません。 + +[Native Chat UI: BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) は、イベント形状、ランタイムヘルパー、および `chatUI` ツール結果メタデータの正規のリファレンスです。外部エージェントをチャットに接続する際はそこから始めてください。 ## 次のステップ {#related-docs} -- [**Actions**](/docs/actions) — 操作を一度定義します。上記のすべてのサーフェスが同じ操作を呼び出します -- [**Native チャット UI**](/docs/native-chat-ui) — 型付き action 結果を表、グラフ、カードとしてチャットに表示します -- [**Generative UI**](/docs/generative-ui) — 一時的または永続化されたサンドボックス UI をチャット内に生成します -- [**Automation-First Apps**](/docs/pure-agent-apps) — ジョブ、キュー、スクリプト、外部エージェント向けの完全なブラウザー不要パターン -- [**External Agents**](/docs/external-agents) — MCP 互換ホストをアプリに接続します -- [**A2A Protocol**](/docs/a2a-protocol) — 他の Agent-Native アプリからエージェントを呼び出します + + +### [アクション](/docs/actions) + +操作を一度定義する。上記のすべてのサーフェスが同じものを呼び出す。 + +### [Native Chat UI](/docs/native-chat-ui) + +型付きアクション結果をテーブル、チャート、カードとしてチャット内に直接レンダリングする。 + +### [Generative UI](/docs/generative-ui) + +チャット内に一時的または永続化されたサンドボックスUIをインラインで生成する。 + +### [自動化ファーストアプリ](/docs/pure-agent-apps) + +ジョブ、キュー、スクリプト、外部エージェントのための完全なブラウザなしパターン。 + +### [外部エージェント](/docs/external-agents) + +MCP対応ホストをツールサーバーとしてアプリに接続する。 + +### [A2Aプロトコル](/docs/a2a-protocol) + +A2A標準を通じて他のagent-nativeアプリからエージェントを呼び出す。 + + diff --git a/packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx b/packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx index ed05925632..6342a32062 100644 --- a/packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx @@ -1,88 +1,44 @@ --- -title: "에이전트 표면" -description: "Agent-Native를 헤드리스, 리치 채팅, 기존 앱 내 또는 전체 에이전트 기본 애플리케이션으로 사용하세요." -search: "헤드리스 에이전트 리치 채팅 전체 앱 BYO 에이전트 런타임 AgentChatRuntime 내장 actions MCP A2A HTTP CLI" +title: "에이전트 서피스" +description: "채팅에서 인라인 UI, 영구 앱 페이지, 임베디드 사이드카, 자동화, 외부 에이전트 접근까지 에이전틱 앱이 성장하는 방식을 선택하세요." +search: "에이전틱 앱 리치 채팅 네이티브 채팅 UI 풀 앱 자동화 헤드리스 BYO 에이전트 런타임 AgentChatRuntime 임베드 액션 MCP A2A HTTP CLI" --- -# 에이전트 표면 +# 에이전트 서피스 -## 전체 Agent 작업 공간 {#agent-page} +A **서피스**는 사용자(또는 다른 시스템)가 앱과 상호작용하는 방식입니다: 채팅 창, 대시보드 페이지, 백그라운드 작업, 다른 에이전트로부터의 API 호출 등이 있습니다. Agent-Native를 사용하면 핵심 로직을 다시 구축하지 않고도 이러한 서피스를 자유롭게 조합할 수 있습니다. 모든 서피스가 동일한 기본 액션을 실행하기 때문입니다. Agent-Native를 처음 접하신다면 먼저 [핵심 개념](/docs/key-concepts)을 읽어보세요. -전체 애플리케이션에서 에이전트를 검사하고 구성할 영구 공간이 필요하면 -`/agent`에 `AgentTabsPage`를 마운트하세요. 앱 탐색에 이 경로를 추가하고 -`AgentSidebar`에 `agentPageHref="/agent"`를 전달하면 Resources 및 Settings -모드에서 흐름을 중복하지 않고 전체 페이지로 이동할 수 있습니다. +## 서피스 간의 관계 -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -공유 페이지에는 현재 다섯 개의 탭이 있습니다. - -- **Context** — 범위 미리보기, 토큰 예산, provenance·governance·source별 정렬된 시스템 섹션, 목록/treemap 보기, 최신 live-thread 스냅샷을 보여줍니다. -- **Files** — 개인 또는 조직 리소스에 기존 `ResourcesPanel`을 다시 호스팅합니다. -- **Connections** — MCP 서버 관리와 A2A 원격 에이전트 목록을 제공하며, 앱 에이전트가 호출할 수 있는 기능을 보여줍니다. -- **Automations** — 일시 중지/재개, 상세, 삭제를 지원하는 개인 및 조직 Scheduled/Event 자동화입니다. 호환성 URL은 `/agent#jobs`로 유지됩니다. -- **Access** — MCP URL, 가능한 경우 A2A 에이전트 카드, 공통 클라이언트 설정 가이드를 보여줍니다. 전체 연결 흐름과 토큰 대체 경로는 `/mcp/connect`에 있습니다. - -페이지는 현재 개인 범위를 사용하며 페이지 전체 -**Personal / Organization** 전환을 제공하지 않습니다. 기반 액션이 지원하면 -탭이 자체 조직 섹션을 표시할 수 있습니다. **Automations**는 Scheduled와 Event -모두의 개인 및 조직 섹션을 표시합니다. 조직 Event 자동화는 항상 생성자로 -실행됩니다. 이 페이지는 -기존 컴포넌트, 액션, 접근 검사를 재호스트하는 얇은 셸이며 새로운 관리자 -콘솔이 아닙니다. - -Agent-Native는 의도적으로 구성 가능합니다. UI를 많이 사용하지 않고도 에이전트를 사용할 수 있습니다, -내장된 에이전트 런타임 없이 UI를 사용하거나 둘 다 전체로 함께 사용 -신청. +네 가지 주요 제품 형태는 가장 인터랙티브한 것부터 완전히 헤드리스인 것까지 스펙트럼 위에 위치합니다. 이들이 조합 가능한 이유는 기반이 동일하게 유지되기 때문입니다: 동일한 액션, 동일한 SQL 데이터베이스, 동일한 에이전트 루프가 모든 형태를 지원합니다. 새로운 서피스를 추가한다고 해서 기반을 다시 작성할 필요가 없습니다 — 동일한 작업에 접근하는 새로운 방법을 추가하는 것뿐입니다. -유용한 선택 방법은 프로토콜을 먼저 따르는 것이 아닙니다. 제품 표면을 선택하세요 -원하는 경우 일치하는 프리미티브를 사용하세요. - -| 표면 | 다음 경우에 사용 | 시작 | -| ------------------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **헤드리스 에이전트** | 코드, 작업, 스크립트, 다른 앱 또는 다른 에이전트가 작업을 직접 호출해야 합니다. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Agent-Native의 풍부한 채팅** | 내장된 에이전트 루프가 지원하는 독립형 또는 내장형 채팅을 원합니다. | [Chat template](/docs/template-chat), ``, `` | -| **리치 채팅 on your agent** | You built the agent elsewhere and want Agent-Native's 작성기, 기록, 도구 카드, and native widgets. | `AgentChatRuntime`, `` | -| **임베디드 sidecar** | You already have a SaaS app and want an agent beside it with page context and 호스트 명령. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **전체 애플리케이션** | Humans and agents should share durable screens, data, navigation, and collaboration. | Templates, actions, SQL state, context awareness | - -Those are stages, not separate products. A workflow can start as a headless -agent with one action, appear in chat as a table or chart, and later become a -full screen in an app without changing the operation the agent calls. - - + ```html
- Headlessactions, 작업, 스크립트, 다른 에이전트 + 채팅작성기, 트랜스크립트, 도구 호출
- 리치 채팅작성기, 기록, 도구 카드 + 인라인 UI테이블, 차트, 카드
- 임베디드 sidecaragent beside an existing app + 앱 페이지영구 화면, SQL 데이터
- 대부분의 UI전체 애플리케이션지속 화면, 데이터, 협업 + 헤드리스자동화작업, 스크립트, 외부 에이전트
같은 actions · 같은 SQL · 같은 에이전트 루프동일한 액션 · 동일한 SQL · 동일한 에이전트 루프
``` @@ -116,50 +72,305 @@ full screen in an app without changing the operation the agent calls. -## 헤드리스 에이전트 {#headless} +## 시작점 선택 + +채팅이 가장 일반적인 진입점입니다. 앱은 출력이 풍부해질수록 인라인 UI를 추가하고, 사용자가 탐색하고 공유할 영구 객체가 필요해지면 전체 앱 페이지를 추가합니다. 동일한 액션이 나중에 추가되는 버튼, 예약된 작업, 외부 에이전트를 지원합니다. 이미 소유한 제품에 에이전트를 추가할 때는 임베디드 사이드카를 사용하거나, 브라우저 없이 실행되는 작업에는 자동화 우선 방식을 사용하세요. 전체 그림은 다음과 같습니다: + +| 서피스 | 사용 시기 | 시작 방법 | +| --------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **[리치 채팅](#rich-chat)** | 사용자가 에이전트와 대화하고, 도구 호출을 확인하며, 스레드 히스토리를 유지할 때. | [Chat 템플릿](/docs/template-chat), `` | +| **[네이티브 인라인 UI](#native-inline-ui)** | 액션 결과가 채팅에서 테이블, 차트, 카드, 또는 승인으로 렌더링되어야 할 때. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[생성형 인라인 UI](#generated-inline-ui)** | 에이전트가 채팅 내에서 즉시 임시 또는 재사용 가능한 컨트롤을 생성해야 할 때. | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[풀 애플리케이션](#full-application)** | 사용자에게 영구 화면, 공유 데이터, 내비게이션, 협업이 필요할 때. | 템플릿, 액션, SQL 상태, 컨텍스트 인식 | +| **[임베디드 사이드카](#embedded-sidecar)** | 이미 SaaS 앱이 있고 페이지 컨텍스트와 함께 에이전트를 옆에 두고 싶을 때. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[자동화 우선](#headless)** | 작업, 스크립트, 또는 다른 에이전트가 브라우저 UI 없이 직접 작업을 호출할 때. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[자체 에이전트에서 리치 채팅](#byo-agent)** | 에이전트를 다른 곳에서 구축했고 Agent-Native의 채팅 UI를 감싸고 싶을 때. | `AgentChatRuntime`, `` | + +## Agent-Native에서 리치 채팅 {#rich-chat} + +사용자가 에이전트와 대화하고, 도구 호출을 확인하며, 작업을 승인하고, 네이티브 결과를 검사하며, 영구 스레드 히스토리를 유지해야 할 때 내장 채팅을 사용하세요. + +전체 앱 시작점으로는 [Chat 템플릿](/docs/template-chat)을 사용하세요: + +```bash +npx @agent-native/core@latest create my-chat-app --template chat +``` + +가장 간단한 전체 페이지 채팅: + +```tsx +import { AgentChatSurface } from "@agent-native/core/client/chat"; + +export default function ChatRoute() { + return ; +} +``` + +앱에 전체 페이지 채팅 탭과 `AgentSidebar`가 모두 있을 때, 두 서피스에서 동일한 `storageKey`를 사용하고, `chatViewTransition`을 활성화하며, 레이아웃에 chat-home 핸드오프 헬퍼를 설치하세요. 채팅 페이지에서 나가는 일반 인앱 링크는 활성 스레드를 유지하면서 전체 채팅을 사이드바로 변환할 수 있습니다: + +```tsx +import { + AgentChatSurface, + AgentSidebar, + useAgentChatHomeHandoff, + useAgentChatHomeHandoffLinks, +} from "@agent-native/core/client/chat"; +import { useLocation } from "react-router"; + +function ChatRoute() { + return ( + + ); +} + +function AppLayout({ children }: { children: React.ReactNode }) { + const location = useLocation(); + const handoffActive = useAgentChatHomeHandoff({ + storageKey: "my-app", + activePath: location.pathname, + enabled: location.pathname !== "/chat", + }); + useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" }); + + return ( + + {children} + + ); +} +``` + +자체 크롬이 있는 가장 간단한 임베디드 채팅: + +```tsx +import { AssistantChat } from "@agent-native/core/client/chat"; + +export function ProjectChat({ threadId }: { threadId: string }) { + return ; +} +``` + +액션은 채팅 출력이 단순 텍스트가 아닌 명시적 네이티브 위젯 결과를 반환할 수 있습니다. 테이블, 차트, 타입이 지정된 제품 카드가 iframes 없이 채팅에서 1st-party React 컴포넌트로 렌더링됩니다. [Native Chat UI](/docs/native-chat-ui)를 참조하세요. 에이전트가 미리 정의된 React 위젯 대신 임의로 생성된 컨트롤이 필요할 때는 [Generative UI](/docs/generative-ui)를 사용하세요: Alpine/Tailwind UI를 인라인으로 샌드박스 렌더링하고, 앱 상태와 슬롯 컨텍스트를 읽을 수 있으며, 선택된 값을 채팅으로 다시 보낼 수 있습니다. + +## 네이티브 인라인 UI {#native-inline-ui} + +액션이 구조화된 데이터(레코드 목록, 차트 데이터셋, 상태 요약)를 반환하고, 이를 채팅 스레드에서 일반 텍스트 설명이 아닌 실제 UI 컴포넌트로 렌더링해야 할 때 사용하세요. 액션에 `chatUI` 렌더러를 정의하면 Agent-Native가 이를 1st-party React 컴포넌트로 렌더링합니다: iframes 없이, 별도의 렌더링 경로 없이. + +이는 출력이 명확하고 재사용 가능한 형태를 가지고, 한 번 설계하여 여러 에이전트 응답에서 사용할 때 적합한 선택입니다. 에이전트가 런타임에 동적으로 생성해야 하는 컨트롤에 대해서는 [생성형 인라인 UI](#generated-inline-ui)를 참조하세요. + +전체 렌더러 API, 위젯 라이브러리, BYO 에이전트 런타임 통합은 [Native Chat UI](/docs/native-chat-ui)를 참조하세요. + +## 생성형 인라인 UI {#generated-inline-ui} + +에이전트가 미리 구축된 위젯으로 존재하지 않는 컨트롤을 생성해야 할 때 사용하세요 — 커스텀 폼, 현재 컨텍스트를 기반으로 구축된 피커, 일회성 계산기 등. 네이티브 위젯과 달리 생성형 UI는 에이전트가 런타임에 Alpine.js와 Tailwind로 구성하고, iframe 안에서 샌드박스로 실행되며, 선택된 값을 채팅 스레드로 다시 보낼 수 있습니다. + +생성형 UI는 일시적(한 번 렌더링되고 폐기)이거나 사용자에게 지속되는 재사용 가능한 확장으로 저장될 수 있습니다. + +전체 API, 샌드박스 제약 사항, 확장 지속 모델은 [Generative UI](/docs/generative-ui)를 참조하세요. + +## 풀 애플리케이션 {#full-application} + +사용자에게 영구 객체와 워크플로우가 필요할 때 전체 앱 경로를 사용하세요: 폼, 대시보드, 캘린더, 받은 편지함, 에디터, 문서, 에셋, 또는 보고서. + +풀 앱은 동일한 액션 및 에이전트 계약을 중심으로 제품 UI를 추가합니다: + + + +### SQL 상태 + +앱 데이터, 내비게이션, 설정, 채팅 히스토리가 모두 영구적입니다. 에이전트는 UI가 사용하는 것과 동일한 행을 읽고 씁니다. + +### 컨텍스트 인식 + +에이전트는 현재 경로, 선택 항목, 포커스된 객체를 알기 때문에 "이것을 편집해"는 항상 올바른 것을 의미합니다. + +### 실시간 동기화 + +에이전트 변경 사항이 UI를 실시간으로 업데이트하고, UI 변경 사항이 에이전트의 컨텍스트를 업데이트합니다. 폴링 없이, 새로고침 없이. + +### 딥 링크 + +액션 결과가 올바른 앱 뷰를 직접 열 수 있습니다: 차트는 대시보드로 연결되고, 초안은 받은 편지함으로 연결됩니다. + +### 네이티브 채팅 위젯 + +테이블, 차트, 카드, 승인, 타입이 지정된 결과가 채팅 인라인에서 1st-party React 컴포넌트로 렌더링됩니다. + +### 생성형 UI 및 확장 + +에이전트는 즉시 인라인 컨트롤을 생성할 수 있고, 워크플로우가 지속되어야 할 때 재사용 가능한 미니앱을 저장할 수 있습니다. + + + +액션 주위에 최소한의 앱을 원한다면 [Chat 템플릿](/docs/template-chat)에서, 완전한 제품 형태를 원한다면 도메인 [템플릿](/docs/cloneable-saas)에서 시작하세요. + +### 전체 페이지 에이전트 관리 {#agent-page} + +모든 Agent-Native 앱은 결국 사용자가 에이전트를 구성할 수 있는 공간이 필요합니다: 상시 지침 설정, 완료된 작업 검토, MCP 서버 연결, 자동화 관리, 접근 제어. 처음부터 해당 UI를 구축하는 것은 많은 작업이 필요합니다. Agent-Native는 열두 개의 탭에 걸쳐 이 모든 것을 처리하는 미리 구축된 전체 페이지 컴포넌트 `AgentTabsPage`를 제공합니다. + +앱의 `/agent`에 마운트하세요. 현재 템플릿은 해당 경로를 앱 내비게이션 항목과 연결하고 `AgentSidebar`에 `agentPageHref="/agent"`를 전달하여, 사이드바의 Resources 및 Settings 모드가 해당 흐름을 중복하지 않고 전체 페이지로 연결할 수 있습니다. + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; +} +``` + +공유 페이지는 현재 두 그룹에 걸쳐 열두 개의 탭을 제공합니다: + +| 그룹 | 탭 | 표시 내용 | +| --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | 개인 또는 조직 파일을 위한 기존 `ResourcesPanel` | +| Resources | **Instructions** | 항상 켜져 있는 AGENTS.md 스타일 규칙 | +| Resources | **Agents** | 커스텀 서브 에이전트 프로필 | +| Resources | **Memory** | 장기 기억 메모 | +| Resources | **Skills** | 재사용 가능한 워크플로우 | +| Resources | **Learnings** | 시간이 지남에 따라 캡처된 수정 사항 및 패턴 | +| Resources | **Remote agents** | 다른 agent-native 앱에 대한 A2A 연결 (이전에 Connections 탭에 표시되던 내용을 대체) | +| Agent | **Snapshots** | 범위 미리보기, 토큰 예산, 출처/거버넌스/소스별로 그룹화된 정렬된 시스템 섹션, 최신 라이브 스레드 스냅샷. "Context"에서 이름 변경됨; 이전 `#context` 링크는 여기로 리디렉션됩니다. | +| Agent | **Connections** | MCP 서버 관리만 | +| Agent | **Automations** | 일시 중지/재개, 세부 정보, 삭제 흐름이 있는 개인 및 조직 예약/이벤트 자동화. 안정적인 호환성 URL은 `/agent#jobs`로 유지됩니다. | +| Agent | **Settings** | 에이전트 모델, API 키, 제한, 음성, 자동화 설정 | +| Agent | **Access** | 앱 MCP URL, 사용 가능한 경우 A2A 에이전트 카드, Claude, ChatGPT, Cursor, Claude Code, Codex 및 기타 클라이언트를 위한 공유 설정 가이드. 전체 연결 흐름 및 토큰 대체를 위한 `/mcp/connect` 링크. | + +이 페이지는 개인(`user` 범위) 데이터만 표시합니다. 현재 조직 수준 토글은 없습니다. 이는 기존 컴포넌트 및 접근 확인 위에 있는 얇은 셸로, 새로운 관리 콘솔이 아닙니다: Connections는 앱이 호출할 수 있는 것을 설명하고; Access는 외부 클라이언트가 연결하는 방법을 설명합니다. + +아직 포함되지 않은 기능: + +- 조직 범위 뷰 +- 권한 및 범위 편집 +- 취소 UI +- 반복당 출처 히스토리 + +## 임베디드 사이드카 {#embedded-sidecar} + +주요 제품이 이미 존재하고 그 옆에 에이전트를 두고 싶을 때 임베디드 사이드카를 사용하세요. + +서버 플러그인은 Agent-Native 경로를 호스트 앱에 마운트하고 서버 측에서 호스트 ID를 확인합니다: + +```ts +import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; + +export default createAgentNativeEmbeddedPlugin({ + databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL, + auth: getHostSession, + actions: hostActions, +}); +``` + +React 사이드카는 페이지 컨텍스트와 호스트 명령을 전달합니다: + +```tsx +import { AgentNativeEmbedded } from "@agent-native/core/client/host"; +export function AppShell({ children }) { + return ( + ({ + route: { pathname: window.location.pathname }, + selection: { text: window.getSelection()?.toString() || undefined }, + })} + onNavigate={(payload) => + router.navigate((payload as { path: string }).path) + } + onRefresh={() => queryClient.invalidateQueries()} + > + {children} + + ); +} +``` + +### 연결 방식 + +두 부분은 브리지로 작동합니다: 호스트 앱이 페이지 컨텍스트(현재 경로, 선택된 텍스트, 포커스된 객체)를 `AgentNativeEmbedded`로 전달하고, 에이전트는 `onNavigate`와 `onRefresh`를 통해 명령을 다시 보냅니다. 서버 플러그인은 ID를 처리합니다 — 별도의 로그인 없이 에이전트가 올바른 사용자로 작동할 수 있도록 호스트 세션을 확인합니다. 호스트 앱에서 변경할 것은 없습니다; 플러그인이 기존 경로 옆에 Agent-Native 경로를 연결합니다. + + + +```html +
+
+ 호스트 앱기존 SaaS +
+ getContext()
경로 · 선택 항목 +
+
+ onNavigate / onRefresh
호스트 명령 +
+
+
+ + +
+
+ AgentNativeEmbedded에이전트 + 리소스 +
+ Agent-Native 경로
서버 플러그인에 의해 마운트됨 +
+
+
+``` + +```css +.diagram-sidecar { + display: flex; + align-items: center; + gap: 14px; + flex-wrap: wrap; +} +.diagram-sidecar .diagram-panel { + display: flex; + flex-direction: column; + gap: 8px; + padding: 14px 16px; + min-width: 200px; +} +.diagram-sidecar .diagram-col-arrows { + display: flex; + flex-direction: column; + gap: 6px; +} +.diagram-sidecar .diagram-arrow { + font-size: 22px; + line-height: 1; +} +``` + + + +호스트 인증, 데이터베이스 격리, iframe/피커 모드, 하위 레벨 브리지 API는 [Embedding SDK](/docs/embedding-sdk)를 참조하세요. -사용자 지정 앱 화면을 쳐다볼 필요가 없는 경우 헤드리스 경로를 사용하세요. -작업 실행: 예약된 작업, 통합, 백엔드 워크플로, CLI 루프, -다른 상담원 또는 기존 제품이 Agent-Native를 호출합니다. +## 자동화 우선 앱 {#headless} -이것은 **대리인이 제품이다**일 때 도달할 수 있는 형태이기도 합니다. -app-agent 루프는 대시보드가 아닌 현관문입니다. -터미널, Slack, 이메일, 예약된 작업, 다른 상담원 또는 채팅 — "내 요약 -읽지 않은 이메일," "일일 지표를 Slack에 게시," "다음에 해당하는 후보자 찾기 -지난주에 응답했습니다." - 에이전트는 어디에서나 작업을 수행하고 결과를 반환합니다. -속합니다. 상태 비저장 프롬프트가 아닌 실제 앱입니다: actions, 인증 세션, -앱 상태, 스레드/실행 기록, 설정, 자격 증명 및 공유 기록이 모두 실시간으로 표시됩니다. -SQL에서. +작업이 실행되는 동안 커스텀 브라우저 화면이 필요 없을 때 자동화 우선 경로를 사용하세요: 예약된 작업, 통합, 백엔드 워크플로우, CLI 루프, 다른 에이전트, 또는 Agent-Native를 호출하는 기존 제품. -다음과 같은 경우에 이 패턴을 선택하세요: +이것은 자동화가 제품 서피스일 때 사용할 형태입니다. 터미널, Slack, 이메일, 예약된 작업, 다른 에이전트, 또는 Chat에서 요청을 보내면("읽지 않은 이메일을 요약해줘," "Slack에 일일 지표를 게시해줘," "지난 주에 답변한 후보자를 찾아줘") 에이전트가 작동하고 결과를 적절한 곳에 반환합니다. 이는 상태 없는 프롬프트가 아닌 실제 앱입니다: 액션, 인증 세션, 앱 상태, 스레드/실행 히스토리, 설정, 자격 증명, 공유 레코드가 모두 SQL에 저장됩니다. -- **작업은 백그라운드에서 이루어집니다.** 선별 에이전트, 일일 보고 에이전트, 대기 중인 응답자 등 대부분의 가치는 사용자가 보지 않는 동안 생성됩니다. -- **출력은 앱에서 나갑니다.** 에이전트는 Slack에 게시하거나 이메일을 보내거나 타사 시스템을 업데이트합니다. 앱 내에서 탐색할 항목이 없습니다. -- **도메인은 일회성입니다.** 연구 봇, 요약 생성기, 보고서 작성자 — 목록 보기가 필요한 영구 개체가 없습니다. -- **프로토타입을 제작 중입니다.** 지금 에이전트를 배송하세요. 사용자가 원하는 경우 나중에 더 풍부한 UI를 추가하세요. +다음 경우에 이 패턴을 선택하세요: -귀하의 제품이 영구 객체를 기반으로 구축된 경우 사용자는 탐색, 피벗 및 -share — emails, events, documents, charts — pick a [full application](#full-application) -or a [template](/docs/cloneable-saas) instead; 전체 UI _plus_ 에이전트를 추가합니다. +- **작업이 백그라운드에서 실행됩니다.** 대부분의 가치는 사용자가 보지 않는 동안 생성됩니다: 분류 에이전트, 일일 보고서 에이전트, 온콜 응답자. +- **출력이 앱 밖으로 나갑니다.** 에이전트가 Slack에 게시하거나, 이메일을 보내거나, 서드파티 시스템을 업데이트합니다; 앱 내에서 탐색할 것이 없습니다. +- **도메인이 일회성입니다.** 연구 봇, 요약 생성기, 목록 뷰가 필요한 영구 객체가 없는 보고서 작성기. +- **자동화를 프로토타이핑 중입니다.** 지금 작업을 출시하고; 사용자가 검사하고 조정해야 할 때 채팅 또는 앱 페이지를 추가하세요. -### 상자 내용물 {#in-the-box} +제품이 사용자가 탐색, 피벗, 공유하는 영구 객체(이메일, 이벤트, 문서, 차트)를 중심으로 구축되어 있다면 [풀 애플리케이션](#full-application) 또는 [템플릿](/docs/cloneable-saas)을 선택하세요; 이들은 에이전트 _플러스_ 전체 UI를 추가합니다. -헤드리스 앱은 몇 주간의 대시보드 작업을 건너뛰고 하루부터 채널에 구애받지 않습니다. -1 — 동일한 에이전트가 웹, Slack, 텔레그램, 이메일 및 기타 에이전트에서 실행됩니다. -모든 것이 UI가 아닌 에이전트를 통과하기 때문입니다. 절충안은 다음과 같습니다. -"모든 것을 한 눈에 찾아보기" 보기가 없습니다. 사용자가 필요하다면 패턴을 혼합하고 -작은 상태 페이지나 목록 보기를 추가하세요. +### 기본 제공 내용 {#in-the-box} -내장된 Chat 셸을 추가하면 프레임워크에서 5가지 관리 기능을 제공합니다. -만들 필요가 없는 표면: **채팅**(주 입력), **작업 공간** -(skills, 메모리, 명령, 하위 에이전트, 연결된 MCP 서버, 예약됨 -작업), **작업 기록**, **스레드 기록** 및 **설정**. 보통 -충분합니다. 대화하고, 수행된 작업을 확인하고, 작동 방식을 구성하세요. -[Chat](/docs/template-chat) when you're ready to add that browser UI, or the -[Dispatch template](/docs/template-dispatch) for a workspace-style starting -Slack/Telegram, 예약된 작업 및 공유 비밀을 즉시 사용할 수 있습니다. +자동화 우선 앱은 대시보드 작업을 건너뛰고, 처음부터 채널 독립적입니다. 모든 것이 동일한 액션을 통해 이루어지기 때문에 동일한 에이전트가 웹, Slack, Telegram, 이메일, 다른 에이전트에서 실행됩니다. 트레이드오프는 "모든 것을 한 눈에 탐색"하는 뷰가 없다는 것입니다; 사용자에게 그것이 필요하다면 [Chat](/docs/template-chat)에서 시작하거나 작은 상태 페이지나 목록 뷰를 추가하세요. -가장 작은 로컬 경로는 헤드리스 에이전트 스캐폴드에 하나의 작업을 더한 것입니다: +내장 Chat 셸을 추가하면 프레임워크가 직접 구축할 필요 없는 다섯 가지 관리 서피스를 제공합니다: **Chat**(주요 입력), **Resources**(스킬, 메모리, 지침, 서브 에이전트, 연결된 MCP 서버), **Automations**, **Thread history**, **Settings**. 이것들은 보통 충분합니다: 대화하고, 완료된 것을 확인하고, 동작 방식을 구성합니다. 브라우저 UI를 추가할 준비가 되면 [Chat](/docs/template-chat)을, 또는 Slack/Telegram, 예약된 작업, 공유 비밀이 기본 제공되는 워크스페이스 스타일 시작점으로는 [Dispatch 템플릿](/docs/template-dispatch)을 사용하세요. + +가장 작은 브라우저 없는 로컬 경로는 스캐폴드와 하나의 액션입니다: ```bash npx @agent-native/core@latest create my-agent --headless @@ -167,7 +378,7 @@ cd my-agent pnpm install ``` -그런 다음 지속성 작업을 정의합니다. +그런 다음 영구 작업을 정의하세요: ```ts filename="actions/summarize-week.ts" import { defineAction } from "@agent-native/core/action"; @@ -183,107 +394,83 @@ export default defineAction({ }); ``` -그런 다음 하나의 작업을 다음과 같이 호출할 수 있습니다. +하나의 액션은 다음과 같이 호출할 수 있습니다: -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **앱 에이전트 CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot 및 기타 MCP 호스트에서 -- **A2A** — 다른 에이전트 기반 앱 또는 에이전트 피어에서 -- **UI** — `useActionQuery`, `useActionMutation` 또는 `callAction`를 통해 -- **에이전트 도구** — 내장된 채팅 루프에서 +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **App-agent CLI:** `pnpm agent "Summarize form_123"` +- **MCP:** Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot 및 기타 MCP 호스트에서 +- **A2A:** 다른 agent-native 앱 또는 에이전트 피어에서 +- **UI:** `useActionQuery`, `useActionMutation`, 또는 `callAction`을 통해 +- **에이전트 도구:** 내장 채팅 루프에서 - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. +모든 `defineAction`은 `/_agent-native/actions/`에 자동으로 마운트됩니다. JSON 본문은 `run`이 실행되기 전에 액션의 zod 스키마에 대해 유효성 검사됩니다. 장기 실행 bearer 토큰으로 외부 시스템에서 호출하려면 [HTTP API](/docs/http-api)를 참조하세요. -이것은 데이터베이스 없음 또는 상태 비저장 모드가 아닙니다. 앱 에이전트 루프는 세션을 저장합니다. -스레드, 실행, 설정, 자격 증명, 애플리케이션 상태 및 공유 기록 -SQL. 로컬 개발의 기본값은 SQLite입니다. 호스팅된 헤드리스 앱은 -영구적인 SQL 데이터베이스. +이것은 데이터베이스가 없거나 상태 없는 모드가 아닙니다. app-agent 루프는 세션, 스레드, 실행, 설정, 자격 증명, 애플리케이션 상태, 공유 레코드를 SQL에 저장합니다. 로컬 개발은 기본적으로 SQLite를 사용합니다; 호스팅된 자동화 우선 앱은 영구 SQL 데이터베이스를 사용해야 합니다. -프로젝트 폴더에서 헤드리스로 전체 에이전트 루프가 필요한 경우 다음을 사용하세요. +프로젝트 폴더에서 전체 에이전트 루프를 헤드리스로 실행해야 하는 경우: ```bash pnpm agent "Summarize this week's forms." ``` -다른 앱이나 스크립트가 전체 에이전트를 호출해야 하는 경우 다음을 사용하세요 -`agentNative.invoke("analytics", "...")` 또는 `agent-native invoke` CLI. 그 -로컬 작업은 actions에 유지되는 동안 크로스 앱 작업은 A2A 경로에서 유지됩니다. +다른 앱 또는 스크립트가 전체 에이전트를 호출해야 하는 경우 `agentNative.invoke("analytics", "...")` 또는 `agent-native invoke` CLI를 사용하세요. 이렇게 하면 크로스 앱 작업이 A2A 경로에 유지되고 로컬 작업은 액션에 유지됩니다. -작업자, 작업, 통합 webhooks 및 사용자 정의 호스트가 에이전트 루프를 구동할 수 있습니다 -서버 API를 통해 직접. 이는 actions보다 낮은 수준입니다 — 귀하가 제공합니다 -엔진, 모델, 메시지, actions 및 이벤트 싱크를 직접 설정하세요: +워커, 작업, 통합 웹훅, 커스텀 호스트는 서버 API를 통해 에이전트 루프를 직접 구동할 수 있습니다. 이것은 액션보다 하위 레벨입니다 — 엔진, 모델, 메시지, 도구, 액션, 이벤트 싱크, 중단 신호를 직접 제공합니다: ```ts import { runAgentLoop } from "@agent-native/core/server"; -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); ``` -대부분의 앱에서 예약된 프롬프트 및 통합 webhooks는 이미 이 루프를 호출합니다 -당신을 위해. 사용자 정의 헤드리스 호스트 eval을 구축할 때만 직접 접근하세요. -러너 또는 서버측 오케스트레이션 표면 — [서버 — 프로덕션 에이전트 -handler](/docs/server#agent-handler)를 사용하여 전체 서명을 받으세요. +대부분의 앱에서 예약된 프롬프트와 통합 웹훅이 이미 이 루프를 자동으로 호출합니다. 커스텀 브라우저 없는 호스트, 평가 실행기, 또는 서버 측 오케스트레이션 서피스를 구축할 때만 직접 사용하세요. 전체 시그니처는 [Server: Production agent handler](/docs/server#agent-handler)를 참조하세요. ### 폴더에 대해 실행 {#folder-loop} -목표가 "이 폴더에 대해 에이전트 실행"이라면 app-agent로 시작하세요. -해당 폴더에서 루프: 헤드리스 앱을 스캐폴드하고 actions/instructions를 추가하고 실행 -`pnpm agent "..."`. 이는 동일한 작업/런타임/상태 내에서 작업을 유지합니다 -프로덕션에서 앱이 사용할 계약 +"이 폴더에 대해 에이전트를 실행"하는 것이 목표라면, 해당 폴더에서 app-agent 루프로 시작하세요: 자동화 우선 앱을 스캐폴드하고, 액션/지침을 추가하고, `pnpm agent "..."`를 실행하세요. 이렇게 하면 작업이 앱이 프로덕션에서 사용할 동일한 액션/런타임/상태 계약 안에 유지됩니다. -외부 코딩 하네스는 Claude 내장을 위한 별도의 제품 표면입니다. -코드, Codex, Pi, Cursor, Mastra 또는 Agent-Native 앱 내의 유사한 런타임 -기본 방법이 아닌 코딩 에이전트 제품을 구축할 때 이를 사용하십시오. -로컬 에이전트 기반 워크플로를 시작합니다. +외부 코딩 하네스는 Agent-Native 앱 내에서 Claude Code, Codex, Pi, Cursor, Mastra 또는 유사한 런타임을 임베딩하기 위한 별도의 제품 서피스입니다. 로컬 agent-native 워크플로우를 시작하는 기본 방법이 아닌, 코딩 에이전트 제품을 구축할 때 사용하세요. -### 클라우드 저장소 액세스 {#cloud-repo-access} +### 클라우드 저장소 접근 {#cloud-repo-access} -저장소 액세스가 필요한 클라우드 헤드리스 앱의 경우 GitHub 커넥터를 사용하세요. -플러스 토큰 CRUD 모델: 저장소 나열, 파일 검색, 파일 읽기, 생성 또는 -공급자 범위를 통해 파일 편집, 파일 삭제 및 액세스 취소 -자격증명. 로컬 개발에서는 대상 저장소를 명시적으로 설정하세요: +저장소 접근이 필요한 클라우드 자동화 우선 앱의 경우, GitHub 커넥터와 토큰 CRUD 모델을 사용하세요: 저장소 나열, 파일 검색, 파일 읽기, 파일 생성 또는 편집, 파일 삭제, 공급자 범위 자격 증명을 통한 접근 취소. 로컬 개발에서 대상 저장소를 명시적으로 설정하세요: ```bash GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." ``` -VM 복제 또는 수명이 긴 샌드박스 체크아웃을 기본 클라우드로 취급하지 마세요 -저장소 액세스 모델. 샌드박스는 여전히 격리된 코드 실행에 중요하지만 -저장소 액세스는 명시적이고, 허가되고, 감사 및 취소 가능해야 합니다. -커넥터 레이어를 통해 +VM 복제 또는 장기 실행 샌드박스 체크아웃을 기본 클라우드 저장소 접근 모델로 취급하지 마세요. 샌드박스는 격리된 코드 실행에 여전히 중요하지만, 저장소 접근은 커넥터 레이어를 통해 명시적이고, 권한이 있으며, 감사 가능하고, 취소 가능해야 합니다. ### 세션 및 실행 공유 {#sharing-runs} -헤드리스 세션 및 실행은 내구성이 있는 개체입니다. 공유 가능성은 단계적으로 이루어져야 합니다: -먼저 링크를 읽고 공유하여 팀원이 정리된 프롬프트, 출력을 검사할 수 있도록 -및 실행 상태; 나중에 허가된 쓰기 가능 공동 작업을 계속 실행하세요. -actions 승인, 일정 편집 또는 구성 변경이 진행됩니다 -명시적 액세스 확인. - -## Agent-Native의 리치 채팅 {#rich-chat} - -사용자가 상담원과 대화해야 할 때 내장된 채팅을 사용하세요. 도구 호출을 확인하세요. -작업을 승인하고 기본 결과를 검사하며 지속적인 스레드 기록을 유지합니다. - -전체 앱 시작점의 경우 [Chat template](/docs/template-chat)를 사용하세요. +자동화 우선 세션과 실행은 영구 객체입니다. 공유 가능성은 단계적으로 구현해야 합니다: 먼저 읽기/공유 링크를 통해 팀원이 정리된 프롬프트, 출력, 실행 상태를 검사할 수 있게 하고; 그다음 권한이 있는 쓰기 가능한 협업을 통해 실행 계속, 액션 승인, 일정 편집, 구성 변경이 명시적 접근 확인을 거치도록 하세요. ```bash npx @agent-native/core@latest create my-chat-app --template chat @@ -355,12 +542,9 @@ Actions는 명시적인 기본 위젯 결과를 반환할 수 있으므로 채 텍스트. 표, 차트 및 입력된 제품 카드는 자사 React로 렌더링됩니다. iframe이 없는 채팅 구성요소. [Native 채팅 UI](/docs/native-chat-ui)를 참조하세요. -## 에이전트의 풍부한 채팅 {#byo-agent} +## 자체 에이전트에서 리치 채팅 {#byo-agent} -에이전트가 이미 다른 프레임워크로 구축된 경우 이 경로를 사용하거나 -런타임이 있고 그 주변에 Agent-Native의 채팅 UI가 있기를 원합니다. `AgentChatRuntime`는 -경계: 런타임은 정규화된 이벤트를 스트리밍하고 Agent-Native는 -작성자, 기록, 도구 호출, 승인, 기본 위젯 및 앱 레이아웃. +에이전트가 이미 다른 프레임워크나 런타임으로 구축되었고 Agent-Native의 채팅 UI를 감싸고 싶을 때 이 경로를 사용하세요. `AgentChatRuntime`이 경계입니다: 런타임이 정규화된 이벤트를 스트리밍하면 Agent-Native가 작성기, 트랜스크립트, 도구 호출, 승인, 네이티브 위젯, 앱 레이아웃을 렌더링합니다. ```tsx import { @@ -377,155 +561,36 @@ export function SupportAgentChat() { } ``` -OpenAI 에이전트, OpenAI 응답, Claude를 위해 미리 만들어진 런타임 도우미가 존재합니다. -에이전트 SDK, Vercel AI SDK, AG-UI 및 위의 정규화된 HTTP 런타임 -기타 에이전트(Mastra, Flue, Eve, LangGraph 또는 맞춤형 서비스)의 경우. ACP는 -최종 사용자 앱 채팅이나 A2A 전송이 아니며 Agent-Native는 현재 -A2UI 지원을 요청하세요. ACP는 특정 장소에서 지원됩니다 — 지역 운전 -코딩 에이전트(Gemini CLI, Claude 코드, …)를 통해 -[harness layer](/docs/harness-agents#acp), 여기서는 채팅 런타임이 아닙니다. - -[Native 채팅 UI — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -is the canonical home for the event shapes, the runtime helpers, and `chatUI` -도구 결과 메타데이터. Start there when wiring an external agent into the chat. - -## 내장형 사이드카 {#embedded-sidecar} - -Use the embedded sidecar when the main product already exists and you want an -옆에 있는 요원 - -The server plugin mounts Agent-Native 라우트 into your host app and resolves -호스트 ID 서버측: - -```ts -import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; - -export default createAgentNativeEmbeddedPlugin({ - databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL, - auth: getHostSession, - actions: hostActions, -}); -``` - -React 사이드카는 페이지 컨텍스트 및 호스트 명령을 전달합니다. +OpenAI Agents, OpenAI Responses, Claude Agent SDK, Vercel AI SDK, AG-UI를 위한 즉시 사용 가능한 런타임 헬퍼와, 다른 에이전트(Mastra, Flue, Eve, LangGraph, 또는 커스텀 서비스)를 위한 위의 정규화된 HTTP 런타임이 있습니다. ACP는 최종 사용자 앱 채팅이나 A2A 전송이 아니며, Agent-Native는 현재 A2UI 지원을 주장하지 않습니다. ACP는 한 가지 특정 장소에서 지원됩니다: [하네스 레이어](/docs/harness-agents#acp)를 통해 로컬 코딩 에이전트(Gemini CLI, Claude Code, …)를 구동하는 것으로, 여기서 채팅 런타임으로는 사용되지 않습니다. -```tsx -import { AgentNativeEmbedded } from "@agent-native/core/client/host"; -export function AppShell({ children }) { - return ( - ({ - route: { pathname: window.location.pathname }, - selection: { text: window.getSelection()?.toString() || undefined }, - })} - onNavigate={(payload) => - router.navigate((payload as { path: string }).path) - } - onRefresh={() => queryClient.invalidateQueries()} - > - {children} - - ); -} -``` +[Native Chat UI: BYO 에이전트 런타임](/docs/native-chat-ui#byo-agent-runtimes)은 이벤트 형태, 런타임 헬퍼, `chatUI` 도구 결과 메타데이터의 공식 참고 문서입니다. 외부 에이전트를 채팅에 연결할 때 여기서 시작하세요. - +## 다음 단계 {#related-docs} -```html -
-
- 호스트 앱기존 SaaS -
- getContext()
라우트 · 선택 -
-
- onNavigate / onRefresh
호스트 명령 -
-
-
- - -
-
- AgentNativeEmbeddedagent + workspace -
- Agent-Native 라우트
mounted by the server plugin -
-
-
-``` + -```css -.diagram-sidecar { - display: flex; - align-items: center; - gap: 14px; - flex-wrap: wrap; -} -.diagram-sidecar .diagram-panel { - display: flex; - flex-direction: column; - gap: 8px; - padding: 14px 16px; - min-width: 200px; -} -.diagram-sidecar .diagram-col-arrows { - display: flex; - flex-direction: column; - gap: 6px; -} -.diagram-sidecar .diagram-arrow { - font-size: 22px; - line-height: 1; -} -``` +### [액션](/docs/actions) - +한 번 작업을 정의하세요. 위의 모든 서피스가 동일한 것을 호출합니다. -호스트 인증, 데이터베이스 격리는 [Embedding SDK](/docs/embedding-sdk)를 참조하세요. -iframe/선택기 모드 및 하위 수준 브리지 API. +### [Native Chat UI](/docs/native-chat-ui) -## 전체 적용 {#full-application} +채팅에서 타입이 지정된 액션 결과를 테이블, 차트, 카드로 렌더링하세요. -사용자에게 지속 가능한 개체와 워크플로가 필요한 경우 전체 앱 경로(양식, -대시보드, 달력, 받은 편지함, 편집기, 문서, 자산 또는 보고서. +### [Generative UI](/docs/generative-ui) -전체 앱은 동일한 작업 및 에이전트 계약에 제품 UI를 추가합니다. +채팅 인라인에서 일시적 또는 지속되는 샌드박스 UI를 생성하세요. -- **SQL 상태** — 앱 데이터, 탐색, 설정 및 채팅 기록이 지속됩니다. -- **컨텍스트 인식** — 에이전트는 현재 경로, 선택 및 초점이 맞춰진 개체를 알고 있습니다. -- **실시간 동기화** — 에이전트 변경 사항은 UI를 업데이트하고 UI 변경 사항은 에이전트의 컨텍스트를 업데이트합니다. -- **딥 링크** — 작업 결과로 올바른 앱 보기가 열릴 수 있습니다. -- **기본 채팅 위젯** — 표, 차트, 카드, 승인 및 입력된 결과가 인라인으로 표시됩니다. +### [자동화 우선 앱](/docs/pure-agent-apps) -최소한의 앱을 원한다면 [Chat template](/docs/template-chat)부터 시작하세요 -actions 주변 또는 도메인 [template](/docs/cloneable-saas)에서 -완전한 제품 모양을 원합니다. +작업, 큐, 스크립트, 외부 에이전트를 위한 전체 브라우저 없는 패턴. -## 선택 방법 {#how-to-choose} +### [외부 에이전트](/docs/external-agents) -| 생각해보면... | 선택 | -| ---------------------------------------------------------------------- | ------------------------ | -| "호출 가능한 도구나 작업 흐름이 필요합니다." | 헤드리스 에이전트 | -| "프레임워크 에이전트를 원하지만 채팅이 기본 UI여야 합니다." | Agent-Native의 리치 채팅 | -| "이미 에이전트가 있습니다. 이를 위해서는 세련된 채팅 UI가 필요합니다." | 에이전트의 풍부한 채팅 | -| "이미 SaaS 앱이 있습니다. 옆에 에이전트를 추가하세요." | 내장형 사이드카 | -| "에이전트와 UI는 하나의 제품으로 함께 진화해야 합니다." | 전체 적용 | +MCP 호환 호스트를 도구 서버로 앱에 연결하세요. -계약을 작게 유지: 지속 가능한 작업을 actions로 정의하고 명시적으로 반환 -채팅에 풍부한 UI가 필요한 경우 위젯 결과를 제공하고 사용자가 있는 경우에만 전체 화면을 추가합니다. -영구 객체를 탐색, 비교, 구성 또는 공동 작업해야 합니다. +### [A2A 프로토콜](/docs/a2a-protocol) -## 다음 단계 {#related-docs} +A2A 표준을 통해 다른 agent-native 앱의 에이전트를 호출하세요. -- [**Actions**](/docs/actions) — 작업을 한 번 정의하면 위의 모든 표면이 같은 작업을 호출합니다 -- [**Native 채팅 UI**](/docs/native-chat-ui) — 형식화된 action 결과를 채팅에서 표, 차트, 카드로 렌더링합니다 -- [**Generative UI**](/docs/generative-ui) — 임시 또는 영구 sandbox UI를 채팅 안에서 생성합니다 -- [**Automation-First Apps**](/docs/pure-agent-apps) — 작업, 대기열, 스크립트 및 외부 에이전트를 위한 완전한 브라우저 없는 패턴입니다 -- [**External Agents**](/docs/external-agents) — MCP 호환 호스트를 앱에 연결합니다 -- [**A2A Protocol**](/docs/a2a-protocol) — 다른 Agent-Native 앱에서 에이전트를 호출합니다 + diff --git a/packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx b/packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx index 31d74e9c03..26835f3b1f 100644 --- a/packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx @@ -1,91 +1,46 @@ --- -title: "Superfícies do agente" -description: "Use Agent-Native sem controle, como bate-papo avançado, dentro de um aplicativo existente ou como um aplicativo completo nativo do agente." -search: "aplicativo completo de bate-papo rico com agente sem cabeça BYO tempo de execução do agente AgentChatRuntime incorporado actions MCP A2A HTTP CLI" +title: "Superfícies do Agente" +description: "Escolha como um app agêntico evolui do chat para UI inline, páginas de app duráveis, sidecars embarcados, automação e acesso de agentes externos." +search: "app agêntico rich chat UI de chat nativo app completo automação headless BYO agent runtime AgentChatRuntime embed actions MCP A2A HTTP CLI" --- -# Superfícies do agente +# Superfícies do Agente -## Espaço de trabalho completo do Agent {#agent-page} +Uma **superfície** é a forma como usuários (ou outros sistemas) interagem com seu app: uma janela de chat, uma página de dashboard, um job em background, uma chamada de API de outro agente. O Agent-Native permite combinar e combinar essas superfícies sem reconstruir sua lógica central, porque toda superfície executa as mesmas actions subjacentes. Se você é novo no Agent-Native, leia [Conceitos-Chave](/docs/key-concepts) primeiro. -Quando um aplicativo completo precisa de um lugar permanente para inspecionar e -configurar seu agente, monte `AgentTabsPage` em `/agent`. Adicione a rota à -navegação do aplicativo e passe `agentPageHref="/agent"` para `AgentSidebar`, -para que os modos Resources e Settings apontem para a página completa sem -duplicar esses fluxos. +## Como as superfícies se relacionam -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -A página compartilhada oferece atualmente cinco abas: - -- **Context** — prévia do escopo, orçamento de tokens, seções de sistema ordenadas por procedência, governança e fonte, visualização em lista/treemap e o snapshot da thread ativa mais recente. -- **Files** — reutiliza `ResourcesPanel` para recursos pessoais ou da organização. -- **Connections** — gerenciamento de servidores MCP e lista de agentes remotos A2A: o que o agente deste app pode chamar. -- **Automations** — automações pessoais e da organização Scheduled e Event com pausar/retomar, detalhes e excluir. A URL de compatibilidade continua sendo `/agent#jobs`. -- **Access** — URL MCP, cartão de agente A2A quando disponível e guias compartilhados de configuração; o fluxo completo e o fallback de token ficam em `/mcp/connect`. +As quatro formas principais de produto estão em um espectro que vai da mais interativa até a totalmente headless. O que as torna combináveis é que a base permanece a mesma em todos os casos: as mesmas actions, o mesmo banco de dados SQL e o mesmo loop de agente alimentam cada forma. Adicionar uma nova superfície não significa reescrever o que está por baixo — você está apenas adicionando uma nova forma de acessar as mesmas operações. -A página usa atualmente o escopo pessoal e não oferece um seletor -**Personal / Organization** para toda a página. Uma aba pode mostrar suas -próprias seções de organização quando as actions subjacentes as suportam: -**Automations** mostra seções pessoais e da organização para Scheduled e Event. -Automações Event da organização sempre executam como seu criador. A página é uma camada -fina sobre componentes, actions e verificações de acesso existentes, não um -novo console administrativo. - -Agent-Native é deliberadamente combinável. Você pode usar o agente sem muito UI, -use o UI sem o tempo de execução do agente integrado ou use os dois juntos como um pacote completo -aplicativo. - -A maneira útil de escolher não é primeiro por protocolo. Escolha a superfície do produto -você deseja, então use a primitiva correspondente. - -| Superfície | Use quando | Comece com | -| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **Agente sem cabeça** | Código, tarefas, scripts, outro aplicativo ou outro agente devem chamar o trabalho diretamente. | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Bate-papo rico em Agent-Native** | Você deseja um bate-papo independente ou incorporado, apoiado pelo loop de agente integrado. | [Chat template](/docs/template-chat), ``, `` | -| **Bate-papo avançado com seu agente** | Você criou o agente em outro lugar e deseja o compositor, a transcrição, os cartões de ferramentas e os widgets nativos do Agent-Native. | `AgentChatRuntime`, `` | -| **Carro lateral incorporado** | Você já tem um aplicativo SaaS e deseja um agente ao lado dele com contexto de página e comandos de host. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **Aplicativo completo** | Humanos e agentes devem compartilhar telas, dados, navegação e colaboração duráveis. | Modelos, actions, estado SQL, reconhecimento de contexto | - -São etapas, não produtos separados. Um fluxo de trabalho pode começar sem interface -agente com uma ação, aparece no chat como uma tabela ou gráfico e depois se torna um -tela inteira em um aplicativo sem alterar a operação que o agente chama. - - + ```html
- Headlessactions, jobs, scripts, outros agentes + Chatcompositor, transcrição, chamadas de ferramenta
- Chat enriquecidocomposer, transcrição, cards de ferramentas + UI Inlinetabelas, gráficos, cards
- Sidecar incorporadoagent beside an existing app + Página de apptelas duráveis, dados SQL
- maior parte do UIAplicação completatelas duráveis, dados, colaboração + headlessAutomaçãojobs, scripts, agentes externos
mesmas actions · mesmo SQL · mesmo loop do agentemesmas actions · mesmo SQL · mesmo loop de agente
``` @@ -119,180 +74,31 @@ tela inteira em um aplicativo sem alterar a operação que o agente chama. -## Agente sem cabeça {#headless} - -Use o caminho sem cabeça quando ninguém precisar olhar para a tela de um aplicativo personalizado enquanto -o trabalho é executado: jobs agendados, integrações, fluxos de trabalho de back-end, loops CLI, -outro agente ou um produto existente ligando para Agent-Native. - -Essa também é a forma a ser alcançada quando **o agente _é_ o produto** — o -o loop do agente de aplicativo é a porta de entrada, não um painel. Você envia uma solicitação do -terminal, Slack, e-mail, um trabalho agendado, outro agente ou Chat — "resuma meu -e-mails não lidos", "postar as métricas diárias em Slack", "encontrar os candidatos que -respondeu na semana passada" — e o agente age e retorna o resultado onde quer que esteja -pertence. Ainda é um aplicativo real, não um prompt sem estado: actions, sessões de autenticação, -estado do aplicativo, histórico de thread/execução, configurações, credenciais e registros de compartilhamento, tudo ao vivo -em SQL. +## Escolha um ponto de partida -Escolha este padrão quando: - -- **O trabalho acontece em segundo plano.** A maior parte do valor é criada enquanto o usuário não está olhando: agentes de triagem, agentes de relatórios diários, atendentes de plantão. -- **A saída sai do aplicativo.** O agente posta no Slack, envia e-mail ou atualiza um sistema de terceiros; não há nada para navegar no aplicativo. -- **O domínio é único.** Bot de pesquisa, gerador de resumo, redator de relatórios — nenhum objeto persistente que precise de uma visualização de lista. -- **Você está criando um protótipo.** Envie o agente agora; adicione UI mais rico posteriormente se os usuários desejarem. +O chat é o ponto de entrada mais comum. Os apps geralmente evoluem para UI inline conforme as saídas ficam mais ricas, depois adicionam páginas de app completas quando os usuários precisam de objetos persistentes para navegar e compartilhar. As mesmas actions alimentam os botões, os jobs agendados e os agentes externos que vêm depois. Use o sidecar Embarcado ao adicionar um agente a um produto que você já possui, ou Automação-primeiro para trabalhos que rodam sem um navegador. Aqui está o quadro completo: -Se o seu produto for construído em torno de objetos persistentes, os usuários navegam, dinamizam e -compartilhe — e-mails, eventos, documentos, gráficos — escolha um [full application](#full-application) -ou um [template](/docs/cloneable-saas); eles adicionam um UI completo _mais_ o agente. - -### O que vem na caixa {#in-the-box} +| Superfície | Use quando | Comece com | +| -------------------------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | +| **[Rich chat](#rich-chat)** | Os usuários falam com o agente, veem chamadas de ferramenta e mantêm um histórico de thread. | [Template Chat](/docs/template-chat), `` | +| **[UI inline nativa](#native-inline-ui)** | Os resultados de actions devem ser renderizados como tabelas, gráficos, cards ou aprovações no chat. | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[UI inline gerada](#generated-inline-ui)** | O agente deve criar controles temporários ou reutilizáveis dentro do chat sob demanda. | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[Aplicação completa](#full-application)** | Os usuários precisam de telas duráveis, dados compartilhados, navegação e colaboração. | Templates, actions, estado SQL, context awareness | +| **[Sidecar embarcado](#embedded-sidecar)** | Você já tem um app SaaS e quer um agente ao lado dele com contexto da página. | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[Automação-primeiro](#headless)** | Jobs, scripts ou outros agentes chamam o trabalho diretamente sem UI de navegador. | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[Rich chat no seu agente](#byo-agent)** | Você construiu o agente em outro lugar e quer a UI de chat do Agent-Native ao redor dele. | `AgentChatRuntime`, `` | -Um aplicativo headless pula semanas de trabalho no painel e é independente de canal durante o dia -um — o mesmo agente é executado na web, Slack, Telegram, e-mail e outros agentes -porque tudo passa pelo agente e não pelo UI. A desvantagem é que existe -sem visualização "navegar tudo de relance"; se os usuários precisarem disso, misture padrões e -adicione uma pequena página de status ou visualização de lista. +## Rich chat no Agent-Native {#rich-chat} -Quando você adiciona o shell de bate-papo integrado, a estrutura fornece cinco gerenciamentos -superfícies que você não precisa criar: **Chat** (a entrada principal), **Workspace** -(skills, memória, instruções, subagentes, servidores MCP conectados, agendados -trabalhos), **Histórico de trabalhos**, **Histórico de threads** e **Configurações**. Geralmente são -basta — converse com ele, veja o que ele faz, configure como ele se comporta. Alcance -[Chat](/docs/template-chat) quando estiver pronto para adicionar o navegador UI ou o -[Dispatch template](/docs/template-dispatch) para uma inicialização estilo espaço de trabalho -ponto com Slack/Telegram, trabalhos agendados e segredos compartilhados prontos para uso. +Use o chat integrado quando o usuário deve conversar com o agente, ver chamadas de ferramenta, aprovar trabalhos, inspecionar resultados nativos e manter um histórico de thread durável. -O menor caminho local é um andaime de agente sem cabeça mais uma ação: - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -Em seguida, defina a operação durável: - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -Uma ação pode ser chamada como: - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **Agente de aplicativo CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — de Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot e outros hosts MCP -- **A2A** — de outro aplicativo nativo do agente ou peer de agente -- **UI** — por meio de `useActionQuery`, `useActionMutation` ou `callAction` -- **Ferramenta de agente** — no loop de bate-papo integrado - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -Este não é um modo sem banco de dados ou sem estado. O loop app-agent armazena sessões, -threads, execuções, configurações, credenciais, estado do aplicativo e registros de compartilhamento em -SQL. O padrão de desenvolvimento local é SQLite; aplicativos headless hospedados devem usar um -banco de dados SQL persistente. - -Se você precisar de todo o loop do agente sem cabeça na pasta do projeto, use: - -```bash -pnpm agent "Summarize this week's forms." -``` - -Se outro aplicativo ou script precisar chamar todo o agente, use -`agentNative.invoke("analytics", "...")` ou `agent-native invoke` CLI. Isso -mantém o trabalho entre aplicativos no caminho A2A enquanto o trabalho local permanece em actions. - -Workers, jobs, integração webhooks e hosts personalizados podem conduzir o loop do agente -diretamente através do servidor API. Este é um nível inferior ao actions — você fornece -o mecanismo, o modelo, as mensagens, o actions e o coletor de eventos: - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -Para a maioria dos aplicativos, os prompts programados e a integração webhooks já chamam esse loop -para você. Alcance-o diretamente apenas ao criar um host headless personalizado, eval -executor ou superfície de orquestração do lado do servidor — consulte [Servidor — Agente de produção -handler](/docs/server#agent-handler) para obter a assinatura completa. - -### Executando em uma pasta {#folder-loop} - -Se seu objetivo é "executar um agente nesta pasta", comece com o app-agent -fazer um loop nessa pasta: criar o scaffold do aplicativo headless, adicionar actions/instructions, executar -`pnpm agent "..."`. Isso mantém o trabalho dentro da mesma ação/tempo de execução/estado -contrato que o aplicativo usará na produção. - -Os chicotes de codificação externos são uma superfície de produto separada para incorporar Claude -Código, Codex, Pi, Cursor, Mastra ou tempos de execução semelhantes dentro de um aplicativo Agent-Native. -Use-os ao criar um produto de agente de codificação, não como a forma padrão de fazer -iniciar um fluxo de trabalho nativo do agente local. - -### Acesso ao repositório na nuvem {#cloud-repo-access} - -Para aplicativos headless em nuvem que precisam de acesso ao repositório, use o conector GitHub -modelo plus token CRUD: listar repositórios, pesquisar arquivos, ler arquivos, criar ou -editar arquivos, excluir arquivos e revogar acesso por meio do escopo do provedor -credenciais. No desenvolvimento local, defina explicitamente o repositório de destino: - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -Não trate um clone de VM ou uma verificação de sandbox de longa duração como a nuvem primária -modelo de acesso ao repositório. Sandboxes ainda são importantes para execução isolada de código, mas -o acesso ao repositório deve ser explícito, autorizado, auditável e revogável -pela camada do conector. - -### Compartilhamento de sessões e execuções {#sharing-runs} - -Sessões e execuções headless são objetos duráveis. A partilha deve ser faseada: -leia/compartilhe links primeiro, para que os colegas de equipe possam inspecionar prompts e saídas higienizados -e status de execução; colaboração gravável com permissão posteriormente, continuando a execução, -aprovação de actions, edição de cronogramas ou alteração de configurações -verificações de acesso explícito. - -## Bate-papo rico em Agent-Native {#rich-chat} - -Use o chat integrado quando o usuário precisar falar com o agente, veja chamadas de ferramentas, -aprove trabalhos, inspecione resultados nativos e mantenha um histórico de conversas duradouro. - -Para um ponto de partida completo do aplicativo, use [Chat template](/docs/template-chat): +Para um ponto de partida de app completo, use o [template Chat](/docs/template-chat): ```bash npx @agent-native/core@latest create my-chat-app --template chat ``` -O chat de página inteira mais simples: +O chat de página completa mais simples: ```tsx import { AgentChatSurface } from "@agent-native/core/client/chat"; @@ -302,11 +108,7 @@ export default function ChatRoute() { } ``` -Quando um aplicativo tiver uma guia de bate-papo de página inteira e um `AgentSidebar`, use o mesmo -`storageKey` em ambas as superfícies, habilite `chatViewTransition` e instale o -ajudantes de transferência chat-home no layout. Links comuns no aplicativo fora do bate-papo -a página pode então transformar o bate-papo completo na barra lateral enquanto mantém o ativo -tópico: +Quando um app tem uma aba de chat de página completa e um `AgentSidebar`, use o mesmo `storageKey` em ambas as superfícies, habilite `chatViewTransition` e instale os helpers de handoff chat-home no layout. Links comuns de dentro da página de chat podem então transformar o chat completo em sidebar enquanto mantêm a thread ativa: ```tsx import { @@ -344,7 +146,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -O bate-papo incorporado mais simples com seu próprio Chrome: +O chat embarcado mais simples com seu próprio chrome: ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -354,51 +156,104 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -Actions pode retornar resultados de widget nativos explícitos para que a saída do chat não seja apenas -texto. Tabelas, gráficos e cartões de produtos digitados são renderizados como React primários -componentes no chat, sem iframes. Consulte [Native Interface de chat](/docs/native-chat-ui). +As actions podem retornar resultados de widgets nativos explícitos para que a saída do chat não seja apenas texto. Tabelas, gráficos e cards de produto tipados são renderizados como componentes React de primeira linha no chat, sem iframes. Veja [Native Chat UI](/docs/native-chat-ui). Quando o agente precisa de controles gerados arbitrários em vez de um widget React predefinido, use [Generative UI](/docs/generative-ui): ele renderiza UI Alpine/Tailwind em sandbox inline, pode ler o estado do app e o contexto de slot, e pode enviar valores selecionados de volta ao chat. -## Bate-papo avançado com seu agente {#byo-agent} +## UI inline nativa {#native-inline-ui} -Use este caminho quando seu agente já estiver construído com outra estrutura ou -tempo de execução e você deseja o bate-papo do Agent-Native UI em torno dele. `AgentChatRuntime` é o -limite: seu tempo de execução transmite eventos normalizados e Agent-Native renderiza o -compositor, transcrição, chamadas de ferramentas, aprovações, widgets nativos e layout do aplicativo. +Use isso quando suas actions retornam dados estruturados — uma lista de registros, um conjunto de dados de gráfico, um resumo de status — que devem ser renderizados como um componente de UI real dentro da thread do chat, em vez de uma descrição em texto simples. Você define um renderizador `chatUI` na action, e o Agent-Native o renderiza como um componente React de primeira linha: sem iframes, sem caminho de renderização separado. -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +Esta é a escolha certa quando a saída tem uma forma clara e reutilizável que você projetaria uma vez e usaria em muitas respostas do agente. Para controles que o agente precisa criar dinamicamente em tempo de execução, veja [UI inline gerada](#generated-inline-ui). -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +Veja [Native Chat UI](/docs/native-chat-ui) para a API completa de renderizador, biblioteca de widgets e integração de runtime BYO agent. -export function SupportAgentChat() { - return ; +## UI inline gerada {#generated-inline-ui} + +Use isso quando o agente precisa criar um controle que ainda não existe como widget pré-construído — um formulário personalizado, um picker construído em torno do contexto atual, uma calculadora de uso único. Diferentemente dos widgets nativos, a UI gerada é composta pelo agente em tempo de execução a partir de Alpine.js e Tailwind, roda em sandbox em um iframe e pode enviar valores selecionados de volta à thread do chat. + +A UI gerada pode ser transiente (renderizada uma vez e descartada) ou salva como uma extensão reutilizável que persiste para o usuário. + +Veja [Generative UI](/docs/generative-ui) para a API completa, restrições do sandbox e modelo de persistência de extensões. + +## Aplicação completa {#full-application} + +Use o caminho de app completo quando os usuários precisam de objetos e fluxos de trabalho duráveis: formulários, dashboards, calendários, caixas de entrada, editores, documentos, ativos ou relatórios. + +Apps completos adicionam UI de produto em torno do mesmo contrato de action e agente: + + + +### Estado SQL + +Dados do app, navegação, configurações e histórico de chat são todos duráveis. O agente lê e escreve as mesmas linhas que a UI faz. + +### Context awareness + +O agente conhece a rota atual, a seleção e o objeto em foco, então "editar isso" sempre significa a coisa certa. + +### Sincronização em tempo real + +As mudanças do agente atualizam a UI em tempo real, e as mudanças da UI atualizam o contexto do agente. Sem polling, sem atualização de página. + +### Deep links + +Os resultados de actions podem abrir a visualização correta do app diretamente: um gráfico linka para o dashboard, um rascunho linka para a caixa de entrada. + +### Widgets de chat nativos + +Tabelas, gráficos, cards, aprovações e resultados tipados são renderizados como componentes React de primeira linha inline no chat. + +### UI gerada e extensões + +O agente pode criar controles inline sob demanda e salvar mini-apps reutilizáveis quando um fluxo de trabalho precisa persistir. + + + +Comece pelo [template Chat](/docs/template-chat) quando quiser um app mínimo em torno de suas actions, ou por um [template](/docs/cloneable-saas) de domínio quando quiser uma forma de produto completa. + +### Gerenciar Agente em página completa {#agent-page} + +Todo app Agent-Native eventualmente precisa de um lugar onde os usuários possam configurar seu agente: definir instruções permanentes, revisar o que ele fez, conectar servidores MCP, gerenciar automações e controlar o acesso. Construir essa UI do zero dá muito trabalho. O Agent-Native inclui um componente pré-construído de página completa, `AgentTabsPage`, que cobre tudo isso em doze abas. + +Monte-o em `/agent` no seu app. Os templates atuais combinam essa rota com uma entrada de navegação do app e passam `agentPageHref="/agent"` para `AgentSidebar`, para que os modos Resources e Settings do sidebar possam linkar para a página completa sem duplicar esses fluxos. + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -Existem auxiliares de tempo de execução prontos para agentes OpenAI, respostas OpenAI e Claude -Agente SDK, Vercel AI SDK e AG-UI, além do tempo de execução HTTP normalizado acima -para qualquer outro agente (Mastra, Flue, Eve, LangGraph ou um serviço personalizado). ACP é -não é o bate-papo do aplicativo do usuário final ou o transporte A2A, e Agent-Native atualmente não -reivindicar suporte A2UI. ACP é compatível com um local específico: dirigindo um local -agente de codificação (Gemini CLI, Claude Code, …) através do -[harness layer](/docs/harness-agents#acp), não como o tempo de execução do chat aqui. +A página compartilhada atualmente fornece doze abas em dois grupos: + +| Grupo | Aba | Exibe | +| --------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | O `ResourcesPanel` existente para arquivos pessoais ou da organização | +| Resources | **Instructions** | Regras sempre ativas no estilo AGENTS.md | +| Resources | **Agents** | Perfis de sub-agentes personalizados | +| Resources | **Memory** | Notas de recall de longo prazo | +| Resources | **Skills** | Fluxos de trabalho reutilizáveis | +| Resources | **Learnings** | Correções e padrões capturados ao longo do tempo | +| Resources | **Remote agents** | Conexões A2A com outros apps agent-native (substitui o que a aba Connections costumava mostrar) | +| Agent | **Snapshots** | Uma prévia de escopo, orçamento de tokens, seções do sistema ordenadas agrupadas por proveniência/governança/fonte, e o snapshot mais recente da thread em tempo real. Renomeado de "Context"; links antigos com `#context` redirecionam aqui. | +| Agent | **Connections** | Gerenciamento de servidor MCP apenas | +| Agent | **Automations** | Automações pessoais e da organização Scheduled/Event com fluxos de pause/resume, detalhes e exclusão. A URL de compatibilidade estável permanece `/agent#jobs`. | +| Agent | **Settings** | Modelo do agente, chaves de API, limites, voz e configurações de automação | +| Agent | **Access** | A URL MCP do app, um card de agente A2A quando disponível, e guias de configuração compartilhados para Claude, ChatGPT, Cursor, Claude Code, Codex e outros clientes. Links para `/mcp/connect` para o fluxo de conexão completo e fallback de token. | -[Native Interface de chat — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -é o local canônico para os formatos de evento, os auxiliares de tempo de execução e `chatUI` -metadados de resultados da ferramenta. Comece por aí ao conectar um agente externo ao chat. +A página mostra apenas dados de escopo pessoal (`user`). Não há alternância de nível de organização atualmente. É uma camada fina sobre componentes e verificações de acesso existentes, não um novo console administrativo: Connections descreve o que o app pode chamar; Access descreve como clientes externos se conectam a ele. -## Carrinho lateral incorporado {#embedded-sidecar} +Ainda não incluído: -Use o arquivo secundário incorporado quando o produto principal já existir e você quiser um -agente ao lado. +- Visualização com escopo de organização +- Edição de concessões e escopos +- UI de revogação +- Histórico de proveniência por iteração -O plug-in do servidor monta rotas Agent-Native em seu aplicativo host e resolve -identidade do host no lado do servidor: +## Sidecar embarcado {#embedded-sidecar} + +Use o sidecar embarcado quando o produto principal já existe e você quer um agente ao lado dele. + +O plugin do servidor monta as rotas do Agent-Native no seu app host e resolve a identidade do host no lado do servidor: ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -410,7 +265,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -O sidecar React passa o contexto da página e comandos de host: +O sidecar React passa o contexto da página e os comandos do host: ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -432,7 +287,11 @@ export function AppShell({ children }) { } ``` - +### Como ele se conecta + +As duas partes funcionam como uma ponte: o app host passa o contexto da página (rota atual, texto selecionado, objeto em foco) para `AgentNativeEmbedded`, e o agente envia comandos de volta através de `onNavigate` e `onRefresh`. O plugin do servidor trata da identidade — ele resolve a sessão do host para que o agente atue como o usuário correto sem um login separado. Nada no app host precisa mudar; o plugin anexa as rotas do Agent-Native ao lado das suas rotas existentes. + + ```html
@@ -454,10 +313,10 @@ export function AppShell({ children }) {
AgentNativeEmbeddedagent + workspace + >agente + recursos
- rotas Agent-Native
mounted by the server pluginmontadas pelo plugin do servidor
@@ -491,45 +350,180 @@ export function AppShell({ children }) { -Consulte [Embedding SDK](/docs/embedding-sdk) para autenticação de host e isolamento de banco de dados -modo iframe/seletor e ponte de nível inferior APIs. +Veja [Embedding SDK](/docs/embedding-sdk) para autenticação do host, isolamento de banco de dados, modo iframe/picker e APIs de bridge de nível mais baixo. + +## App automação-primeiro {#headless} + +Use o caminho automação-primeiro quando ninguém precisa de uma tela de navegador personalizada enquanto o trabalho roda: jobs agendados, integrações, fluxos de trabalho de backend, loops de CLI, outro agente ou um produto existente chamando o Agent-Native. + +Esta é a forma a usar quando a automação é a superfície do produto. Você envia uma solicitação do terminal, Slack, e-mail, um job agendado, outro agente ou Chat ("resumir meus e-mails não lidos", "publicar as métricas diárias no Slack", "encontrar os candidatos que responderam na semana passada") e o agente age e retorna o resultado onde ele pertence. Ainda é um app real, não um prompt sem estado: actions, sessões de autenticação, estado do app, histórico de thread/run, configurações, credenciais e registros de compartilhamento vivem todos no SQL. + +Escolha este padrão quando: + +- **O trabalho acontece em background.** A maior parte do valor é criada enquanto o usuário não está olhando: agentes de triagem, agentes de relatório diário, respondentes de plantão. +- **A saída sai do app.** O agente publica no Slack, envia e-mail ou atualiza um sistema de terceiros; não há nada para navegar no app. +- **O domínio é de uso único.** Bot de pesquisa, gerador de resumo, redator de relatório sem objeto persistente que precise de uma visualização em lista. +- **Você está prototipando uma automação.** Publique a operação agora; adicione chat ou páginas de app quando os usuários precisarem inspecionar e guiar. + +Se o seu produto é construído em torno de objetos persistentes que os usuários navegam, pivotam e compartilham (e-mails, eventos, documentos, gráficos), escolha uma [aplicação completa](#full-application) ou um [template](/docs/cloneable-saas); esses adicionam uma UI completa _mais_ o agente. + +### O que vem na caixa {#in-the-box} + +Um app automação-primeiro pula o trabalho de dashboard e é agnóstico de canal desde o primeiro dia. O mesmo agente roda pela web, Slack, Telegram, e-mail e outros agentes porque tudo passa pelas mesmas actions. A contrapartida é que não há visualização "veja tudo de uma vez"; se os usuários precisarem disso, comece pelo [Chat](/docs/template-chat) ou adicione uma pequena página de status ou visualização em lista. + +Quando você adiciona o shell Chat integrado, o framework fornece cinco superfícies de gerenciamento que você não precisa construir: **Chat** (a entrada principal), **Resources** (skills, memória, instruções, sub-agentes e servidores MCP conectados), **Automations**, **Histórico de threads** e **Settings**. Geralmente isso é suficiente: fale com ele, veja o que ele fez, configure como ele se comporta. Use [Chat](/docs/template-chat) quando estiver pronto para adicionar essa UI de navegador, ou o [template Dispatch](/docs/template-dispatch) para um ponto de partida estilo workspace com Slack/Telegram, jobs agendados e segredos compartilhados prontos para uso. + +O menor caminho local sem navegador é um scaffold mais uma action: + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +Em seguida, defina a operação durável: + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +Uma action pode então ser chamada como: + +- **HTTP:** `POST /_agent-native/actions/summarize-week` +- **CLI:** `pnpm action summarize-week --formId form_123` +- **App-agent CLI:** `pnpm agent "Summarize form_123"` +- **MCP:** do Claude, ChatGPT, Codex, Cursor, OpenCode, Copilot e outros hosts MCP +- **A2A:** de outro app agent-native ou peer de agente +- **UI:** através de `useActionQuery`, `useActionMutation` ou `callAction` +- **Ferramenta do agente:** do loop de chat integrado + + + +Todo `defineAction` é auto-montado em `/_agent-native/actions/`. O corpo JSON é validado contra o schema zod da action antes de `run` ser executado. Para chamá-lo de um sistema externo com um bearer token de longa duração, veja [HTTP API](/docs/http-api). + + + +Este não é um modo sem banco de dados nem sem estado. O loop app-agent armazena sessões, threads, runs, configurações, credenciais, estado da aplicação e registros de compartilhamento no SQL. O desenvolvimento local usa SQLite por padrão; apps automação-primeiro hospedados devem usar um banco de dados SQL persistente. + +Se você precisar de todo o loop do agente de forma headless a partir da pasta do projeto, use: + +```bash +pnpm agent "Summarize this week's forms." +``` + +Se outro app ou script precisar chamar todo o agente, use `agentNative.invoke("analytics", "...")` ou o CLI `agent-native invoke`. Isso mantém o trabalho entre apps no caminho A2A enquanto o trabalho local permanece nas actions. + +Workers, jobs, webhooks de integração e hosts personalizados podem acionar o loop do agente diretamente através da API do servidor. Este é um nível mais baixo do que as actions — você fornece o engine, o modelo, as mensagens, as ferramentas, as actions, um sink de eventos e um sinal de abort: + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +Para a maioria dos apps, prompts agendados e webhooks de integração já chamam esse loop para você. Use-o diretamente apenas quando estiver construindo um host sem navegador personalizado, um executor de avaliação ou uma superfície de orquestração no lado do servidor. Veja [Servidor: Manipulador de agente de produção](/docs/server#agent-handler) para a assinatura completa. + +### Rodando contra uma pasta {#folder-loop} + +Se seu objetivo é "rodar um agente contra esta pasta", comece com o loop app-agent nessa pasta: faça o scaffold do app automação-primeiro, adicione actions/instruções, execute `pnpm agent "..."`. Isso mantém o trabalho dentro do mesmo contrato de action/runtime/estado que o app usará em produção. + +Harnesses de codificação externos são uma superfície de produto separada para embutir Claude Code, Codex, Pi, Cursor, Mastra ou runtimes similares dentro de um app Agent-Native. Use-os quando estiver construindo um produto de agente de codificação, não como a forma padrão de iniciar um fluxo de trabalho agent-native local. + +### Acesso a repositório na nuvem {#cloud-repo-access} + +Para apps automação-primeiro na nuvem que precisam de acesso a repositório, use o conector do GitHub mais o modelo CRUD de tokens: listar repositórios, pesquisar arquivos, ler arquivos, criar ou editar arquivos, deletar arquivos e revogar acesso através de credenciais com escopo por provedor. No desenvolvimento local, defina o repositório alvo explicitamente: + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +Não trate um clone de VM ou um checkout de sandbox de longa duração como o modelo primário de acesso a repositório na nuvem. Sandboxes ainda importam para execução de código isolada, mas o acesso a repositório deve ser explícito, com permissões, auditável e revogável através da camada de conector. + +### Compartilhando sessões e runs {#sharing-runs} + +Sessões e runs automação-primeiro são objetos duráveis. A possibilidade de compartilhamento deve ser faseada: links de leitura/compartilhamento primeiro, para que os colegas de equipe possam inspecionar prompts sanitizados, saídas e status de run; colaboração editável com permissão depois, para que continuar um run, aprovar actions, editar agendamentos ou alterar configurações passe por verificações de acesso explícitas. + +## Rich chat no seu agente {#byo-agent} + +Use este caminho quando seu agente já está construído com outro framework ou runtime e você quer a UI de chat do Agent-Native ao redor dele. `AgentChatRuntime` é a fronteira: seu runtime transmite eventos normalizados, e o Agent-Native renderiza o compositor, a transcrição, as chamadas de ferramenta, as aprovações, os widgets nativos e o layout do app. + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; + +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); + +export function SupportAgentChat() { + return ; +} +``` + +Existem helpers de runtime prontos para OpenAI Agents, OpenAI Responses, o Claude Agent SDK, o Vercel AI SDK e AG-UI, além do runtime HTTP normalizado acima para qualquer outro agente (Mastra, Flue, Eve, LangGraph ou um serviço personalizado). ACP não é o chat de app do usuário final nem o transporte A2A, e o Agent-Native não afirma suporte a A2UI atualmente. ACP é suportado em um lugar específico: acionando um agente de codificação local (Gemini CLI, Claude Code, ...) através da [camada de harness](/docs/harness-agents#acp), não como o runtime de chat aqui. + +[Native Chat UI: runtimes BYO agent](/docs/native-chat-ui#byo-agent-runtimes) é o local canônico para os formatos de evento, os helpers de runtime e os metadados de resultado de ferramenta `chatUI`. Comece por lá ao conectar um agente externo ao chat. + +## O que vem a seguir {#related-docs} + + + +### [Actions](/docs/actions) + +Defina a operação uma vez. Cada superfície acima chama a mesma. + +### [Native Chat UI](/docs/native-chat-ui) -## Aplicativo completo {#full-application} +Renderize resultados de actions tipados como tabelas, gráficos e cards diretamente no chat. -Use o caminho completo do aplicativo quando os usuários precisarem de objetos e fluxos de trabalho duráveis: formulários, -painéis, calendários, caixas de entrada, editores, documentos, ativos ou relatórios. +### [Generative UI](/docs/generative-ui) -Aplicativos completos adicionam o produto UI em torno da mesma ação e contrato de agente: +Gere UI sandboxed transiente ou persistida inline no chat. -- **Estado SQL** — dados do aplicativo, navegação, configurações e histórico de bate-papo são duráveis. -- **Reconhecimento de contexto** — o agente conhece a rota atual, a seleção e o objeto em foco. -- **Sincronização ao vivo** — as alterações do agente atualizam o UI e as alterações do UI atualizam o contexto do agente. -- **Links diretos** — os resultados da ação podem abrir a visualização correta do aplicativo. -- **Widgets de bate-papo nativos** — tabelas, gráficos, cartões, aprovações e resultados digitados aparecem inline. +### [Apps Automação-Primeiro](/docs/pure-agent-apps) -Comece pelo [Chat template](/docs/template-chat) quando quiser um aplicativo mínimo -em torno de seu actions ou de um domínio [template](/docs/cloneable-saas) quando você -quer um formato de produto completo. +O padrão completo sem navegador para jobs, filas, scripts e agentes externos. -## Como escolher {#how-to-choose} +### [Agentes Externos](/docs/external-agents) -| Se você está pensando... | Escolher | -| -------------------------------------------------------------------------- | --------------------------------- | -| "Só preciso de uma ferramenta ou fluxo de trabalho que possa ser chamado." | Agente sem cabeça | -| "Quero o agente do framework, mas o chat deve ser o principal UI." | Bate-papo rico em Agent-Native | -| "Já tenho um agente; preciso de um chat sofisticado UI para isso." | Bate-papo avançado com seu agente | -| "Já tenho um aplicativo SaaS; adicione um agente ao lado dele." | Carrinho lateral incorporado | -| "O agente e UI devem evoluir juntos como o produto." | Aplicativo completo | +Conecte hosts compatíveis com MCP ao seu app como um servidor de ferramentas. -Mantenha o contrato pequeno: defina operações duráveis como actions, retorne explícito -resultados de widget quando o bate-papo precisa de UI rico e adicionar telas inteiras somente quando os usuários -precisa navegar, comparar, configurar ou colaborar em objetos persistentes. +### [Protocolo A2A](/docs/a2a-protocol) -## Próximos passos {#related-docs} +Chame agentes de outros apps agent-native pelo padrão A2A. -- [**Actions**](/docs/actions) — defina a operação uma vez; todas as superfícies acima chamam a mesma operação -- [**Native Interface de chat**](/docs/native-chat-ui) — renderize resultados tipados como tabelas, gráficos e cartões no chat -- [**Generative UI**](/docs/generative-ui) — gere UI em sandbox, transitória ou persistida, diretamente no chat -- [**Automation-First Apps**](/docs/pure-agent-apps) — o padrão completo sem navegador para trabalhos, filas, scripts e agentes externos -- [**External Agents**](/docs/external-agents) — conecte hosts compatíveis com MCP a um aplicativo -- [**A2A Protocol**](/docs/a2a-protocol) — chame agentes de outros aplicativos Agent-Native + diff --git a/packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx b/packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx index eb2db6708a..db41c4e5f4 100644 --- a/packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx @@ -1,83 +1,43 @@ --- -title: "特工表面" -description: "将 Agent-Native 无头使用，作为丰富的聊天，在现有应用程序中，或作为完整的代理本机应用程序。" -search: "无头代理丰富聊天完整应用程序 BYO 代理运行时 AgentChatRuntime 嵌入 actions MCP A2A HTTP CLI" +title: "Agent 界面" +description: "选择智能应用的呈现方式：从聊天到内联 UI、持久化应用页面、嵌入式边栏、自动化以及外部 Agent 访问。" +search: "智能应用 富聊天 原生聊天 UI 完整应用 自动化 无头 BYO agent runtime AgentChatRuntime 嵌入 动作 MCP A2A HTTP CLI" --- -# 特工表面 +# Agent 界面 -## 完整的 Agent 工作区 {#agent-page} +**界面（surface）**是用户（或其他系统）与你的应用交互的方式：聊天窗口、仪表板页面、后台作业、来自另一个 Agent 的 API 调用。Agent-Native 让你可以自由组合这些方式，而无需重建核心逻辑，因为每个界面都运行相同的底层动作（actions）。如果你是 Agent-Native 的新用户，请先阅读[核心概念](/docs/key-concepts)。 -当完整应用需要一个持久位置来检查和配置代理时，请在 `/agent` 挂载 -`AgentTabsPage`。将此路由加入应用导航，并向 `AgentSidebar` 传入 -`agentPageHref="/agent"`，这样 Resources 和 Settings 模式就可以链接到完整 -页面，而不必重复这些流程。 +## 界面之间的关系 -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -共享页面目前提供五个选项卡： - -- **Context** — 显示范围预览、令牌预算、按来源/治理/来源引用分组的有序系统部分、列表/treemap 视图和最新实时线程快照。 -- **Files** — 为个人或组织资源重新托管现有的 `ResourcesPanel`。 -- **Connections** — MCP 服务器管理和 A2A 远程代理列表，即此应用的代理可以调用什么。 -- **Automations** — 支持暂停/恢复、详情和删除的个人与组织 Scheduled/Event 自动化。兼容 URL 仍为 `/agent#jobs`。 -- **Access** — MCP URL、可用时的 A2A 代理卡片以及共享客户端设置指南；完整连接流程和令牌回退位于 `/mcp/connect`。 +四种主要产品形态处于一个从最具交互性到完全无头的连续谱上。它们之所以可以自由组合，是因为基础始终保持不变：相同的动作、相同的 SQL 数据库以及相同的 Agent 循环为每种形态提供支持。添加新界面并不意味着重写底层逻辑——你只是在增加一种访问相同操作的新方式。 -该页面目前使用个人范围，不提供页面级 **Personal / Organization** 切换器。 -当底层操作支持时，选项卡可以显示自己的组织部分：**Automations** 显示 Scheduled -与 Event 的个人和组织部分。组织 Event 自动化始终以创建者身份运行。该页面只是对现有组件、操作和访问 -检查的薄封装，不是新的管理控制台。 - -Agent-Native 是故意可组合的。不用太多就可以使用代理UI， -在没有内置代理运行时的情况下使用 UI，或者将两者一起用作完整的 -应用程序。 - -有用的选择方法不是先按协议。选择产品表面 -你想要，然后使用匹配的原语。 - -| 表面 | 什么时候使用它 | 开始于 | -| ----------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **无头代理** | 代码、作业、脚本、另一个应用程序或另一个代理应直接调用该工作。 | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Agent-Native 上的丰富聊天** | 您想要由内置代理循环支持的独立或嵌入式聊天。 | [Chat template](/docs/template-chat), ``, `` | -| **与您的代理进行丰富的聊天** | 您在其他地方构建了代理，并想要 Agent-Native 的编写器、脚本、工具卡和本机小部件。 | `AgentChatRuntime`, `` | -| **嵌入式边车** | 您已经有一个 SaaS 应用程序，并希望在其旁边有一个具有页面上下文和主机命令的代理。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **完整应用程序** | 人类和代理应该共享持久的屏幕、数据、导航和协作。 | 模板、actions、SQL 状态、上下文感知 | - -这些是阶段，而不是单独的产品。工作流程可以以无头方式启动 -代理只需执行一个操作，就会以表格或图表的形式出现在聊天中，然后成为 -应用程序中的全屏，而不更改代理调用的操作。 - - + ```html
- Headlessactions、任务、脚本、其他代理 + 聊天输入框、对话记录、工具调用
- 丰富聊天输入框、转录、工具卡片 + 内联 UI表格、图表、卡片
- 嵌入式 sidecaragent beside an existing app + 应用页面持久化界面、SQL 数据
- 大部分 UI完整应用持久屏幕、数据、协作 + 无头自动化作业、脚本、外部 Agent
- 相同 actions · 相同 SQL · 相同代理循环 + 相同动作 · 相同 SQL · 相同 Agent 循环
``` @@ -110,174 +70,25 @@ Agent-Native 是故意可组合的。不用太多就可以使用代理UI， -## 无头代理 {#headless} - -当没有人需要盯着自定义应用屏幕时，请使用无头路径 -工作运行：计划作业、集成、后端工作流程、CLI 循环， -另一个代理或调用 Agent-Native 的现有产品。 - -这也是当**代理*是*产品**时要达到的形状 - -app-agent 循环是前门，而不是仪表板。您从 -终端、Slack、电子邮件、预定工作、其他代理或聊天 —“总结我的 -未读电子邮件，”“将每日指标发布到 Slack，”“查找符合以下条件的候选人 -上周回复”——代理执行操作并返回结果 -属于。它仍然是一个真正的应用程序，而不是无状态提示：actions，身份验证会话， -应用程序状态、线程/运行历史记录、设置、凭据和共享记录全部实时 -在SQL。 +## 选择起点 -在以下情况下选择此模式： - -- **工作在后台进行。**大部分价值是在用户不注意的时候创造的 - 分类代理、每日报告代理、待命响应人员。 -- **输出离开应用程序。**代理发布到 Slack、发送电子邮件或更新第三方系统；应用内没有任何内容可供浏览。 -- **该域是一次性的。**研究机器人、摘要生成器、报告编写器 - 没有需要列表视图的持久对象。 -- **您正在制作原型。**立即发送代理；如果用户想要的话，稍后添加更丰富的 UI。 +聊天是最常见的切入点。随着输出内容越来越丰富，应用通常会逐步添加内联 UI；当用户需要持久化对象来浏览和分享时，则进一步添加完整应用页面。同样的动作为后续的按钮、定时作业和外部 Agent 提供支持。如果你要在已有产品中添加 Agent，请使用嵌入式边栏；如果工作无需浏览器即可运行，则选择自动化优先模式。以下是完整概览： -如果您的产品是围绕持久对象构建的，用户会浏览、透视和 -分享 — 电子邮件、事件、文档、图表 — 选择 [full application](#full-application) -或 [template](/docs/cloneable-saas) 代替；这些添加了完整的 UI _plus_ 代理。 +| 界面 | 适用场景 | 起点 | +| ------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------- | +| **[富聊天](#rich-chat)** | 用户与 Agent 对话、查看工具调用并保留会话历史。 | [Chat template](/docs/template-chat), `` | +| **[原生内联 UI](#native-inline-ui)** | 动作结果应在聊天中以表格、图表、卡片或审批形式渲染。 | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[生成式内联 UI](#generated-inline-ui)** | Agent 应在聊天中动态创建临时或可复用的控件。 | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[完整应用](#full-application)** | 用户需要持久化界面、共享数据、导航和协作功能。 | Templates, actions, SQL state, context awareness | +| **[嵌入式边栏](#embedded-sidecar)** | 你已有一个 SaaS 应用，想在其旁边添加一个能感知页面上下文的 Agent。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[自动化优先](#headless)** | 作业、脚本或其他 Agent 直接调用工作，无需浏览器 UI。 | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[在你的 Agent 上使用富聊天](#byo-agent)** | 你在其他地方构建了 Agent，想用 Agent-Native 的聊天 UI 包裹它。 | `AgentChatRuntime`, `` | -### 盒子里装的是什么 {#in-the-box} +## Agent-Native 上的富聊天 {#rich-chat} -无头应用程序会跳过数周的仪表板工作，并且从一天开始就与渠道无关 -一个 - 同一代理从网络、Slack、Telegram、电子邮件和其他代理运行 -因为一切都通过代理，而不是 UI。权衡是有的 -没有“一目了然地浏览所有内容”视图；如果用户需要，请混合模式和 -添加小型状态页面或列表视图。 +当用户需要与 Agent 对话、查看工具调用、审批工作、查看原生结果，并保留持久化的会话历史时，请使用内置聊天功能。 -当添加内置的Chat shell时，框架提供了五种管理 -您不必构建的界面：**聊天**（主要输入）、**工作区** -（skills、内存、指令、子代理、连接的 MCP 服务器、已调度 -jobs）、**作业历史记录**、**线程历史记录**和**设置**。这些通常是 -足够了——与它交谈，看看它做了什么，配置它的行为方式。伸手去拿 -[Chat](/docs/template-chat) 当您准备好添加浏览器 UI 时，或 -[Dispatch template](/docs/template-dispatch) 工作空间式启动 -使用 Slack/Telegram、计划作业和开箱即用的共享机密。 - -最小的本地路径是无头代理脚手架加上一个操作： - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -然后定义持久操作： - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -然后可以调用一个操作： - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **应用程序代理 CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — 来自 Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot 和其他 MCP 主机 -- **A2A** - 来自另一个代理本机应用程序或代理对等点 -- **UI** — 通过 `useActionQuery`、`useActionMutation` 或 `callAction` -- **代理工具** - 来自内置聊天循环 - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. - - - -这不是无数据库或无状态模式。应用程序代理循环存储会话， -线程、运行、设置、凭据、应用程序状态和共享记录 -SQL。本地开发默认为SQLite；托管无头应用程序应使用 -持久 SQL 数据库。 - -如果您需要从项目文件夹中无头地执行整个代理循环，请使用： - -```bash -pnpm agent "Summarize this week's forms." -``` - -如果另一个应用程序或脚本需要调用整个代理，请使用 -`agentNative.invoke("analytics", "...")` 或 `agent-native invoke` CLI。那 -将跨应用工作保留在 A2A 路径上，而本地工作保留在 actions 上。 - -工作人员、作业、集成 webhooks 和自定义主机可以驱动代理循环 -直接通过服务器API。这比 actions 级别低 - 您提供 -您自己的引擎、模型、消息、actions 和事件接收器： - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -对于大多数应用程序，计划的提示和集成 webhooks 已经调用此循环 -给你。仅在构建自定义无头主机时直接获取它，eval -运行程序，或服务器端编排表面 - 请参阅[服务器 - 生产代理 -handler](/docs/server#agent-handler) 获取完整签名。 - -### 针对文件夹运行 {#folder-loop} - -如果您的目标是“针对此文件夹运行代理”，请从应用程序代理开始 -在该文件夹中循环：构建无头应用程序，添加 actions/指令，运行 -`pnpm agent "..."`。这使工作保持在相同的操作/运行时/状态内 -应用程序将在生产中使用的合同。 - -外部编码线束是用于嵌入 Claude 的独立产品表面 -Agent-Native 应用内的代码、Codex、Pi、Cursor、Mastra 或类似运行时。 -在构建编码代理产品时使用它们，而不是作为默认方式 -启动本地代理本机工作流程。 - -### 云存储库访问 {#cloud-repo-access} - -对于需要存储库访问的云无头应用程序，请使用 GitHub 连接器 -加上代币CRUD模型：列出存储库、搜索文件、读取文件、创建或 -通过提供商范围编辑文件、删除文件和撤销访问权限 -凭证。在本地开发中，明确设置目标存储库： - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -不要将虚拟机克隆或长期沙箱签出视为主要云 -存储库访问模型。沙箱对于隔离代码执行仍然很重要，但是 -存储库访问应该是明确的、经过许可的、可审核的和可撤销的 -通过连接器层。 - -### 共享会话和运行 {#sharing-runs} - -无头会话和运行是持久对象。共享性应该分阶段进行： -首先阅读/共享链接，以便队友可以检查经过清理的提示、输出 -和运行状态；稍后授予可写协作权限，因此继续运行， -批准 actions、编辑计划或更改配置已完成 -显式访问检查。 - -## Agent-Native 上的丰富聊天 {#rich-chat} - -当用户应该与代理交谈时使用内置聊天，查看工具调用， -批准工作、检查本机结果并保留持久的线程历史记录。 - -要获得完整的应用程序起点，请使用 [Chat template](/docs/template-chat)： +如需完整的应用起点，请使用 [Chat template](/docs/template-chat)： ```bash npx @agent-native/core@latest create my-chat-app --template chat @@ -293,11 +104,7 @@ export default function ChatRoute() { } ``` -当应用同时具有全页聊天选项卡和 `AgentSidebar` 时，请使用相同的 -在两个表面上安装`storageKey`，启用`chatViewTransition`，并安装 -布局中的聊天主页切换助手。聊天之外的普通应用内链接 -页面可以将完整的聊天内容转变为侧边栏，同时保持活动状态 -线程： +当应用同时包含全页聊天标签页和 `AgentSidebar` 时，请在两个界面上使用相同的 `storageKey`，启用 `chatViewTransition`，并在布局中安装 chat-home 切换助手。这样，聊天页面中的普通应用内链接就可以将全屏聊天变形为边栏，同时保持当前活跃的会话： ```tsx import { @@ -335,7 +142,7 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -使用您自己的 chrome 进行最简单的嵌入式聊天： +使用自定义外壳的最简嵌入式聊天： ```tsx import { AssistantChat } from "@agent-native/core/client/chat"; @@ -345,51 +152,104 @@ export function ProjectChat({ threadId }: { threadId: string }) { } ``` -Actions 可以返回显式的本机小部件结果，因此聊天输出不仅仅是 -文本。表格、图表和键入的产品卡呈现为第一方 React -聊天中的组件，没有 iframe。参见[Native 聊天界面](/docs/native-chat-ui)。 +动作可以返回明确的原生控件结果，使聊天输出不仅仅是文字。表格、图表和带类型的产品卡片以第一方 React 组件的形式在聊天中渲染，无需 iframe。详见 [Native Chat UI](/docs/native-chat-ui)。当 Agent 需要的是任意生成的控件而非预定义的 React 组件时，请使用 [Generative UI](/docs/generative-ui)：它在沙箱中内联渲染 Alpine/Tailwind UI，可以读取应用状态和插槽上下文，并将选中的值发回聊天。 -## 与您的代理进行丰富的聊天 {#byo-agent} +## 原生内联 UI {#native-inline-ui} -当您的代理已使用其他框架构建时，请使用此路径 -运行时，你想要 Agent-Native 的聊天 UI 围绕它。 `AgentChatRuntime` 是 -边界：您的运行时流规范化事件，Agent-Native 呈现 -作曲家、脚本、工具调用、批准、本机小部件和应用布局。 +当你的动作返回结构化数据——记录列表、图表数据集、状态摘要——且这些数据应在聊天会话中以真实 UI 组件而非纯文字描述的形式渲染时，请使用此功能。你在动作上定义一个 `chatUI` 渲染器，Agent-Native 会将其渲染为第一方 React 组件：无 iframe，无独立渲染路径。 -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +当输出具有清晰、可复用的形态，且你希望一次设计、在多个 Agent 响应中反复使用时，这是正确的选择。如果 Agent 需要在运行时动态创建控件，请参见[生成式内联 UI](#generated-inline-ui)。 -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +完整的渲染器 API、控件库以及 BYO agent runtime 集成，请参见 [Native Chat UI](/docs/native-chat-ui)。 -export function SupportAgentChat() { - return ; +## 生成式内联 UI {#generated-inline-ui} + +当 Agent 需要创建一个尚不存在于预构建控件中的控件时——自定义表单、基于当前上下文构建的选择器、一次性计算器——请使用此功能。与原生控件不同，生成式 UI 由 Agent 在运行时从 Alpine.js 和 Tailwind 组合而成，在 iframe 沙箱中运行，并可将选中的值发回聊天会话。 + +生成式 UI 可以是临时的（渲染一次后丢弃），也可以保存为对用户持久化的可复用扩展。 + +完整 API、沙箱约束和扩展持久化模型，请参见 [Generative UI](/docs/generative-ui)。 + +## 完整应用 {#full-application} + +当用户需要持久化对象和工作流时——表单、仪表板、日历、收件箱、编辑器、文档、资产或报告——请选择完整应用路径。 + +完整应用在相同的动作和 Agent 合约之上增加产品 UI： + + + +### SQL 状态 + +应用数据、导航、设置和聊天历史都是持久化的。Agent 读写与 UI 相同的数据行。 + +### 上下文感知 + +Agent 知道当前路由、选择项和焦点对象，因此"编辑这个"始终指向正确的内容。 + +### 实时同步 + +Agent 的变更实时更新 UI，UI 的变更同时更新 Agent 的上下文。无需轮询，无需刷新。 + +### 深度链接 + +动作结果可以直接打开对应的应用视图：图表链接到仪表板，草稿链接到收件箱。 + +### 原生聊天控件 + +表格、图表、卡片、审批和带类型的结果以第一方 React 组件的形式内联渲染在聊天中。 + +### 生成式 UI 与扩展 + +Agent 可以动态创建内联控件，并在工作流需要持久化时保存可复用的迷你应用。 + + + +当你想要围绕动作构建一个最简应用时，从 [Chat template](/docs/template-chat) 开始；当你想要一个完整的产品形态时，从某个领域[模板](/docs/cloneable-saas)开始。 + +### 全页 Manage Agent {#agent-page} + +每个 Agent-Native 应用最终都需要一个让用户配置其 Agent 的地方：设置常驻指令、查看已完成的工作、连接 MCP 服务器、管理自动化，以及控制访问权限。从头构建该 UI 工作量很大。Agent-Native 内置了一个预构建的全页组件 `AgentTabsPage`，涵盖了所有这些功能，分布在十二个标签页中。 + +在你的应用中将其挂载到 `/agent`。当前模板将该路由与应用导航条目配对，并向 `AgentSidebar` 传递 `agentPageHref="/agent"`，这样边栏的资源和设置模式就可以链接到全页，而无需重复这些流程。 + +```tsx filename="app/routes/agent.tsx" +import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; +export default function AgentRoute() { + return ; } ``` -针对 OpenAI 代理、OpenAI 响应、Claude 存在现成的运行时助手 -Agent SDK、Vercel AI SDK 和 AG-UI，以及上面的标准化 HTTP 运行时 -对于任何其他代理（Mastra、Flue、Eve、LangGraph 或自定义服务）。 ACP 是 -不是最终用户应用聊天或 A2A 传输，并且 Agent-Native 目前没有 -要求 A2UI 支持。 ACP 在一个特定位置受支持 - 驾驶本地 -编码代理（Gemini CLI，Claude代码，...）通过 -[harness layer](/docs/harness-agents#acp)，这里不作为聊天运行时。 +该共享页面目前提供分为两组的十二个标签页： + +| 分组 | 标签页 | 显示内容 | +| --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | 用于个人或组织文件的现有 `ResourcesPanel` | +| Resources | **Instructions** | 始终生效的 AGENTS.md 风格规则 | +| Resources | **Agents** | 自定义子 Agent 配置 | +| Resources | **Memory** | 长期记忆笔记 | +| Resources | **Skills** | 可复用的工作流 | +| Resources | **Learnings** | 随时间积累的修正和模式 | +| Resources | **Remote agents** | 到其他 agent-native 应用的 A2A 连接（替代原 Connections 标签页所显示的内容） | +| Agent | **Snapshots** | 范围预览、token 预算、按来源/治理/源分组排序的系统章节，以及最新的实时会话快照。由"Context"重命名而来；旧的 `#context` 链接将重定向至此。 | +| Agent | **Connections** | 仅限 MCP 服务器管理 | +| Agent | **Automations** | 个人和组织的定时/事件自动化，支持暂停/恢复、详情和删除流程。兼容 URL `/agent#jobs` 保持稳定。 | +| Agent | **Settings** | Agent 模型、API 密钥、限制、语音和自动化设置 | +| Agent | **Access** | 应用 MCP URL、可用时的 A2A agent card，以及适用于 Claude、ChatGPT、Cursor、Claude Code、Codex 等客户端的共享设置指南。链接到 `/mcp/connect` 以完成完整连接流程和令牌回退。 | + +该页面仅显示个人（`user` 范围）数据，目前没有组织级别的切换。它是现有组件和访问检查的薄层封装，而非新的管理控制台：Connections 描述应用可以调用什么；Access 描述外部客户端如何连接到它。 + +尚未包含的功能： -[Native 聊天界面 — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -是事件形状、运行时助手和 `chatUI` 的规范主页 -工具结果元数据。将外部代理连接到聊天中时从这里开始。 +- 组织范围视图 +- 授权和范围编辑 +- 撤销 UI +- 每次迭代的来源历史 -## 嵌入式边车 {#embedded-sidecar} +## 嵌入式边栏 {#embedded-sidecar} -当主产品已经存在并且您想要一个时，请使用嵌入式 sidecar -代理在旁边。 +当主产品已经存在，你想在其旁边添加一个 Agent 时，请使用嵌入式边栏。 -服务器插件将 Agent-Native 路由安装到您的主机应用程序中并解析 -主机身份服务器端： +服务端插件将 Agent-Native 路由挂载到你的宿主应用中，并在服务端解析宿主身份： ```ts import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; @@ -401,7 +261,7 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -React sidecar 传递页面上下文和主机命令： +React 边栏传递页面上下文和宿主命令： ```tsx import { AgentNativeEmbedded } from "@agent-native/core/client/host"; @@ -423,14 +283,18 @@ export function AppShell({ children }) { } ``` - +### 连接方式 + +两个部分作为桥接器协同工作：宿主应用将页面上下文（当前路由、选中文本、焦点对象）传入 `AgentNativeEmbedded`，Agent 则通过 `onNavigate` 和 `onRefresh` 将命令发送回去。服务端插件负责处理身份——它解析宿主会话，使 Agent 以正确的用户身份运行，无需单独登录。宿主应用无需任何改动；插件将 Agent-Native 的路由附加到你现有路由旁边。 + + ```html
宿主应用你现有的 SaaS
- getContext()
路由 · 选择 + getContext()
路由 · 选择项
onNavigate / onRefresh
宿主命令 @@ -442,10 +306,10 @@ export function AppShell({ children }) {
AgentNativeEmbeddedagent + workspace + >Agent + 资源
Agent-Native 路由
mounted by the server plugin由服务端插件挂载
@@ -479,45 +343,180 @@ export function AppShell({ children }) { -请参阅 [Embedding SDK](/docs/embedding-sdk) 以了解主机身份验证、数据库隔离， -iframe/picker 模式，以及较低级别的桥 APIs。 +宿主认证、数据库隔离、iframe/选择器模式和底层桥接 API，请参见 [Embedding SDK](/docs/embedding-sdk)。 + +## 自动化优先应用 {#headless} + +当工作运行期间无需自定义浏览器界面时，请选择自动化优先路径：定时作业、集成、后端工作流、CLI 循环、另一个 Agent，或者已有产品调用 Agent-Native。 + +这是当自动化本身就是产品界面时应选择的形态。你从终端、Slack、电子邮件、定时作业、另一个 Agent 或聊天（"总结我未读的邮件"、"将每日指标发布到 Slack"、"找出上周回复的候选人"）发送请求，Agent 执行后将结果返回到对应的地方。它仍然是一个真正的应用，而非无状态的提示词：动作、认证会话、应用状态、会话/运行历史、设置、凭证和共享记录都存储在 SQL 中。 + +在以下情况下选择此模式： + +- **工作在后台发生。** 大部分价值在用户不在线时创建：分类 Agent、日报 Agent、值班响应器。 +- **输出离开应用。** Agent 发布到 Slack、发送电子邮件或更新第三方系统；应用内没有可浏览的内容。 +- **领域是一次性的。** 研究机器人、摘要生成器、无需持久化对象和列表视图的报告撰写器。 +- **你在原型化一个自动化。** 现在发布操作；当用户需要检查和控制时再添加聊天或应用页面。 + +如果你的产品围绕用户浏览、切换和共享的持久化对象（电子邮件、事件、文档、图表）构建，请选择[完整应用](#full-application)或[模板](/docs/cloneable-saas)；这些方案在 Agent 之上还提供完整的 UI。 + +### 开箱即用的功能 {#in-the-box} + +自动化优先应用跳过了仪表板工作，并从第一天起就是渠道无关的。相同的 Agent 可以从 Web、Slack、Telegram、电子邮件和其他 Agent 运行，因为所有内容都通过相同的动作处理。权衡之处在于没有"一览全局"视图；如果用户需要这个，请从 [Chat](/docs/template-chat) 开始或添加一个小型状态页面或列表视图。 + +当你添加内置 Chat 壳层时，框架提供五个无需自己构建的管理界面：**Chat**（主要输入）、**Resources**（技能、记忆、指令、子 Agent 和已连接的 MCP 服务器）、**Automations**、**Thread history** 和 **Settings**。这些通常已经足够：与它对话、查看它做了什么、配置它的行为。当你准备好添加浏览器 UI 时，请使用 [Chat](/docs/template-chat)；或者使用 [Dispatch template](/docs/template-dispatch) 作为工作区风格的起点，开箱即用地支持 Slack/Telegram、定时作业和共享密钥。 + +最小的无浏览器本地路径是脚手架加上一个动作： + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +然后定义持久化操作： + +```ts filename="actions/summarize-week.ts" +import { defineAction } from "@agent-native/core/action"; +import { z } from "zod"; + +export default defineAction({ + description: "Summarize this week's submissions.", + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: "34 submissions, up 18% from last week." }; + }, +}); +``` + +一个动作随后可以通过以下方式调用： + +- **HTTP：** `POST /_agent-native/actions/summarize-week` +- **CLI：** `pnpm action summarize-week --formId form_123` +- **App-agent CLI：** `pnpm agent "Summarize form_123"` +- **MCP：** 来自 Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot 和其他 MCP 宿主 +- **A2A：** 来自另一个 agent-native 应用或 Agent 对等方 +- **UI：** 通过 `useActionQuery`、`useActionMutation` 或 `callAction` +- **Agent 工具：** 来自内置聊天循环 + + + +每个 `defineAction` 都自动挂载到 `/_agent-native/actions/`。JSON 请求体在 `run` 执行前会针对动作的 zod schema 进行校验。如需使用长期有效的 bearer token 从外部系统调用，请参见 [HTTP API](/docs/http-api)。 + + + +这不是无数据库或无状态模式。App-agent 循环将会话、线程、运行、设置、凭证、应用状态和共享记录存储在 SQL 中。本地开发默认使用 SQLite；托管的自动化优先应用应使用持久化 SQL 数据库。 + +如果你需要从项目文件夹无头运行整个 Agent 循环，请使用： + +```bash +pnpm agent "Summarize this week's forms." +``` + +如果另一个应用或脚本需要调用整个 Agent，请使用 `agentNative.invoke("analytics", "...")` 或 `agent-native invoke` CLI。这样可以将跨应用的工作保持在 A2A 路径上，而本地工作则保持在动作上。 + +Workers、作业、集成 webhooks 和自定义宿主可以通过服务端 API 直接驱动 Agent 循环。这比动作更底层——你需要自己提供引擎、模型、消息、工具、动作、事件接收器和中止信号： + +```ts +import { runAgentLoop } from "@agent-native/core/server"; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +对于大多数应用，定时提示词和集成 webhooks 已经会为你调用此循环。只有在构建自定义无浏览器宿主、评估运行器或服务端编排界面时才直接使用它。完整签名请参见 [Server: Production agent handler](/docs/server#agent-handler)。 + +### 针对文件夹运行 {#folder-loop} + +如果你的目标是"针对此文件夹运行一个 Agent"，请从该文件夹中的 app-agent 循环开始：搭建自动化优先应用，添加动作/指令，运行 `pnpm agent "..."`。这样可以将工作保持在应用在生产环境中使用的相同动作/运行时/状态合约内。 + +外部编码工具是一个独立的产品界面，用于在 Agent-Native 应用中嵌入 Claude Code、Codex、Pi、Cursor、Mastra 或类似运行时。当你在构建编码 Agent 产品时使用它们，而不是作为启动本地 agent-native 工作流的默认方式。 + +### 云端仓库访问 {#cloud-repo-access} + +对于需要仓库访问的云端自动化优先应用，请使用 GitHub 连接器加令牌 CRUD 模型：通过提供商范围的凭证列出仓库、搜索文件、读取文件、创建或编辑文件、删除文件以及撤销访问。在本地开发中，请明确设置目标仓库： + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." +``` + +不要将虚拟机克隆或长期存在的沙箱检出作为主要的云端仓库访问模型。沙箱在隔离代码执行方面仍然很重要，但仓库访问应该是明确的、有权限的、可审计的，并且可以通过连接器层撤销。 -## 完整应用程序 {#full-application} +### 共享会话和运行 {#sharing-runs} -当用户需要持久对象和工作流程时使用完整的应用路径：表单， -仪表板、日历、收件箱、编辑器、文档、资产或报告。 +自动化优先的会话和运行是持久化对象。共享能力应该分阶段实现：首先是只读/共享链接，让团队成员可以查看经过净化的提示词、输出和运行状态；之后是有权限的可写协作，使继续运行、审批动作、编辑计划或更改配置需要通过明确的访问检查。 -完整应用程序围绕相同的操作和代理合同添加产品 UI： +## 在你的 Agent 上使用富聊天 {#byo-agent} -- **SQL 状态** — 应用数据、导航、设置和聊天历史记录是持久的。 -- **上下文感知** - 代理知道当前路线、选择和聚焦对象。 -- **实时同步** - 代理更改会更新 UI，UI 更改会更新代理的上下文。 -- **深层链接** — 操作结果可以打开正确的应用视图。 -- **本机聊天小部件** — 表格、图表、卡片、批准和键入的结果内联显示。 +当你的 Agent 已经用其他框架或运行时构建好，并且你想用 Agent-Native 的聊天 UI 包裹它时，请选择此路径。`AgentChatRuntime` 是边界所在：你的运行时流式传输归一化的事件，Agent-Native 负责渲染输入框、对话记录、工具调用、审批、原生控件和应用布局。 -当您想要一个最小的应用程序时，请从 [Chat template](/docs/template-chat) 开始 -您的 actions 周围，或来自域 [template](/docs/cloneable-saas)，当您 -想要一个完整的产品形状。 +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from "@agent-native/core/client/chat"; -## 如何选择 {#how-to-choose} +const runtime = createHttpAgentChatRuntime({ + endpoint: "/api/support-agent/chat", +}); -| 如果您在想... | 选择 | -| ---------------------------------------------------- | ------------------------- | -| “我只需要一个可调用的工具或工作流程。” | 无头代理 | -| “我想要框架的代理，但是聊天应该是主要的UI。” | Agent-Native 上的丰富聊天 | -| “我已经有一个代理；我需要一个完美的聊天 UI。” | 与您的代理进行丰富的聊天 | -| “我已经有一个 SaaS 应用程序；在它旁边添加一个代理。” | 嵌入式边车 | -| “代理和 UI 应该作为产品一起进化。” | 完整应用程序 | +export function SupportAgentChat() { + return ; +} +``` -保持合约较小：将持久操作定义为 actions，显式返回 -聊天需要丰富UI时的小部件结果，并且仅在用户时添加全屏 -需要浏览、比较、配置或协作持久对象。 +现成的运行时助手适用于 OpenAI Agents、OpenAI Responses、Claude Agent SDK、Vercel AI SDK 和 AG-UI，以及上面用于任何其他 Agent（Mastra、Flue、Eve、LangGraph 或自定义服务）的归一化 HTTP 运行时。ACP 不是面向终端用户的应用聊天或 A2A 传输，Agent-Native 目前也不声称支持 A2UI。ACP 仅在一个特定场景中受支持：通过[工具层](/docs/harness-agents#acp)驱动本地编码 Agent（Gemini CLI、Claude Code 等），而非此处的聊天运行时。 + +[Native Chat UI: BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) 是事件形态、运行时助手和 `chatUI` 工具结果元数据的规范文档。将外部 Agent 接入聊天时请从那里开始。 ## 下一步 {#related-docs} -- [**Actions**](/docs/actions) — 只需定义一次操作；上述每个界面都会调用同一个操作 -- [**Native 聊天界面**](/docs/native-chat-ui) — 在聊天中将类型化的 action 结果呈现为表格、图表和卡片 -- [**Generative UI**](/docs/generative-ui) — 在聊天中生成临时或持久化的沙盒 UI -- [**Automation-First Apps**](/docs/pure-agent-apps) — 面向作业、队列、脚本和外部代理的完整无浏览器模式 -- [**External Agents**](/docs/external-agents) — 将 MCP 兼容主机连接到应用 -- [**A2A Protocol**](/docs/a2a-protocol) — 从其他 Agent-Native 应用调用代理 + + +### [动作（Actions）](/docs/actions) + +一次定义操作，以上所有界面都调用同一个。 + +### [原生聊天 UI（Native Chat UI）](/docs/native-chat-ui) + +在聊天中直接将带类型的动作结果渲染为表格、图表和卡片。 + +### [生成式 UI（Generative UI）](/docs/generative-ui) + +在聊天中内联生成临时或持久化的沙箱 UI。 + +### [自动化优先应用（Automation-First Apps）](/docs/pure-agent-apps) + +作业、队列、脚本和外部 Agent 的完整无浏览器模式。 + +### [外部 Agent（External Agents）](/docs/external-agents) + +将兼容 MCP 的宿主作为工具服务器连接到你的应用。 + +### [A2A 协议（A2A Protocol）](/docs/a2a-protocol) + +通过 A2A 标准从其他 agent-native 应用调用 Agent。 + + diff --git a/packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx b/packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx index 3224d6d07d..d25dafc31d 100644 --- a/packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx +++ b/packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx @@ -1,83 +1,43 @@ --- -title: "代理表面" -description: "將 Agent-Native 無頭使用，作為豐富的聊天，在現有應用程式中，或作為完整的 Agent-Native 應用程式。" -search: "無頭代理豐富聊天完整應用程式 BYO 代理執行時 AgentChatRuntime 嵌入 actions MCP A2A HTTP CLI" +title: "Agent 介面" +description: "選擇一個代理應用程式的成長方式：從對話到內嵌 UI、持久應用頁面、嵌入式側邊欄、自動化，以及外部代理存取。" +search: "代理應用程式 豐富對話 原生對話 UI 完整應用程式 自動化 headless BYO agent runtime AgentChatRuntime 嵌入 actions MCP A2A HTTP CLI" --- -# 代理表面 +# Agent 介面 -## 完整的 Agent 工作區 {#agent-page} +**介面（surface）**是使用者（或其他系統）與應用程式互動的方式：對話視窗、儀表板頁面、背景工作，或來自另一個代理的 API 呼叫。Agent-Native 讓你可以自由搭配這些介面，無需重建核心邏輯，因為每個介面都執行相同的底層 actions。如果你是 Agent-Native 的新手，請先閱讀[關鍵概念](/docs/key-concepts)。 -當完整應用程式需要一個持久位置來檢查和設定代理時，請在 `/agent` 掛載 -`AgentTabsPage`。將此路由加入應用程式導覽，並向 `AgentSidebar` 傳入 -`agentPageHref="/agent"`，這樣 Resources 和 Settings 模式就能連結到完整頁面， -而不必重複這些流程。 +## 介面之間的關係 -```tsx filename="app/routes/agent.tsx" -import { AgentTabsPage } from "@agent-native/core/client/agent-chat"; -export default function AgentRoute() { - return ; -} -``` - -共用頁面目前提供五個分頁： - -- **Context** — 顯示範圍預覽、權杖預算、按來源/治理/來源參照分組的有序系統區段、清單/treemap 檢視和最新即時執行緒快照。 -- **Files** — 為個人或組織資源重新託管現有的 `ResourcesPanel`。 -- **Connections** — MCP 伺服器管理和 A2A 遠端代理清單，也就是此應用程式的代理可以呼叫什麼。 -- **Automations** — 支援暫停/恢復、詳細資料和刪除的個人與組織 Scheduled/Event 自動化。相容 URL 仍為 `/agent#jobs`。 -- **Access** — MCP URL、可用時的 A2A 代理卡片以及共用用戶端設定指南；完整連線流程和權杖備援位於 `/mcp/connect`。 - -此頁面目前使用個人範圍，不提供頁面級 **Personal / Organization** 切換器。 -當底層動作支援時，分頁可以顯示自己的組織區段：**Automations** 顯示 Scheduled -與 Event 的個人和組織區段。組織 Event 自動化始終以建立者身分執行。此頁面只是對現有元件、動作和存取檢查 -的薄封裝，不是新的管理主控台。 +四種主要的產品形態位於一個從最互動到完全無介面的光譜上。使它們可組合的關鍵在於基礎始終保持不變：相同的 actions、相同的 SQL 資料庫，以及相同的代理循環驅動每一種形態。新增一個介面並不意味著要重寫底層的內容——你只是在新增一種觸及相同操作的方式。 -Agent-Native 是故意可組合的。不用太多就可以使用代理 UI， -在沒有內建代理執行時的情況下使用 UI，或者將兩者一起用作完整的 -應用程式。 - -有用的選取方法不是先按協議。選取產品表面 -你想要，然後使用匹配的原語。 - -| 表面 | 什麼時候使用它 | 開始於 | -| ----------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | -| **無頭代理** | 程式碼、作業、指令碼、另一個應用程式或另一個代理應直接呼叫該工作。 | `agent-native create --headless`, `defineAction`, `agent-native agent`, HTTP, CLI, MCP, A2A | -| **Agent-Native 上的豐富聊天** | 您想要由內建代理迴圈支援的獨立或嵌入式聊天。 | [Chat template](/docs/template-chat), ``, `` | -| **與您的代理進行豐富的聊天** | 您在其他地方建置了代理，並想要 Agent-Native 的編寫器、指令碼、工具卡和本機小工具。 | `AgentChatRuntime`, `` | -| **嵌入式邊車** | 您已經有一個 SaaS 應用程式，並希望在其旁邊有一個具有頁面脈絡和主機指令的代理。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | -| **完整應用程式** | 人類和代理應該共用持久的螢幕、資料、導覽和協作。 | 範本、actions、SQL 狀態、脈絡感知 | - -這些是階段，而不是單獨的產品。工作流程可以以無頭方式啟動 -代理只需執行一個操作，就會以表格或圖表的形式出現在聊天中，然後成為 -應用程式中的全螢幕，而不更改代理呼叫的操作。 - - + ```html -
-
- Headlessactions、工作、指令碼、其他代理 +
+
+ 對話撰寫器、對話紀錄、工具呼叫
- -
- 豐富聊天輸入框、轉錄、工具卡片 +
→
+
+ 內嵌 UI表格、圖表、卡片
- -
- 嵌入式 sidecaragent beside an existing app +
→
+
+ 應用頁面持久畫面、SQL 資料
- -
- 大部分 UI完整應用持久螢幕、資料、協作 +
→
+
+ headless自動化工作、腳本、外部代理
-
- 相同 actions · 相同 SQL · 相同代理迴圈 +
+ 相同 actions · 相同 SQL · 相同代理循環
``` @@ -110,194 +70,41 @@ Agent-Native 是故意可組合的。不用太多就可以使用代理 UI， -## 無頭代理 {#headless} - -當沒有人需要盯著自訂應用螢幕時，請使用無頭路徑 -工作執行：計畫作業、整合、後端工作流程、CLI 迴圈， -另一個代理或呼叫 Agent-Native 的現有產品。 - -這也是當**代理*是*產品**時要達到的形狀 - -app-agent 迴圈是前門，而不是儀表板。您從 -終端、Slack、電子郵件、預定工作、其他代理或聊天 —“總結我的 -未讀電子郵件，”“將每日指標發布到 Slack，”“尋找符合以下條件的候選項 -上週回覆”——代理執行操作並返回結果 -屬於。它仍然是一個真正的應用程式，而不是無狀態提示：actions，驗證工作階段， -應用程式狀態、對話串/執行歷史紀錄、設定、憑證和共用紀錄全部即時 -在 SQL。 - -在以下情況下選取此模式： - -- **工作在背景進行。**大部分價值是在使用者不注意的時候創造的 - 分類代理、每日報告代理、待命回應人員。 -- **輸出離開應用程式。**代理發布到 Slack、傳送電子郵件或更新第三方系統；應用內沒有任何內容可供瀏覽。 -- **該域是一次性的。**研究機器人、摘要生成器、報告編寫器 - 沒有需要清單檢視的持久物件。 -- **您正在製作原型。**立即傳送代理；如果使用者想要的話，稍後新增更豐富的 UI。 - -如果您的產品是圍繞持久物件建置的，使用者會瀏覽、透視和 -分享 — 電子郵件、事件、檔案、圖表 — 選取 [full application](#full-application) -或 [template](/docs/cloneable-saas) 代替；這些新增了完整的 UI _plus_ 代理。 - -### 盒子裡裝的是什麼 {#in-the-box} - -無頭應用程式會跳過數週的儀表板工作，並且從一天開始就與管道無關 -一個 - 同一代理從網路、Slack、Telegram、電子郵件和其他代理執行 -因為一切都透過代理，而不是 UI。權衡是有的 -沒有“一目了然地瀏覽所有內容”檢視；如果使用者需要，請混合模式和 -新增小型狀態頁面或清單檢視。 - -當新增內建的Chat shell時，框架提供了五種管理 -您不必建置的介面：**聊天**（主要輸入）、**工作區** -（skills、記憶、指令、子代理、連線的 MCP 伺服器、已調度 -jobs）、**作業歷史紀錄**、**對話串歷史紀錄**和**設定**。這些通常是 -足夠了——與它交談，看看它做了什麼，設定它的行為方式。伸手去拿 -[Chat](/docs/template-chat) 當您準備好新增瀏覽器 UI 時，或 -[Dispatch template](/docs/template-dispatch) 工作空間式啟動 -使用 Slack/Telegram、計畫作業和開箱即用的共用機密。 - -最小的本機路徑是無頭代理腳手架加上一個操作： - -```bash -npx @agent-native/core@latest create my-agent --headless -cd my-agent -pnpm install -``` - -然後定義持久操作： - -```ts filename="actions/summarize-week.ts" -import { defineAction } from "@agent-native/core/action"; -import { z } from "zod"; - -export default defineAction({ - description: "Summarize this week's submissions.", - readOnly: true, - schema: z.object({ formId: z.string() }), - run: async ({ formId }) => { - return { formId, summary: "34 submissions, up 18% from last week." }; - }, -}); -``` - -然後可以呼叫一個操作： - -- **HTTP** — `POST /_agent-native/actions/summarize-week` -- **CLI** — `pnpm action summarize-week --formId form_123` -- **應用程式代理 CLI** — `pnpm agent "Summarize form_123"` -- **MCP** — 來自 Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot 和其他 MCP 主機 -- **A2A** - 來自另一個 Agent-Native 應用程式或代理對等點 -- **UI** — 透過 `useActionQuery`、`useActionMutation` 或 `callAction` -- **代理工具** - 來自內建聊天迴圈 - - - -Every `defineAction` is auto-mounted at `/_agent-native/actions/`. The JSON body is validated against the action's zod schema before `run` executes. +## 選擇起點 - - -這不是無資料庫或無狀態模式。應用程式代理迴圈儲存工作階段， -對話串、執行、設定、憑證、應用程式狀態和共用紀錄 -SQL。本機開發預設為 SQLite；託管無頭應用程式應使用 -持久 SQL 資料庫。 - -如果您需要從專案資料夾中無頭地執行整個代理迴圈，請使用： - -```bash -pnpm agent "Summarize this week's forms." -``` - -如果另一個應用程式或指令碼需要呼叫整個代理，請使用 -`agentNative.invoke("analytics", "...")` 或 `agent-native invoke` CLI。那 -將跨應用工作保留在 A2A 路徑上，而本機工作保留在 actions 上。 - -工作人員、作業、整合 webhooks 和自訂主機可以驅動代理迴圈 -直接透過伺服器 API。這比 actions 層級低 - 您提供 -您自己的引擎、模型、訊息、actions 和事件接收器： - -```ts -import { runAgentLoop } from "@agent-native/core/server"; - -await runAgentLoop({ engine, model, systemPrompt, actions, messages, send }); -``` - -對於大多數應用程式，計畫的提示和整合 webhooks 已經呼叫此迴圈 -給你。僅在建置自訂無頭主機時直接取得它，eval -執行程式，或伺服器端編排表面 - 請參閱[伺服器 - 正式環境代理 -handler](/docs/server#agent-handler) 取得完整簽名。 +對話是最常見的切入點。隨著輸出內容愈來愈豐富，應用程式通常會加入內嵌 UI；當使用者需要可瀏覽和分享的持久物件時，再新增完整的應用頁面。相同的 actions 也能驅動之後加入的按鈕、排程工作和外部代理。如果你要在現有產品中加入代理，請使用嵌入式側邊欄；如果工作無需瀏覽器即可執行，請選擇自動化優先模式。以下是完整概覽： -### 針對資料夾執行 {#folder-loop} - -如果您的目標是“針對此資料夾執行代理”，請從應用程式代理開始 -在該資料夾中迴圈：建置無頭應用程式，新增 actions/指令，執行 -`pnpm agent "..."`。這使工作保持在相同的操作/執行時/狀態內 -應用程式將在正式環境中使用的合同。 +| 介面 | 適用時機 | 起點 | +| ------------------------------------------ | ---------------------------------------------------------- | --------------------------------------------------------------------- | +| **[豐富對話](#rich-chat)** | 使用者與代理對話、查看工具呼叫，並保留對話串歷史紀錄。 | [Chat template](/docs/template-chat), `` | +| **[原生內嵌 UI](#native-inline-ui)** | Action 結果應在對話中以表格、圖表、卡片或審核介面呈現。 | [Native Chat UI](/docs/native-chat-ui), `chatUI.renderer` | +| **[生成式內嵌 UI](#generated-inline-ui)** | 代理應在對話中即時建立臨時或可重複使用的控制項。 | [Generative UI](/docs/generative-ui), `render-inline-extension` | +| **[完整應用程式](#full-application)** | 使用者需要持久畫面、共享資料、導覽和協作功能。 | 範本、actions、SQL 狀態、context awareness | +| **[嵌入式側邊欄](#embedded-sidecar)** | 你已有 SaaS 應用程式，想在旁邊加入具有頁面情境感知的代理。 | `createAgentNativeEmbeddedPlugin()`, `AgentNativeEmbedded` | +| **[自動化優先](#headless)** | 工作、腳本或其他代理直接呼叫，無需瀏覽器 UI。 | `agent-native create --headless`, `defineAction`, HTTP, CLI, MCP, A2A | +| **[在你的代理上使用豐富對話](#byo-agent)** | 你已在別處建立代理，想用 Agent-Native 的對話 UI 包裝它。 | `AgentChatRuntime`, `` | -外部編碼線束是用於嵌入 Claude 的獨立產品表面 -Agent-Native 應用內的程式碼、Codex、Pi、Cursor、Mastra 或類似執行時。 -在建置編碼代理產品時使用它們，而不是作為預設方式 -啟動本機 Agent-Native 工作流程。 +## Agent-Native 上的豐富對話 {#rich-chat} -### 雲端儲存庫存取 {#cloud-repo-access} +當使用者需要與代理對話、查看工具呼叫、審核工作、檢視原生結果，並保留持久的對話串歷史紀錄時，請使用內建對話功能。 -對於需要儲存庫存取的雲端無頭應用程式，請使用 GitHub 連線器 -加上代幣CRUD模型：列出儲存庫、搜尋檔案、讀取檔案、建立或 -透過提供者範圍編輯檔案、刪除檔案和撤銷存取權限 -憑證。在本機開發中，明確設定目標儲存庫： - -```bash -GITHUB_REPOSITORY=owner/repo pnpm agent "Read README.md and suggest the next action." -``` - -不要將虛擬機克隆或長期沙箱簽出視為主要雲端 -儲存庫存取模型。沙箱對於隔離程式碼執行仍然很重要，但是 -儲存庫存取應該是明確的、經過授權的、可審核的和可撤銷的 -透過連線器層。 - -### 共用工作階段和執行 {#sharing-runs} - -無頭工作階段和執行是持久物件。共用性應該分階段進行： -首先閱讀/共用連結，以便隊友可以檢查經過清理的提示、輸出 -和執行狀態；稍後授予可寫協作權限，因此繼續執行， -核准 actions、編輯計畫或更改設定已完成 -顯式存取檢查。 - -## Agent-Native 上的豐富聊天 {#rich-chat} - -當使用者應該與代理交談時使用內建聊天，檢視工具呼叫， -核准工作、檢查本機結果並保留持久的對話串歷史紀錄。 - -要獲得完整的應用程式起點，請使用 [Chat template](/docs/template-chat)： +若要快速建立完整應用程式，請使用 [Chat template](/docs/template-chat)： ```bash npx @agent-native/core@latest create my-chat-app --template chat ``` -最簡單的全頁面聊天： +最簡單的全頁對話： ```tsx -import { AgentChatSurface } from "@agent-native/core/client/chat"; +import { AgentChatSurface } from “@agent-native/core/client/chat”; export default function ChatRoute() { - return ; + return ; } ``` -當應用同時具有全頁面聊天分頁和 `AgentSidebar` 時，請使用相同的 -在兩個表面上安裝`storageKey`，啟用`chatViewTransition`，並安裝 -布局中的聊天主頁面切換助手。聊天之外的普通應用內連結 -頁面可以將完整的聊天內容轉變為側邊欄，同時保持活動狀態 -對話串： +當應用程式同時有全頁對話分頁和 `AgentSidebar` 時，請在兩個介面上使用相同的 `storageKey`，啟用 `chatViewTransition`，並在佈局中安裝 chat-home 交接輔助程式。如此一來，從對話頁面發出的普通應用內連結，就能在保持當前對話串的情況下，將全頁對話轉變為側邊欄： ```tsx import { @@ -305,27 +112,27 @@ import { AgentSidebar, useAgentChatHomeHandoff, useAgentChatHomeHandoffLinks, -} from "@agent-native/core/client/chat"; -import { useLocation } from "react-router"; +} from “@agent-native/core/client/chat”; +import { useLocation } from “react-router”; function ChatRoute() { return ( - + ); } function AppLayout({ children }: { children: React.ReactNode }) { const location = useLocation(); const handoffActive = useAgentChatHomeHandoff({ - storageKey: "my-app", + storageKey: “my-app”, activePath: location.pathname, - enabled: location.pathname !== "/chat", + enabled: location.pathname !== “/chat”, }); - useAgentChatHomeHandoffLinks({ storageKey: "my-app", chatPath: "/chat" }); + useAgentChatHomeHandoffLinks({ storageKey: “my-app”, chatPath: “/chat” }); return ( @@ -335,64 +142,117 @@ function AppLayout({ children }: { children: React.ReactNode }) { } ``` -使用您自己的 chrome 進行最簡單的嵌入式聊天： +使用你自己的外框嵌入對話的最簡方式： ```tsx -import { AssistantChat } from "@agent-native/core/client/chat"; +import { AssistantChat } from “@agent-native/core/client/chat”; export function ProjectChat({ threadId }: { threadId: string }) { return ; } ``` -Actions 可以返回顯式的本機小工具結果，因此聊天輸出不僅僅是 -文字。表格、圖表和鍵入的產品卡呈現為第一方 React -聊天中的元件，沒有 iframe。參見[Native 聊天介面](/docs/native-chat-ui)。 +Actions 可以回傳明確的原生 widget 結果，讓對話輸出不僅限於文字。表格、圖表和類型化產品卡片會以第一方 React 元件的形式在對話中呈現，無需 iframe。詳見 [Native Chat UI](/docs/native-chat-ui)。當代理需要任意生成的控制項，而非預先定義的 React widget 時，請使用 [Generative UI](/docs/generative-ui)：它在對話中內嵌呈現沙盒化的 Alpine/Tailwind UI，可讀取應用程式狀態和 slot context，並能將選取的值回傳至對話。 -## 與您的代理進行豐富的聊天 {#byo-agent} +## 原生內嵌 UI {#native-inline-ui} -當您的代理已使用其他框架建置時，請使用此路徑 -執行時，你想要 Agent-Native 的聊天 UI 圍繞它。 `AgentChatRuntime` 是 -邊界：您的執行時流規範化事件，Agent-Native 呈現 -撰寫器、指令碼、工具呼叫、核准、本機小工具和應用布局。 +當你的 actions 回傳結構化資料——記錄清單、圖表資料集、狀態摘要——且這些資料應在對話串中呈現為真實的 UI 元件，而非純文字描述時，請使用此功能。你在 action 上定義 `chatUI` 渲染器，Agent-Native 會將其呈現為第一方 React 元件：沒有 iframe，沒有獨立的渲染路徑。 -```tsx -import { - AssistantChat, - createHttpAgentChatRuntime, -} from "@agent-native/core/client/chat"; +當輸出具有明確、可重複使用的形狀，且你只需設計一次就能跨多個代理回應使用時，這是正確的選擇。若代理需要在執行時動態建立控制項，請改用[生成式內嵌 UI](#generated-inline-ui)。 -const runtime = createHttpAgentChatRuntime({ - endpoint: "/api/support-agent/chat", -}); +完整的渲染器 API、widget 函式庫和 BYO agent runtime 整合，請參閱 [Native Chat UI](/docs/native-chat-ui)。 -export function SupportAgentChat() { - return ; +## 生成式內嵌 UI {#generated-inline-ui} + +當代理需要建立一個尚不存在於預建 widget 中的控制項時，請使用此功能——例如自訂表單、根據當前情境建立的選擇器，或一次性計算機。與原生 widget 不同，生成式 UI 由代理在執行時從 Alpine.js 和 Tailwind 組合而成，在 iframe 中沙盒化執行，並能將選取的值回傳至對話串。 + +生成式 UI 可以是暫時性的（渲染一次後捨棄），也可以儲存為為使用者持久化的可重複使用擴充功能。 + +完整 API、沙盒限制和擴充功能持久化模型，請參閱 [Generative UI](/docs/generative-ui)。 + +## 完整應用程式 {#full-application} + +當使用者需要持久物件和工作流程時，請選擇完整應用程式路徑：表單、儀表板、日曆、收件匣、編輯器、文件、資產或報告。 + +完整應用程式在相同的 action 和代理契約之上新增產品 UI： + + + +### SQL 狀態 + +應用程式資料、導覽、設定和對話歷史紀錄都是持久的。代理讀寫的資料列與 UI 相同。 + +### Context awareness + +代理知道當前路由、選取項目和焦點物件，因此「編輯此項目」永遠指向正確的內容。 + +### 即時同步 + +代理的變更會即時更新 UI，UI 的變更也會更新代理的情境。無需輪詢，無需重新整理。 + +### 深層連結 + +Action 結果可以直接開啟正確的應用程式檢視：圖表連結至儀表板，草稿連結至收件匣。 + +### 原生對話 widget + +表格、圖表、卡片、審核項目和類型化結果，在對話中以第一方 React 元件呈現。 + +### 生成式 UI 和擴充功能 + +代理可以即時建立內嵌控制項，並在工作流程需要持久化時儲存可重複使用的迷你應用程式。 + + + +如果你只想在 actions 周圍建立一個最小化應用程式，請從 [Chat template](/docs/template-chat) 開始；如果你想要完整的產品形態，請從領域[範本](/docs/cloneable-saas)開始。 + +### 全頁 Manage Agent {#agent-page} + +每個 Agent-Native 應用程式最終都需要一個讓使用者設定代理的地方：設定常駐指令、檢視已完成的工作、連接 MCP 伺服器、管理自動化，以及控制存取權限。從頭建立這個 UI 需要大量工作。Agent-Native 附帶一個預建的全頁元件 `AgentTabsPage`，涵蓋十二個分頁的所有功能。 + +在你的應用程式中將其掛載於 `/agent`。目前的範本會將該路由與應用程式導覽項目配對，並將 `agentPageHref="/agent"` 傳遞給 `AgentSidebar`，讓側邊欄的 Resources 和 Settings 模式可以連結至完整頁面，而不需要重複這些流程。 + +```tsx filename=”app/routes/agent.tsx” +import { AgentTabsPage } from “@agent-native/core/client/agent-chat”; +export default function AgentRoute() { + return ; } ``` -針對 OpenAI 代理、OpenAI 回應、Claude 存在現成的執行時助手 -Agent SDK、Vercel AI SDK 和 AG-UI，以及上面的標準化 HTTP 執行時 -對於任何其他代理（Mastra、Flue、Eve、LangGraph 或自訂服務）。 ACP 是 -不是最終使用者應用聊天或 A2A 傳輸，並且 Agent-Native 目前沒有 -要求 A2UI 支援。 ACP 在一個特定位置受支援 - 駕駛本機 -編碼代理（Gemini CLI，Claude 程式碼，...）透過 -[harness layer](/docs/harness-agents#acp)，這裡不作為聊天執行時。 +共享頁面目前提供兩個群組共十二個分頁： -[Native 聊天介面 — BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) -是事件形狀、執行時助手和 `chatUI` 的規範主頁面 -工具結果中繼資料。將外部代理連線到聊天中時從這裡開始。 +| 群組 | 分頁 | 顯示內容 | +| --------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Resources | **Files** | 用於個人或組織檔案的現有 `ResourcesPanel` | +| Resources | **Instructions** | 常駐的 AGENTS.md 樣式規則 | +| Resources | **Agents** | 自訂子代理設定檔 | +| Resources | **Memory** | 長期記憶筆記 | +| Resources | **Skills** | 可重複使用的工作流程 | +| Resources | **Learnings** | 隨時間累積的修正和模式 | +| Resources | **Remote agents** | 連接至其他 agent-native 應用程式的 A2A 連線（取代先前 Connections 分頁的顯示內容） | +| Agent | **Snapshots** | 範圍預覽、token 預算、依來源/治理/來源分組的有序系統區塊，以及最新的即時對話串快照。從「Context」更名；舊的 `#context` 連結會重新導向至此。 | +| Agent | **Connections** | 僅限 MCP 伺服器管理 | +| Agent | **Automations** | 個人和組織的排程/事件自動化，含暫停/恢復、詳細資訊和刪除流程。穩定的相容性 URL 仍為 `/agent#jobs`。 | +| Agent | **Settings** | 代理模型、API 金鑰、限制、語音和自動化設定 | +| Agent | **Access** | 應用程式 MCP URL、可用時的 A2A 代理卡，以及 Claude、ChatGPT、Cursor、Claude Code、Codex 和其他用戶端的共用設定指南。連結至 `/mcp/connect` 以進行完整連線流程和 token 備援。 | -## 嵌入式邊車 {#embedded-sidecar} +該頁面僅顯示個人（`user` 範圍）資料。目前沒有組織層級的切換。它是現有元件和存取控制的薄殼，而非新的管理主控台：Connections 描述應用程式可以呼叫的內容；Access 描述外部用戶端如何連接至它。 -當主產品已經存在並且您想要一個時，請使用嵌入式 sidecar -代理在旁邊。 +尚未包含： -伺服器外掛將 Agent-Native 路由安裝到您的主機應用程式中並解析 -主機身分伺服器端： +- 組織範圍檢視 +- 授予和範圍編輯 +- 撤銷 UI +- 每次迭代的來源歷史紀錄 + +## 嵌入式側邊欄 {#embedded-sidecar} + +當主要產品已存在，且你想在旁邊加入代理時，請使用嵌入式側邊欄。 + +伺服器插件將 Agent-Native 路由掛載到你的宿主應用程式中，並在伺服器端解析宿主身份： ```ts -import { createAgentNativeEmbeddedPlugin } from "@agent-native/core/server"; +import { createAgentNativeEmbeddedPlugin } from “@agent-native/core/server”; export default createAgentNativeEmbeddedPlugin({ databaseUrl: process.env.AGENT_NATIVE_DATABASE_URL, @@ -401,10 +261,10 @@ export default createAgentNativeEmbeddedPlugin({ }); ``` -React sidecar 傳遞頁面脈絡和主機指令： +React 側邊欄傳遞頁面情境和宿主命令： ```tsx -import { AgentNativeEmbedded } from "@agent-native/core/client/host"; +import { AgentNativeEmbedded } from “@agent-native/core/client/host”; export function AppShell({ children }) { return ( +### 連接方式 + +這兩個部分作為橋樑運作：宿主應用程式將頁面情境（當前路由、選取文字、焦點物件）傳入 `AgentNativeEmbedded`，代理則透過 `onNavigate` 和 `onRefresh` 回傳命令。伺服器插件處理身份驗證——它會解析宿主 session，讓代理以正確的使用者身份行動，無需單獨登入。宿主應用程式無需任何變更；插件會將 Agent-Native 的路由附加在現有路由旁。 + + ```html -
-
- 主機應用你現有的 SaaS -
- getContext()
路由 · 選取 +
+
+ 宿主應用程式你現有的 SaaS +
+ getContext()
路由 · 選取項目
-
- onNavigate / onRefresh
主機指令 +
+ onNavigate / onRefresh
宿主命令
-
- - +
+
→
+
←
-
- AgentNativeEmbeddedagent + workspace -
- Agent-Native 路由
mounted by the server plugin + AgentNativeEmbedded代理 + 資源 +
+ Agent-Native 路由
由伺服器插件掛載
@@ -479,45 +346,180 @@ export function AppShell({ children }) { -請參閱 [Embedding SDK](/docs/embedding-sdk) 以了解主機驗證、資料庫隔離， -iframe/picker 模式，以及較低階別的橋 APIs。 +宿主驗證、資料庫隔離、iframe/選擇器模式和較低層級的橋接 API，請參閱 [Embedding SDK](/docs/embedding-sdk)。 -## 完整應用程式 {#full-application} +## 自動化優先應用程式 {#headless} + +當沒有人需要在工作執行時使用自訂瀏覽器畫面時，請選擇自動化優先路徑：排程工作、整合、後端工作流程、CLI 迴圈、另一個代理，或現有產品呼叫 Agent-Native。 + +當自動化本身就是產品介面時，這是最適合的形態。你從終端機、Slack、電子郵件、排程工作、另一個代理或對話（「摘要我未讀的電子郵件」、「將每日指標發布到 Slack」、「找出上週回覆的候選人」）發送請求，代理會執行並將結果回傳至適當的地方。它仍然是一個真實的應用程式，而非無狀態的提示：actions、驗證 session、應用程式狀態、對話串/執行歷史紀錄、設定、憑證和分享記錄都儲存在 SQL 中。 + +以下情況請選擇此模式： + +- **工作在背景執行。** 大部分的價值是在使用者不在時創造的：分流代理、每日報告代理、值班應答代理。 +- **輸出離開應用程式。** 代理發文至 Slack、傳送電子郵件，或更新第三方系統；應用程式內沒有可瀏覽的內容。 +- **領域是一次性的。** 研究機器人、摘要生成器、報告撰寫工具，沒有需要列表檢視的持久物件。 +- **你正在製作自動化原型。** 現在先發布操作；當使用者需要檢視和調整時，再新增對話或應用頁面。 + +如果你的產品圍繞著使用者需要瀏覽、轉換和分享的持久物件（電子郵件、活動、文件、圖表），請選擇[完整應用程式](#full-application)或[範本](/docs/cloneable-saas)；那些會新增完整的 UI _加上_ 代理。 + +### 開箱即用的功能 {#in-the-box} + +自動化優先應用程式省去了儀表板的工作，且從第一天起就與頻道無關。相同的代理可從網頁、Slack、Telegram、電子郵件和其他代理執行，因為一切都透過相同的 actions 進行。取捨之處在於沒有「一覽全貌」的視圖；如果使用者需要這個，請從 [Chat](/docs/template-chat) 開始，或新增一個小型狀態頁面或列表檢視。 + +當你加入內建的 Chat 殼層時，框架提供五個你不需要自己建立的管理介面：**Chat**（主要輸入）、**Resources**（技能、記憶、指令、子代理和已連接的 MCP 伺服器）、**Automations**、**Thread history** 和 **Settings**。這些通常就已足夠：與它對話、查看它做了什麼、設定它的行為方式。當你準備好新增瀏覽器 UI 時，請選用 [Chat](/docs/template-chat)；或選用 [Dispatch template](/docs/template-dispatch) 作為一個附帶 Slack/Telegram、排程工作和共用密碼的工作區風格起點。 + +最小的無瀏覽器本地路徑是一個鷹架加上一個 action： + +```bash +npx @agent-native/core@latest create my-agent --headless +cd my-agent +pnpm install +``` + +然後定義持久操作： + +```ts filename=”actions/summarize-week.ts” +import { defineAction } from “@agent-native/core/action”; +import { z } from “zod”; + +export default defineAction({ + description: “Summarize this week's submissions.”, + readOnly: true, + schema: z.object({ formId: z.string() }), + run: async ({ formId }) => { + return { formId, summary: “34 submissions, up 18% from last week.” }; + }, +}); +``` + +一個 action 可以透過以下方式呼叫： + +- **HTTP：** `POST /_agent-native/actions/summarize-week` +- **CLI：** `pnpm action summarize-week --formId form_123` +- **App-agent CLI：** `pnpm agent "Summarize form_123"` +- **MCP：** 從 Claude、ChatGPT、Codex、Cursor、OpenCode、Copilot 和其他 MCP 宿主 +- **A2A：** 從另一個 agent-native 應用程式或代理對等方 +- **UI：** 透過 `useActionQuery`、`useActionMutation` 或 `callAction` +- **Agent tool：** 從內建的對話迴圈 + + + +每個 `defineAction` 都會自動掛載於 `/_agent-native/actions/`。JSON 主體在 `run` 執行前會根據 action 的 zod schema 進行驗證。若要從具有長效 bearer token 的外部系統呼叫它，請參閱 [HTTP API](/docs/http-api)。 + + + +這不是無資料庫或無狀態模式。App-agent 迴圈將 session、對話串、執行記錄、設定、憑證、應用程式狀態和分享記錄儲存在 SQL 中。本地開發預設使用 SQLite；託管的自動化優先應用程式應使用持久的 SQL 資料庫。 + +如果你需要從專案資料夾以無介面方式執行整個代理迴圈，請使用： + +```bash +pnpm agent “Summarize this week's forms.” +``` + +如果另一個應用程式或腳本需要呼叫整個代理，請使用 `agentNative.invoke("analytics", "...")` 或 `agent-native invoke` CLI。這樣可以讓跨應用程式的工作保持在 A2A 路徑上，而本地工作則保持在 actions 上。 + +Workers、工作、整合 webhook 和自訂宿主可以透過伺服器 API 直接驅動代理迴圈。這比 actions 更底層——你需要自行提供引擎、模型、訊息、工具、actions、事件接收器和中止訊號： + +```ts +import { runAgentLoop } from “@agent-native/core/server”; + +await runAgentLoop({ + engine, + model, + systemPrompt, + tools, + actions, + messages, + send, + signal, +}); +``` + +對大多數應用程式而言，排程提示和整合 webhook 已經會為你呼叫此迴圈。只有在建立自訂無瀏覽器宿主、評估執行器或伺服器端協調介面時，才需要直接使用它。完整簽名請參閱 [Server: Production agent handler](/docs/server#agent-handler)。 + +### 針對資料夾執行 {#folder-loop} + +如果你的目標是「針對此資料夾執行代理」，請從該資料夾中的 app-agent 迴圈開始：建立自動化優先應用程式的鷹架，新增 actions/指令，執行 `pnpm agent "..."`。這樣可以讓工作保持在應用程式在生產環境中使用的相同 action/runtime/state 契約內。 + +外部程式碼執行環境是另一種產品介面，用於在 Agent-Native 應用程式中嵌入 Claude Code、Codex、Pi、Cursor、Mastra 或類似的執行時環境。只有在你正在建立程式碼代理產品時才使用它們，而不是作為啟動本地 agent-native 工作流程的預設方式。 + +### 雲端存放庫存取 {#cloud-repo-access} + +對於需要存放庫存取的雲端自動化優先應用程式，請使用 GitHub 連接器加上 token CRUD 模型：透過提供者範圍的憑證列出存放庫、搜尋檔案、讀取檔案、建立或編輯檔案、刪除檔案，以及撤銷存取權限。在本地開發中，請明確設定目標存放庫： + +```bash +GITHUB_REPOSITORY=owner/repo pnpm agent “Read README.md and suggest the next action.” +``` + +不要將 VM 複製或長效沙盒 checkout 視為主要的雲端存放庫存取模型。沙盒在隔離程式碼執行方面仍然很重要，但存放庫存取應透過連接器層進行明確、有權限、可稽核且可撤銷的管理。 + +### 分享 session 和執行記錄 {#sharing-runs} + +自動化優先的 session 和執行記錄是持久物件。可分享性應分階段推進：先提供讀取/分享連結，讓隊友可以檢視已清理的提示、輸出和執行狀態；之後再提供有權限的可寫入協作，讓繼續執行、審核 actions、編輯排程或變更設定都需要通過明確的存取控制。 + +## 在你的代理上使用豐富對話 {#byo-agent} + +當你的代理已使用另一個框架或執行時環境建立，且你想用 Agent-Native 的對話 UI 包裝它時，請使用此路徑。`AgentChatRuntime` 是邊界：你的執行時環境串流標準化事件，Agent-Native 渲染撰寫器、對話紀錄、工具呼叫、審核、原生 widget 和應用程式佈局。 + +```tsx +import { + AssistantChat, + createHttpAgentChatRuntime, +} from “@agent-native/core/client/chat”; + +const runtime = createHttpAgentChatRuntime({ + endpoint: “/api/support-agent/chat”, +}); + +export function SupportAgentChat() { + return ; +} +``` + +現成的 runtime 輔助程式適用於 OpenAI Agents、OpenAI Responses、Claude Agent SDK、Vercel AI SDK 和 AG-UI，以及上述適用於任何其他代理（Mastra、Flue、Eve、LangGraph 或自訂服務）的標準化 HTTP runtime。ACP 不是終端使用者應用程式的對話或 A2A 傳輸，Agent-Native 目前也不聲稱支援 A2UI。ACP 僅在一個特定地方受到支援：透過 [harness 層](/docs/harness-agents#acp)驅動本地程式碼代理（Gemini CLI、Claude Code 等），而非作為此處的對話 runtime。 + +[Native Chat UI: BYO agent runtimes](/docs/native-chat-ui#byo-agent-runtimes) 是事件形狀、runtime 輔助程式和 `chatUI` 工具結果元資料的標準說明文件。在將外部代理連接至對話時，請從那裡開始。 + +## 後續步驟 {#related-docs} + + + +### [Actions](/docs/actions) + +一次定義操作，上述所有介面都呼叫相同的操作。 + +### [Native Chat UI](/docs/native-chat-ui) + +將類型化的 action 結果直接在對話中呈現為表格、圖表和卡片。 -當使用者需要持久物件和工作流程時使用完整的應用路徑：表單， -儀表板、行事曆、收件箱、編輯器、檔案、資產或報告。 +### [Generative UI](/docs/generative-ui) -完整應用程式圍繞相同的操作和代理合同新增產品 UI： +在對話中內嵌生成臨時或持久化的沙盒 UI。 -- **SQL 狀態** — 應用資料、導覽、設定和聊天歷史紀錄是持久的。 -- **脈絡感知** - 代理知道目前路由、選取和聚焦物件。 -- **即時同步** - 代理更改會更新 UI，UI 更改會更新代理的脈絡。 -- **深層連結** — 操作結果可以開啟正確的應用檢視。 -- **本機聊天小工具** — 表格、圖表、卡片、核准和鍵入的結果行內顯示。 +### [Automation-First Apps](/docs/pure-agent-apps) -當您想要一個最小的應用程式時，請從 [Chat template](/docs/template-chat) 開始 -您的 actions 週圍，或來自域 [template](/docs/cloneable-saas)，當您 -想要一個完整的產品形狀。 +適用於工作、佇列、腳本和外部代理的完整無瀏覽器模式。 -## 如何選取 {#how-to-choose} +### [External Agents](/docs/external-agents) -| 如果您在想... | 選取 | -| ---------------------------------------------------- | ------------------------- | -| “我只需要一個可呼叫的工具或工作流程。” | 無頭代理 | -| “我想要框架的代理，但是聊天應該是主要的 UI。” | Agent-Native 上的豐富聊天 | -| “我已經有一個代理；我需要一個完美的聊天 UI。” | 與您的代理進行豐富的聊天 | -| “我已經有一個 SaaS 應用程式；在它旁邊新增一個代理。” | 嵌入式邊車 | -| “代理和 UI 應該作為產品一起進化。” | 完整應用程式 | +將相容 MCP 的宿主連接至你的應用程式作為工具伺服器。 -保持合約較小：將持久操作定義為 actions，顯式返回 -聊天需要豐富 UI 時的小工具結果，並且僅在使用者時新增全螢幕 -需要瀏覽、比較、設定或協作持久物件。 +### [A2A Protocol](/docs/a2a-protocol) -## 下一步 {#related-docs} +透過 A2A 標準從其他 agent-native 應用程式呼叫代理。 -- [**Actions**](/docs/actions) — 只需定義一次操作；上述每個介面都會呼叫同一個操作 -- [**Native 聊天介面**](/docs/native-chat-ui) — 在聊天中將型別化的 action 結果呈現為表格、圖表和卡片 -- [**Generative UI**](/docs/generative-ui) — 在聊天中產生暫時或持久化的沙盒 UI -- [**Automation-First Apps**](/docs/pure-agent-apps) — 面向作業、佇列、指令碼和外部代理的完整無瀏覽器模式 -- [**External Agents**](/docs/external-agents) — 將 MCP 相容主機連線到應用 -- [**A2A Protocol**](/docs/a2a-protocol) — 從其他 Agent-Native 應用呼叫代理 + diff --git a/scripts/i18n-localized-docs-baseline.txt b/scripts/i18n-localized-docs-baseline.txt index 98fb285e15..b19514fc7b 100644 --- a/scripts/i18n-localized-docs-baseline.txt +++ b/scripts/i18n-localized-docs-baseline.txt @@ -1,11 +1,6 @@ # Existing localized docs strings that still match English source. # Keep this file sorted. Remove entries as translated docs improve. # Format: relative/localized/path.md|English source string -packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|A2A Protocol -packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|Automation-First Apps -packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|External Agents -packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|Generative UI -packages/core/docs/content/locales/ar-SA/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/ar-SA/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/ar-SA/frames.mdx|type: \"code\" packages/core/docs/content/locales/ar-SA/messaging.mdx|Microsoft Teams @@ -20,10 +15,11 @@ packages/core/docs/content/locales/ar-SA/toolkit-capability-packages.mdx|Creativ packages/core/docs/content/locales/ar-SA/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/ar-SA/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. packages/core/docs/content/locales/ar-SA/what-is-agent-native.mdx|Agent Surfaces -packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|A2A Protocol -packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|Automation-First Apps -packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|Agent-Native routes packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|Native Chat UI +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|route · selection +packages/core/docs/content/locales/de-DE/agent-surfaces.mdx|same actions · same SQL · same agent loop packages/core/docs/content/locales/de-DE/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/de-DE/frames.mdx|type: \"code\" packages/core/docs/content/locales/de-DE/messaging.mdx|Microsoft Teams @@ -36,10 +32,8 @@ packages/core/docs/content/locales/de-DE/template-forms.mdx|"add an NPS question packages/core/docs/content/locales/de-DE/template-slides.mdx|"10-slide pitch deck" packages/core/docs/content/locales/de-DE/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/de-DE/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. -packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|A2A Protocol -packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|Automation-First Apps -packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|External Agents packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/es-ES/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/es-ES/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/es-ES/frames.mdx|type: \"code\" packages/core/docs/content/locales/es-ES/messaging.mdx|Microsoft Teams @@ -53,10 +47,8 @@ packages/core/docs/content/locales/es-ES/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/es-ES/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/es-ES/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/es-ES/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. -packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|A2A Protocol -packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|Automation-First Apps -packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|External Agents packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/fr-FR/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/fr-FR/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/fr-FR/frames.mdx|type: \"code\" packages/core/docs/content/locales/fr-FR/messaging.mdx|Microsoft Teams @@ -72,9 +64,24 @@ packages/core/docs/content/locales/fr-FR/toolkit-context-knowledge.mdx|Context X packages/core/docs/content/locales/fr-FR/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. packages/core/docs/content/locales/fr-FR/what-is-agent-native.mdx|Agent Surfaces packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|A2A Protocol +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Agent-Native routes packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Calling an action over HTTP +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Context awareness +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Deep links packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|External Agents packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Generative UI and extensions +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|How the sidecar bridges to a host app +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Invoke any action by name over HTTP +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Live sync +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Native Chat UI +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|Native chat widgets +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|One action surface, four product shapes, each adding UI without changing the operation underneath. +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|SQL state +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|The surface spectrum +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|route · selection +packages/core/docs/content/locales/hi-IN/agent-surfaces.mdx|same actions · same SQL · same agent loop packages/core/docs/content/locales/hi-IN/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/hi-IN/frames.mdx|type: \"code\" packages/core/docs/content/locales/hi-IN/messaging.mdx|Microsoft Teams @@ -98,10 +105,8 @@ packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|Team-wide rule packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|Tool surface packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|Typed contract packages/core/docs/content/locales/hi-IN/what-is-agent-native.mdx|`/slash` commands -packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|A2A Protocol -packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|Automation-First Apps -packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|External Agents packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/ja-JP/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/ja-JP/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/ja-JP/frames.mdx|type: \"code\" packages/core/docs/content/locales/ja-JP/messaging.mdx|Microsoft Teams @@ -115,11 +120,8 @@ packages/core/docs/content/locales/ja-JP/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/ja-JP/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/ja-JP/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/ja-JP/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. -packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|A2A Protocol -packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|Automation-First Apps -packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|External Agents packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|Generative UI -packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|SQL state +packages/core/docs/content/locales/ko-KR/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/ko-KR/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/ko-KR/frames.mdx|type: \"code\" packages/core/docs/content/locales/ko-KR/messaging.mdx|Microsoft Teams @@ -134,10 +136,10 @@ packages/core/docs/content/locales/ko-KR/template-slides.mdx|"10-slide pitch dec packages/core/docs/content/locales/ko-KR/toolkit-capability-packages.mdx|Creative Context packages/core/docs/content/locales/ko-KR/toolkit-context-knowledge.mdx|Context X-Ray packages/core/docs/content/locales/ko-KR/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. -packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|A2A Protocol -packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|Automation-First Apps -packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|External Agents +packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|Context awareness +packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|Deep links packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/pt-BR/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/pt-BR/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/pt-BR/frames.mdx|type: \"code\" packages/core/docs/content/locales/pt-BR/messaging.mdx|Microsoft Teams @@ -155,6 +157,8 @@ packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|A2A Protocol packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|Automation-First Apps packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|External Agents packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|Native Chat UI +packages/core/docs/content/locales/zh-CN/agent-surfaces.mdx|SQL state packages/core/docs/content/locales/zh-CN/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/zh-CN/frames.mdx|type: \"code\" packages/core/docs/content/locales/zh-CN/messaging.mdx|Microsoft Teams @@ -170,8 +174,10 @@ packages/core/docs/content/locales/zh-CN/toolkit-context-knowledge.mdx|Context X packages/core/docs/content/locales/zh-CN/using-your-agent.mdx|**Shared awareness is two-way.** You and the agent both read and write `application_state`, so "reply to this" or "summarize the selection" just works — and when the agent navigates, the real UI moves with it. packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|A2A Protocol packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|Automation-First Apps +packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|Context awareness packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|External Agents packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|Generative UI +packages/core/docs/content/locales/zh-TW/agent-surfaces.mdx|Native Chat UI packages/core/docs/content/locales/zh-TW/dispatch.mdx|"summarize last week's signups" packages/core/docs/content/locales/zh-TW/frames.mdx|type: \"code\" packages/core/docs/content/locales/zh-TW/messaging.mdx|Microsoft Teams diff --git a/scripts/template-standard-baseline.json b/scripts/template-standard-baseline.json index 830e971c6d..193de586c6 100644 --- a/scripts/template-standard-baseline.json +++ b/scripts/template-standard-baseline.json @@ -11,26 +11,6 @@ "template": "clips", "note": "Extended the shared scaffold (and reworded its header) with real app-specific learnings. Same reasoning as analytics — intentional customization, not a gap to silently overwrite." }, - { - "rule": "byte-sync:learnings-defaults:missing", - "template": "content", - "note": "Never got the starter learnings.defaults.md scaffold. Add via `pnpm sync:template-standard` once this entry is removed." - }, - { - "rule": "byte-sync:learnings-defaults:missing", - "template": "forms", - "note": "Never got the starter learnings.defaults.md scaffold. Add via `pnpm sync:template-standard` once this entry is removed." - }, - { - "rule": "byte-sync:learnings-defaults:missing", - "template": "macros", - "note": "Never got the starter learnings.defaults.md scaffold. Add via `pnpm sync:template-standard` once this entry is removed." - }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "analytics", - "note": "Has a working .gitignore but no _gitignore, so scaffolding a new app from this template won't get the canonical ignore rules re-applied. Add via `pnpm sync:template-standard` once this entry is removed." - }, { "rule": "byte-sync:gitignore-source:mismatch", "template": "assets", @@ -41,21 +21,11 @@ "template": "brain", "note": "Existing _gitignore predates the canonical shape (different section ordering/entries). Needs reconciliation in Phase 2/3." }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "calendar", - "note": "Has a working .gitignore but no _gitignore. Add via `pnpm sync:template-standard` once this entry is removed." - }, { "rule": "byte-sync:gitignore-source:mismatch", "template": "chat", "note": "Existing _gitignore adds .generated/ and data/*.db* on top of the shared base. Needs reconciliation in Phase 2/3." }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "content", - "note": "Has a working .gitignore but no _gitignore. Add via `pnpm sync:template-standard` once this entry is removed." - }, { "rule": "byte-sync:gitignore-source:mismatch", "template": "crm", @@ -71,40 +41,10 @@ "template": "dispatch", "note": "Existing _gitignore adds .generated/ and data/*.db* on top of the shared base. Needs reconciliation in Phase 2/3." }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "forms", - "note": "Has a working .gitignore but no _gitignore. Add via `pnpm sync:template-standard` once this entry is removed." - }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "macros", - "note": "Has a working .gitignore but no _gitignore. Add via `pnpm sync:template-standard` once this entry is removed." - }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "mail", - "note": "Has a working .gitignore but no _gitignore — this is the template the canonical learnings.defaults.md scaffold is sourced from, but it never got a _gitignore of its own. Add via `pnpm sync:template-standard` once this entry is removed." - }, { "rule": "byte-sync:gitignore-source:mismatch", "template": "plan", "note": "Existing _gitignore adds .generated/ and data/*.db* on top of the shared base. Needs reconciliation in Phase 2/3." - }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "slides", - "note": "Has a working .gitignore but no _gitignore. Add via `pnpm sync:template-standard` once this entry is removed." - }, - { - "rule": "byte-sync:gitignore-source:missing", - "template": "tasks", - "note": "Has a working .gitignore but no _gitignore. Add via `pnpm sync:template-standard` once this entry is removed." - }, - { - "rule": "agents-md-placeholder", - "template": "chat", - "note": "AGENTS.md still starts with the unrendered `{{APP_NAME}}` scaffold placeholder from template generation; needs the real title substituted in Phase 2." } ] } From eb50b8b56106abd3cf4183236671553fa2771888 Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Wed, 5 Aug 2026 11:34:40 -0700 Subject: [PATCH 4/5] docs: document POSTGRES_DB, POSTGRES_HOST_AUTH_METHOD, S2573_PGLITE_INSTALL_PREFIX in env inventory --- docs/environment-variables.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/environment-variables.md b/docs/environment-variables.md index f3c46cbfcb..0d3adc2087 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -228,6 +228,15 @@ application configuration. The secrets and vars used by those workflows are listed in the workflow files under `.github/workflows`; values must be supplied through GitHub Actions secrets/variables, never committed to this repository. +The following variables are set by the CI workflow for service containers and +integration tests only — they are not used in application runtime code: + +| Variable | Purpose | +| ----------------------------- | ---------------------------------------------------------------------------------------------------- | +| `POSTGRES_DB` | Database name for the PostgreSQL service container used in CI integration tests. | +| `POSTGRES_HOST_AUTH_METHOD` | PostgreSQL host-based authentication method for the CI service container (e.g. `trust`). | +| `S2573_PGLITE_INSTALL_PREFIX` | Override for the PGlite native binary install prefix used by the content-database lock CI test. | + ## Dynamic environment keys Some framework paths intentionally read `process.env[key]` after a key has been From 4f7466e828bbc3ddff6b727deaebb3fb22801aeb Mon Sep 17 00:00:00 2001 From: Kapunahele Wong Date: Wed, 5 Aug 2026 11:42:29 -0700 Subject: [PATCH 5/5] docs: document POSTGRES_DB, POSTGRES_HOST_AUTH_METHOD, S2573_PGLITE_INSTALL_PREFIX in env inventory --- docs/environment-variables.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/environment-variables.md b/docs/environment-variables.md index 0d3adc2087..42c990654c 100644 --- a/docs/environment-variables.md +++ b/docs/environment-variables.md @@ -231,11 +231,11 @@ through GitHub Actions secrets/variables, never committed to this repository. The following variables are set by the CI workflow for service containers and integration tests only — they are not used in application runtime code: -| Variable | Purpose | -| ----------------------------- | ---------------------------------------------------------------------------------------------------- | -| `POSTGRES_DB` | Database name for the PostgreSQL service container used in CI integration tests. | -| `POSTGRES_HOST_AUTH_METHOD` | PostgreSQL host-based authentication method for the CI service container (e.g. `trust`). | -| `S2573_PGLITE_INSTALL_PREFIX` | Override for the PGlite native binary install prefix used by the content-database lock CI test. | +| Variable | Purpose | +| ----------------------------- | ----------------------------------------------------------------------------------------------- | +| `POSTGRES_DB` | Database name for the PostgreSQL service container used in CI integration tests. | +| `POSTGRES_HOST_AUTH_METHOD` | PostgreSQL host-based authentication method for the CI service container (e.g. `trust`). | +| `S2573_PGLITE_INSTALL_PREFIX` | Override for the PGlite native binary install prefix used by the content-database lock CI test. | ## Dynamic environment keys