@agentify/a2a-framework

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

주요 기능

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

설치

npm install @agentify/a2a-framework

빠른 시작

1. 에이전트 실행기 구현

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. 서버 생성 및 시작

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에서 에이전트 정보 제공
• 에러 처리: 자동 에러 핸들링 및 로깅

고급 사용법

커스텀 아티팩트 생성

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}`;
  }
}

커스텀 라우트 추가

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

개발 환경 설정

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 생성

타입 정의

주요 타입들:

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;
}

개발 가이드

로컬 개발

# 의존성 설치
pnpm install

# 빌드
pnpm build

# 개발 모드 (watch)
pnpm dev

테스트

pnpm test

린트

pnpm lint

예제

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

라이선스

MIT

기여

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