Artifacts: Structured Content Generation

Here is a Go function for handling HTTP requests:

```go
func handleRequest(w http.ResponseWriter, r *http.Request) {
    // ...
}

This output is friendly to humans, but extracting the code block programmatically requires extra parsing logic and is error-prone (for example, the code block may contain explanatory text). The Artifacts mechanism solves this by making the model explicitly mark "this is an independent, extractable content unit."

From an architectural perspective, Artifacts realize the leap from unstructured narrative to structured data in LLM output. This enables:

1. **Frontend rendering optimization**: The UI can use dedicated renderers for different Artifact types (syntax highlighting, chart drawing, table display).
2. **Downstream system integration**: Generated JSON can be consumed directly by APIs, and generated SQL can be executed directly.
3. **Version control and tracking**: Each Artifact has an independent identifier and can be tracked, updated, and rolled back individually.
4. **Multimodal workflows**: One Artifact can be code, while another can be a test case for that code, and references can be established between them.

## Artifacts Architecture in ADK Go

The ADK Go Artifacts system consists of three core components:

**Artifact definition**: describes content metadata such as type, title, and language.
**Artifact content**: the actual data payload (string or binary).
**Artifact handler**: responsible for converting an Artifact into the final output format.

Unlike simple "embedding code blocks in Markdown", Artifacts are first-class citizens at the protocol level. This means the client knows precisely "here is an Artifact of type `application/vnd.go` titled `handler.go`."

## Basic Usage: Enabling Artifact Generation

Enabling Artifacts in ADK Go requires explicitly declaring them in the Agent configuration. Below is a complete, production-ready configuration example:

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "google.golang.org/adk/agent"
    "google.golang.org/adk/artifact"
    "google.golang.org/adk/llm"
)

func main() {
    ctx := context.Background()

    model, err := llm.NewGeminiModel(ctx, llm.GeminiConfig{
        APIKey: os.Get...Y"),
        Model:  "gemini-2.0-pro",
    })
    if err != nil {
        log.Fatalf("Failed to initialize model: %v", err)
    }

    // Register supported Artifact types
    registry := artifact.NewRegistry()
    registry.Register(artifact.TypeCode, artifact.CodeHandler{
        Languages: []string{"go", "python", "javascript", "sql"},
    })
    registry.Register(artifact.TypeMarkdown, artifact.MarkdownHandler{})
    registry.Register(artifact.TypeJSON, artifact.JSONHandler{
        SchemaValidator: true,  // enable JSON Schema validation
    })
    registry.Register(artifact.TypeHTML, artifact.HTMLHandler{
        Sanitize: true,  // apply XSS filtering to HTML
    })

    agent, err := agent.New(agent.Config{
        Name:  "code-generator",
        Model: model,
        Instruction: `You are a full-stack development assistant. When the user requests code, documentation, or configuration, you must output the generated structured content as Artifacts.

Artifact usage rules:
1. Every Artifact must have an explicit type and title.
2. Code Artifacts must specify the programming language.
3. Multiple related files should be output as independent Artifacts.
4. Provide brief explanatory text before and after each Artifact.`,
        Artifacts: artifact.Config{
            Enabled:   true,
            Registry:  registry,
            MaxCount:  10,  // at most 10 Artifacts per response
            MaxSize:   64 * 1024,  // each Artifact up to 64 KB
        },
    })
    if err != nil {
        log.Fatalf("Failed to create Agent: %v", err)
    }

    resp, err := agent.Run(ctx, "Write a Go HTTP service with user registration and login endpoints")
    if err != nil {
        log.Fatalf("Execution failed: %v", err)
    }

    // Iterate over Artifacts in the response
    for _, art := range resp.Artifacts {
        fmt.Printf("Artifact: %s (%s)\n", art.Title, art.Type)
        fmt.Println("---")
        fmt.Println(art.Content)
        fmt.Println("---")
    }
}

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "regexp"

    "google.golang.org/adk/agent"
    "google.golang.org/adk/artifact"
)

// TerraformArtifact represents a Terraform configuration file
type TerraformArtifact struct {
    Title       string
    Content     string
    Provider    string  // aws, gcp, azure
    Resources   []string
}

// TerraformHandler validates and transforms Terraform Artifacts
type TerraformHandler struct {
    // You can inject the Terraform binary path for syntax validation
    TerraformPath string
}

func (h *TerraformHandler) Type() string {
    return "application/vnd.terraform"
}

func (h *TerraformHandler) Validate(art *artifact.Artifact) error {
    // Basic syntax check: ensure valid HCL format
    if !regexp.MustCompile(`^\s*(resource|data|module|variable|output|provider)\s+"`).MatchString(art.Content) {
        return fmt.Errorf("invalid Terraform configuration: missing resource definition")
    }

    // Production recommendation: call terraform validate for full validation
    // Simplified here for the example
    return nil
}

func (h *TerraformHandler) Render(art *artifact.Artifact) (string, error) {
    // Return syntax-highlighted HTML or plain text
    return fmt.Sprintf("```hcl\n%s\n```", art.Content), nil
}

func (h *TerraformHandler) Transform(art *artifact.Artifact, target string) (*artifact.Artifact, error) {
    // Support conversion to other formats, e.g. JSON (equivalent of terraform show -json)
    switch target {
    case "json":
        // Call hcl2json or a similar tool
        return nil, fmt.Errorf("JSON conversion not yet implemented")
    default:
        return nil, fmt.Errorf("unsupported conversion target: %s", target)
    }
}

func main() {
    registry := artifact.NewRegistry()
    registry.Register("application/vnd.terraform", &TerraformHandler{
        TerraformPath: "/usr/local/bin/terraform",
    })

    // ... create Agent and use registry
}

func generateProject(ctx context.Context, agent *agent.Agent, description string) (*Project, error) {
    resp, err := agent.Run(ctx, fmt.Sprintf(`
Generate a complete Go Web project based on the following description:
%s

Requirements:
1. Generate main.go, handlers.go, models.go, and go.mod as separate files
2. Output each file as an independent Artifact
3. Include appropriate error handling and logging
4. Use the standard library net/http and no external dependencies
`, description))
    if err != nil {
        return nil, err
    }

    proj := &Project{Files: make(map[string]string)}
    for _, art := range resp.Artifacts {
        if art.Type != "application/vnd.code" {
            continue
        }
        // Assume the title is the file name
        proj.Files[art.Title] = art.Content
    }

    // Validate project completeness
    requiredFiles := []string{"main.go", "handlers.go", "models.go", "go.mod"}
    for _, f := range requiredFiles {
        if _, ok := proj.Files[f]; !ok {
            return nil, fmt.Errorf("generated project is missing required file: %s", f)
        }
    }

    return proj, nil
}

type Project struct {
    Files map[string]string
}

func (p *Project) WriteToDisk(basePath string) error {
    for filename, content := range p.Files {
        path := filepath.Join(basePath, filename)
        if err := os.WriteFile(path, []byte(content), 0644); err != nil {
            return fmt.Errorf("failed to write %s: %w", filename, err)
        }
    }
    return nil
}

// Declare dependencies in Artifact metadata
art := &artifact.Artifact{
    Title: "main.go",
    Type:  "application/vnd.code",
    Content: mainGoContent,
    Metadata: map[string]interface{}{
        "language": "go",
        "dependencies": []string{"handlers.go", "models.go"},
    },
}

htmlHandler := artifact.HTMLHandler{
    Sanitize: true,
    // Use a strict HTML sanitizer such as bluemonday
    AllowedTags: []string{"p", "br", "strong", "em", "code", "pre"},
    AllowedAttrs: map[string][]string{
        "a": {"href"},
    },
}

func safeExecuteSQL(db *sql.DB, sqlArt *artifact.Artifact) error {
    // 1. Analyze statement type with an SQL parser
    stmt, err := sqlparser.Parse(sqlArt.Content)
    if err != nil {
        return fmt.Errorf("SQL parsing failed: %w", err)
    }

    // 2. Only allow operations on a whitelist
    switch stmt.(type) {
    case *sqlparser.Select:
        // SELECT is safe (read-only)
    default:
        return fmt.Errorf("non-SELECT statements are not allowed")
    }

    // 3. Execute on a read-only replica
    rows, err := db.Query(sqlArt.Content)
    // ...
}

func executeInSandbox(code string, timeout time.Duration) (*SandboxResult, error) {
    ctx, cancel := context.WithTimeout(context.Background(), timeout)
    defer cancel()

    cmd := exec.CommandContext(ctx, "firejail", "--noprofile", "python3", "-c", code)
    cmd.Env = []string{}  // clear environment variables

    output, err := cmd.CombinedOutput()
    // ...
}

func validateArtifacts(artifacts []artifact.Artifact) []ValidationError {
    var errors []ValidationError

    for _, art := range artifacts {
        handler := registry.Get(art.Type)
        if handler == nil {
            errors = append(errors, ValidationError{
                Artifact: art.Title,
                Message:  fmt.Sprintf("unknown Artifact type: %s", art.Type),
            })
            continue
        }

        if err := handler.Validate(&art); err != nil {
            errors = append(errors, ValidationError{
                Artifact: art.Title,
                Message:  err.Error(),
            })
        }
    }

    // Cross-Artifact validation: check reference consistency
    errors = append(errors, validateCrossReferences(artifacts)...)

    return errors
}

func diffArtifacts(old, new []artifact.Artifact) []ArtifactDiff {
    // Match by title and compute text differences
    // Use libraries such as github.com/sergi/go-diff/diffmatchpatch
}