Skip to main content

🤖 Understanding TypeScript Errors in AI SDKs

The Problem​

I wrote:

const builtInAgent = new BuiltInAgent({
  model: "openai:gpt-5.4-mini",
  instructions: `
    You are Erzan's personal AI assistant.
  `,
});

And TypeScript showed:

Object literal may only specify known properties,
and 'instructions' does not exist in type 'BuiltInAgentConfiguration'.

Why This Error Happens​

TypeScript validates object literals against the expected type.

Imagine we have:

type User = {
  name: string;
};

This is valid:

const user: User = {
  name: "Erzan",
};

This is invalid:

const user: User = {
  name: "Erzan",
  age: 25,
};

Error:

Property 'age' does not exist on type 'User'

The exact same thing happened with BuiltInAgent.

TypeScript expected:

type BuiltInAgentConfiguration = {
  model: string;
  prompt?: string;
};

But I provided:

{
  model: "...",
  instructions: "..."
}

Since instructions wasn't part of the type definition, TypeScript rejected it.

The Important Lesson

Never assume a property exists just because it exists in another AI framework.

Different frameworks often use different names for the same concept.

ConceptPossible Property Names
System Promptprompt
System Promptinstructions
System Promptsystem
System PromptsystemPrompt
System Promptcontext

They all mean roughly:

"Tell the AI how it should behave."

The name depends entirely on the library.

Why do docs sometimes use instructions?

This is one of the most common sources of confusion in JavaScript/TypeScript ecosystems.

Different libraries and even different versions of the same library often use different names for the same concept:

LibraryProperty
OpenAI Responses APIinstructions
OpenAI Agents SDKinstructions
LangChainsystemPrompt
CopilotKit v1.xprompt
Some CopilotKit v2 examplessystem message in a factory
Other AI SDKssystem

They're all trying to accomplish the same thing:

"Tell the AI how it should behave."

The property name depends entirely on the library author.

The Golden Rule

When using TypeScript:

Trust the types more than the documentation.

Documentation can be:

  • outdated
  • written for another version
  • written for another package

Your installed types are always the source of truth.

Fast Debugging Technique #1

Use IntelliSense.

new BuiltInAgent({
  model: "",
  // press Ctrl+Space here
});

VS Code will show every valid property.

This is often faster than searching docs.

Fast Debugging Technique #2

Inspect the Type

type Config = ConstructorParameters<
  typeof BuiltInAgent
>[0];

Hover over Config.

You'll immediately see the expected structure.

Fast Debugging Technique #3

Read the Error Literally

Many developers try random fixes.

Instead, read the error exactly.

Example:

'instructions' does not exist in type
'BuiltInAgentConfiguration'

Translation:

"The object type does not contain a property named instructions."

That's all the error is saying.

AI Development Pattern:

Prompt as Configuration

Think of prompts as configuration files.

Bad:

prompt: "You are helpful."

Better:

prompt: `
You are Erzan's personal AI assistant.

You can answer questions about projects.

Be concise.
Recommend projects when relevant.
`

Best:

prompt: `
You are Erzan's personal AI assistant.

Responsibilities:
- Answer project questions
- Recommend projects
- Explain technologies
- Share demo links when available

Communication Style:
- concise
- technical
- professional

Project Knowledge:

${projectContext}
`

Structure usually beats raw text.

AI Development Pattern:

Label Everything

LLMs understand structure extremely well.

Weak:

Title: Portfolio
Description: ...
Stack: React

Strong:

Project Name:
Portfolio

Description:
...

Technologies:
React
Next.js
TypeScript

Github:
...

Demo:
...

Clear labels improve retrieval accuracy.

AI Development Pattern:

Give the AI a Job

Weak Prompt:

You know about Erzan.

Strong Prompt:

You are Erzan's portfolio assistant.

Your goals:

1. Recommend relevant projects.
2. Explain technologies.
3. Share demo links.
4. Keep responses concise.

The more explicit the role, the more predictable the behavior.

TypeScript Pattern:

Let the Compiler Teach You

Most developers fight TypeScript.

Advanced developers use TypeScript as documentation.

Examples:

type User = ...
type Config = ...
type Props = ...

When you're unsure:

type X = SomeLibraryType;

Hover.

Read.

Learn.

The compiler often knows more than the docs.

Debugging Mindset

When something fails:

Step 1​

Read the error.

Step 2​

Identify the type involved.

Example:

BuiltInAgentConfiguration

Step 3​

Inspect that type.

Step 4​

Compare what you passed vs what it expects.

This solves a huge percentage of TypeScript issues.

A Mental Model for Modern Development

Think of modern development as three layers.

Layer 1: Runtime​

What actually executes.

Example:

new BuiltInAgent(...)

Layer 2: Types​

What TypeScript expects.

Example:

BuiltInAgentConfiguration

Layer 3: Documentation​

What humans wrote.

Example:

  • blog posts
  • tutorials
  • docs

When they disagree:

Types > Documentation

because the compiler is checking the actual installed package.

My Personal Checklist When Integrating Any SDK

  1. Install package.
  2. Check version.
  3. Inspect types.
  4. Use IntelliSense.
  5. Read docs.
  6. Build small prototype.
  7. Expand gradually.

Never jump directly into large implementations.

Key Takeaway

The bug wasn't really about instructions vs prompt.

The real lesson was:

TypeScript was already telling me exactly what was wrong.

Instead of guessing, inspect the type definition and let the compiler guide you.

That's one of the fastest ways to become effective with modern TypeScript and AI SDKs.