feat(agent): design @typia/agent streaming function-calling harness interface

[samchon]

Intent

@typia/agent의 인터페이스 설계(타입 + 문서 전용) 1차 산출물. typia validation 위에 구축된, 벤더 중립 streaming function-calling harness의 타입 표면을 확정한다.

핵심 use-case가 타입 안전·자동완성되도록 모든 타입을 정렬했다:

const agent = new TypiaAgent({ adapter, controllers });
const response = await agent.conversate("Yaho~");
for await (const r of response) {
  if (r.type === "tool") {
    if ((await r.success()) === false) await r.feedback();
    else                               await r.execute();
  } else if (r.type === "text") {
    for await (const piece of r.stream()) console.log("piece", piece);
  }
}

Scope

• IAgent/TypiaAgent — conversate()가 IAgentExecution(async-iterable of IAgentResponse) 반환, iterator는 IAgentTurn 결과를 return.
• Harness 표면 — incremental validation(IAgentValidation: snapshot/locked/watch/phase), IAgentTool parse→validate→feedback→execute state machine, output-token 천장 continuation.
• IAgentAdapter — OpenAI/Vercel를 한 줄로 갈아끼우는 벤더 중립 chat-stream 시임. 통합 ILlmSchema 덕에 provider 지식은 adapter 안에만.
• Controllers/operations(class | http | mcp | output), 대규모 함수용 IAgentSelector, 직렬화 가능한 IAgentHistory(.Json) 메모리, 부차 IAgentEvent telemetry.
• 타입 하나당 파일 하나(namespace 중첩 없음). 근거는 packages/agent/ARCHITECTURE.md.

Deferred

• 런타임 구현 없음(adapter 구현체 OpenAiAdapter/VercelAdapter + harness loop는 후속).
• 테스트(tests/test-agent/)는 후속.

Test plan

• tsgo --noEmit -p packages/agent/tsconfig.json → 클린(전체 타입 표면 정합).
• prettier --write 적용(import 정렬 + repo의 prettier-plugin-jsdoc).
• 주의: 이 패키지는 types-only이며 CI의 pnpm build(ttsc) 검증은 후속 작업이 필요할 수 있다.

🤖 Generated with Claude Code

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​typescript/​native-preview@​7.0.0-dev.20260527.2

View full report

[Copilot]

Pull request overview

Introduces the initial types + documentation only surface for a new @typia/agent package, defining a vendor-neutral streaming function-calling harness API (adapter seam, incremental validation view, tool/text parts, histories, and telemetry events) without runtime implementation.

Changes:

• Adds a new packages/agent package with build scaffolding and a types-only public API (IAgent/TypiaAgent, streaming IAgentExecution, IAgentTool/IAgentText parts).
• Defines a vendor-neutral adapter contract (IAgentAdapter + streamed chunk model) and the harness-facing incremental validation interfaces.
• Adds package-level docs (ARCHITECTURE.md, INSTRUCTION.md) and updates repo ignore rules for research folders.

Reviewed changes

Copilot reviewed 74 out of 76 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds packages/agent importer dependency graph.
packages/agent/tsconfig.json	Adds TS build config for the new package.
packages/agent/src/TypiaAgent.ts	Declares the TypiaAgent facade class (types-only).
packages/agent/src/structures/IAgentTokenUsageOutput.ts	Adds output token usage breakdown type.
packages/agent/src/structures/IAgentTokenUsageInput.ts	Adds input token usage breakdown type.
packages/agent/src/structures/IAgentTokenUsage.ts	Adds aggregate token usage accounting type.
packages/agent/src/structures/IAgentTextDeltaChunk.ts	Adds adapter text-delta chunk type.
packages/agent/src/structures/IAgentTextContent.ts	Adds multimodal text content-part type.
packages/agent/src/structures/IAgentSystemPrompt.ts	Adds system-prompt override shape.
packages/agent/src/structures/IAgentSelectorProps.ts	Adds selector input props type.
packages/agent/src/structures/IAgentSelector.ts	Adds “many tools” selection strategy interface.
packages/agent/src/structures/IAgentRawChunk.ts	Adds raw passthrough provider chunk type.
packages/agent/src/structures/IAgentProps.ts	Adds agent constructor props type.
packages/agent/src/structures/IAgentOutputOperation.ts	Adds structured-output operation protocol type.
packages/agent/src/structures/IAgentOperationBase.ts	Adds shared operation header shape.
packages/agent/src/structures/IAgentOperation.ts	Adds operation union type.
packages/agent/src/structures/IAgentMessageContent.ts	Adds multimodal message content-part union.
packages/agent/src/structures/IAgentMessage.ts	Adds provider-neutral message type.
packages/agent/src/structures/IAgentMcpOperation.ts	Adds MCP-backed operation shape.
packages/agent/src/structures/IAgentMcpController.ts	Adds MCP controller shape.
packages/agent/src/structures/IAgentImageContent.ts	Adds multimodal image content-part type.
packages/agent/src/structures/IAgentHttpOperation.ts	Adds HTTP-backed operation shape.
packages/agent/src/structures/IAgentHttpExecuteProps.ts	Adds custom HTTP executor input type.
packages/agent/src/structures/IAgentHttpController.ts	Adds HTTP controller shape.
packages/agent/src/structures/IAgentFinishReason.ts	Adds normalized finish reason union.
packages/agent/src/structures/IAgentFinishChunk.ts	Adds adapter finish chunk (reason + usage).
packages/agent/src/structures/IAgentFileContent.ts	Adds multimodal file content-part type.
packages/agent/src/structures/IAgentErrorChunk.ts	Adds adapter error chunk type.
packages/agent/src/structures/IAgentConversateOptions.ts	Adds per-turn conversate options type.
packages/agent/src/structures/IAgentController.ts	Adds controller union type.
packages/agent/src/structures/IAgentContinuation.ts	Adds ceiling-continuation policy type.
packages/agent/src/structures/IAgentConfig.ts	Adds agent tuning configuration type.
packages/agent/src/structures/IAgentCompaction.ts	Adds history compaction hook type.
packages/agent/src/structures/IAgentClassOperation.ts	Adds class-backed operation shape.
packages/agent/src/structures/IAgentClassExecuteProps.ts	Adds class dispatch/proxy executor input type.
packages/agent/src/structures/IAgentClassController.ts	Adds class controller shape.
packages/agent/src/structures/IAgentChunk.ts	Adds adapter chunk union type.
packages/agent/src/structures/IAgentAudioContent.ts	Adds multimodal audio content-part type.
packages/agent/src/structures/IAgentAdapterRequest.ts	Adds vendor-neutral adapter request type.
packages/agent/src/structures/IAgentAdapterCapabilities.ts	Adds adapter capability advertisement type.
packages/agent/src/structures/IAgentAdapter.ts	Adds vendor-neutral streaming adapter interface.
packages/agent/src/responses/IAgentValidationState.ts	Adds incremental validation tick/state type.
packages/agent/src/responses/IAgentValidation.ts	Adds incremental validation interface contract.
packages/agent/src/responses/IAgentTurn.ts	Adds terminal turn result type returned by iterator.
packages/agent/src/responses/IAgentTool.ts	Adds streamed tool-call part state machine interface.
packages/agent/src/responses/IAgentText.ts	Adds streamed assistant text part interface.
packages/agent/src/responses/IAgentResponse.ts	Adds response-part discriminated union type.
packages/agent/src/responses/IAgentFeedbackProps.ts	Adds tool feedback/correction input type.
packages/agent/src/responses/IAgentExecution.ts	Adds async-iterable execution surface (+ join/abort).
packages/agent/src/responses/IAgentExecute.ts	Adds tool execution record type.
packages/agent/src/index.ts	Adds public export surface for the package.
packages/agent/src/IAgent.ts	Adds main agent contract interface.
packages/agent/src/histories/IAgentToolHistoryJson.ts	Adds serialized tool history mirror type.
packages/agent/src/histories/IAgentToolHistory.ts	Adds live tool history record type.
packages/agent/src/histories/IAgentTextHistoryJson.ts	Adds serialized text history mirror type.
packages/agent/src/histories/IAgentTextHistory.ts	Adds live text history record type.
packages/agent/src/histories/IAgentSystemHistoryJson.ts	Adds serialized system history mirror type.
packages/agent/src/histories/IAgentSystemHistory.ts	Adds live system history record type.
packages/agent/src/histories/IAgentHistoryJson.ts	Adds serialized history union type.
packages/agent/src/histories/IAgentHistoryBase.ts	Adds shared history header type.
packages/agent/src/histories/IAgentHistory.ts	Adds live history union type.
packages/agent/src/events/IAgentValidateEvent.ts	Adds validation telemetry event type.
packages/agent/src/events/IAgentUsageEvent.ts	Adds usage telemetry event type.
packages/agent/src/events/IAgentResponseEvent.ts	Adds adapter-response telemetry event type.
packages/agent/src/events/IAgentRequestEvent.ts	Adds adapter-request telemetry event type.
packages/agent/src/events/IAgentParseEvent.ts	Adds parse telemetry event type.
packages/agent/src/events/IAgentEventSource.ts	Adds event source phase union type.
packages/agent/src/events/IAgentEventMapper.ts	Adds event discriminator→payload mapping.
packages/agent/src/events/IAgentEventBase.ts	Adds shared event header type.
packages/agent/src/events/IAgentEvent.ts	Adds event union type.
packages/agent/src/events/IAgentContinuationEvent.ts	Adds continuation telemetry event type.
packages/agent/rollup.config.mjs	Adds rollup config forwarding to repo config.
packages/agent/package.json	Adds new package manifest and publish config.
packages/agent/INSTRUCTION.md	Adds package-level instruction/notes document.
packages/agent/ARCHITECTURE.md	Adds architecture/design documentation for the new package.
.gitignore	Ignores .repositories/ research clone folder.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.