@nuxtagentic/agents

Agents

Saved agents run through CloudConfig's provider harness. “Test agent” runs the saved version with JSON input and displays progress, approval waits and output. Runs are scoped to the authenticated owner, active workspace, agent and session.

Agent code never names a platform. server/cloudconfig/agents.ts default-exports defineAgentHost(...), built from agentRunHost; server code opens runs and schedules through useCloudConfigAgents(event) or getAgentPlatform(env). CloudConfig's Nuxt module creates the platform's agent from the host: the official Cloudflare Agents SDK with SQLite checkpoints in Cloudflare builds, and an in-memory runner with the local CLI adapters in development.

Deployment declarations live in the host application's cloud.config.ts: deploy.agents names the host entry, and deploy.workflows exports the automation runner. Use cloudconfig deploy to reconcile their bindings and migrations. OpenAI uses NUXT_OPENAI_API_KEY; configure NUXT_ANTHROPIC_API_KEY or NUXT_GOOGLE_AI_API_KEY for those providers. Optional keys are pushed when supplied locally. Secrets never enter saved definitions or the browser.

@nuxtagentic/agents provides the Agents collection and Markdown editor. The framework-independent definitions, ownership rules, validation, frontmatter and provider tool schemas belong to @cloudconfig/core/agents in CloudConfig.

Agents is a core feature, always available in every workspace. It has no install or remove controls in the Modules catalog.

Open Agents in the workspace navigation, or type agents in the hero prompt. Create agent: Release notes writer creates a named draft agent. New agent inserts a draft record right away and opens it; edit its instructions, choose a runtime and model, and add tool declarations. Edits autosave after an 800 ms pause. ⌘/Ctrl Enter saves immediately. Leaving the editor saves pending edits first; failed saves keep your changes available to retry. Search and selection live in the URL; open /dashboard/agents or link directly with /dashboard/agents?agent=<id>. Older query-based links redirect to these URLs.

In local development at localhost, the runtime picker lists Codex CLI and Claude Code when they are installed on the server's PATH (including ~/.local/bin). Install the CLI and sign in using codex login or claude auth login. Model choices come from the installed runtime's catalog; Runtime default uses the CLI default. Runtime and model have separate inline menus. Search the model list by name or ID, or enter a custom ID. Claude discovery follows Open Run: it includes models with effort support alongside the latest model in each family, and falls back to the opus, sonnet and haiku aliases. Catalogs are read once per installed CLI version (or Codex models cache) and reused by every editor in the session; opening a menu refreshes them after a minute.

Local runtime and model choices are saved separately from the production API provider and model. The cloud button opens that API configuration when using a local runtime. Deployed hosts always execute through OpenAI, Anthropic, or Google APIs; they never attempt to spawn a local process. Configure the selected server key: NUXT_AGENTS_OPENAI_API_KEY, NUXT_AGENTS_ANTHROPIC_API_KEY, or NUXT_AGENTS_GOOGLE_AI_API_KEY. Existing NUXT_OPENAI_API_KEY, NUXT_ANTHROPIC_API_KEY, NUXT_GOOGLE_AI_API_KEY and Automations key overrides continue to work. Add your chosen key to deploy.secrets before deploying with CloudConfig. API model lists are fetched from the provider account, cached for an hour and refreshed in the background; saved and custom IDs remain editable if discovery is unavailable.

@cloudconfig/core/agents owns the runtime fields, validation and Markdown frontmatter alongside the existing agent contract. This package supplies the UI, catalog discovery and local execution adapters. Both execution paths use the module's native handlers and granted integration handlers; the CLI's own tools are disabled.

The visual editor and Markdown source edit the same definition. Source shows the settings as YAML frontmatter: runtime, model, status, tool choice and the names of enabled tools. The toolbar and Tools drawer stay available in both views and update the frontmatter as you change them. Tool declarations are edited in the drawer; frontmatter with complete JSON tool declarations is still accepted. The tools drawer supports enabling tools, auto/required/none choice, parameters, and copying schemas for OpenAI Responses, Anthropic and Google. Connected integration tools appear as suggestions at the bottom of the drawer.

Create agents through MCP

The module exports registerAgentMcpTools from @nuxtagentic/agents/mcp. It supplies agent_tools, agents_list, agents_get, agents_create, and agents_update for a process-local MCP server. Creation accepts Markdown instructions, runtime/model settings, and exact granted tool names. New agents include web_fetch; saved schemas come from the authoritative tool catalog. All writes use the typed CloudConfig client and existing ownership and validation.

The shared Kit package supplies nuxt-agentic-mcp and the portable Codex/Claude Code plugin. The Agents module contributes its own tools, so an Agents-only installation does not require Automations.

Read the public web

The Agents package includes Web fetch (web_fetch) with no additional account, API key, or integration setup. New agents created in the workspace have it enabled. Existing agents can add web_fetch from the Tools drawer. It works with API providers, local Codex and Claude runtimes, and automations.

Give the agent an instruction such as “Read the configured documentation page and summarize its contents with a link to the source.” The tool accepts url and optional maxCharacters (1–50,000; default 20,000). It returns the final URL, title, description, readable text, ordered links, image URLs with alt text, and a truncation flag.

Web fetch reads public HTTPS documents on port 443. Requests have a 20-second deadline, a 2 MB response limit, and at most five redirects; each redirect is validated. Local, private, reserved, and credential-bearing addresses are rejected. Node connections use the validated DNS answers directly. No cookies or login credentials are forwarded, and page JavaScript is not executed.

Server code can use the same installed handler:

import { fetchWebPage } from '@nuxtagentic/agents/runtime/server/utils/web-fetch'
import { createDefaultAgentDefinition } from '@nuxtagentic/agents/runtime/shared/native-tools'

const page = await fetchWebPage({ url: 'https://example.com/guide', maxCharacters: 8000 })
const definition = createDefaultAgentDefinition('Documentation assistant')

To add Agents to another host, install its local packages and register @nuxtagentic/agents in Nuxt. It remains available outside the optional catalog. Include agentsModels from its schema export in cloud.config.ts, then generate and apply a migration. The host uses generated CloudConfig CRUD and the typed SDK; no custom agent CRUD routes or database tables are needed.

Active marks a definition ready for automatic execution. Use Automations to run it from events and webhooks, or use a test run while the definition is still a draft. Configure its provider key on the server. Connect accounts in Integrations, then pick an integration tool suggestion in the Tools drawer to attach granted runtime handlers. Custom tool declarations need a handler before execution. The existing @nuxtagentic/prompt package continues to own workspace prompt planning and reviewed mutations.

Deployment verification runs pnpm build followed by pnpm test:worker. The Worker test loads the complete production bundle with its real D1 migrations, authentication, Nuxt SSR, Agent and AutomationRunner exports. Provider responses are mocked, so verification does not call a paid model API. pnpm test:agents also checks durable execution and the generated deployment wrapper, while pnpm test:automations checks approvals, retries and integration permissions.

The production build uses a bounded Node heap and exposes garbage collection. Default code verification is pnpm typecheck; build and runtime verification require an explicit request.