Responses

curl https://ai-api.vanguardinitiative.com/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast",
    "system": "Use search_gigs to find freelancers. Answer in the language you are asked in.",
    "messages": [
      { "role": "user", "content": "Find me a logo designer in Vientiane" }
    ],
    "tools": [{
      "name": "search_gigs",
      "description": "Search gigs by keyword, optionally in one city.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "city": { "type": "string" }
        },
        "required": ["query"]
      }
    }],
    "endUserId": "user-42"
  }'

const API = 'https://ai-api.vanguardinitiative.com/v1/responses';
const SYSTEM = 'Use search_gigs to find freelancers. Answer in the language you are asked in.';

const tools = [
  {
    name: 'search_gigs',
    description: 'Search gigs by keyword, optionally in one city.',
    inputSchema: {
      type: 'object',
      properties: { query: { type: 'string' }, city: { type: 'string' } },
      required: ['query'],
    },
  },
];

const messages: object[] = [
  { role: 'user', content: 'Find me a logo designer in Vientiane' },
];

// One step: the model, your system prompt, the whole history, your tools.
function respond() {
  return fetch(API, {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      model: 'fast',
      system: SYSTEM,
      messages,
      tools,
      endUserId: 'user-42',
    }),
  }).then((r) => r.json());
}

const first = await respond();
first.finishReason; // 'tool-calls'

curl https://ai-api.vanguardinitiative.com/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "fast",
    "system": "Use search_gigs to find freelancers. Answer in the language you are asked in.",
    "messages": [
      { "role": "user", "content": "Find me a logo designer in Vientiane" },
      { "role": "assistant", "toolCalls": [{
        "id": "call_242746",
        "name": "search_gigs",
        "input": { "query": "logo design", "city": "Vientiane" },
        "signature": "CiQB..."
      }] },
      { "role": "tool", "toolCallId": "call_242746", "name": "search_gigs",
        "output": "[{\"title\":\"Logo design\",\"seller\":\"Noy\",\"priceLak\":250000}]" }
    ],
    "tools": [{
      "name": "search_gigs",
      "description": "Search gigs by keyword, optionally in one city.",
      "inputSchema": {
        "type": "object",
        "properties": {
          "query": { "type": "string" },
          "city": { "type": "string" }
        },
        "required": ["query"]
      }
    }],
    "endUserId": "user-42"
  }'

// 1. The model's turn, exactly as it came back: ids, inputs, signatures.
messages.push({ role: 'assistant', toolCalls: first.output.toolCalls });

// 2. One tool message per call. output is a string: serialize your result.
for (const call of first.output.toolCalls) {
  const rows = await searchGigs(call.input.query, call.input.city); // your code
  messages.push({
    role: 'tool',
    toolCallId: call.id,
    name: call.name,
    output: JSON.stringify(rows),
  });
}

// 3. Call again. respond() sends the same tools, and it has to: every tool
//    named in the history must be declared.
const second = await respond();

second.finishReason; // 'stop'
second.output.text; // 'Noy in Vientiane does professional logo design, ...'

// API, SYSTEM and tools as in step 1.

type ToolCall = {
  id: string;
  name: string;
  input: Record<string, unknown>;
  signature?: string;
};

type Message =
  | { role: 'user'; content: string }
  | { role: 'assistant'; content?: string; toolCalls?: ToolCall[] }
  | { role: 'tool'; toolCallId: string; name: string; output: string };

type ResponsesResult = {
  status: 'success';
  id: string;
  model: string;
  output: { text: string; toolCalls: ToolCall[]; object?: unknown };
  finishReason: 'stop' | 'tool-calls' | 'length' | 'content-filter';
  usage: { inputTokens: number; outputTokens: number };
  credits: number;
  latencyMs: number;
};

// Your tools, run by your code. The API only ever tells you which one to call.
async function runTool(call: ToolCall): Promise<unknown> {
  switch (call.name) {
    case 'search_gigs': {
      const { query, city } = call.input as { query: string; city?: string };
      return searchGigs(query, city);
    }
    default:
      return { error: 'Unknown tool: ' + call.name };
  }
}

async function respond(messages: Message[]): Promise<ResponsesResult> {
  const res = await fetch(API, {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.VANGUARD_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ model: 'fast', system: SYSTEM, messages, tools }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(body.code + ': ' + body.message);
  return body;
}

export async function ask(question: string, maxSteps = 5): Promise<string> {
  const messages: Message[] = [{ role: 'user', content: question }];

  for (let step = 0; step < maxSteps; step++) {
    const r = await respond(messages);
    if (r.finishReason !== 'tool-calls') return r.output.text;

    // Echo the calls back as they came, signature included.
    messages.push({
      role: 'assistant',
      content: r.output.text || undefined,
      toolCalls: r.output.toolCalls,
    });

    // Answer every call before calling again. A tool that throws still gets an
    // answer, so the model can see what went wrong and try something else.
    for (const call of r.output.toolCalls) {
      const result = await runTool(call).catch((e) => ({ error: String(e) }));
      messages.push({
        role: 'tool',
        toolCallId: call.id,
        name: call.name,
        output: JSON.stringify(result),
      });
    }
  }
  throw new Error('Still calling tools after ' + maxSteps + ' steps');
}

curl https://ai-api.vanguardinitiative.com/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "smart",
    "messages": [{
      "role": "user",
      "content": "Lao-English logo for my cafe in Luang Prabang, ~300,000 kip, in 2 weeks"
    }],
    "responseFormat": {
      "type": "json_schema",
      "name": "job_brief",
      "schema": {
        "type": "object",
        "properties": {
          "category": {
            "type": "string",
            "enum": ["design", "writing", "translation", "development", "other"]
          },
          "city": { "type": "string" },
          "budgetLak": { "type": "integer" },
          "deadlineDays": { "type": "integer" }
        },
        "required": ["category", "city", "budgetLak", "deadlineDays"]
      }
    }
  }'

const res = await fetch('https://ai-api.vanguardinitiative.com/v1/responses', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'smart',
    messages: [{ role: 'user', content: jobPostText }],
    responseFormat: {
      type: 'json_schema',
      name: 'job_brief',
      schema: {
        type: 'object',
        properties: {
          category: {
            type: 'string',
            enum: ['design', 'writing', 'translation', 'development', 'other'],
          },
          city: { type: 'string' },
          budgetLak: { type: 'integer' },
          deadlineDays: { type: 'integer' },
        },
        required: ['category', 'city', 'budgetLak', 'deadlineDays'],
      },
    },
  }),
}).then((r) => r.json());

// Only a finished answer carries an object; a truncated one does not.
const brief = res.finishReason === 'stop' ? res.output.object : null;