@kentcdodds/ai

@kentcdodds/ai

Intent

Hosted AI chat app and package-first generic Kody agent turns. Runs OpenAI-compatible chat calls through the Cloudflare AI Gateway (cloudflareAiGatewayId user value; auto-resolved or created as gateway kody on first run). Ships a default system prompt (defaultKodyAgentSystem) that teaches the generic search → entity detail → execute workflow. Prefer runModelStep when a host package should execute kody.search / kody.execute in its own package context (correct secret allowlists). The convenience agentChatTurn / runAgentTurn loop still runs tools via direct runtime kody.search/kody.execute in the ai package — not via self-MCP. When a model emits tool calls as JSON text instead of structured tool_calls, the turn loop recovers and executes them.

When To Use

• Run a single tool-using agent turn from Discord chat, email automation, or another package harness.
• Stream or poll buffered turn events (assistant_delta, tool_call_*, turn_complete) for UI or workflow glue.
• Open the hosted HTML chat app for a quick manual turn (open_generated_ui({ kody_id: 'ai' })).
• Start a storage-backed background turn when a workflow needs start / readNext / cancel semantics.
• Import ./turn directly when you only need the engine without the root wrapper.

Required setup

• User-scoped cloudflareApiToken secret and cloudflareAccountId value.
• Optional cloudflareAiModel value (defaults to @cf/mistralai/mistral-small-3.1-24b-instruct).
• Optional cloudflareAiGatewayId value; auto-created as gateway kody when the token can manage AI Gateway.
• Package storage and workflows runtime for ./runs background polling (provided by Kody when the package app/jobs run).
• Host packages that need their own secret allowlists should call runModelStep and execute tools with local kody.search / kody.execute.
• Convenience agentChatTurn tool calls run as package ai, so secrets used that way must allow package ai.

Exports

• kody:@kentcdodds/ai — default agentChatTurn; also agentTurnStream, runModelStep, defaultKodyAgentSystem, startAgentTurn, readNextAgentTurnEvents, cancelAgentTurn.
• kody:@kentcdodds/ai/model-step — model-only completion (runModelStep) plus kodyAgentToolDefinitions for host-side tool loops.
• kody:@kentcdodds/ai/turn — merged agent-turn engine (runAgentTurn default export).
• kody:@kentcdodds/ai/app — hosted fetch handler (GET form, POST one turn as JSON events).
• kody:@kentcdodds/ai/runs — storage-backed turn start, poll, cancel, and runStoredAgentTurn worker default export.
• kody:@kentcdodds/ai/types — AgentTurnInput, AgentTurnResult, AgentTurnStreamEvent, and related types.

agentTurnStream awaits the full turn then yields at most one assistant_delta plus turn_complete (not incremental token streaming). modelLane on input is accepted but currently ignored.

Example

import { agentTurnStream } from 'kody:@kentcdodds/ai'

export default async function main() {
	let answer = ''
	for await (const event of agentTurnStream({
		messages: [{ role: 'user', content: 'Search for weather helpers' }],
	})) {
		if (event.type === 'assistant_delta') answer += event.text
		if (event.type === 'turn_complete') return { answer: event.assistantText, tools: event.toolCalls }
	}
	return { answer }
}