Recursive Zod Schemas lead to Invalid Schema in OpenAI

[csibbach]

Language Affected

• Python
• TypeScript

🐛 Describe the bug

I am using the AgentKit template, using Typescript and Langchain with a local wallet. Works out of the box. I have created my own ActionProvider, and it also works great, except when I use a recursive schema. I have created an action using this schema (greatly simplified for clarity, but it still fails):

export const contractMethodParamsSchema: z.ZodType<{
  [key: string]:
    | string
    | { [key: string]: any }
    | Array<any>;
}> = z.record(
  z.string(),
  z.union([
    z.string(),
    z.lazy(() => contractMethodParamsSchema),
    z.array(z.lazy(() => contractMethodParamsSchema)),
  ]),
);

export const executeSchema = z.object({
  params: contractMethodParamsSchema,
});

As soon as I query the model I get this error:

Error processing request: BadRequestError: 400 Invalid schema for function 'OneShotActionProvider_execute-contract-method-with-1shot-wallet': In context=(), object schema missing properties.
    at APIError.generate (webpack-internal:///(rsc)/./node_modules/openai/error.mjs:60:20)
    at OpenAI.makeStatusError (webpack-internal:///(rsc)/./node_modules/openai/core.mjs:333:65)
    at OpenAI.makeRequest (webpack-internal:///(rsc)/./node_modules/openai/core.mjs:377:30)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async eval (webpack-internal:///(rsc)/./node_modules/@langchain/openai/dist/chat_models.js:1594:29)       
    at async RetryOperation.eval [as _fn] (webpack-internal:///(rsc)/./node_modules/p-retry/index.js:50:12) {    
  status: 400,
  headers: {
    'access-control-expose-headers': 'X-Request-ID',
    'alt-svc': 'h3=":443"; ma=86400',
    'cf-cache-status': 'DYNAMIC',
    'cf-ray': '96a175719f7e7c03-LAX',
    connection: 'keep-alive',
    'content-length': '307',
    'content-type': 'application/json',
    date: 'Mon, 04 Aug 2025 22:23:23 GMT',
    'openai-organization': 'uxly-software',
    'openai-processing-ms': '127',
    'openai-project': 'proj_2EjCCsonQJXknpWRniGsDyco',
    'openai-version': '2020-10-01',
    server: 'cloudflare',
    'set-cookie': '__cf_bm=fTuAa.HBiGpxnn7OfIUFGbQnbJ6LT8mbxb3w7Hp1n9M-1754346203-1.0.1.1-8H9LF9PaeTqtGpt2ru1s_96MeDqSnHymzBeti8U.MGzlir01wLWUwqydEE97HTmh.S3mpFR7NpZ5gMUj0s940fsbUT48iMRExDN_2LGfrSA; path=/; expires=Mon, 04-Aug-25 22:53:23 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=CiSBt45NztZkj7OT1vwCQKO60AeF2LEoMf9.5Z5E9Zk-1754346203757-0.0.1.1-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None', 
    'strict-transport-security': 'max-age=31536000; includeSubDomains; preload',
    'x-content-type-options': 'nosniff',
    'x-envoy-decorator-operation': 'router.openai.svc.cluster.local:5004/*',
    'x-envoy-upstream-service-time': '238',
    'x-ratelimit-limit-requests': '10000',
    'x-ratelimit-limit-tokens': '200000',
    'x-ratelimit-remaining-requests': '9999',
    'x-ratelimit-remaining-tokens': '199663',
    'x-ratelimit-reset-requests': '8.64s',
    'x-ratelimit-reset-tokens': '101ms',
    'x-request-id': 'req_9dd533995e7533c215a7b1a8a93825d4'
  },
  request_id: 'req_9dd533995e7533c215a7b1a8a93825d4',
  error: {
    message: "Invalid schema for function 'OneShotActionProvider_execute-contract-method-with-1shot-wallet': In context=(), object schema missing properties.",
    type: 'invalid_request_error',
    param: 'tools[16].function.parameters',
    code: 'invalid_function_parameters'
  },
  code: 'invalid_function_parameters',
  param: 'tools[16].function.parameters',
  type: 'invalid_request_error',
  attemptNumber: 1,
  retriesLeft: 6,
  pregelTaskId: '0002e74e-e320-5793-b0d5-f773fd759126'
}
 POST /api/agent 200 in 3904ms

For reference, the action provider definition looks like this:

@CreateAction({
    name: "execute-contract-method-with-1shot-wallet",
    description: `...`,
    schema: executeSchema,
  })
  public async executeContractMethodWith1ShotWallet(
    args: z.infer<typeof executeSchema>,
  ): Promise<Transaction> {

If I comment out the two lines in the schema with the lazy recursion, then the error goes away. There seems to be an issue with generating a tool for OpenAI. I did the exact same thing (used the same schema) with the GOAT SDK, similar to AgentKit, and did not have an issue with this, so I think this is an issue inside the AgentKit layer and not a general OpenAI issue, but I'm not sure.

Versions

Node JS Version: v20.19.1
AgentKit Version: ```
├─┬ @coinbase/agentkit-langchain@0.3.0
│ └── @coinbase/agentkit@0.9.1 deduped
├─┬ @coinbase/agentkit-vercel-ai-sdk@0.1.0
│ └── @coinbase/agentkit@0.9.1 deduped
└── @coinbase/agentkit@0.9.1

AgentKit langchain version: @coinbase/agentkit-langchain@0.3.0

[csibbach]

I've been trying to research this, and found some docs about OpenAI specifically, which says that recursive schemas are allowed: https://platform.openai.com/docs/guides/structured-outputs#recursive-schemas-are-supported. I haven't found the place inside AgentKit yet that converts the Zod schema to the JSON schema but the issue is probably in there.

[csibbach]

I spent most of the day testing this yesterday, I I have zeroed in on the exact cause. If you use a Zod sub-schema twice in a union then you get the bug about invalid schema:

export const contractMethodParamsSchemaSub = z.record(
  z.string(),
  z.union([z.string(), z.number(), z.boolean()]),
);

// This works
export const contractMethodParamsSchema = z.record(
  z.string(),
  z.union([
    z.string(),
    z.number(),
    z.boolean(),
    //contractMethodParamsSchemaSub,
    z.array(contractMethodParamsSchemaSub),
  ]),
);

// This does not
export const contractMethodParamsSchemaDupe = z.record(
  z.string(),
  z.union([
    z.string(),
    z.number(),
    z.boolean(),
    contractMethodParamsSchemaSub,
    z.array(contractMethodParamsSchemaSub),
  ]),
);

export const executeContractMethodSchema = z
  .object({
    ...
    params: contractMethodParamsSchema
      .optional()
      .nullable()
      .describe("The parameters to pass to the contractMethod"),
   ...
  })

I was going crazy! The recursive thing immediately triggers it as well, even if it's not used for multiple properties in a union, probably because the recursion does effectively the same thing. That's why, in the recursive case, commenting out one usage didn't fix the problem. But once I made it non-recursive, the only way to trigger the bug was to use a sub-schema multiple times in the union.

I don't have time to pursue it deeper right now, hopefully this helps out and someone on the AgentKit team can look into this. I reiterate, this same schema worked in a different agentic framework, so I believe the problem is in AgentKit and not either Zod or OpenAI.