Kern

Structured Input for Agents

Validate input data for agents with Pydantic models.

Pass structured data to agents using Pydantic models. You can either pass a model instance directly or set input_schema to validate dictionaries automatically.

Input Format Types

Use CaseInput Format
You're building the input in codeUse Pydantic Model instance
Input comes from external sources (APIs, files, user input)Use input_schema

Using Pydantic Models

Pass a Pydantic model instance to input:

1from pydantic import BaseModel, Field
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4
5class ResearchRequest(BaseModel):
6    topic: str
7    max_sources: int = Field(ge=1, le=20, default=5)
8    focus_areas: list[str] = Field(default_factory=list)
9
10agent = Agent(model=OpenAIResponses(id="gpt-5.2"))
11
12# Pass the model instance directly
13request = ResearchRequest(
14    topic="AI Agents",
15    max_sources=10,
16    focus_areas=["multi-agent systems", "tool use"]
17)
18
19response = agent.run(input=request)

Validation happens when you create the model instance. Invalid data raises a Pydantic ValidationError before the agent runs.

Using input_schema

Set input_schema on the agent to validate dictionaries automatically:

1from pydantic import BaseModel, Field
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4
5class ResearchRequest(BaseModel):
6    topic: str
7    max_sources: int = Field(ge=1, le=20, default=5)
8    focus_areas: list[str] = Field(default_factory=list)
9
10agent = Agent(
11    model=OpenAIResponses(id="gpt-5.2"),
12    input_schema=ResearchRequest,
13)
14
15# Pass a dict - validated against ResearchRequest
16response = agent.run(
17    input={
18        "topic": "AI Agents",
19        "max_sources": 10,
20        "focus_areas": ["multi-agent systems", "tool use"]
21    }
22)

This is useful when input comes from external sources like API requests or configuration files.

Handling Input ValidationError

Invalid input raises a Pydantic ValidationError:

1from pydantic import BaseModel, Field, ValidationError
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4
5class OrderRequest(BaseModel):
6    product_id: str
7    quantity: int = Field(gt=0)
8
9agent = Agent(
10    model=OpenAIResponses(id="gpt-5.2"),
11    input_schema=OrderRequest,
12)
13
14try:
15    agent.run(input={"product_id": "SKU-123", "quantity": -5})
16except ValidationError as e:
17    print(e)
18    # quantity: Input should be greater than 0

Common Patterns

API Request Handler

1from pydantic import BaseModel, Field
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4
5class SummaryRequest(BaseModel):
6    text: str = Field(min_length=1, max_length=50000)
7    max_length: int = Field(ge=50, le=500, default=200)
8    style: str = Field(default="concise")
9
10agent = Agent(
11    model=OpenAIResponses(id="gpt-5.2"),
12    input_schema=SummaryRequest,
13)
14
15# In your API endpoint
16def summarize(request_data: dict):
17    response = agent.run(input=request_data)  # Auto-validated
18    return {"summary": response.content}

Configuration-Driven Tasks

1from pydantic import BaseModel, Field
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4from kern.tools.hackernews import HackerNewsTools
5
6class ResearchConfig(BaseModel):
7    topic: str
8    depth: int = Field(ge=1, le=10, default=5)
9    include_sources: bool = True
10    output_format: str = Field(default="markdown")
11
12agent = Agent(
13    model=OpenAIResponses(id="gpt-5.2"),
14    tools=[HackerNewsTools()],
15    input_schema=ResearchConfig,
16)
17
18# Load config from file or environment
19config = {
20    "topic": "LLM frameworks",
21    "depth": 7,
22    "include_sources": True
23}
24
25response = agent.run(input=config)

Nested Models

1from pydantic import BaseModel
2from kern.agent import Agent
3from kern.models.openai import OpenAIResponses
4
5class Author(BaseModel):
6    name: str
7    email: str
8
9class ArticleRequest(BaseModel):
10    title: str
11    author: Author
12    tags: list[str]
13
14agent = Agent(
15    model=OpenAIResponses(id="gpt-5.2"),
16    input_schema=ArticleRequest,
17)
18
19response = agent.run(
20    input={
21        "title": "Getting Started with Kern",
22        "author": {"name": "Jane Doe", "email": "jane@example.com"},
23        "tags": ["tutorial", "agents"]
24    }
25)

Related