getAgentByName stub RPC methods return type `never`

[alexander-zuev]

Description

When using getAgentByName() to get an Agent stub, calling RPC methods returns type never instead of the actual return type. Accessing properties on the result causes TypeScript errors.

Reproduction

import { Agent, getAgentByName } from 'agents'

interface MyState {
  count: number
}

class MyAgent extends Agent<Env, MyState> {
  async myMethod(): Promise<{ data: string }> {
    return { data: 'hello' }
  }
}

// In worker:
const agent = await getAgentByName(env.MY_AGENT, 'id')
const result = await agent.myMethod()  // result: never
console.log(result.data)  // ❌ Property 'data' does not exist on type 'never'

Expected behavior

result should be typed as { data: string }

Workaround

Passing the result directly to c.json({ data: result }) works because it doesn't access properties. But any property access fails.

Environment

• agents: 0.3.3
• @cloudflare/workers-types: ^4.20251231.0
• wrangler: ^4.54.0

Root cause hypothesis

The Rpc.DurableObjectBranded type brand isn't properly flowing through the type inheritance chain from DurableObject → Server → Agent → user's class, causing DurableObjectStub<T> to resolve methods as returning never.

[whoiskatrin]

@alexander-zuev I will try to fix this tonight

[alexander-zuev]

Appreciate a prompt reply @whoiskatrin !

Let me know if you need me to reproduce this - issue came up in a private repo

[whoiskatrin]

@alexander-zuev I think I somewhat managed to repro it locally. #766 this returned a proper type to me, give it a go once it's build a test package

[alexander-zuev]

@whoiskatrin thanks for a quick turnaround on this - I did a bit more digging and I think I've found a different root cause. I think my initial analysis was incorrect.

Context

I have an agent class that exposes RPC methods:

// agent-runtime.do.ts
export interface LLMOutput {
  result: string | unknown  // ← notice the `unknown`
  metadata: ExecutionMeta
}

export class AgentRuntime extends Agent<Env, AgentRuntimeState> {
  async generate(input: LLMInput): Promise<LLMOutput> { ... }
}

The unknown was intentional - LLMInput accepts a responseFormat schema, and I wanted the return type to support both plain text (string) and structured output (unknown for arbitrary JSON shapes).

Problem

When I call the RPC method .generate() from a caller, IDE complains it cannot be awaited:

// ai-executor.ts
const agent = await getAgentByName(env.AGENT_RUNTIME, agentId)
const result = await agent.generate(runtimeInput)  // "await has no effect on the type of this expression"

Return type resolves to never:

type _GenerateReturnType = ReturnType<typeof agent.generate>  // → never

What I tried

I isolated the issue by adding a simple ping method to the same Agent class:

async ping(msg: string): Promise<{ pong: string; ts: number }> {
  return { pong: msg, ts: Date.now() }
}

In the caller:

type _PingReturnType = ReturnType<typeof agent.ping>  // → Promise<{ pong: string; ts: number }> ✅
type _GenerateReturnType = ReturnType<typeof agent.generate>  // → never ❌

Same class, same export chain - but ping works and generate returns never.

What worked

Removed unknown from the interface:

export interface LLMOutput {
  result: string  // was: string | unknown
  metadata: ExecutionMeta
}

After running wrangler types to regenerate types, everything works. string | unknown collapses to unknown, and it seems the RPC type transformation bails to never when it encounters it.

I did try patching the agents SDK with your PR #766 change btw - it didn't fix the never type on its own, so the tests above used vanilla agents@0.3.3.