Typing tool call execute parameters.

未关闭
#4,484 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看

还没有人认领这个 Issue。

评估

难度
4/5
预计耗时
3-5 天
新手友好度
52/100
Issue 类型
功能
描述清晰度
基本清楚
活跃度
冷清
技术栈
typescript

调研方向

先定位 runtime package 中的 AgentConfig.tools、AgentTool 以及 public AgentTool re-export,然后检查 entity-stream-db-…d.ts:847 中所指出的生成声明。将当前的类型推断行为与报告中的 TypeBox 示例进行比较,并添加针对性的 type-check 覆盖;当选定的 public API 无需为每个 tool 单独进行 cast 即可推断 tool 参数,并保留预期的泛型声明时,即表示完成。

由索引模型根据 Issue 内容生成。

描述

feature request triage

I have a tool definition in my example code that requires params: unknown and then casting to the real type:

import { Type, type Static } from '@sinclair/typebox'

const taskParameters = Type.Object({
  task: Type.String({ description: `The task for the assistant.` }),
})
type TaskParams = Static<typeof taskParameters>

function createSpawnAssistantTool(ctx: HandlerContext) {
  return {
    name: `spawn_assistant`,
    label: `Spawn Assistant`,
    description: `Spawn an assistant sub-agent to perform a task.`,
    parameters: taskParameters,
    execute: async (_toolCallId: string, params: unknown) => {
      const { task } = params as TaskParams
      ...
    },
    ...
  }
}  

My initial reaction reading the code was "why can't the type of params be inferred from the parameters: taskParameters". I asked Claude and this was his verdict:

P1 — the tools array fixes the schema generic at its default. AgentConfig.tools is typed Array<AgentTool$1>
(entity-stream-db-…d.ts:847), and AgentTool's execute is (id, params: Static<TParameters>, …). With TParameters left at its
default TSchema, Static<TSchema> is unknown. So every execute slot demands params: unknown, and strictFunctionTypes checks
function params contravariantly — only a supertype of unknown (i.e. unknown or any) is accepted. TaskParams is a subtype, so it's
rejected. That's your error verbatim.

P2 — the public AgentTool export isn't even generic. The rolled-up .d.ts has type AgentTool$1 = AgentTool (line 841) and
re-exports AgentTool$1 as AgentTool. That alias collapses the type params to their defaults, so importing AgentTool from
@electric-ax/agents-runtime and writing AgentTool<typeof taskParameters> fails with "Type 'AgentTool$1' is not generic." (I hit
this directly.) It's almost certainly a dts-bundler artifact (the $1 rename), not intentional — a consumer can't parameterize the
tool type at all through the public name.

Runtime-side fixes

Fix A — one token, unblocks typed execute with zero call-site changes. Widen the array element to any:
interface AgentConfig {
  tools: Array<AgentTool<any>>   // was Array<AgentTool>
}
Static<any> is any, and any params are bivariant, so your original execute: async (_id, params: TaskParams) => … slots in with no
cast. Verified. This is also exactly what pi-agent-core already does for Agent.tools and AgentContext.tools (both
AgentTool<any>[]), so it's consistency, not a hack. Trade-off: any won't flag a wrong param shape — but that's no worse than the
cast you have now.

Fix B — best DX + actual soundness: ship a defineTool helper. TypeScript won't infer a type parameter across the fields of a bare
object literal, so the only way to get parameters → execute(params) inference is a wrapper call:
export function defineTool<P extends TSchema, D = unknown>(def: AgentTool<P, D>): AgentTool<P, D> {
  return def
}
Then params is inferred from parameters — no annotation, no cast. Consuming the result still needs Fix A (or making the config
generic over a tuple, <const T extends readonly AgentTool<any>[]>). This is the Vercel AI SDK tool() pattern. Verified (params
inferred to { task: string }, proven narrowed not any).

Fix P2 regardless: re-export the generic properly, e.g. export type { AgentTool } from '@mariozechner/pi-agent-core', so the name
keeps its parameters for downstream code. Fix A alone resolves your error without this; P2 only bites consumers who want to name
AgentTool<Schema> themselves.

Without touching the runtime

Write your own structural helper — it doesn't reference the runtime's (non-generic) AgentTool, so P2 doesn't block it, and the
single cast is hidden in one place instead of one per tool:

import type { AgentTool } from '@electric-ax/agents-runtime'
import { type Static, type TSchema } from '@sinclair/typebox'

function tool<P extends TSchema>(def: {
  name: string
  label: string
  description: string
  parameters: P
  execute: (id: string, params: Static<P>, signal?: AbortSignal) => Promise<{
    content: Array<{ type: `text`; text: string }>
    details?: unknown
    terminate?: boolean
  }>
}): AgentTool {
  return def as unknown as AgentTool
}
const spawnAssistant = tool({
  parameters: taskParameters,
  execute: async (_id, params) => {       // params: { task: string }, inferred
    const { task } = params
    ...
  },
  // name/label/description...
})
Verified against the real runtime types — it slots straight into AgentConfig['tools']. The downside is you hand-maintain that
structural shape to match the runtime's AgentToolResult.

Bottom line

- Smallest real library fix for the error you hit: Array<AgentTool> → Array<AgentTool<any>> in AgentConfig.
- Proper library fix: that plus a generic defineTool helper plus fixing the non-generic re-export (P2).
- For this example specifically, the inline params as TaskParams you've already got is the clearest thing for a reader — the helper only pays off across many tools. Worth filing P1/P2 against the runtime though, since P2 in particular looks like an unintended packaging regression.

Does this make sense? Should we:

  • update Array<AgentTool> to Array<AgentTool<any>> in AgentConfig?
  • define a generic defineTool helper
  • fix the non-generic re-export
主要语言
TypeScript
星标
10.4k
派生
399
PR 合并指标
30 天内没有已合并 PR

环境准备

  • 没有 Dockerfile 或 Docker Compose 文件
  • 没有 Pull Request 模板
  • 阅读贡献指南

从这里开始

  1. 先读完整个 Issue,再读项目的贡献指南。
  2. 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
  3. Fork 仓库,在一个分支上完成修改。
  4. 提交 Pull Request,并在描述里引用这个 Issue 编号。

electric-sql/electric 的其他 Issue

查看 electric-sql/electric 的全部 Issue

相似的 Issue

更多 TypeScript Issue

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。