Skip to main content

Create your first Coworker Agent

Connect a GitHub repository, create an agent in it, and trigger its first run.

Prerequisites​

  • Coworker agents enabled for your organization (Enterprise plans, currently in beta)
  • Permission to manage agents (org:agents:manage). Creating a platform-managed agent also needs org:vmcps:manage, because it creates the agent's identity and connector bundle
  • Permission to install a GitHub App on the repository's organization
  • A model credential: an Anthropic API key, claude setup-token subscription token, or Claude-compatible API key for the Claude Agent harness; or an OpenAI API key for Codex

Connect GitHub​

  1. Open Coworker Agents in Mintive at app.mintmcp.com/agents.
  2. Click Install GitHub App and grant the MintMCP GitHub App access to the repository (or repositories) where agents will live.
  3. Back in Mintive, pick the repository from the Select a Repository card. You can connect more repositories later from the page header.

If the repository is empty, Mintive shows an Initialize repository button that creates an initial commit.

Set up the repository​

Agents share workflow files and helper scripts that live in the repository. When the repository doesn't have them yet, Mintive shows an Agent infrastructure setup needed card listing the files it will create.

  1. Click Set up repository. Mintive commits the shared agent infrastructure to the default branch.
  2. If branch protection blocks direct commits, Mintive opens a pull request instead — merge it to finish setup.

When Mintive ships infrastructure improvements later, an Agent infrastructure needs an update banner appears with a one-click update.

Create the agent​

  1. Click New Agent.
  2. Enter an Agent name (for example, "Bella Billing Agent"). The dialog shows the derived slug and directory name.
  3. Describe what the agent should do. This description seeds the agent's AGENTS.md instructions, so the more specific you are about its role, tools, and cadence, the better the agent behaves.
  4. Click Create Agent. New agents are platform-managed: Mintive provisions the agent's identity, scaffolds its instructions and memory (AGENTS.md, progress.md, activity-log.csv, and inbound/) in the repository, and writes its trigger-bridge workflow. Its configuration lives in Mintive, not in an agent.yml file. If branch protection requires it, the repository changes land as a pull request you merge before continuing.

Older GitHub-managed agents, whose configuration lives in an agent.yml file in the repository, keep working. See What lives where for the difference, and Upgrade a GitHub-managed agent to the platform to move an existing legacy agent over.

The dialog then walks through setup sections, each skippable:

  • Harness — most agents run on the default Claude Agent harness; switch to Codex here to run the agent on OpenAI models instead.
  • Model & credentials — pick the model and add its API key — by default an Anthropic API key or claude setup-token subscription token. Claude Agent also supports Amazon Bedrock and Claude-compatible APIs; Codex uses an OpenAI key. See Harness and model for all combinations. If another agent already holds a matching credential, reuse it here instead of pasting a new one. Skip for now leaves the credential unset — the agent shows "Needs setup: Model credential" until you add one.
  • Connect to Slack — give the agent a Slack identity. See Connect a Coworker Agent to Slack.
  • Connect a vMCP — give the agent access to tools from one of your vMCPs.

You can do all of these later from the agent's detail page.

Run the agent​

  1. Click Run on the agent's card or detail page.
  2. Enter a prompt (instructions for this run) and pick a model.
  3. Watch the run under the Runs tab: it moves from queued to in progress to succeeded or failed.
  4. Click the run to open its detail sheet with the run log and, once the run completes, the full conversation transcript.

Add a schedule​

Schedule a platform-managed agent from its page in Mintive. Mintive fires the scheduled runs itself, so no GitHub Actions cron is involved.

  1. Open the agent and go to the Runs tab.
  2. In the Schedules section, click Add schedule.
  3. Pick a recurring schedule or a one-off:
    • Recurring: choose Every hour, Daily, Weekdays, or Weekly (times are in your local time zone), or choose Custom cron (advanced) and enter a five-field cron expression in UTC.
    • One-off: pick a date and time, at least 10 minutes from now.
  4. Click Save schedule.

The Schedules table shows each schedule's next run and last run. Click a schedule to change or remove it, and use its On switch to pause it without deleting it. You need permission to manage agents to edit schedules.

The agent can also schedule itself: ask it in plain language, and it updates its schedules with its update_agent_schedule tool. Both paths enforce the same limits:

  • At most 10 schedules per agent.
  • A recurring schedule can't fire more often than every 10 minutes.
  • A one-off has to be at least 10 minutes in the future and at least 10 minutes from the agent's other pending one-offs.

Switch from a GitHub Actions schedule​

Platform-managed agents that were scheduled before Mintive scheduling existed still fire from a cron in their GitHub Actions workflow. Their Schedules section shows GitHub Actions cron with the cron lines instead of a schedule table. To move one to Mintive scheduling:

  1. In the Schedules section, click Switch to built-in scheduling.
  2. Review the preview. Each cron line becomes its own schedule, and a line is dropped if it runs more often than every 10 minutes, isn't a valid cron expression (GitHub never ran it), or goes past the limit of 10 schedules. Add replacements for dropped lines after the switch.
  3. Click Confirm switch. The switch can't be undone.
  4. Remove the old cron from the repository. If the agent shows Old GitHub schedule still in the repository, click Remove GitHub Schedule, or merge the workflow sync pull request on a branch-protected repo. Until then GitHub keeps firing the old cron and using Actions minutes, but Mintive skips those runs.

Upgrading a legacy GitHub-managed agent to the platform does this switch for you. See Upgrade a GitHub-managed agent to the platform.

Legacy GitHub-managed agents​

For a legacy GitHub-managed agent, add cron expressions (UTC) under triggers.schedule in the agent's agent.yml, either by editing the file directly or with Update Agent on the detail page.

triggers:
  schedule: "0 13 * * *"

Troubleshooting​

  • Needs setup: Model credential — the agent has no model credential yet. Open Model & credentials from the agent's detail page and add one. Which credential it needs depends on the harness and provider — see Harness and model.
  • Needs setup: agent.yml or workflow — the agent directory is missing files or its workflow drifted from the expected configuration. The banner on the detail page offers a one-click fix or Sync Workflow.
  • The agent runs but does nothing useful — that's an instructions problem, not a configuration problem. Refine CLAUDE.md: state the agent's goals, priorities, and what "done" looks like each run.

Next steps​