Kingsmen Agent Curl Tutorial 🎩

This tutorial shows how to interact with the Kingsmen agent team using curl commands. You'll learn how to send tasks, manage sessions, and work with the A2A protocol directly.

Prerequisites

Start the Kingsmen server:

export OPENAI_API_KEY="your-api-key-here"
python -m a2a_server.run

Verify the server is running:

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "timestamp": "2024-01-XX", 
  "handlers": ["kingsmen_agent", "supervisor_agent", ...]
}

Quick Start - Interactive Examples

For a quick interactive demo of all the examples, run:

./docs/examples/kingsmen_curl_examples.sh

This interactive script lets you try all the examples with a simple menu interface.

Basic Agent Information
Sending Tasks
Session Management
Streaming Responses
Team-Specific Examples
Error Handling
Advanced Usage

Basic Agent Information

Get Agent Card

Retrieve the Kingsmen agent's capabilities and information:

curl -X GET http://localhost:8000/kingsmen_agent/.well-known/agent.json | jq

Expected response:

{
  "name": "The Kingsmen 🎩",
  "description": "An elite team of IBM Cloud specialists - Galahad, Lancelot, Percival, Gareth, and Tristan",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "elite_team_coordination",
      "name": "🎩 Elite Team Coordination",
      "description": "Coordinates an elite team of IBM Cloud specialists..."
    }
  ]
}

Sending Tasks

Basic Task Submission

Send a simple task to the Kingsmen:

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "task-001",
    "sessionId": "session-123",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "I need help setting up a new IBM Cloud resource group"
        }
      ]
    },
    "acceptedOutputModes": ["text/plain"],
    "metadata": {
      "conversation_id": "conv-001"
    }
  }' | jq

Expected response structure:

{
  "result": {
    "id": "task-001",
    "sessionId": "session-123",
    "status": {
      "state": "completed",
      "message": {
        "role": "assistant",
        "parts": [
          {
            "text": "[Handled by Galahad] I'll help you set up a new resource group..."
          }
        ]
      }
    }
  }
}

Request Specific Agent by Codename

Direct a request to a specific Kingsman:

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "task-002", 
    "sessionId": "session-123",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "Have Lancelot create a new service ID for my application"
        }
      ]
    },
    "acceptedOutputModes": ["text/plain"]
  }' | jq

Security and Access Management Task

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "task-003",
    "sessionId": "session-security",
    "message": {
      "role": "user", 
      "parts": [
        {
          "text": "I need to add a new user to my account with editor permissions for the development resource group"
        }
      ]
    },
    "acceptedOutputModes": ["text/plain"],
    "metadata": {
      "task_type": "user_management",
      "priority": "high"
    }
  }' | jq

Serverless Application Request

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "task-004",
    "sessionId": "session-serverless", 
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "Create a Code Engine application that scales from 0 to 10 instances based on HTTP requests"
        }
      ]
    },
    "acceptedOutputModes": ["text/plain"]
  }' | jq

Session Management

Start a New Session

# Create session variable
SESSION_ID="kingsmen-$(date +%s)"
echo "Session ID: $SESSION_ID"

# First message in session
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"task-session-001\",
    \"sessionId\": \"$SESSION_ID\",
    \"message\": {
      \"role\": \"user\",
      \"parts\": [
        {
          \"text\": \"Hello Kingsmen team! I'm setting up a new IBM Cloud environment for my company.\"
        }
      ]
    },
    \"acceptedOutputModes\": [\"text/plain\"]
  }" | jq

Continue Session Conversation

# Follow-up message in the same session
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"task-session-002\", 
    \"sessionId\": \"$SESSION_ID\",
    \"message\": {
      \"role\": \"user\",
      \"parts\": [
        {
          \"text\": \"Now I need to add three developers to the account with appropriate permissions.\"
        }
      ]
    },
    \"acceptedOutputModes\": [\"text/plain\"]
  }" | jq

Get Session History

curl -X GET "http://localhost:8000/kingsmen_agent/sessions/$SESSION_ID/history" | jq

Streaming Responses

Enable Streaming for Real-time Responses

curl -X POST http://localhost:8000/kingsmen_agent/task/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "id": "stream-task-001",
    "sessionId": "stream-session",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "Explain the step-by-step process to set up a complete IBM Cloud development environment with proper governance"
        }
      ]
    },
    "acceptedOutputModes": ["text/plain"]
  }' \
  --no-buffer

Expected streaming response:

data: {"event": "task_status_update", "data": {"state": "running", "message": {"role": "assistant", "parts": [{"text": "Analyzing your request..."}]}}}

data: {"event": "task_status_update", "data": {"state": "running", "message": {"role": "assistant", "parts": [{"text": "Deploying Galahad for infrastructure setup..."}]}}}

data: {"event": "task_status_update", "data": {"state": "completed", "message": {"role": "assistant", "parts": [{"text": "[Handled by Galahad] Here's the step-by-step process..."}]}}}

data: [DONE]

Team-Specific Examples

Infrastructure Setup (Galahad)

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "infra-001",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "List all resource groups in my account and show me which services are in each one"
        }
      ]
    }
  }' | jq '.result.status.message.parts[0].text'

Security Operations (Lancelot)

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "security-001",
    "message": {
      "role": "user", 
      "parts": [
        {
          "text": "Show me all access groups and their members. I want to audit who has access to what."
        }
      ]
    }
  }' | jq '.result.status.message.parts[0].text'

Serverless Applications (Percival)

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "serverless-001", 
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "Deploy a Python Flask application to Code Engine with automatic scaling and custom domain"
        }
      ]
    }
  }' | jq

Best Practices Guidance (Gareth)

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "guidance-001",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "What are the IBM Cloud best practices for organizing resources for a multi-environment development workflow?"
        }
      ]
    }
  }' | jq

Automation & DevOps (Tristan)

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "automation-001",
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "Create a Terraform-based deployable architecture for a 3-tier web application with database"
        }
      ]
    }
  }' | jq

Error Handling

Invalid Task Format

curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "bad-task",
    "message": "This is not a proper message format"
  }' | jq

Expected error response:

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid message format",
    "details": "Message must have role and parts fields"
  }
}

Check Task Status

curl -X GET http://localhost:8000/kingsmen_agent/tasks/task-001/status | jq

Cancel Running Task

curl -X POST http://localhost:8000/kingsmen_agent/tasks/task-001/cancel \
  -H "Content-Type: application/json" | jq

Advanced Usage

Batch Task Submission

Submit multiple tasks for different Kingsmen:

# Submit multiple tasks in sequence
TASKS=(
  '{"id": "batch-001", "message": {"role": "user", "parts": [{"text": "Galahad, list my resource groups"}]}}'
  '{"id": "batch-002", "message": {"role": "user", "parts": [{"text": "Lancelot, show my service IDs"}]}}'  
  '{"id": "batch-003", "message": {"role": "user", "parts": [{"text": "Percival, list my Code Engine projects"}]}}'
)

for task in "${TASKS[@]}"; do
  echo "Submitting: $task"
  curl -X POST http://localhost:8000/kingsmen_agent/task \
    -H "Content-Type: application/json" \
    -d "$task" | jq '.result.status.state'
  echo "---"
done

Complex Multi-Step Workflow

# Step 1: Planning phase
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "workflow-001",
    "sessionId": "complex-workflow",
    "message": {
      "role": "user", 
      "parts": [
        {
          "text": "I need to set up a complete development environment with: 1) Resource groups for dev/test/prod, 2) Service accounts for automation, 3) A serverless API, 4) Monitoring and logging. Can you coordinate this across the team?"
        }
      ]
    }
  }' | jq

# Step 2: Follow up on specific aspects
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{
    "id": "workflow-002",
    "sessionId": "complex-workflow", 
    "message": {
      "role": "user",
      "parts": [
        {
          "text": "Now implement the resource group structure you just planned"
        }
      ]
    }
  }' | jq

Health Check and Status

# Check overall health
curl http://localhost:8000/health | jq

# Check specific agent health  
curl http://localhost:8000/kingsmen_agent/health | jq

# Get metrics (if available)
curl http://localhost:8000/kingsmen_agent/metrics | jq

Useful Shell Functions

Add these to your .bashrc or .zshrc for easier testing:

# Quick task submission
kingsmen_task() {
  local message="$1"
  local task_id="${2:-task-$(date +%s)}"
  
  curl -X POST http://localhost:8000/kingsmen_agent/task \
    -H "Content-Type: application/json" \
    -d "{
      \"id\": \"$task_id\",
      \"message\": {
        \"role\": \"user\",
        \"parts\": [
          {
            \"text\": \"$message\"
          }
        ]
      }
    }" | jq '.result.status.message.parts[0].text' -r
}

# Usage: kingsmen_task "List my resource groups"

# Stream task with real-time output
kingsmen_stream() {
  local message="$1"
  
  curl -X POST http://localhost:8000/kingsmen_agent/task/stream \
    -H "Content-Type: application/json" \
    -H "Accept: text/event-stream" \
    -d "{
      \"id\": \"stream-$(date +%s)\",
      \"message\": {
        \"role\": \"user\",
        \"parts\": [
          {
            \"text\": \"$message\"
          }
        ]
      }
    }" --no-buffer
}

# Direct agent requests
galahad() { kingsmen_task "Galahad, $1"; }
lancelot() { kingsmen_task "Lancelot, $1"; }
percival() { kingsmen_task "Percival, $1"; }
gareth() { kingsmen_task "Gareth, $1"; } 
tristan() { kingsmen_task "Tristan, $1"; }

# Usage examples:
# galahad "list my resource groups"
# lancelot "show my access groups"
# percival "list my Code Engine projects"

Testing Scenarios

Complete Development Setup

#!/bin/bash
# Complete development environment setup test

SESSION="dev-setup-$(date +%s)"

echo "🎩 Starting complete development setup with session: $SESSION"

# Step 1: Resource planning
echo "📋 Step 1: Planning resources..."
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"setup-001\",
    \"sessionId\": \"$SESSION\",
    \"message\": {
      \"role\": \"user\",
      \"parts\": [
        {
          \"text\": \"I need to plan a development environment with separate resource groups for dev, test, and production. What's the best structure?\"
        }
      ]
    }
  }" | jq '.result.status.message.parts[0].text' -r

echo -e "\n⚔️ Step 2: Setting up security..."
# Step 2: Security setup
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"setup-002\", 
    \"sessionId\": \"$SESSION\",
    \"message\": {
      \"role\": \"user\",
      \"parts\": [
        {
          \"text\": \"Now create service IDs and access groups for each environment with appropriate permissions\"
        }
      ]
    }
  }" | jq '.result.status.message.parts[0].text' -r

echo -e "\n🚀 Step 3: Serverless setup..."
# Step 3: Serverless application
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"setup-003\",
    \"sessionId\": \"$SESSION\", 
    \"message\": {
      \"role\": \"user\",
      \"parts\": [
        {
          \"text\": \"Deploy a sample API application to Code Engine in the development environment\"
        }
      ]
    }
  }" | jq '.result.status.message.parts[0].text' -r

echo -e "\n🤖 Step 4: Automation setup..."  
# Step 4: Automation
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d "{
    \"id\": \"setup-004\",
    \"sessionId\": \"$SESSION\",
    \"message\": {
      \"role\": \"user\",
      \"parts\": [
        {
          \"text\": \"Create a CI/CD pipeline to deploy from dev to test to production\"
        }
      ]
    }
  }" | jq '.result.status.message.parts[0].text' -r

echo -e "\n✅ Development setup complete!"

Troubleshooting

Common Issues

Connection refused:

# Check if server is running
ps aux | grep "a2a_server"
curl http://localhost:8000/health

Authentication errors:

# Check API key is set
echo $OPENAI_API_KEY

# Verify agent configuration
curl http://localhost:8000/kingsmen_agent/.well-known/agent.json | jq '.capabilities'

Task timeout:

# Check task status
curl http://localhost:8000/kingsmen_agent/tasks/your-task-id/status

Invalid response format:

# Validate request format
echo '{
  "id": "test",
  "message": {
    "role": "user", 
    "parts": [{"text": "test"}]
  }
}' | jq .

Summary

This tutorial covered:

✅ Basic agent information retrieval
✅ Task submission and management
✅ Session-based conversations
✅ Streaming responses
✅ Team-specific task routing
✅ Error handling and troubleshooting
✅ Advanced workflows and automation
✅ Practical shell functions and scripts

The Kingsmen team is now ready to handle your IBM Cloud operations via the A2A protocol! 🎩

Quick Start:

# Test the team
curl -X POST http://localhost:8000/kingsmen_agent/task \
  -H "Content-Type: application/json" \
  -d '{"id":"test","message":{"role":"user","parts":[{"text":"Hello Kingsmen team!"}]}}' | jq

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Kingsmen Agent Curl Tutorial 🎩

Prerequisites

Quick Start - Interactive Examples

Table of Contents

Basic Agent Information

Get Agent Card

Sending Tasks

Basic Task Submission

Request Specific Agent by Codename

Security and Access Management Task

Serverless Application Request

Session Management

Start a New Session

Continue Session Conversation

Get Session History

Streaming Responses

Enable Streaming for Real-time Responses

Team-Specific Examples

Infrastructure Setup (Galahad)

Security Operations (Lancelot)

Serverless Applications (Percival)

Best Practices Guidance (Gareth)

Automation & DevOps (Tristan)

Error Handling

Invalid Task Format

Check Task Status

Cancel Running Task

Advanced Usage

Batch Task Submission

Complex Multi-Step Workflow

Health Check and Status

Useful Shell Functions

Testing Scenarios

Complete Development Setup

Troubleshooting

Common Issues

Summary

FilesExpand file tree

KINGSMEN_CURL_TUTORIAL.md

Latest commit

History

KINGSMEN_CURL_TUTORIAL.md

File metadata and controls

Kingsmen Agent Curl Tutorial 🎩

Prerequisites

Quick Start - Interactive Examples

Table of Contents

Basic Agent Information

Get Agent Card

Sending Tasks

Basic Task Submission

Request Specific Agent by Codename

Security and Access Management Task

Serverless Application Request

Session Management

Start a New Session

Continue Session Conversation

Get Session History

Streaming Responses

Enable Streaming for Real-time Responses

Team-Specific Examples

Infrastructure Setup (Galahad)

Security Operations (Lancelot)

Serverless Applications (Percival)

Best Practices Guidance (Gareth)

Automation & DevOps (Tristan)

Error Handling

Invalid Task Format

Check Task Status

Cancel Running Task

Advanced Usage

Batch Task Submission

Complex Multi-Step Workflow

Health Check and Status

Useful Shell Functions

Testing Scenarios

Complete Development Setup

Troubleshooting

Common Issues

Summary