Build an AI Agent

Agentic workflows need repeatability, modularity, observability and cross-platform support. Dagger provides a way to build reproducible workflows in any language with custom environments, parallel processing, and seamless chaining.

This quickstart will guide you through creating and running your first AI agent with Dagger.

The agent will use an LLM of your choosing to solve a programming assignment. The agent will have access to tools to write code and validate it.

Requirements

This quickstart will take you approximately 10 minutes to complete. You should be familiar with programming in Go, Python, TypeScript, PHP, or Java.

Before beginning, ensure that:

• you have installed the Dagger CLI.
• you know the basics of Dagger.
• you have a container runtime installed and running. This can be Docker, but you can also use Podman, nerdctl, or other Docker-like systems.
• you have a GitHub account (optional, only if configuring Dagger Cloud)

tip

Dagger SDKs generate native code-bindings for all dependencies from the Dagger API. If you're using an IDE, this gives you automatic type-checking, code completion and other key features when developing Dagger Functions. Setting up your IDE to work with Dagger is a highly recommended step to improve your experience and benefit from Dagger's universal type system.

Configure the LLM endpoint

Follow the LLM endpoint configuration instructions to configure an LLM for use with Dagger.

info

Use environment variables or a .env file. For example: OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY

Configure Dagger Cloud (optional)

important

This step is optional and will create a Dagger Cloud account, which is free of charge for a single user. If you prefer not to sign up for Dagger Cloud, you can skip this section.

Dagger Cloud is an online visualization tool for Dagger workflows. It provides a web interface to visualize each step of your workflow, drill down to detailed logs, understand how long operations took to run, and whether operations were cached.

Create a new Dagger Cloud account by running dagger login:

dagger login

The Dagger CLI will invite you to authenticate your device by displaying a link containing a unique key. Click the link in your browser, and verify that you see the same key in the Dagger Cloud Web interface.

$ dagger login
Browser opened to: https://auth.dagger.cloud/activate?user_code=FCNP-SRLM
Confirmation code: FCNP-SRLM

Once you confirm your authentication code, your Dagger CLI will be authenticated and you will get redirected to your newly created Dagger Cloud organization.

After successfully creating your organization, all future Dagger workflows can be inspected in Dagger Cloud.

Initialize a Dagger module

In an empty directory, create a new Dagger module. This module will host your agent functions.

You can write your module in Go, Python, TypeScript, PHP, or Java. Choose the SDK you are most comfortable with and run the command below to generate a new Dagger module:

Go

dagger init --sdk=go --name=coding-agent

Python

dagger init --sdk=python --name=coding-agent

TypeScript

dagger init --sdk=typescript --name=coding-agent

PHP

dagger init --sdk=php --name=coding-agent

Java

dagger init --sdk=java --name=coding-agent

This will generate various files that make up the Dagger module, including some boilerplate Dagger Functions as examples.

To see the generated Dagger Functions, run:

dagger functions

You should see information about two auto-generated Dagger Functions: container-echo and grep-dir.

Create the agent

Replace the generated Dagger module files as described below.

Go

Edit the agent (main.go) and replace the generated code with this code:

package main

import (
	"dagger/coding-agent/internal/dagger"
)

type CodingAgent struct{}

// Write a Go program
func (m *CodingAgent) GoProgram(
	// The programming assignment, e.g. "write me a curl clone"
	assignment string,
) *dagger.Container {
	environment := dag.Env().
		WithStringInput("assignment", assignment, "the assignment to complete").
		WithContainerInput("builder",
			dag.Container().From("golang").WithWorkdir("/app"),
			"a container to use for building Go code").
		WithContainerOutput("completed", "the completed assignment in the Golang container")

	work := dag.LLM().
		WithEnv(environment).
		WithPrompt(`
			You are an expert Go programmer with an assignment to create a Go program
			Create files in the default directory in $builder
			Always build the code to make sure it is valid
			Do not stop until your assignment is completed and the code builds
			Your assignment is: $assignment
			`)

	return work.
		Env().
		Output("completed").
		AsContainer()
}

Python

Edit the agent (src/coding_agent/main.py) and replace the generated code with this code:

import dagger
from dagger import dag, function, object_type


@object_type
class CodingAgent:
    @function
    def go_program(
        self,
        assignment: str,
    ) -> dagger.Container:
        """Write a Go program"""
        environment = (
            dag.env()
            .with_string_input("assignment", assignment, "the assignment to complete")
            .with_container_input(
                "builder",
                dag.container().from_("golang").with_workdir("/app"),
                "a container to use for building Go code",
            )
            .with_container_output(
                "completed", "the completed assignment in the Golang container"
            )
        )

        work = (
            dag.llm()
            .with_env(environment)
            .with_prompt(
                """
                You are an expert Go programmer
                with an assignment to create a Go program
                Create files in the default directory in $builder
                Always build the code to make sure it is valid
                Do not stop until your assignment is completed and the code builds
                Your assignment is: $assignment"""
            )
        )

        return work.env().output("completed").as_container()

TypeScript

Edit the agent (src/index.ts) and replace the generated code with this code:

import { dag, object, func, Container } from "@dagger.io/dagger"

@object()
export class CodingAgent {
  /**
   * Write a Go program
   */
  @func()
  goProgram(
    /**
     * The programming assignment, e.g. "write me a curl clone"
     */
    assignment: string,
  ): Container {
    const environment = dag
      .env()
      .withStringInput("assignment", assignment, "the assignment to complete")
      .withContainerInput(
        "builder",
        dag.container().from("golang").withWorkdir("/app"),
        "a container to use for building Go code",
      )
      .withContainerOutput(
        "completed",
        "the completed assignment in the Golang container",
      )

    const work = dag
      .llm()
      .withEnv(environment)
      .withPrompt(
        `You are an expert Go programmer with an assignment to create a Go program
        Create files in the default directory in $builder
        Always build the code to make sure it is valid
        Do not stop until your assignment is completed and the code builds
        Your assignment is: $assignment`,
      )

    return work.env().output("completed").asContainer()
  }
}

PHP

Edit the agent (src/CodingAgent.php) and replace the generated code with this code:

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\DaggerFunction;
use Dagger\Attribute\DaggerObject;
use Dagger\Attribute\Doc;
use Dagger\Container;

use function Dagger\dag;

#[DaggerObject]
#[Doc('A generated module for CodingAgent functions')]
class CodingAgent
{
    #[DaggerFunction]
    #[Doc('Write a Go program')]
    public function goProgram(string $assignment): Container
    {
        $environment = dag()->env()
            ->withStringInput('assignment', $assignment, 'the assignment to complete')
            ->withContainerInput('builder', dag()->container()->from('golang')->withWorkdir('/app'), 'a container to use for building Go code')
            ->withContainerOutput('completed', 'the completed assignment in the Golang container');
        return dag()
            ->llm()
            ->withEnv($environment)
            ->withPrompt('
                You are an expert Go programmer with an assignment to create a Go program
                Create files in the default directory in $builder
                Always build the code to make sure it is valid
                Do not stop until your assignment is completed and the code builds
                Your assignment is: $assignment')
            ->env()
            ->output('completed')
            ->asContainer();
    }
}

Java

Edit the agent (src/main/java/io/dagger/modules/codingagent/CodingAgent.java) and replace the generated code with this code:

package io.dagger.modules.codingagent;

import static io.dagger.client.Dagger.dag;

import io.dagger.client.Container;
import io.dagger.client.Env;
import io.dagger.module.annotation.Function;
import io.dagger.module.annotation.Object;

/** CodingAgent main object */
@Object
public class CodingAgent {
  /** Write a Go program */
  @Function
  public Container goProgram(String assignment) {
    Env environment = dag().env()
        .withStringInput("assignment", assignment, "the assignment to complete")
        .withContainerInput("builder", dag().container().from("golang").withWorkdir("/app"), "a container to use for building Go code")
        .withContainerOutput("completed", "the completed assignment in the Golang container");
    return dag()
      .llm()
      .withEnv(environment)
      .withPrompt("""
        You are an expert Go programmer with an assignment to create a Go program
        Create files in the default directory in $builder
        Always build the code to make sure it is valid
        Do not stop until your assignment is completed and the code builds
        Your assignment is: $assignment
        """)
      .env()
      .output("completed")
      .asContainer();
  }
}

This code creates a Dagger Function called go-program that takes an assignment as input and returns a Container with the result of the assignment.

• The variable environment is the environment to define inputs and outputs for the agent. Each input and output provides a description which acts as a declarative form of prompting.
• The input builder is a Container. This provides a workspace for the agent to create files and execute commands like go build.
• The output completed signals the agent that it should return a Container representing the completed assignment
• The environment is given to an instance of an LLM with a prompt describing how it should complete its work. Prompting can vary depending on which model is being used, and generally requires some experimentation.
• When the LLM decides it is finished, the completed container is selected from the Env outputs and returned.

tip

Learn more about agent environments.

Run the agent

Dagger Shell is the fastest way to interact with the Dagger API, allowing access to both core types and custom Dagger Functions using a familiar Bash-like syntax. Type dagger to launch Dagger Shell in interactive mode.

Check the help text for the new Dagger Function:

.help go-program

This should show how to use the go-program function.

Make sure your LLM provider has been properly configured:

llm | model

This should show the model you've configured to use with your provider.

Call the Dagger Function with an assignment:

go-program "write a curl clone"

You'll see the agent receive the prompt, write code, validate it, and return a Container with the result.

If you signed up for Dagger Cloud, the output of the previous command would have also included a link to visualize the workflow run on Dagger Cloud. Click the link in your browser to see a complete breakdown of the steps performed by the agent.

If the agent fails to write code that passes validation, try adding more helpful guidance to the prompt. If you see an error like "binding value is nil" this means that the LLM did not return a value for completed. Try adjusting the prompt to make sure the LLM completes the assignment and returns a Container.

Once the agent has successfully returned a Container, open an interactive terminal in the container so that you can inspect its work and run the generated code. Notice that the solution is not recomputed since it is still cached from the previous execution:

go-program "write a curl clone" | terminal

Run the program and confirm that it works. This will look slightly different depending on how the LLM wrote the code:

> ls
# should see a main.go and a go.mod, maybe other files
> go run main.go https://example.com

If the program does not look or function as you expect, try adjusting the prompt and input descriptions until you get the desired result.

Next steps

Congratulations! You've created your first AI coding agent. You can now use this agent to solve coding prompts using an LLM.

Now that you've grasped the basics of building an agent, look at the AI Agent examples for more examples and ideas for your next agent.

In the meantime, we encourage you to join our awesome community on Discord to introduce yourself and ask questions. And starring our GitHub repository is always appreciated!