에이전트에 사용자 지정 스트림 출력 추가

개요

사용자 지정 스트림 출력을 구성하여 에이전트 일반 텍스트 외에도 스트리밍 호출에 대해 구조화된 기계 판독 가능 출력을 내보내도록 지시할 수 있습니다. Atlas Agent Engine은 이 출력을 사용자 지정 이벤트로 클라이언트에 전송합니다.

이 가이드 다음 작업을 수행하는 방법을 보여줍니다.

• 사용자 지정 스트림 출력 활성화: agent.yaml 파일 에서 features.use_custom_parser: true 플래그를 설정합니다.

• 출력 구문 분석기 등록: 앱 에 OutputParser 하위 클래스를 등록합니다.

• 사용자 지정 이벤트 내보내기: 에이전트 코드에서 사용자 지정 이벤트를 내보냅니다.

전제 조건

시작하기 전에 agent.yaml 파일 로 등록된 에이전트 가 있는지 확인하세요.자세한 학습 은 Atlas Agent 엔진 시작하기를 참조하세요.

사용자 지정 스트림 출력 활성화

에이전트 에 대한 사용자 지정 스트림 출력을 활성화 하려면 agent.yaml 파일 에 다음 코드를 추가합니다.

features:
  use_custom_parser: true

features.use_custom_parser 플래그를 true로 설정하다 출력 구문 분석기를 등록하지 않은 경우, 호출이 시작될 때 에이전트 실패하고 RuntimeError를 반환합니다.

출력 구문 분석기 등록

@app.output_parser 데코레이터를 사용하여 앱 에 OutputParser 하위 클래스를 등록합니다. Atlas Agent Engine은 데코레이션 타임에 클래스의 유효성을 검사하므로 모듈을 가져올 때 OutputParser 하위 클래스가 아닌 클래스는 전달되지 않습니다.

LangGraph 에이전트의 경우 LangGraphOutputParser 클래스를 서브클래스화합니다. stream_modes 클래스 속성을 사용자 지정 이벤트로 변환하려는 LangGraph 스트림 모드로 설정합니다. 그런 다음 parse() 및 on_stream_error() 메서드를 구현 .

다음 예시 LangGraph 에이전트 에 대한 출력 구문 분석기를 등록합니다.

from agent_engine_sdk_langgraph.output_parser import LangGraphOutputParser
@app.output_parser
class BriefParser(LangGraphOutputParser):
    stream_modes = ("messages", "values")
    async def parse(self, item, ctx):
        ...
        yield {"event": "brief", "data": new_brief}
    async def on_stream_error(self, ctx, error):
        ...
        return {"event": "error"}

다음 표에서는 LangGraphOutputParser 멤버에 대해 설명합니다.

parse() 또는 on_stream_error() 메서드에서 오류가 발생하면 출력이 자동으로 삭제되지 않고 스트림 실패합니다.

사용자 지정 이벤트 내보내기

스트리밍 호출 중에 emit_custom_event() 함수를 사용하여 LangGraph 노드, 도구 또는 실행에서 실행되는 기타 코드에서 직접 사용자 지정 이벤트를 내보낼 수 있습니다. 다음 예시 와 같이 문자열 키가 포함된 JSON 객체 emit_custom_event()에 전달합니다.

from runner_shared import emit_custom_event
await emit_custom_event({"event": "todo", "items": ["a", "b"]})

Atlas Agent Engine은 JSON 객체 변경하지 않고 전달하며 스키마 부과하지 않으므로 클라이언트 의 예상과 일치하도록 페이로드의 구조를 정의할 수 있습니다.

emit_custom_event() 함수를 호출할 때는 다음 규칙이 적용.

• 스트리밍 호출에서만 메서드를 호출합니다. 동기 invoke 경로에서 호출하면 오류가 발생합니다.

• agent.yaml 파일 에서 features.use_custom_parser 플래그를 활성화합니다. 플래그가 비활성화되면 플랫폼에서 오류가 발생합니다.

• 비동기 코드에서 메서드를 기다립니다. 동기 코드에서는 emit_custom_event_sync()을 대신 사용합니다.

다음 단계

클라이언트 스트리밍된 출력을 수신하는 방법을 학습 보려면 에이전트 호출 가이드 에서 에이전트 출력 스트리밍을 참조하세요.