Skip to content

data-models.md

Latest commit

 

History

History
138 lines (109 loc) · 7.11 KB

data-models.md

File metadata and controls

138 lines (109 loc) · 7.11 KB
Raw

Data Models

AgentHub uses UniConfig, UniMessage, and UniEvent to represent request options, conversation history, and streamed outputs across providers.

UniConfig

UniConfig is the request config for streamingResponse and streamingResponseStateful. All fields are optional.

const config = {
  max_tokens: 1024,
  temperature: 1.0,
  tools: [{
    name: "get_weather",
    description: "Get weather.",
    parameters: {
      type: "object",
      properties: { location: { type: "string", description: "City name." } },
      required: ["location"],
    },
  }],
  tool_choice: "auto",
  thinking_summary: true,
  thinking_level: ThinkingLevel.HIGH,
  system_prompt: "You are helpful.",
  prompt_caching: PromptCaching.ENABLE,
  image_config: { aspect_ratio: "4:3", image_size: "1K" },
  tts_config: [{ voice: "Kore" }],
  embedding_config: { dimensions: 768 },
  trace_id: "agent1/conversation_001",
};

Fields:

  • max_tokens (number): Output token limit.
  • temperature (number): Sampling temperature; support varies by model.
  • tools (ToolSchema[]): Tools with name, description, and optional JSON Schema parameters.
  • thinking_summary (boolean): Request a thinking summary when supported.
  • thinking_level (ThinkingLevel): NONE, LOW, MEDIUM, HIGH, or XHIGH.
  • tool_choice (ToolChoice): auto, required, none, or a list of tool names; support varies by model.
  • system_prompt (string): System instruction text.
  • prompt_caching (PromptCaching): ENABLE, DISABLE, or ENHANCE.
  • image_config (ImageConfig): aspect_ratio (1:1, 2:3, 3:2, 3:4, 4:3, 9:16, 16:9, 21:9) and image_size (1K, 2K).
  • tts_config (SpeakerConfig[]): Voice config; each item has voice and optional speaker.
  • embedding_config (EmbeddingConfig): Embedding config, currently dimensions.
  • trace_id (string): Stable ID for tracer output.

UniMessage

UniMessage is the durable message shape used in history.

const message = {
  role: "user",
  content_items: [
    { type: "text", text: "Hello", fidelity: { phase: "commentary" } },
    { type: "image_url", image_url: "https://example.com/image.jpg" },
    { type: "inline_data", data: Buffer.from("..."), mime_type: "image/png", fidelity: { signature: "sig" } },
    { type: "thinking", thinking: "Reasoning", fidelity: { signature: "sig" } },
    { type: "inline_thinking", data: Buffer.from("..."), mime_type: "image/png", fidelity: { signature: "sig" } },
    { type: "tool_call", name: "get_weather", arguments: { location: "Paris" }, tool_call_id: "call_1", fidelity: { signature: "sig" } },
    { type: "tool_result", text: "22 C", tool_call_id: "call_1" },
    { type: "embedding", embedding: [0.1, 0.2] },
  ],
};

Fields:

  • role (Role): user or assistant.
  • content_items (ContentItem[]): Message payload.
  • usage_metadata (UsageMetadata | null): Optional token counts on completed assistant messages.
  • finish_reason (FinishReason | null): stop, length, tool_call, unknown, or null.
  • created_at (number): Unix milliseconds.

Content items:

  • text: Text chunk; may carry fidelity.
  • image_url: Image URL or data URI.
  • inline_data: Inline media bytes with MIME type; may carry fidelity.
  • thinking: Text reasoning content; may carry fidelity.
  • inline_thinking: Binary reasoning artifact; may carry fidelity.
  • tool_call: Complete model tool request with name, args, ID, and optional fidelity.
  • tool_result: Tool output text for a tool_call_id; may include image URLs.
  • embedding: Numeric embedding vector.

fidelity is an arbitrary JSON object of wire-level data the client recorded to reproduce the original message on replay — thinking signatures, phase labels, the upstream reasoning field name, and the like. It is opaque: pass it back unchanged, never modify or drop it.

UniEvent

UniEvent is the streamed output shape. Read token counts from usage_metadata here.

const event = {
  role: "assistant",
  event_type: "delta",
  content_items: [
    { type: "partial_tool_call", name: "get_weather", arguments: "{\"location\":\"Par", tool_call_id: "call_1" },
  ],
  usage_metadata: { cached_tokens: 0, prompt_tokens: 10, thoughts_tokens: null, response_tokens: 1 },
  finish_reason: null,
  created_at: 1694502400000,
};

Fields:

  • role (Role): user or assistant.
  • event_type (EventType): start, delta, stop, or unused.
  • content_items (PartialContentItem[]): Stream payload; includes ContentItem plus partial_tool_call.
  • usage_metadata (UsageMetadata | null): Token counts: cached_tokens, prompt_tokens, thoughts_tokens, response_tokens. Token math: input = cached_tokens + prompt_tokens; output = thoughts_tokens + response_tokens; treat null as 0.
  • finish_reason (FinishReason | null): stop, length, tool_call, unknown, or null.
  • created_at (number): Unix milliseconds.

Event-only content item:

  • partial_tool_call: Streaming tool-call fragment with name, partial JSON arguments, and tool_call_id.

Tool-Call Streaming Protocol

Across providers a tool call streams as the same ordered sequence of events, so consumers handle every model the same way:

  1. Announce (name + id first). The first event for a tool call carries a partial_tool_call whose name and tool_call_id are non-empty and whose arguments is a JSON string fragment (often ""). The tool's identity arrives no later than the first argument bytes.
  2. Argument deltas. Zero or more delta events follow, each carrying a partial_tool_call whose arguments is the next fragment of the arguments JSON string (name and tool_call_id are empty ""). Concatenate the fragments in order.
  3. Complete call (last). One final event carries a complete tool_call item: name, tool_call_id, and arguments parsed into an object. Read tool calls from these tool_call items; treat the partial_tool_call fragments as live progress only.

The final arguments value must parse to a JSON object. If the streamed JSON is malformed, truncated, or parses to a non-object value such as an array, AgentHub raises ToolCallArgumentParseError instead of yielding a complete tool_call. The error carries client, toolName, toolCallId, rawArgumentsLength, and rawArgumentsPreview so the caller can log the bad model output and retry or re-prompt without executing a tool from partial arguments.

For consecutive or parallel tool calls, each new call restarts at step 1 with its own name and tool_call_id, so one call's arguments never bleed into the next. Send each tool result back with the exact tool_call_id from its tool_call.

Errors

Errors thrown by AgentHub inherit AgentHubError, an Error subclass:

  • ToolCallArgumentParseError — streamed tool-call arguments were malformed or not a JSON object. It carries client, toolName, toolCallId, rawArgumentsLength, and rawArgumentsPreview.
  • EmptyResponseError — the response finished with thinking content only, which fails with a 400 error when sent back on the next turn. It carries client and finishReason.