Skip to content

core-runtime.md

Latest commit

 

History

History
57 lines (35 loc) · 3.1 KB

core-runtime.md

File metadata and controls

57 lines (35 loc) · 3.1 KB
Raw

Core Runtime Design

English | 简体中文

This document describes the goals, direction, and boundaries of the tinyagent Core Runtime.

Goals

The Core Runtime provides the single agent execution path used by both the CLI and the in-process Python SDK. It brings configuration, providers, streaming events, and stable results together in a small, well-defined conversational core.

The module aims to:

  • serve the CLI, async SDK, and sync SDK with the same application logic;
  • keep the implementation asynchronous, with the synchronous API acting only as a controlled facade;
  • isolate provider SDKs and upstream response formats behind narrow protocols owned by tinyagent;
  • keep public result, event, and error shapes stable as later modules extend the same execution chain;
  • provide actionable error semantics for timeouts, authentication failures, rate limits, interrupted streams, and rejected requests.

Design direction

The main execution path remains:

CLI / SDK -> Agent Runtime -> Provider -> streamed events / RunResult

Sessions, Tools, Memory, MCP, and Skills all join this execution path. None of them introduces a second runtime used by only one entry point. The async API owns resource lifecycles and cancellation propagation; the sync SDK invokes the same async implementation through a dedicated background event loop.

The provider boundary uses tinyagent's own ChatRequest, ProviderResponse, ProviderStreamEvent, and stable error types. OpenAI SDK types and raw provider JSON remain inside adapters and do not leak into the Runtime, Sessions, or public return types.

Public interfaces

The core public types include:

  • Message(role, content);
  • RunResult(run_id, session_id, content, usage, stop_reason, tools_used);
  • AgentEvent;
  • AsyncTinyAgent and TinyAgent.

Event names describe the run lifecycle, including run.started, text.delta, tool.started, tool.completed, tool.failed, run.completed, and run.failed. New capabilities should add events instead of changing the meaning of existing ones.

Provider strategy

tinyagent explicitly supports DeepSeek and user-configured OpenAI-compatible providers, using Chat Completions only. Provider names, models, base URLs, API key environment variables, timeouts, and bounded retries are declared in TOML; providers are not discovered through package scanning.

Retries cover only transient failures that are safe to retry, and remain bound by the overall request timeout or streaming idle timeout. Deterministic failures such as authentication errors and invalid requests are not hidden behind blind retries.

Boundaries and non-goals

The Core Runtime does not:

  • expose an OpenAI-compatible HTTP service;
  • implement the Responses API, fallback routing, or a large provider registry;
  • introduce a Web UI, chat channels, multi-tenancy, or subagents;
  • parse MCP SDK objects, Skill files, or Workspace file-operation details in the core layer.

These boundaries keep the Runtime focused on execution orchestration while dynamic capabilities are validated and normalized at the edges of their owning modules.