AI

Cosmic offers a suite of features in the dashboard powered by AI to help you build your Cosmic projects faster.

AI Studio

Content Model Generation

The AI Studio generates complete content structures from natural language descriptions. Instead of manually configuring fields, relationships, and validation rules, you can describe what you need and receive a fully functional content model with multiple content types, relationships, and demo content to get started fast.

Content model capabilities:

• Generate content models for any type of website or application
• Add new content types that integrate with existing structures
• Configure relationships between content types automatically
• Create complex multi-language structures with custom validation

Working examples:

• "Create a content model for an e-commerce store with products, collections, and customer reviews"
• "Add an Events content model that relates to my existing blog posts and authors"
• "Set up a portfolio website with projects, skills, and testimonials"

Content Management

Beyond structure creation, the AI handles content generation and management at scale.

Content operations:

• Generate realistic sample content for testing and development
• Bulk update existing content with new fields and metadata
• Maintain consistency across large content datasets
• Apply SEO optimization and structured data automatically

Practical applications:

• "Create 10 sample blog posts with realistic content for my existing blog model"
• "Update all product entries to include pricing and availability status"

Application Development and Deployment

AI-Powered Code Generation

The Cosmic AI Platform generates production-ready applications using your existing content structure. Applications are built with modern frameworks and include proper TypeScript definitions, responsive design, and performance optimizations.

Supported frameworks:

• Next.js applications with server-side rendering
• React dashboards and single-page applications
• Astro static sites with modern tooling
• Vue.js progressive web applications

AI assisted development

Click the "AI chat" button in the top right corner of the Cosmic dashboard to open the AI chat drawer. Use AI chat to learn how to integrate your content into your apps. Available for the admin and developer role.

Get insights from media

Click the "AI chat" button on any media asset to get summaries and insights from PDFs, spreadsheets, documents, and more. Available for all roles.

Generate alt text

To generate alt text for an image, go to any image, find the alt text area, and click the "Generate" button. You can also generate alt text for a group of images at once. Available for all roles.

Generate images

To generate images, open the Media modal, click the "Create" button, and describe the image you want to generate. Available for all roles.

Generate videos

Create compelling video content using natural language, powered by Google's Veo 3.1 models. Available for all roles.

Prompt: "Cinematic close-up of raindrops falling on a window at night, city lights blurred in background"

Key features:

• Native audio generation - Videos include automatically generated audio that matches your scene
• Two quality tiers - Fast (30-90s) or Standard (60-180s, premium cinematic quality)
• Flexible options - Generate 4, 6, or 8-second videos at 720p or 1080p
• Image-to-video mode - Use a reference image as the starting frame for precise control
• Video extension - Extend any Veo-generated video to create longer sequences

How to use:

1. Navigate to Media in your project
2. Click "Create" and select "Video Generation"
3. Choose "Veo 3.1 Fast" or "Veo 3.1 Standard"
4. Enter your video prompt
5. (Optional) Add a reference image for image-to-video mode
6. Choose duration and resolution, then click "Generate"

Videos are automatically saved to your Media Library with global CDN delivery. See the AI API documentation for programmatic access.

Generate audio

Convert any text to natural-sounding speech using OpenAI's text-to-speech models. Perfect for creating audio versions of articles, podcast intros, product descriptions, and more. Available for all roles.

Key features:

• 9 natural-sounding voices - Feminine (nova, shimmer, coral, sage, alloy) and masculine (echo, onyx, fable, ash)
• Two quality tiers - Standard (fast, low-latency) or HD (higher quality, 2x cost)
• Long text support - Texts over 4,096 characters are automatically chunked and concatenated
• Instant media library - Generated audio is saved as MP3 and available via CDN

How to use:

1. Navigate to Media in your project
2. Click "Create" and select "Audio"
3. Select a voice from the dropdown (default: Nova)
4. Paste or type the text you want to convert to speech
5. Click "Generate" to create the audio file

Audio files are automatically saved to your Media Library in MP3 format. See the AI API documentation for programmatic access.

Auto translate content with AI

You can use Cosmic AI to auto translate content from one language to another. Available for all roles.

Content generation

You can use Cosmic AI to generate content for your projects. Create summaries, SEO optimized content, translations, and more. Available for all roles.

Agents

AI Agents are autonomous assistants that work on tasks independently. Agents help you automate content management, application development, and browser-based workflows. For recurring or scheduled execution, use Workflows to run agents on a schedule.

Access Requirements: AI Agents are available to users with Admin or Developer bucket roles only. Editor and Contributor roles do not have access to these features.

Agent Types

Cosmic provides four specialized agent types, each designed for specific automation tasks:

Team Agent

The Team Agent joins your communication channels as a fully conversational AI team member. Define a persona with a custom name, role, and personality. Set measurable goals and let the agent communicate with your team on Slack, WhatsApp, Telegram, and more. Team Agents can read and write CMS content, build and deploy applications, and manage connected GitHub repositories, all while carrying on natural conversations.

Capabilities:

• Multi-channel presence on Slack, WhatsApp, Telegram, API, Webhook, and Email
• Persona-driven conversations with custom name and personality
• Measurable goal tracking aligned with business objectives
• Scheduled heartbeats for proactive check-ins (Mon-Fri, daily, etc.)
• Lead qualification and customer support automation
• CMS read and write access for content-aware responses
• Code read and write access for connected GitHub repositories
• Runtime log analysis to diagnose production errors and create fixes
• Build and deploy full web applications from a conversation

Example prompts:

• "You are Lisa, our CMO. You are strategic, data-driven, and creative. Ask clarifying questions about target audience and goals before proposing campaigns."
• "You are Sam, our Customer Success Manager. Be warm and empathetic. Help customers get the most value from our product. Escalate bugs to engineering."

Content Agent

The Content Agent works directly with your Cosmic CMS to create, update, and manage content at scale. It understands your existing content structure, researches topics via progressive web discovery, and generates perfectly formatted objects that match your schema.

Capabilities:

• Generate blog posts, landing pages, and product catalogs
• Create and modify object types with custom metafields
• Progressive web discovery for research-backed content
• Batch operations for bulk content creation
• Auto-publish or human review workflow
• Email notifications on task completion

Example prompts:

• "Research the latest AI trends from Hacker News and TechCrunch, then create a 5-part blog series covering each major development"
• "Create a complete product catalog for our new summer collection with 20 products, descriptions, and pricing"

Code Agent

The Code Agent connects to your GitHub repository and writes production-ready code autonomously. It discovers relevant files, understands your codebase structure, creates feature branches, commits changes, and opens pull requests.

Capabilities:

• Progressive file discovery to understand codebases
• Automatic branch creation and PR submission
• Conflict detection and auto-resolution
• Multi-iteration development with checkpoints
• CMS integration for content-aware features
• Email notifications with commit summaries

Example prompts:

• "Build a user notification system with real-time updates, API endpoints, and React components with TypeScript"
• "Create a dynamic landing page that pulls content from our Cosmic CMS with hero section, feature grid, and testimonials"

Computer Use Agent

The Computer Use Agent sees and controls browsers exactly like a human. It can fill out forms, record demo videos, download and upload media across platforms, and automate any workflow you can do manually.

Capabilities:

• Professional demo video recording with animated cursors
• Cross-platform media transfer and downloads
• AI-powered content extraction from web pages
• Visual navigation with stealth mode
• Screenshot and file operations
• Authenticated browser sessions with Saved Authentications

Pre-Authentication:

Computer Use Agents can start with pre-authenticated browser sessions, so they can access protected sites without manual login. Manage reusable credentials in your Account settings > Saved Authentications, then select one or more from the agent's Pre-Authentication section. Saved Authentications persist across runs and can be shared between agents and workflows.

Execution Limits:

• Each Computer Use Agent execution is limited to 100 steps (actions) by default
• This limit helps prevent runaway costs and ensures efficient task completion
• The agent automatically stops when the goal is achieved, typically well before reaching the limit
• If your task doesn't complete within 100 steps, consider breaking it into smaller, more focused tasks

Example prompts:

• "Record a 2-minute demo video of our new dashboard feature, navigate through the analytics section, and export a report"
• "Download our top-performing video from TikTok, then upload it to YouTube Shorts and Instagram Reels with optimized captions"

Creating an Agent

1. Navigate to the AI Agents page in your bucket
2. Click "Create Agent"
3. Choose your agent type (Team, Content, Code, or Computer Use)
4. Describe the task you want the agent to complete
5. (Optional) For content agents, enable Progressive Discovery to crawl web content

Note: Content, Code, and Computer Use agents can run on a recurring schedule via Workflows. Team Agents support heartbeat schedules directly from the agent form for proactive check-ins.

Event Triggers

Agents can be triggered automatically when content events occur. When enabled, your agent runs automatically whenever selected events happen on matching object types.

Available Events:

• Object Created: Triggers when a new object is added
• Object Edited: Triggers when an existing object is modified
• Object Deleted: Triggers when an object is removed
• Object Published: Triggers when an object's status changes to published
• Object Unpublished: Triggers when a published object is unpublished

Event Context Data:

When an event triggers your agent, the following data is automatically included in the prompt context:

• Event Type: The action that triggered the agent (created, edited, published, etc.)
• Object Type: The content type that was affected
• Object ID: The unique identifier of the object
• Object Title: The title of the triggered object
• Object Slug: The slug of the triggered object
• Object Status: Current status (draft, published, etc.)
• Object Metadata: All field values from the object

Using Event Data for Conditional Logic:

You can reference this event data in your prompt to implement conditional behavior:

If the object status is "draft", generate SEO metadata for the content.
If the object is already "published", complete early without changes.
If the object type is "blog-posts" and the title contains "urgent",
prioritize this task and notify the team.

Example Use Cases:

• Auto-generate social media posts when a blog is published
• Create translations when new content is added
• Update related content when a product price changes
• Send notifications based on specific field values

Team Agent Configuration

Team Agents are conversational by default. They receive messages and respond through multiple channels, maintain conversation context, use tools to interact with your CMS and external services, and support both real-time chat and automated scheduled messaging. When you create a Team Agent, channels, capabilities, and memory settings are available directly in the agent form.

Just ask your agent "What can you do?" and it will tell you exactly which capabilities are enabled and what tools it has access to. This is the fastest way to understand what your agent can help with.

Channels

Channels determine how messages reach your agent. You can enable multiple channels simultaneously.

• REST API: Send messages to your agent programmatically using a Personal Access Token. After creating a Team Agent, the endpoint URL is shown on the agent detail page. Create a token at Account Settings > API Tokens, then authenticate requests with it:

curl -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/messages \
  -H "Authorization: Bearer cos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

Use this for custom integrations, scripts, or any application that needs to communicate with your agent programmatically.

• Inbound Webhook: Receive messages from external systems without Cosmic authentication. When enabled, a webhook endpoint and secret are shown on the agent detail page. Use the Reveal button to view the secret and Copy to copy it.

Authenticate webhook requests using one of these methods:

curl -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/webhook?secret=YOUR_WEBHOOK_SECRET \
  -H "Content-Type: application/json" \
  -d '{"message": "New deployment completed successfully"}'

The request body should include a message field (string, required). Optional fields: conversation_id (to continue an existing conversation) and metadata (object, passed to the agent as context). If a webhook secret is compromised, click Regenerate on the agent detail page to generate a new secret. The old secret stops working immediately. Use this for third-party integrations like Zapier, GitHub Actions, or any automation platform.

• Slack: Chat with your agent directly in a Slack channel. Requires the Slack integration to be configured in your Bucket Settings > Integrations (see Setting up Slack). Once connected, select a Slack channel and your agent will respond to messages there. The agent can see recent channel history (up to 50 messages), so it has full context of the team conversation when responding. For thread replies, the agent sees the full thread context. Enable "Only respond when @mentioned" to limit the agent to only replying when explicitly tagged with @Cosmic Agent. When this option is on, the agent still sees the full channel conversation but only responds to @mentions.

• Telegram: Chat with your agent through a Telegram bot. Set up the bot token in your Bucket Settings > Integrations (see Setting up Telegram), then generate a connect code in the agent edit page and send /connect <code> to the bot in your Telegram chat to link the agent.

• WhatsApp: Chat with your agent on WhatsApp. Cosmic supports two modes: a shared number hosted by Cosmic (quick start), or Bring Your Own Number (BYON) where you connect your own WhatsApp Business number for full control. Enable WhatsApp on your agent, generate a connect code, and tap the "Open WhatsApp" link to send the activation code. Once paired, any message from that phone number is routed to the agent. See Setting up WhatsApp for configuration details.

• Email: Receive and respond to messages via email. When enabled, the agent can participate in email-based conversations with your team or customers.

Capabilities

Capabilities control what your agent can do when processing messages. Enable only the capabilities your agent needs. Each capability unlocks a set of tools that the agent can call autonomously.

CMS Read

Query and read objects, object types, and media from your bucket.

Tools:

• get_objects: Fetch objects from the CMS, filtered by object type, search query, with pagination. Parameters: type, query, limit, skip, props
• get_object_types: List all content models (object types) in the bucket and their metafield schemas
• get_media: Fetch media files from the media library with optional search and pagination. Parameters: limit, skip, query

Example prompts:

• "List all published blog posts"
• "Show me the schema for the products object type"
• "Find media files with 'hero' in the name"

CMS Write

Create, update, and delete objects and object types in your bucket. Also includes AI image generation and media uploads.

Tools:

• create_object_type: Create a new content model with metafield definitions. Parameters: title, slug, singular, emoji, metafields
• update_object_type: Update an existing content model (rename, add/remove metafields). Parameters: type_slug, title, singular, emoji, metafields_to_add, metafields_to_remove
• create_object: Create a new CMS object. Parameters: type, title, slug, thumbnail, metadata, status, publish_at, unpublish_at
• update_object: Edit an existing object by ID. Parameters: id, title, slug, thumbnail, metadata, status, publish_at, unpublish_at
• delete_object: Delete an object by ID. Parameters: id
• generate_image: Generate an AI image from a text description and upload it to the media library. Parameters: prompt, size, aspect_ratio
• upload_media: Upload a file from a public URL to the media library. Parameters: url, name, folder

Example prompts:

• "Create a new blog post about AI trends"
• "Generate a hero image for the homepage"
• "Upload the image from this URL to the media library"
• "Update the status of all draft posts to published"

Code Read

Read files and browse the directory structure of a connected GitHub repository. The agent can discover relevant files, understand your codebase structure, and search for specific content.

Tools:

• list_repository_files: List files and directories in the connected repo, filtered by an optional path prefix. Parameters: path (optional), branch (optional)
• read_file: Read the contents of a file from the repo. Parameters: path (required), branch (optional)
• search_files: Search for files by filename pattern (e.g. "*.tsx", "package.json"). Parameters: pattern (required), path (optional directory filter)
• list_branches: List all branches in the repo with their latest commit SHA and protection status
• get_repository_info: Get metadata about the connected repository including production URL, GitHub URL, framework, and Vercel project details
• get_deployments: List recent Vercel deployments with status, URLs, commit info, and timestamps. Parameters: limit (optional, default 5, max 20)
• get_deployment_logs: Get build and deployment logs for a specific Vercel deployment. Use get_deployments first to find the deployment ID, then use this tool to see the full build output including any errors. Parameters: deployment_id (required)
• get_access_logs: Get runtime access logs and function console output for a deployed Vercel project. Shows HTTP requests with status codes, paths, and methods, plus any console.log/console.error output from serverless functions. Useful for diagnosing production errors like 500s, 404s, or failed form submissions. Defaults to showing errors (status >= 400) from the last 24 hours. Parameters: time_range (optional: 1h, 6h, 24h, 3d), status_filter (optional: errors, client_errors, server_errors, all), method (optional), path (optional, supports regex), limit (optional, default 50, max 100)

Example prompts:

• "Show me the contents of src/index.ts"
• "List all files in the components directory"
• "Search for files that import the AuthService"
• "What branches exist in the repo?"
• "Show me the latest deployments"
• "Get the build logs for the failed deployment"
• "Check the access logs for any 500 errors on the contact page"
• "Show me all POST errors from the last hour"

Code Write

Create branches, commit changes, open pull requests, and build full applications in a connected repository. Requires Code Read to also be enabled. The agent creates feature branches, commits changes, opens PRs for review, and can generate entire applications from a description.

Tools:

• commit_files: Create a commit with file changes (create, update, or delete multiple files). Parameters: branch (required), message (required), files (required array of { path, content, action })
• create_branch: Create a new branch from an existing one. Parameters: branch_name (required), from_branch (optional, defaults to base branch)
• create_pull_request: Open a pull request. Parameters: title (required), head (required source branch), body (optional), base (optional target branch)
• merge_pull_request: Merge a pull request. Parameters: pull_number (required), commit_title (optional), merge_method (optional: merge, squash, or rebase, defaults to squash)
• redeploy_project: Trigger a Vercel redeployment. Parameters: branch (optional), commit_sha (optional)
• build_app: Build a new web application using AI. Generates content models, installs demo content, and produces the full application code within the current project. This is an async operation that returns a job_id you can poll with get_build_status. Parameters: description (required), app_name (optional), goal (optional: online_business, creative_work, promote_company, manage_content, other), type (optional sub-type like blog, online_store, saas), model (optional)
• get_build_status: Check the status and progress of a build_app or deploy_app job. Parameters: job_id (required)
• deploy_app: Deploy a completed build_app job to GitHub and Vercel. Only call after build_app has completed and the user confirms they want to deploy. Parameters: job_id (required), repo_name (optional)

App building workflow:

The build_app, get_build_status, and deploy_app tools work together as an async pipeline. The agent kicks off a build, polls for progress, and then asks the user if they want to deploy:

1. Agent calls build_app with a description of the desired app
2. The tool returns a job_id immediately while the build runs in the background
3. The user (or agent) can check progress with get_build_status at any time
4. Once complete, the agent asks the user if they want to deploy
5. If yes, agent calls deploy_app with the build's job_id to create a GitHub repo and deploy to Vercel

Example prompts:

• "Create a feature branch and add a dark mode toggle component"
• "Fix the bug in the header component and open a PR"
• "Merge pull request #42 using squash"
• "Build me a blog app with posts, categories, and an author page"
• "Check the status of my app build"
• "Deploy the app we just built"

Web Browse

Fetch and read content from web page URLs. The agent can research information, read linked articles, and gather context from the web.

Tools:

• fetch_url: Fetch and read web page content (HTML stripped to text). Parameters: url

Example prompts:

• "Read the content of https://example.com/blog/ai-trends"
• "Summarize the article at this URL"

API Requests

Make HTTP requests to any external REST API or service. Supports all standard HTTP methods (GET, POST, PUT, PATCH, DELETE) with custom headers for authentication. Use this to integrate with third-party services like Zapier, Shopify, Stripe, Gmail API, or any REST endpoint. All requests must use HTTPS.

Secrets allow you to store sensitive values like API keys and tokens securely. Values are encrypted at rest using AES-256-GCM and never exposed in conversations or logs. You can manage secrets from the agent form UI or let the agent manage them conversationally. Reference a secret in any endpoint URL or header value using the template syntax {{secret:sec_xxx}}. The template is resolved server-side at runtime, so raw credentials are never sent to the model.

API Endpoints let you save reusable endpoint configurations (URL, method, headers, body template) so the agent can call them by name instead of rebuilding requests from scratch. Endpoints can reference secrets in their headers and URLs.

Tools:

• api_request: Make an HTTP request to an external API. Parameters: url (required, HTTPS only), method (required: GET/POST/PUT/PATCH/DELETE), headers (optional), body (optional JSON for POST/PUT/PATCH). Secret references ({{secret:sec_xxx}}) in URLs and headers are resolved automatically before the request is sent.
• manage_api_endpoints: Save, update, list, and remove reusable API endpoint configurations. Actions: list, add, update, remove. When adding or updating, the agent can include {{secret:sec_xxx}} references in headers and URLs.
• manage_secrets: Securely store, list, and remove API keys and tokens. Actions: list (returns names and IDs only, never raw values), add (encrypts and stores a new secret), remove (deletes a secret, with a warning if referenced by any saved endpoints).

Example prompts:

• "Save my Stripe API key as a secret, then add an endpoint for listing customers"
• "POST the updated product data to the Shopify API"
• "GET the latest orders from the Stripe API and summarize them"
• "Send a trigger to my Zapier webhook with the new content data"
• "List my saved secrets and endpoints"

Send Notifications

Send messages to project members via email, Slack, Telegram, or WhatsApp. Email recipients are restricted to confirmed project members for security. Slack, Telegram, and WhatsApp require the respective integration to be connected in Project Settings > Integrations.

Tools:

• send_email: Send an email to project members. Use to: "owner" for the project owner, to: "team" for all members, or a specific project member email address. Parameters: to, subject, body
• send_slack_message: Post a message to a Slack channel. Uses the agent's configured Slack channel by default. Parameters: message, channel_id (optional), blocks (optional Block Kit JSON)
• send_telegram_message: Send a message to a Telegram chat. Uses the agent's configured Telegram chat by default. Parameters: message, chat_id (optional)
• send_whatsapp_message: Send a message to a WhatsApp user. Uses the agent's connected WhatsApp phone number by default. Parameters: message, phone_number (optional)

Example prompts:

• "Email the team that the content migration is complete"
• "Post a summary of today's published articles to the Slack channel"
• "Send a Telegram alert that the scheduled workflow finished"
• "Send a WhatsApp message to let them know the order shipped"

Agent Delegate

Hand off tasks to other agents in the same project. Useful for orchestrating specialized agents where one agent coordinates work across others.

Tools:

• message_agent: Send a message to another agent and receive its response. Parameters: agent_id, message

Example prompts:

• "Ask the content-writer agent to draft a blog post about this topic"
• "Delegate the image generation to the media agent"

Agent Manage

Create, list, update, and delete agents and workflows in the project. Allows agents to self-manage and orchestrate other agents programmatically.

Tools:

• list_agents: List all agents in the project with their IDs, names, types, and status
• create_agent: Create a new agent (content, repository, or computer_use type)
• update_agent: Update an agent's configuration (name, prompt, capabilities, schedule, status)
• delete_agent: Delete an agent and all its execution history
• list_workflows: List all workflows in the project
• create_workflow: Create a new multi-step workflow with ordered agent steps
• delete_workflow: Delete a workflow and its execution history

Example prompts:

• "Create a new content agent called weekly-reporter"
• "List all agents in this project"
• "Pause the daily-digest agent"
• "Create a workflow that runs the content agent then the code agent"

Execute Workflows

Run workflows and check their execution status. Workflows are multi-step automated processes that chain agents together.

Tools:

• execute_workflow: Run a workflow by ID with optional trigger data. Parameters: workflow_id, trigger_data
• get_workflow_status: Check the status of a running workflow execution. Parameters: execution_id

Example prompts:

• "Run the content-pipeline workflow"
• "Check the status of the last workflow execution"

Always Available Tools

These tools are available to all Team Agents regardless of which capabilities are enabled:

• send_message: Send a formatted message to the current conversation channel
• request_approval: Pause execution and request human approval before proceeding with an action

Conversation Memory

Memory controls how your agent retains conversation history.

• Session: Conversation history resets when the conversation ends. Best for stateless interactions.
• Persistent: Conversation history is maintained across sessions. The agent remembers previous interactions, which is useful for ongoing relationships with users or long-running tasks.

Customer Facing Mode

Enable Customer Facing when your agent interacts with external users (e.g., customers on WhatsApp or a public API). When enabled, the agent's get_my_config tool returns only basic information (name, type, and description) instead of the full configuration. This prevents sensitive details like internal prompts, connected agents, and webhook URLs from being exposed to end users.

Heartbeat Schedule

A Heartbeat Schedule runs your Team Agent on a recurring cron schedule. This is useful for agents that should proactively perform tasks at regular intervals, such as daily content summaries or periodic status checks.

To configure a heartbeat, enable the schedule toggle and set:

• Cron Expression: Standard cron syntax (e.g., 0 9 * * 1-5 for weekdays at 9 AM)
• Timezone: The timezone for the schedule
• Schedule Prompt (optional): A separate prompt used specifically for scheduled runs. When set, the agent keeps its main prompt as its identity and personality, while the schedule prompt defines what the agent should do each time the schedule fires. If left empty, the main agent prompt is used.

How it works with Slack: When a Slack channel is connected, the agent processes the schedule prompt and sends its response directly to the connected Slack channel. This is the primary use case for heartbeat schedules.

Example use cases:

• "Every weekday at 9 AM, summarize today's content calendar and highlight any items that need attention"
• "Every Monday, review all draft blog posts and suggest improvements"
• "Every hour, check for new support tickets and categorize them by priority"

AI Context

AI Context gives your agent knowledge beyond its base prompt. When configured, the selected content is included in every conversation, allowing the agent to reference your actual data when responding.

You can include:

• Object Types: Specific content types and their schemas
• Objects: Individual content items and their field values
• Media: Media library items
• Links: URLs for web crawling and progressive discovery. The agent fetches and indexes linked pages to inform its responses.
• Brand Guidelines: Include your project's brand guidelines so the agent maintains a consistent voice and style across all generated content.
• Reference Screenshots: Screenshot URLs that give the agent visual reference for design-aware tasks.
• MCP Servers: Connect external Model Context Protocol servers to extend the agent's tool set with custom integrations.

This is configured through the AI Context modal when creating or editing an agent. Context helps agents give accurate, content-aware responses without users needing to describe the data in every message.

Setting up Slack

1. Go to your Bucket Settings > Integrations
2. Click Connect Slack to start the OAuth flow
3. Authorize the Cosmic app in your Slack workspace
4. Once connected, create or edit a Team Agent
5. Toggle the Slack channel and select a channel from the dropdown
6. Optionally enable "Only respond when @mentioned" for busy channels

The agent will now respond to messages in the selected Slack channel. It sees up to 50 recent messages for context and has full thread awareness.

Setting up Telegram

1. Create a Telegram bot via BotFather and copy the bot token
2. Go to your Bucket Settings > Integrations
3. Paste the bot token and click Connect
4. Create a Team Agent and toggle the Telegram channel
5. Save the agent, then edit it to click Generate Connect Code
6. In your Telegram chat with the bot, send /connect <code> to link the agent

The agent will now respond to messages in that Telegram chat. Connect codes expire after 10 minutes.

Setting up WhatsApp

Cosmic supports two WhatsApp modes:

Option 1: Shared Number (Quick Start)

Use Cosmic's hosted WhatsApp Business number. No Meta account required.

1. Create or edit a Team Agent
2. Toggle the WhatsApp channel
3. Save the agent, then edit it and click Generate Connect Code
4. Click Open WhatsApp to open a pre-filled message with the activation code
5. Send the message from your WhatsApp to pair your phone number with the agent

The agent will now respond to messages from that phone number. Connect codes expire after 10 minutes.

Option 2: Bring Your Own Number (BYON)

Connect your own WhatsApp Business number for full control and branding.

1. Create a WhatsApp Business App in the Meta Developer Dashboard
2. Generate a System User access token with whatsapp_business_messaging permission
3. Go to your Bucket Settings > Integrations
4. Under WhatsApp, select Bring Your Own Number and enter your access token and phone number ID
5. Configure the webhook URL in your Meta App to point to the URL shown in Integrations
6. Create a Team Agent, toggle WhatsApp, and generate a connect code

With BYON, messages are sent from your own branded number and the integration is fully isolated to your project.

Agent Messaging API Reference

Send a message

POST /v3/ai/agents/:agentId/messages

Authentication: Personal Access Token or session JWT via Authorization: Bearer header.

Request body:

Example:

curl -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/messages \
  -H "Authorization: Bearer cos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize our latest blog posts"}'

Streaming

Pass stream: true in the request body to receive a streaming response via Server-Sent Events (Content-Type: text/event-stream). Each event is a data: line containing JSON.

Example:

curl -N -X POST https://dapi.cosmicjs.com/v3/ai/agents/AGENT_ID/messages \
  -H "Authorization: Bearer cos_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Summarize our latest blog posts", "stream": true}'

Event types:

Example event stream:

data: {"type":"info","conversation_id":"abc123","model":"claude-opus-4-6"}

data: {"type":"text_delta","text":"Here","fullText":"Here"}

data: {"type":"text_delta","text":" are","fullText":"Here are"}

data: {"type":"tool_progress","label":"Fetching content..."}

data: {"type":"text_delta","text":"The latest","fullText":"The latest"}

data: {"type":"done","conversation_id":"abc123","message":"The latest posts cover...","tokens_used":1234,"model":"claude-opus-4-6"}

Inbound webhook

POST /v3/ai/agents/:agentId/webhook

Authentication: Webhook secret (no Bearer token required). See Inbound Webhook for authentication methods.

Request body:

List conversations

GET /v3/ai/agents/:agentId/conversations

Authentication: Personal Access Token or session JWT.

Get conversation history

GET /v3/ai/agents/:agentId/conversations/:conversationId

Authentication: Personal Access Token or session JWT.

Key Features

• Parallel Execution: Run multiple agents simultaneously (limits based on your plan)
• Branch Isolation: Code agents work on separate Git branches to prevent conflicts
• Progress Tracking: Monitor commits, files changed, and real-time status updates
• Email Notifications: Receive updates when agents complete their work
• Pull Request Management: Agents can create PRs for code review before merging
• Progressive Discovery: Content agents can crawl web content to inform their work

Plan Limits

Plan-Based Limits (varies by plan):

• Free Plan: 2 agents at a time
• Paid Plans: More agents based on your plan (check your plan details)

Agent Limits by Plan

Agent limits apply at the project level (for standalone projects) or workspace level (for workspace projects):

• Free Plan: 3 agents per project (manual only)
• Builder Plan: 5 agents per project (with scheduling)
• Team Plan: 15 agents per project (with scheduling)
• Business Plan: 25 agents per project (with scheduling)
• Enterprise Plan: Custom agent limits

Note: Scheduled execution is available through Workflows on paid plans.

Progressive Discovery

Content Agents can use Progressive Discovery to crawl and analyze web content before generating or updating CMS content. This feature allows agents to:

• Research current trends and topics from specified websites
• Gather real-world examples and data
• Reference actual sources with accurate URLs
• Create content informed by the latest information

To use Progressive Discovery, enable it when creating a content agent and specify the URLs or topics you want the agent to explore.

Workflows

AI Workflows allow you to chain multiple AI agents together to complete complex operations that previously required entire teams. Define a workflow once, and run it on-demand or on a schedule.

What Are Workflows?

Workflows orchestrate multiple AI agents (Content, Code, and Computer Use) to execute complex, multi-step operations autonomously. Each step in a workflow passes context to the next—content feeds into code, code deploys, and Computer Use tests and records demos.

How Workflows Work

1. Define Your Workflow: Choose a template or build custom. Chain Content, Code, and Computer Use agents in any sequence. Set triggers—manual, scheduled, or event-driven.

2. Execute Automatically: Agents work sequentially or in parallel. Each step passes context to the next, maintaining continuity throughout the workflow.

3. Monitor in Real-Time: Watch progress live with step-by-step updates. See token usage, costs, and duration. Pause for approval gates when human review is needed.

4. Review & Iterate: Get complete execution summaries. View all created content, code changes, and recordings. Clone successful workflows for future projects.

5. Rerun Anytime: Run workflows on-demand or schedule them to run automatically. Your automation runs 24/7 without intervention.

Workflow Use Cases

Full-Stack Product Launch

Time: 20 minutes vs 2-3 weeks

Content Agent creates your product catalog, Code Agent builds the storefront, Computer Use Agent tests and records a demo video. Complete e-commerce site, deployed.

Workflow steps: Content Generation → Code Development → Deploy & Test

Automated Content Optimization

Schedule: Runs every Monday at 2 AM

Automatically analyze 500+ articles for outdated content, validate links, capture fresh screenshots, and update flagged articles. Always-fresh content, zero manual work.

Workflow steps: Analyze Content → Validate Links → Auto-Update

Multi-Market Launch

Time: 90 minutes vs 16 weeks

Launch in 12+ markets simultaneously. Localized content, market-specific websites, compliance validation, and demo videos—all running in parallel.

Workflow steps: Localize Content → Deploy Sites → Validate Compliance

Auto-Documentation

Trigger: On every deploy

Code deploys to production, agents analyze changes, test new features, capture demo videos, write documentation, and create sales materials. Docs ship with features.

Workflow steps: Analyze Code → Test Features → Generate Docs

Creating a Workflow

1. Navigate to the AI Workflows page in your bucket
2. Click "Create Workflow"
3. Add steps by selecting agent types (Content, Code, or Computer Use)
4. Configure each step with specific instructions
5. Set execution order (sequential or parallel)
6. (Optional) Add approval gates for human review
7. (Optional) Set a schedule or trigger for automatic execution

Workflow Features

• Sequential or Parallel Execution: Run steps one after another or simultaneously
• Context Passing: Each step receives output from previous steps
• Approval Gates: Pause workflow for human review when needed
• Scheduling: Run workflows on a schedule (hourly, daily, weekly, monthly)
• Event Triggers: Automatically trigger workflows on specific events
• Real-Time Monitoring: Watch progress with live updates
• Execution History: Review past runs with complete logs and outputs
• Templates: Start with pre-built workflow templates for common use cases

Event-Triggered Workflows

Workflows can be configured to run automatically when content events occur, enabling powerful automation scenarios.

Available Events:

• Object Created: Run workflow when new content is added
• Object Edited: Run workflow when content is modified
• Object Deleted: Run workflow when content is removed
• Object Published: Run workflow when content goes live
• Object Unpublished: Run workflow when content is taken offline

Event Context Data:

When an event triggers your workflow, the following data is automatically included in the prompt context for all workflow steps:

• Event Type: The action that triggered the workflow
• Object Type: The content type that was affected
• Object ID: The unique identifier of the object
• Object Data: Title, slug, status, locale, and all metadata fields

Using Event Data for Conditional Logic:

Each step in your workflow can reference the event data to make decisions:

Step 1 (Content Agent):
"If the triggered object's status is 'draft', generate SEO metadata.
 If the object is 'published', create social media posts instead."

Step 2 (Code Agent):
"If the object type is 'products' and the price field changed,
 update the pricing display component."

Example Event-Triggered Workflows:

Auto-SEO on Publish:

Trigger: Object Published (blog-posts)
Step 1: Generate meta description and keywords from content
Step 2: Create Open Graph image using AI image generation
Step 3: Update object with SEO metadata

Content Localization Pipeline:

Trigger: Object Created (articles)
Step 1: If locale is 'en-US', translate to Spanish, French, German
Step 2: Create localized versions as new objects
Step 3: Send notification with translation summary

Product Update Automation:

Trigger: Object Edited (products)
Step 1: If price changed, update all related promotional content
Step 2: Regenerate product comparison charts
Step 3: Notify sales team via email

Workflow Examples

Research-to-Publication Pipeline:

Step 1 (Content Agent): Research topic from specified sources
Step 2 (Content Agent): Write article draft with citations
Step 3 (Code Agent): Create landing page for article
Step 4 (Computer Use Agent): Record demo video and screenshots
Step 5 (Content Agent): Publish with all media assets

Code Review and Documentation:

Step 1 (Code Agent): Implement feature from requirements
Step 2 (Code Agent): Write unit tests
Step 3 (Computer Use Agent): Test in browser and record demo
Step 4 (Content Agent): Generate documentation from code changes
Step 5 (Code Agent): Open PR with docs and demo video

Best Practices

• Start Simple: Begin with 2-3 step workflows and add complexity as needed
• Use Approval Gates: Add human review steps for critical operations
• Test First: Run workflows manually before scheduling
• Monitor Costs: Watch token usage across workflow steps
• Clone Successful Workflows: Reuse working workflows as templates for new projects

Execution Retention

Agent and workflow executions are automatically cleaned up after a retention period to manage storage and keep your dashboard performant.

Retention Policy

• Retention Period: 90 days
• Affected Executions: Completed, failed, and cancelled executions
• Protected Executions: Running and active executions are never automatically deleted

What Gets Deleted

When an execution exceeds the retention period, the following data is removed:

• Execution logs and message history
• Step-by-step results and outputs
• Token usage records for that execution
• Associated metadata (commits, file changes for code agents)

What's Preserved

• Agent and Workflow configurations are never deleted by retention policies
• Running executions remain until they complete
• Content created by agents (CMS objects, media) persists independently
• Code changes committed to your repository remain in Git history
• Pull requests created by code agents remain in GitHub

Best Practices

• Export important execution logs before the 90-day retention period if you need long-term records
• Use the execution detail view to review results while they're available
• Agent configurations store your prompts and settings permanently—only execution history expires

Usage and limits

Cosmic AI is available on all Cosmic plans with varying limits. You can add more tokens to your account by upgrading your plan or adding the AI tokens add-on. Go to the pricing page to learn more.

Tokens

Tokens are the unit of usage for Cosmic AI. In general, 1 token equals 1 word or 4 characters. You can view your AI usage from the Usage section of your projects.

Input tokens are the number of tokens used in your request. These are typically lower cost and represent the content you send to the AI (prompts, context, etc.). For text generation, this includes your messages and conversation history.

Output tokens are the number of tokens generated by the AI. These are higher cost (typically 5x more than input tokens) and represent what the AI creates:

• Text generation: Varies by response length
• Image generation: Fixed cost per image (4,800 - 57,600 tokens depending on model and size)
• Video generation: Fixed cost per video (144,000 - 768,000 tokens depending on model and duration)

Media generation (images and videos) costs are counted as output tokens to reflect the computational requirements of generating visual content.

Getting started

Log in to your Cosmic account and start using Cosmic AI today.