open-responses-agent-skill AGENTS.md

Open Responses Agent Development

About This Skill

Build autonomous agents using the Open Responses API via the HuggingFace Inference Providers router.

Core Knowledge

Single Unified Endpoint

All requests go to ONE endpoint:

https://router.huggingface.co/v1/responses

Provider selection is done via MODEL SUFFIX (not separate URLs).

Provider Selection via Model Suffix

moonshotai/Kimi-K2-Instruct-0905:groq      # Groq (fast inference)
meta-llama/Llama-3.1-70B-Instruct:together # Together AI
meta-llama/Llama-3.1-70B-Instruct:nebius   # Nebius (EU infrastructure)
meta-llama/Llama-3.1-70B-Instruct:auto     # Auto selection

Request Structure

{
  "model": "moonshotai/Kimi-K2-Instruct-0905:groq",
  "instructions": "You are a helpful assistant.",
  "input": "User's task",
  "tools": [...],
  "tool_choice": "auto",
  "reasoning": { "effort": "medium" }
}

Response Structure

{
  "id": "resp_abc123",
  "model": "moonshotai/Kimi-K2-Instruct-0905",
  "output": [
    { "type": "reasoning", "content": "..." },
    { "type": "function_call", "name": "...", "arguments": {...} },
    { "type": "function_call_output", "output": "..." },
    { "type": "message", "content": "..." }
  ],
  "output_text": "convenience helper",
  "usage": { "input_tokens": 100, "output_tokens": 200 }
}

Tool Definition Format

Tools are defined at TOP LEVEL - NOT nested in function:

{
  "type": "function",
  "name": "search",
  "description": "Search for information",
  "parameters": { ... }
}

Reasoning Visibility

Level	Field	Providers
RAW	content	Groq, Together, Nebius (open weight)
SUMMARY	summary	Some proprietary models
ENCRYPTED	encrypted_content	Most proprietary models

Control with: "reasoning": { "effort": "low" | "medium" | "high" }

SDK Usage (Recommended)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://router.huggingface.co/v1",
  apiKey: process.env.HF_TOKEN,
});

const response = await client.responses.create({
  model: "moonshotai/Kimi-K2-Instruct-0905:groq",
  instructions: "You are a helpful assistant.",
  input: "Your task here",
});

console.log(response.output_text);
for (const item of response.output) {
  console.log(item.type, item);
}