REST Resource: tasks

리소스: Task

Task는 A2A의 핵심 작업 단위입니다. 현재 상태가 있으며 작업의 결과가 생성되면 아티팩트에 저장됩니다. 작업에 여러 턴이 있는 경우 기록에 저장됩니다.

JSON 표현 
{
  "id": string,
  "contextId": string,
  "status": {
    object (TaskStatus)
  },
  "artifacts": [
    {
      object (Artifact)
    }
  ],
  "history": [
    {
      object (Message)
    }
  ],
  "metadata": {
    object
  }
}
필드
id

string

필수 항목입니다. 새 작업에 대해 서버에서 생성한 작업의 고유 식별자 (예: UUID)입니다.
contextId

string

상호작용 (작업 및 메시지)의 컨텍스트 컬렉션에 대한 고유 식별자 (예: UUID)입니다.
status

object (TaskStatus)

필수 항목입니다. state 및 message을 포함한 Task의 현재 상태입니다.
artifacts[]

object (Artifact)

Task의 출력 아티팩트 집합입니다.
history[]

object (Message)

protolint:disable REPEATED_FIELD_NAMES_PLURALIZED Task의 상호작용 기록입니다.
metadata

object (Struct format)

protolint:enable REPEATED_FIELD_NAMES_PLURALIZED 작업에 관한 맞춤 메타데이터를 저장하는 키/값 객체입니다.

TaskStatus

작업 상태의 컨테이너

JSON 표현 
{
  "state": enum (TaskState),
  "message": {
    object (Message)
  },
  "timestamp": string
}
필드
state

enum (TaskState)

필수 항목입니다. 이 작업의 현재 상태입니다.
message

object (Message)

상태와 관련된 메시지입니다.
timestamp

string (Timestamp format)

상태가 기록된 ISO 8601 타임스탬프입니다. 예: '2023-10-27T10:00:00Z'

생성된 출력은 항상 Z-정규화되고 소수점 이하 0, 3, 6 또는 9자리인 RFC 3339를 사용합니다. 'Z' 이외의 오프셋도 허용됩니다. 예를 들면 "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" 또는 "2014-10-02T15:01:23+05:30"입니다.

TaskState

Task의 가능한 수명 주기 상태를 정의합니다.

열거형
TASK_STATE_UNSPECIFIED 작업이 알 수 없거나 불확실한 상태입니다.
TASK_STATE_SUBMITTED 작업이 제출되고 확인되었음을 나타냅니다.
TASK_STATE_WORKING 태스크가 에이전트에 의해 적극적으로 처리되고 있음을 나타냅니다.
TASK_STATE_COMPLETED 작업이 성공적으로 완료되었음을 나타냅니다. 이는 터미널 상태입니다.
TASK_STATE_FAILED 작업이 오류와 함께 완료되었음을 나타냅니다. 이는 터미널 상태입니다.
TASK_STATE_CANCELED 작업이 완료되기 전에 취소되었음을 나타냅니다. 이는 터미널 상태입니다.
TASK_STATE_INPUT_REQUIRED 계속 진행하려면 에이전트에 추가 사용자 입력이 필요함을 나타냅니다. 이는 중단된 상태입니다.
TASK_STATE_REJECTED 에이전트가 작업을 실행하지 않기로 결정했음을 나타냅니다. 이 작업은 초기 작업 생성 중에 수행하거나 에이전트가 작업을 진행할 수 없거나 진행하지 않을 것이라고 판단한 후에 수행할 수 있습니다. 이는 터미널 상태입니다.
TASK_STATE_AUTH_REQUIRED 계속하려면 인증이 필요함을 나타냅니다. 이는 중단된 상태입니다.

메시지

Message는 클라이언트와 서버 간의 통신 단위입니다. 컨텍스트 또는 작업과 연결될 수 있습니다. 서버 메시지의 경우 contextId가 제공되어야 하고 taskId는 작업이 생성된 경우에만 제공되어야 합니다. 클라이언트 메시지의 경우 두 필드 모두 선택사항입니다. 단, 두 필드가 모두 제공되는 경우 일치해야 합니다 (contextId은 작업에 설정된 필드여야 함). taskId만 제공된 경우 서버는 이를 기반으로 contextId를 추론합니다.

JSON 표현 
{
  "messageId": string,
  "contextId": string,
  "taskId": string,
  "role": enum (Role),
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ],
  "referenceTaskIds": [
    string
  ]
}
필드
messageId

string

필수 항목입니다. 메시지의 고유 식별자 (예: UUID)입니다. 메시지 작성자가 만듭니다.
contextId

string

(선택사항) 메시지의 컨텍스트 ID입니다. 설정된 경우 메시지가 지정된 컨텍스트와 연결됩니다.
taskId

string

(선택사항) 메시지의 작업 ID입니다. 설정된 경우 메시지가 지정된 작업과 연결됩니다.
role

enum (Role)

필수 항목입니다. 메시지 발신자를 식별합니다.
parts[]

object (Part)

필수 항목입니다. Parts는 메시지 콘텐츠의 컨테이너입니다.
metadata

object (Struct format)

(선택사항) 메시지와 함께 제공할 메타데이터입니다.
extensions[]

string

이 메시지에 있거나 이 메시지에 제공된 확장 프로그램의 URI입니다.
referenceTaskIds[]

string

이 메시지가 추가 컨텍스트를 위해 참조하는 작업 ID 목록입니다.

역할

A2A 프로토콜 통신에서 메시지의 발신자를 정의합니다.

열거형
ROLE_UNSPECIFIED 역할이 지정되지 않았습니다.
ROLE_USER 메시지는 클라이언트에서 서버로 전송됩니다.
ROLE_AGENT 메시지는 서버에서 클라이언트로 전송됩니다.

파트

Part는 커뮤니케이션 콘텐츠 섹션의 컨테이너를 나타냅니다. 파트는 순수 텍스트, 파일 (이미지, 동영상 등) 또는 구조화된 데이터 blob (예: JSON)일 수 있습니다.

JSON 표현 
{
  "metadata": {
    object
  },
  "filename": string,
  "mediaType": string,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "text": string,
  "raw": string,
  "url": string,
  "data": value
  // End of mutually exclusive fields.
}
필드
metadata

object (Struct format)

선택사항. 이 부분과 연결된 메타데이터입니다.
filename

string

파일의 선택적 filename입니다 (예: 'document.pdf').
mediaType

string

파트 콘텐츠의 mediaType (MIME 유형)(예: 'text/plain', 'application/json', 'image/png')입니다. 이 필드는 모든 부품 유형에 사용할 수 있습니다.
다음은 상호 배타적인 필드의 목록입니다. 응답에는 다음 필드 중 최대 하나가 설정됩니다.
text

string

text 부분의 문자열 콘텐츠입니다.
raw

string (bytes format)

파일의 raw 바이트 콘텐츠입니다. JSON 직렬화에서 이는 base64 문자열로 인코딩됩니다.

base64 인코딩 문자열입니다.
url

string

파일 콘텐츠를 가리키는 url입니다.
data

value (Value format)

JSON 값 (객체, 배열, 문자열, 숫자, 불리언 또는 null)로 임의의 구조화된 data입니다.
상호 배타적 필드의 끝입니다.

아티팩트

아티팩트는 작업 출력을 나타냅니다.

JSON 표현 
{
  "artifactId": string,
  "name": string,
  "description": string,
  "parts": [
    {
      object (Part)
    }
  ],
  "metadata": {
    object
  },
  "extensions": [
    string
  ]
}
필드
artifactId

string

필수 항목입니다. 아티팩트의 고유 식별자 (예: UUID)입니다. 작업 내에서 고유해야 합니다.
name

string

아티팩트의 인간이 읽을 수 있는 이름입니다.
description

string

(선택사항) 아티팩트에 대한 사람이 읽을 수 있는 설명입니다.
parts[]

object (Part)

필수 항목입니다. 아티팩트의 콘텐츠입니다. 하나 이상의 파트를 포함해야 합니다.
metadata

object (Struct format)

(선택사항) 아티팩트에 포함된 메타데이터입니다.
extensions[]

string

이 아티팩트에 있거나 기여한 확장 프로그램의 URI입니다.

메서드

cancel

 진행 중인 작업을 취소합니다.

get

 작업의 최신 상태를 가져옵니다.

list

 지정된 필터와 일치하는 작업을 나열합니다.

subscribe

 종료 상태가 아닌 작업의 작업 업데이트를 구독합니다.