A2A 메시지 요청

llamon 에이전트 런타임은 A2A 0.3.0 호환 JSON-RPC message/send 요청을 받습니다.

기본 요청

curl -s -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "messageId": "msg-001",
        "contextId": "demo",
        "role": "user",
        "parts": [
          { "kind": "text", "text": "안녕하세요" }
        ]
      }
    }
  }'

필드

필드	필수	설명
`jsonrpc`	필수	`"2.0"`
`id`	필수	JSON-RPC 요청 ID
`method`	필수	`"message/send"`
`params.message.messageId`	필수	메시지별 고유 ID
`params.message.contextId`	권장	대화/세션 ID. 대화를 이어가려면 같은 값을 계속 사용
`params.message.role`	필수	사용자 입력은 `"user"`
`params.message.parts`	필수	`TextPart`, `DataPart`, `FilePart` 메시지 본문

messageId는 메시지마다 새 값을 사용하고, contextId는 같은 대화를 이어갈 때 같은 값을 사용합니다.

Part 종류

TextPart

자연어 질의나 지시사항을 보낼 때 사용합니다.

{
  "kind": "text",
  "text": "이 문서를 요약해줘"
}

DataPart

구조화된 JSON 객체를 보낼 때 사용합니다. 파일 ID처럼 수신측 시스템이 따로 조회할 참조값도 DataPart에 담습니다.

{
  "kind": "data",
  "data": {
    "schema": "document.review.v1",
    "documentId": "doc-123",
    "locale": "ko-KR",
    "options": {
      "includeSummary": true
    }
  }
}

FilePart — URI

대용량 파일은 접근 가능한 URI를 전달합니다.

{
  "kind": "file",
  "file": {
    "uri": "https://storage.example.com/files/report.pdf",
    "name": "report.pdf",
    "mimeType": "application/pdf"
  }
}

FilePart — bytes

소용량 파일은 base64 문자열로 인라인 전달할 수 있습니다.

{
  "kind": "file",
  "file": {
    "bytes": "SGVsbG8=",
    "name": "hello.txt",
    "mimeType": "text/plain"
  }
}

FilePart.file에는 uri 또는 bytes 중 하나만 넣습니다. 내부 파일 식별자만 전달할 때는 FilePart가 아니라 DataPart를 사용하세요.

혼합 요청

하나의 메시지에 TextPart, DataPart, FilePart를 함께 넣을 수 있습니다.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "messageId": "msg-003",
      "contextId": "demo",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "첨부 파일과 옵션을 기준으로 리포트를 만들어줘"
        },
        {
          "kind": "file",
          "file": {
            "uri": "https://storage.example.com/files/data.csv",
            "name": "data.csv",
            "mimeType": "text/csv"
          }
        },
        {
          "kind": "data",
          "data": {
            "format": "xlsx",
            "locale": "ko-KR",
            "includeSummary": true
          }
        }
      ]
    }
  }
}

사용자 메타데이터

사용자 식별자나 라우팅 정보는 params.metadata에 넣습니다.

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "metadata": {
      "userId": "user-123"
    },
    "message": {
      "messageId": "msg-002",
      "contextId": "demo",
      "role": "user",
      "parts": [
        { "kind": "text", "text": "이전 대화 이어서 답해줘" }
      ]
    }
  }
}

message.metadata가 아니라 params.metadata에 넣어야 SDK의 세션 식별 로직이 인식합니다.