feat: Add artifact server support with MinIO integration and update documentation

Signed-off-by: Eden Reich <eden.reich@gmail.com>

Author: edenreich

.adl-ignore

@@ -17,9 +17,6 @@ skills/validate.go
 
 main.go
 
-# Mock implementations
-internal/mock/
-
 # Go dependency files
 go.mod
 

README.md

@@ -81,6 +81,20 @@ Configure the agent via environment variables:
 | **Storage** | `A2A_QUEUE_URL` | Redis connection URL (when using Redis) | - |
 | **Storage** | `A2A_QUEUE_MAX_SIZE` | Maximum queue size | `100` |
 | **Storage** | `A2A_QUEUE_CLEANUP_INTERVAL` | Task cleanup interval | `30s` |
+| **Artifacts** | `ARTIFACTS_ENABLE` | Enable artifacts support | `false` |
+| **Artifacts** | `ARTIFACTS_SERVER_HOST` | Artifacts server host | `localhost` |
+| **Artifacts** | `ARTIFACTS_SERVER_PORT` | Artifacts server port | `8081` |
+| **Artifacts** | `ARTIFACTS_STORAGE_PROVIDER` | Storage backend (`filesystem` or `minio`) | `filesystem` |
+| **Artifacts** | `ARTIFACTS_STORAGE_BASE_PATH` | Base path for filesystem storage | `./artifacts` |
+| **Artifacts** | `ARTIFACTS_STORAGE_BASE_URL` | Override base URL for direct downloads | (auto-generated) |
+| **Artifacts** | `ARTIFACTS_STORAGE_ENDPOINT` | MinIO/S3 endpoint URL | - |
+| **Artifacts** | `ARTIFACTS_STORAGE_ACCESS_KEY` | MinIO/S3 access key | - |
+| **Artifacts** | `ARTIFACTS_STORAGE_SECRET_KEY` | MinIO/S3 secret key | - |
+| **Artifacts** | `ARTIFACTS_STORAGE_BUCKET_NAME` | MinIO/S3 bucket name | `artifacts` |
+| **Artifacts** | `ARTIFACTS_STORAGE_USE_SSL` | Use SSL for MinIO/S3 connections | `true` |
+| **Artifacts** | `ARTIFACTS_RETENTION_MAX_ARTIFACTS` | Max artifacts per task (0 = unlimited) | `5` |
+| **Artifacts** | `ARTIFACTS_RETENTION_MAX_AGE` | Max artifact age (0 = no age limit) | `7d` |
+| **Artifacts** | `ARTIFACTS_RETENTION_CLEANUP_INTERVAL` | Cleanup frequency (0 = manual only) | `24h` |
 | **Authentication** | `A2A_AUTH_ENABLE` | Enable OIDC authentication | `false` |
 
 ## Development

agent.yaml

@@ -10,6 +10,8 @@ spec:
     streaming: true
     pushNotifications: false
     stateTransitionHistory: false
+  artifacts:
+    enabled: true
   agent:
     provider: ""
     model: ""

example/README.md

@@ -9,6 +9,7 @@ This example demonstrates how to use the mock-agent for testing and development.
 - **5 Testing Skills** - Pre-configured skills for various testing scenarios
 - **Fast & Reliable** - Instant, predictable responses perfect for testing
 - **A2A Protocol Compliant** - Full implementation of the A2A protocol
+- **Artifact Server** - MinIO-backed artifact storage for testing file artifacts
 
 ## Quick Start
 
@@ -188,6 +189,63 @@ docker compose run --rm a2a-debugger tasks submit 'Generate 10 test email addres
 docker compose run --rm a2a-debugger tasks submit 'Generate 3 JSON objects for testing'
 ```
 
+### Testing Artifacts
+
+The mock agent includes a fully operational artifact server with MinIO storage backend:
+
+```bash
+# Verify artifact server is running
+curl http://localhost:8081/health
+# Response: {"status":"ok","time":"2025-10-19T17:37:20Z"}
+
+# Verify artifact service is initialized
+docker compose logs mock-agent | grep "artifact service initialized"
+# Should show: artifact service initialized with MinIO storage
+
+# Submit a task
+docker compose run --rm a2a-debugger tasks submit 'Please create an artifact with sample data'
+```
+
+**Infrastructure Status:**
+- ✅ Artifact server running on port 8081
+- ✅ MinIO storage backend connected (minio:9000)
+- ✅ Artifact service initialized successfully
+- ✅ Download endpoint: `GET /artifacts/:artifactId/:filename`
+- ✅ `create_artifact` tool available to LLM
+
+**How Artifacts Work:**
+1. The ADK automatically provides a `create_artifact` tool to the LLM
+2. When the LLM calls this tool, artifacts are stored in MinIO
+3. The artifact metadata (ID, download URL) is returned to the client
+4. Clients download artifacts from `:8081/artifacts/:artifactId/:filename`
+
+**Testing with Real LLM:**
+The mock LLM is designed for testing A2A protocol infrastructure without API costs. To test actual artifact creation:
+
+1. Replace mock LLM with a real provider in `main.go`:
+   ```go
+   // Instead of:
+   llmClient := mock.NewMockLLMClient()
+
+   // Use:
+   llmClient, err := server.NewOpenAICompatibleLLMClient(&cfg.A2A.AgentConfig, l)
+   ```
+
+2. Set environment variables:
+   ```bash
+   A2A_AGENT_CLIENT_PROVIDER=openai
+   A2A_AGENT_CLIENT_API_KEY=your-key
+   A2A_AGENT_CLIENT_MODEL=gpt-4
+   ```
+
+3. The LLM will then call `create_artifact` and store files in MinIO
+
+Access MinIO console to view/manage artifacts:
+```bash
+# Open in browser: http://localhost:9001
+# Credentials: minioadmin / minioadmin
+```
+
 ## Monitoring and Debugging
 
 ### View Agent Logs
@@ -219,19 +277,45 @@ docker compose down
 ## Architecture
 
 ```
-┌─────────────┐         ┌──────────────┐
-│ a2a-debugger│────────>│  mock-agent  │
-│    (CLI)    │  A2A    │   :8080      │
-└─────────────┘ Protocol└──────────────┘
-                               │
-                               v
-                        ┌──────────────┐
-                        │ Mock LLM     │
-                        │ Client       │
-                        │ (No API Key) │
-                        └──────────────┘
+┌─────────────┐   A2A Protocol  ┌──────────────┐
+│ a2a-debugger│────────────────>│  mock-agent  │
+│ (A2A Client)│                 │ (A2A Server) │
+│             │                 │   :8080      │
+│             │                 └──────┬───────┘
+│             │                        │
+│             │                        │ Uses
+│             │                        v
+│             │                 ┌──────────────┐
+│             │                 │  Mock LLM    │
+│             │                 │   Client     │
+│             │                 │ (Generates   │
+│             │                 │  Artifacts)  │
+│             │                 └──────┬───────┘
+│             │                        │
+│             │                        │ Stores
+│             │                        v
+│             │  Download        ┌──────────────┐
+│             │  Artifacts       │   MinIO      │
+│             │<─────────────────│   :9000      │
+└─────────────┘  via :8081       └──────────────┘
+                 Artifact Server
 ```
 
+## Services
+
+This example runs the following services:
+
+1. **mock-agent** (:8080) - The main A2A agent server with Mock LLM client
+2. **artifacts-server** (:8081) - HTTP server for clients to download generated artifacts
+3. **minio** (:9000, :9001) - Object storage backend where artifacts are stored
+4. **a2a-debugger** - CLI tool for interacting with the agent (manual profile)
+
+The flow is:
+1. Client sends request to mock-agent via A2A protocol
+2. Mock LLM generates artifacts and stores them in MinIO
+3. Mock-agent returns artifact metadata to client
+4. Client downloads artifacts from artifact server (:8081) which retrieves them from MinIO
+
 ## Why Use the Mock Agent?
 
 ✅ **No API Costs** - Completely free to run

example/docker-compose.yaml

@@ -1,5 +1,25 @@
 ---
 services:
+  minio:
+    image: minio/minio:latest
+    container_name: mock-agent-minio
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    networks:
+      - mock-network
+    volumes:
+      - minio-data:/data
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
   mock-agent:
     build:
       context: ..
@@ -26,10 +46,28 @@ services:
       A2A_QUEUE_MAX_SIZE: 1000
       A2A_QUEUE_CLEANUP_INTERVAL: 1h
       A2A_AUTH_ENABLE: false
+      A2A_AGENT_CLIENT_TOOLS_CREATE_ARTIFACT: "true"
+      A2A_ARTIFACTS_ENABLE: "true"
+      A2A_ARTIFACTS_SERVER_HOST: "0.0.0.0"
+      A2A_ARTIFACTS_SERVER_PORT: "8081"
+      A2A_ARTIFACTS_STORAGE_PROVIDER: minio
+      A2A_ARTIFACTS_STORAGE_ENDPOINT: minio:9000
+      A2A_ARTIFACTS_STORAGE_ACCESS_KEY: minioadmin
+      A2A_ARTIFACTS_STORAGE_SECRET_KEY: minioadmin
+      A2A_ARTIFACTS_STORAGE_BUCKET_NAME: artifacts
+      A2A_ARTIFACTS_STORAGE_USE_SSL: "false"
+      A2A_ARTIFACTS_STORAGE_BASE_URL: http://localhost:9000
+      A2A_ARTIFACTS_RETENTION_MAX_ARTIFACTS: "10"
+      A2A_ARTIFACTS_RETENTION_MAX_AGE: 168h
+      A2A_ARTIFACTS_RETENTION_CLEANUP_INTERVAL: 24h
     ports:
       - "8080:8080"
+      - "8081:8081"
     networks:
       - mock-network
+    depends_on:
+      minio:
+        condition: service_healthy
     healthcheck:
       test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:8080/health"]
       interval: 10s
@@ -57,3 +95,7 @@ services:
 networks:
   mock-network:
     driver: bridge
+
+volumes:
+  minio-data:
+    driver: local

internal/mock/llm_client.go

@@ -317,6 +317,41 @@ func generateMockToolCalls(tools []sdk.ChatCompletionTool, userMessage string) [
 		}
 	}
 
+	if contains(lowerMsg, "artifact") || contains(lowerMsg, "create file") || contains(lowerMsg, "save file") {
+		for _, tool := range tools {
+			if tool.Function.Name == "create_artifact" {
+				name := "sample-data.json"
+				content := `{"id": 1, "name": "John Doe", "email": "john.doe@example.com"}`
+
+				if contains(lowerMsg, "text") || contains(lowerMsg, "txt") {
+					name = "sample-data.txt"
+					content = "This is a sample text artifact created by the mock agent."
+				} else if contains(lowerMsg, "csv") {
+					name = "sample-data.csv"
+					content = "id,name,email\n1,John Doe,john.doe@example.com\n2,Jane Smith,jane.smith@example.com"
+				}
+
+				args, _ := json.Marshal(map[string]any{
+					"name":     name,
+					"content":  content,
+					"type":     "url",
+					"filename": name,
+				})
+
+				return []sdk.ChatCompletionMessageToolCall{
+					{
+						Id:   "call-" + generateID(),
+						Type: sdk.Function,
+						Function: sdk.ChatCompletionMessageToolCallFunction{
+							Name:      "create_artifact",
+							Arguments: string(args),
+						},
+					},
+				}
+			}
+		}
+	}
+
 	if contains(lowerMsg, "random") || contains(lowerMsg, "generate") {
 		for _, tool := range tools {
 			if tool.Function.Name == "random_data" {
@@ -359,6 +394,31 @@ func generateMockToolCalls(tools []sdk.ChatCompletionTool, userMessage string) [
 		}
 	}
 
+	for _, tool := range tools {
+		if tool.Function.Name == "create_artifact" {
+			name := "default-file.json"
+			content := `{"message": "Default artifact content"}`
+
+			args, _ := json.Marshal(map[string]any{
+				"name":     name,
+				"content":  content,
+				"type":     "url",
+				"filename": name,
+			})
+
+			return []sdk.ChatCompletionMessageToolCall{
+				{
+					Id:   "call-" + generateID(),
+					Type: sdk.Function,
+					Function: sdk.ChatCompletionMessageToolCallFunction{
+						Name:      "create_artifact",
+						Arguments: string(args),
+					},
+				},
+			}
+		}
+	}
+
 	for _, tool := range tools {
 		if tool.Function.Name == "echo" {
 			args, _ := json.Marshal(map[string]any{