npm package: @planetarium/a2a-framework
Description: Reusable framework for building A2A protocol servers
Author: Planetarium Team
Latest version: 0.0.1

# @agentify/a2a-framework

A2A 프로토콜 서버 구축을 위한 재사용 가능한 프레임워크입니다. 공통 로직을 추상화하여 새로운 A2A 서버 구축 시 90% 이상의 보일러플레이트 코드를 제거하고, 비즈니스 로직에만 집중할 수 있도록 합니다.

## 주요 기능

- **BaseAgentExecutor**: A2A 에이전트 실행기의 기본 추상 클래스
- **TaskEventManager**: 태스크 이벤트 관리 헬퍼 클래스
- **A2AServerFactory**: 서버 인스턴스 생성 팩토리
- **AgentCardBuilder**: AgentCard 생성을 위한 빌더 패턴
- **완전한 TypeScript 지원**: 강력한 타입 안전성

## 설치

```bash
npm install @agentify/a2a-framework
```

## 빠른 시작

### 1. 에이전트 실행기 구현

```typescript
import { BaseAgentExecutor } from '@agentify/a2a-framework';
import { RequestContext } from '@a2a-js/sdk';

// 비즈니스 로직 결과 타입
interface MyServiceResult {
  message: string;
  data: any;
}

// 에이전트 실행기 구현
export class MyServiceExecutor extends BaseAgentExecutor<MyServiceResult> {
  protected getServiceName(): string {
    return 'MyService';
  }

  protected async executeAction(
    context: RequestContext
  ): Promise<MyServiceResult> {
    // RequestContext에서 입력 데이터 파싱
    const input = this.parseJsonInput(context);

    // 비즈니스 로직 실행
    const result = await this.processMyLogic(input);

    // 결과 반환 (프레임워크가 자동으로 A2A 이벤트로 변환)
    return {
      message: '작업 완료',
      data: result,
    };
  }

  private async processMyLogic(input: any): Promise<any> {
    // 실제 비즈니스 로직 구현
    return { processed: true, input };
  }
}
```

### 2. 서버 생성 및 시작

```typescript
import { A2AServerFactory, AgentCardBuilder } from '@agentify/a2a-framework';
import { MyServiceExecutor } from './MyServiceExecutor';

// 에이전트 카드 생성
const agentCard = AgentCardBuilder.buildDefault(
  'My Service',
  'http://localhost:3000',
  'Intelligent service for processing requests'
);

// 에이전트 실행기 생성
const executor = new MyServiceExecutor();

// 서버 설정
const config = {
  port: 3000,
  baseUrl: 'http://localhost:3000',
  serviceName: 'MyService',
  version: '1.0.0',
  healthCheckPath: '/health',
  pingPath: '/ping',
};

// 서버 생성 및 시작
const server = A2AServerFactory.create(config, agentCard, executor);
server.start();
```

### 3. 결과

위의 코드만으로 완전한 A2A 서버가 생성됩니다:

- **A2A 프로토콜 완전 지원**: 표준 A2A 메시지 처리
- **자동 태스크 관리**: 태스크 생성, 상태 업데이트, 완료 처리
- **헬스체크 엔드포인트**: `/health`에서 서버 상태 확인
- **에이전트 카드**: `/agent-card`에서 에이전트 정보 제공
- **에러 처리**: 자동 에러 핸들링 및 로깅

## 고급 사용법

### 커스텀 아티팩트 생성

```typescript
export class MyServiceExecutor extends BaseAgentExecutor<MyServiceResult> {
  // ... 기본 구현 ...

  protected createArtifact(result: MyServiceResult): Partial<Artifact> {
    return {
      name: 'my-service-result',
      mimeType: 'application/json',
    };
  }

  protected createResponseMessage(result: MyServiceResult): string {
    return `처리 완료: ${result.message}`;
  }
}
```

### 커스텀 라우트 추가

```typescript
const config = {
  // ... 기본 설정 ...
  customRoutes: app => {
    app.get('/custom', (req, res) => {
      res.json({ message: 'Custom endpoint' });
    });
  },
};
```

### 개발 환경 설정

```typescript
if (process.env.NODE_ENV === 'development') {
  A2AServerFactory.setupDevelopmentEndpoints(server.app, config);
}
```

## API 문서

### BaseAgentExecutor

#### 추상 메서드 (구현 필요)

- `getServiceName()`: 서비스 이름 반환
- `executeAction(context)`: 비즈니스 로직 실행

#### 유틸리티 메서드

- `extractTextInput(context)`: 텍스트 입력 추출
- `parseJsonInput<T>(context)`: JSON 입력 파싱
- `createArtifact(result)`: 아티팩트 생성 (선택적 오버라이드)
- `createResponseMessage(result)`: 응답 메시지 생성 (선택적 오버라이드)

### TaskEventManager

정적 메서드들:

- `publishStatusUpdate(eventBus, options)`: 상태 업데이트 발행
- `publishArtifact(eventBus, options)`: 아티팩트 발행
- `publishWorking(eventBus, taskId, contextId, message)`: 작업 중 상태 발행
- `publishCompletion(eventBus, taskId, contextId, message)`: 완료 상태 발행
- `publishError(eventBus, taskId, contextId, error)`: 에러 상태 발행

### A2AServerFactory

정적 메서드들:

- `create(config, agentCard, executor)`: 서버 인스턴스 생성
- `setupDevelopmentEndpoints(app, config)`: 개발 환경 엔드포인트 설정

### AgentCardBuilder

빌더 메서드들:

- `name(name)`: 에이전트 이름 설정
- `description(description)`: 설명 설정
- `url(url)`: URL 설정
- `version(version)`: 버전 설정
- `addSkill(skill)`: 스킬 추가
- `withDefaultSkills(serviceName, description)`: 기본 스킬 추가
- `build()`: AgentCard 생성

편의 메서드:

- `buildDefault(name, url, description)`: 기본 설정으로 AgentCard 생성

## 타입 정의

주요 타입들:

```typescript
interface A2AServerConfig {
  port: number;
  baseUrl: string;
  serviceName: string;
  version?: string;
  healthCheckPath?: string;
  pingPath?: string;
  customRoutes?: (app: Express) => void;
}

interface A2AServerInstance {
  app: Express;
  start: () => Server;
  stop?: () => void;
}
```

## 개발 가이드

### 로컬 개발

```bash
# 의존성 설치
pnpm install

# 빌드
pnpm build

# 개발 모드 (watch)
pnpm dev
```

### 테스트

```bash
pnpm test
```

### 린트

```bash
pnpm lint
```

## 예제

더 많은 예제는 `examples/` 디렉토리에서 확인할 수 있습니다.

## 라이선스

MIT

## 기여

Issues와 Pull Requests는 언제나 환영합니다!