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.

Where agents live: Agents are project-scoped, so they are available across every bucket in the project. Team Agents have their own top-level section in the project sidebar (Project > Team Agents). Content, Code, and Computer Use agents are managed as Automations inside the project's AI Studio, alongside multi-step Workflows.

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

Team Agents and Automations are created in separate places in the project sidebar.

To create a Team Agent:

1. Open your project and click Team Agents in the project sidebar
2. Click "Create Team Agent"
3. Give the agent a name, persona, and prompt, then configure channels (Slack, WhatsApp, Telegram, Email, API, Webhook) and capabilities
4. (Optional) Enable a heartbeat schedule for proactive check-ins

To create a Content, Code, or Computer Use automation:

1. Open your project and click AI Studio in the project sidebar, then choose Automations
2. Click "Create Automation"
3. Choose your agent type (Content, Code, or Computer Use)
4. Describe the task you want the automation to complete
5. (Optional) For content automations, enable Progressive Discovery to crawl web content
6. (Optional) Set a schedule or an event trigger so the automation runs automatically

Tip: From any bucket you can also jump into AI Studio > Create with AI to describe what you want in natural language, and Cosmic will help scaffold the right agent or automation for you.

Note: Content, Code, and Computer Use automations can run on a recurring schedule or be chained inside Workflows. Team Agents support heartbeat schedules directly from the Team 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. Supports conversation commands like /reset and /tokens.

• 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. Supports conversation commands like /reset and /tokens.

• 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. Supports conversation commands like /reset and /tokens.

• 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. Supports show_when on metafields for conditional visibility
• update_object_type: Update an existing content model (rename, add/remove metafields). Parameters: type_slug, title, singular, emoji, metafields_to_add, metafields_to_remove. Supports show_when on metafields for conditional visibility
• 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
• batch_objects: Create, update, or delete up to 25 objects in a single call. Each operation succeeds or fails independently. Parameters: operations (array of { method, type, id, title, metadata, status, ... })
• 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, set environment variables, 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, manages Vercel environment variables, 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)
• set_environment_variables: Add or update environment variables on a Vercel-deployed repository. Sets variables as encrypted for all targets (production, preview, development). If a variable already exists, it will be updated. Parameters: variables (required array of { key, value }), repository_name (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"
• "Set the GMAIL_CLIENT_ID and GMAIL_CLIENT_SECRET env vars on the gmail-utils repo"
• "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.

How conversations work under the hood

A conversation is a single thread of messages between a user and an agent on one channel (the dashboard, a Slack channel/thread, a Telegram chat, a WhatsApp number, an API session, etc.). Each turn carries the conversation forward, but the agent never sees the entire raw history at once. Instead, every turn is built from three layers:

1. System context: the agent's prompt, tool list, and AI Context content. This is the same on every turn and is cached so subsequent turns only pay for it once.
2. Recent messages (verbatim): the most recent messages in the conversation are passed in word-for-word.
   • Solo agents: last 30 messages are kept in full.
   • Team agents (those with connected_agents that can delegate via message_agent): last 15 messages are kept in full. The smaller window leaves room for cross-agent context blocks without blowing the prompt budget.
3. Compressed summary of older messages: anything beyond the recent-message window is summarized into a single [CONVERSATION SUMMARY - N earlier messages condensed] block by Claude Haiku. The summary captures key decisions, tool calls and their outcomes, important facts, and any unresolved items. It's cached for an hour keyed by conversation id and message count, so the same summary is reused turn after turn until new messages bump the count.

The result: the agent always has the gist of the entire conversation plus the most recent details, even if you've been chatting for hours. Token usage grows linearly per turn rather than quadratically with conversation length.

How handoff summaries work

/reset (without --hard) generates a separate handoff summary at the moment you reset. This is different from the rolling compression summary above:

• The compression summary is per-turn and ephemeral: it lives in the prompt, not in the conversation document.
• The handoff summary is generated once when the conversation is closed via /reset. It's persisted to the closed conversation, then carried forward into the next conversation in the same channel as [Handoff summary from your previous conversation]. The agent treats it as established context and can pick up exactly where you left off without paying to re-read the full prior transcript.

/reset --hard skips both: no handoff summary is generated, and the new conversation starts with no context from the prior session.

Channel-side context (Slack, Telegram, WhatsApp)

Channel integrations layer their own context on top of the conversation:

• Slack: the agent sees up to 50 recent messages from the channel or thread on every turn, so it has full context of what your team has been discussing even if it wasn't directly addressed.
• Telegram / WhatsApp: scoped per chat or sender phone number. The conversation thread is the agent's view of history.
• Cross-channel context: when an agent is active on multiple channels (e.g. a Slack agent that also gets DM'd in the dashboard), each conversation gets a brief Haiku-generated summary of recent activity from the agent's other open conversations, so it can answer questions like "what did the other team ask you about earlier?". This summary is cached for 10 minutes and invalidated immediately when another agent delegates work via message_agent.

Practical guidance

• For long-running, focused chats: just keep going. The compression keeps token cost predictable.
• When the topic shifts or the conversation gets long enough to drift: use /reset to keep continuity without paying for the full transcript every turn.
• For a true clean slate (different project, sensitive topic, etc.): use /reset --hard.
• To check where you stand: /tokens shows the current message count and token usage for the active conversation.

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.

Conversation commands

Team Agents support a small set of conversation commands in the Cosmic dashboard chat as well as on Slack, Telegram, and WhatsApp. Commands are nearly free: they are handled locally and never hit the agent's main model. /reset makes one short call to a small summarization model (Claude Haiku) to produce a handoff summary; the other commands don't call any model.

Parser rules:

• The entire message must be exactly the command (case-insensitive). /reset works; /reset please is treated as a normal message and passed to the agent.
• On Slack, commands work whether the bot is @mentioned or not; the mention is stripped before parsing.
• Commands are scoped to the current conversation. In the dashboard, that's the conversation you have open; on Slack, the channel or thread; on Telegram, the chat; on WhatsApp, the sender's phone number.

When to use /reset:

• The conversation has drifted and you want the agent to start fresh while keeping the high-level context.
• Token usage (visible via /tokens) is getting high and you want to reduce cost on the next turn without losing what you were working on.
• You are about to switch topics. Use --hard if you don't want any prior context bleeding in.

In the dashboard, after a soft /reset the chat pivots to the new conversation immediately: the message count and token counter reset to zero, and the /reset exchange (your command and the handoff summary) is persisted to the new session so it stays visible after a page refresh.

Sharing conversations

Each conversation has its own shareable URL. When you switch between conversations in the rail (or start a new one), the dashboard reflects the active conversation in the address bar as ?conversation=<id>, for example:

https://app.cosmicjs.com/projects/PROJECT_ID/agents/AGENT_ID?conversation=CONVERSATION_ID

Copy that URL to share a direct link to the conversation with anyone who has access to the project. Refreshing the page or opening the link in a new tab loads the same conversation rather than the most recent one. Use /reset (or click "New chat") to switch to a fresh conversation and update the URL.

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-7"}

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-7"}

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, automation, and workflow limits are tracked in three separate pools and apply at the project level (for standalone projects) or workspace level (for workspace projects). Only active entities count toward each cap, so drafts, paused, archived, or deleted items free a slot. Workflow steps do not consume team agent or automation slots.

• Team Agents: Persistent AI agents connected to channels like Slack, WhatsApp, or Telegram.
• Automations: Standalone agents (content, code, or computer use) that run on demand, on a schedule, or on content events.
• Workflows: Multi-step orchestrations that chain agents and logic.

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.