Introducing CircleCI Functions: Reusable CI steps built for coding agents

CircleCI Functions are now available in beta, giving developers and coding agents a faster, more reliable way to set up CI pipelines using reusable, tested steps.

Functions are the next evolution of CircleCI orbs. They make common CI tasks, like installing programming languages, configuring AWS credentials, and setting up Docker, available as ready-to-use programs that agents can discover, configure, and validate before running a pipeline.

In internal testing, Functions helped coding agents set up working CI pipelines up to twice as fast, using ~40% fewer tokens.

The beta is free on every CircleCI plan and includes ten CircleCI-authored Functions. Existing orbs continue to work as they do today, with no migration required.

Less generated configuration, more reliable pipelines

Coding agents can generate CI configuration in seconds, but they often write custom code for problems that already have established solutions. Common setup steps like installing Node, authenticating with AWS, or preparing a Docker environment shouldn’t require writing and maintaining new scripts for every project.

For years, orbs have helped developers avoid rewriting common CI setup steps. But they were designed primarily for people writing configuration by hand. Orb commands typically run shell scripts, so agents often can’t tell whether a setup step works until a pipeline runs. In our testing, without Functions, agents bypassed available orbs and generated their own setup scripts about half the time.

Functions give agents a better starting point. Each Function handles a common CI task using prebuilt, tested code with clearly defined inputs. Agents can discover the right Function through the CircleCI CLI and its built-in MCP server, use it in their config, and catch errors before pushing a change. Developers get less custom code to review, debug, and maintain.

The agent produces a valid configuration using an existing Function rather than generating custom setup scripts, leaving developers with a smaller, more understandable change to review.

How CircleCI Functions work

Functions fit naturally into CircleCI configuration. Declare a Function in your functions: block, then call it by name in any job.

Here’s a pipeline that installs Node and runs a test suite using setup-node:

version: 2.1

functions:
  setup-node: github.com/circleci-functions/setup-node@v0.4.0

jobs:
  test:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - setup-node:
          with:
            node-version: "22"
      - run: npm test

workflows:
  main:
    jobs:
      - test

The functions block pins the Function version, and the job calls setup-node with the desired Node.js version. No separate installation script is needed.

Unlike traditional orb commands, which commonly execute shell scripts, Functions run compiled programs built and tested for Linux, macOS, and Windows. CircleCI downloads the appropriate binary for each job’s operating system and architecture.

Functions also offer practical improvements for everyday CI work:

• Catch configuration errors before running a pipeline. Invalid Function inputs produce specific errors that identify the problem and list the accepted inputs.
• Get consistent behavior across platforms. Functions are built and tested for each supported operating system.
• Spend less time diagnosing failures. Descriptive errors identify what went wrong instead of leaving developers to interpret shell script failures.
• Keep compiled configs smaller. Functions avoid expanding large blocks of orb configuration. In our testing, a Node setup step compiled to about 7x less config than the equivalent orb command.

Every Function uses an exact, immutable version. Aliases such as @latest or @v1 aren’t permitted, so a published version can’t change unexpectedly. Run circleci function update when you’re ready to adopt newer versions.

Developers writing config by hand also benefit from the CircleCI language server (LSP), which supports Function autocomplete, input suggestions, and notifications when newer versions are available.

Dependency caching built into the step

Language setup Functions such as setup-node and setup-go cache what they download as part of the step itself. With some orbs, you have to place separate restore_cache and save_cache steps yourself, and the cache is thrown away when a job doesn’t finish cleanly, so builds can slow down without an obvious cause.

Functions use your existing CircleCI cache storage, the same storage behind save_cache and restore_cache, without separate save and restore steps. Caches persist even when jobs fail, time out, or are canceled.

Caching is on by default. To turn it off for a step, set cache to false:

- setup-node:
    with:
      node-version: "22"
      cache: false

With caching left on, later runs restore the Node.js install from the cache instead of downloading it again.

Give coding agents the tools to configure CI correctly

Each Function includes machine-readable definitions of its inputs, including types, required parameters, defaults, and valid values. The definitions come directly from the Function’s code, so they stay aligned with its behavior.

Agents can access the Function catalog through the CircleCI CLI and its built-in MCP server. Developers can use the same commands in a terminal:

# Browse available functions
circleci function list

# Inspect a function and its inputs
circleci function get setup-node

# Add a function to your configuration
circleci function add setup-node

The get command displays the accepted inputs, their types, defaults, and descriptions, giving agents and developers the details needed to configure a Function correctly.

The add command writes a pinned Function declaration to .circleci/config.yml. Once the agent has configured the job, it can check its work before pushing:

circleci config validate

If an agent uses an unsupported argument (like the misspelled node-verison in this example), validation identifies the problem and lists the accepted inputs so the agent can correct the config before running a pipeline.

Agents can correct configuration mistakes before pushing rather than discovering them during a pipeline run. Developers get a configuration they can review and approve without having to debug generated setup scripts.

Functions build on orbs, without replacing them

Orbs remain an important part of CircleCI. An orb can package commands, jobs, and executors, while Functions focus on reusable commands that perform tasks inside a job.

You can use Functions and orbs together in the same pipeline. There’s no migration requirement or planned orb deprecation, and CircleCI will continue developing both.

Agents won’t automatically replace working orbs with Functions. You can ask an agent to use Functions when adding or updating a step in an existing pipeline, though we recommend starting with a new project during the beta.

Ten Functions available in beta

The first release includes ten CircleCI-maintained Functions covering common language, development environment, and tooling setup.

Function	Purpose
setup-node	Set up Node.js
setup-python	Set up Python
setup-go	Set up Go
setup-ruby	Set up Ruby
setup-java	Set up Java
setup-dotnet	Set up .NET
setup-aws	Configure AWS tooling
setup-docker	Set up Docker
setup-browser-tools	Install browser testing tools
setup-github-cli	Set up GitHub CLI

The Functions available today don’t yet cover every capability of their corresponding orbs. Expanding coverage is one of our priorities as we gather beta feedback.

Agent discovery and configuration require CircleCI CLI version 1.8.0 or later.

Help shape what’s next for Functions

We’re launching Functions in beta to learn how they perform in real development workflows. We’re especially interested in missing orb capabilities, how reliably agents find and use the right Functions, and what might prevent teams from adopting them.

You can share your feedback in the Functions beta feedback thread.

We’re also working toward several additional capabilities:

• Custom Functions: Write and share Functions within your organization.
• Step outputs: Pass structured results between steps.
• Local execution: Run Functions on your development machine.
• Expanded catalog: Bring more CircleCI-maintained orb functionality into Functions.

Your feedback will help us prioritize what ships next.

Try CircleCI Functions today

Install the CircleCI CLI to get started.

For Claude Code, connect the CLI’s built-in MCP server:

claude mcp add -s user circleci -- circleci mcp start

For Cursor, VS Code, or Claude Desktop, use:

circleci mcp cursor enable

Replace cursor with vscode or claude for your preferred environment.

Once connected, ask your agent to set up CircleCI for a new project using Functions. It can find the appropriate steps, configure the pipeline, and validate the config before pushing.

For more on getting started, read the CircleCI Functions documentation.

New to CircleCI? Create a free account to try Functions in your next project.