Building Type-Safe AI Agents

Why Type Safety Matters for Agents

AI agents are inherently unpredictable — they rely on language models that produce variable outputs. That's exactly why the surrounding code should be as predictable as possible. Type safety creates a contract between your agent's components: tools declare what they accept, skills define what they return, and the framework enforces those contracts at every boundary.

The Cost of Untyped Agents

Without type safety, common failure modes include:

• A tool receives a string when it expects a number, causing a silent calculation error
• An agent returns a response in the wrong format, breaking downstream consumers
• A plugin passes malformed data to a memory store, corrupting state
• An A2A message contains unexpected fields that crash the receiving agent

These bugs are hard to reproduce because they depend on LLM output, which varies between runs. Type validation catches them deterministically.

Schema-Driven Tool Definitions

Agent Builder Lib uses schemas to define tool interfaces. In TypeScript, you get compile-time validation. In Python, you get runtime validation via Pydantic. Either way, the LLM sees a precise JSON Schema for each tool.

TypeScript Example

import { defineTool, z } from '@agent-builder/sdk';

const searchTool = defineTool({
  name: 'search_documents',
  description: 'Search internal documents by query',
  input: z.object({
    query: z.string().min(1).describe('The search query'),
    limit: z.number().int().min(1).max(50).default(10),
    filters: z.object({
      department: z.enum(['engineering', 'sales', 'support']).optional(),
      dateAfter: z.string().datetime().optional(),
    }).optional(),
  }),
  output: z.array(z.object({
    title: z.string(),
    snippet: z.string(),
    score: z.number(),
  })),
  handler: async (input) => {
    // input is fully typed: { query: string; limit: number; filters?: ... }
    return searchIndex(input.query, input.limit, input.filters);
  },
});

If the LLM passes limit: "ten" instead of limit: 10, the schema validator rejects the call before your handler runs. The SDK then sends a correction prompt to the LLM with the validation error, giving it a chance to retry with valid input.

Python Example

from agent_builder import tool
from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(min_length=1, description="The search query")
    limit: int = Field(default=10, ge=1, le=50)
    department: str | None = Field(default=None)

class SearchResult(BaseModel):
    title: str
    snippet: str
    score: float

@tool(description="Search internal documents by query")
async def search_documents(input: SearchInput) -> list[SearchResult]:
    results = await search_index(input.query, input.limit)
    return [SearchResult(**r) for r in results]

Typed Agent Responses

Beyond tools, you can type the agent's final output. This is critical when agents feed data to other systems — APIs, databases, or other agents via A2A:

const agent = new Agent({
  name: 'classifier',
  responseSchema: z.object({
    category: z.enum(['bug', 'feature', 'question']),
    confidence: z.number().min(0).max(1),
    summary: z.string(),
  }),
});

The agent will keep refining its response until it matches the schema, or fail with a clear error. No more parsing free-text LLM output and hoping for the best.

Benefits in Production

• Fewer runtime errors: Schema validation catches malformed data at the boundary, not deep inside your business logic
• Better LLM performance: Precise schemas give the model a clear target, reducing hallucinated or malformed tool calls
• Easier debugging: When a validation error occurs, you see exactly which field failed and why — not a stack trace from unrelated code
• Safe A2A communication: Typed AgentCards and task payloads ensure agents from different teams can communicate without surprises

Getting Started

Type safety is built into Agent Builder Lib by default — you don't need to opt in. Install the SDK, define your tools with schemas, and the framework handles validation, error recovery, and schema generation for A2A compatibility. Start building on the Oya.ai platform today.