Skip to main content

Agent Invocation

The client.agents resource provides invoke and stream methods with full generic type inference.

Basic Invocation​

import { FaosClient } from '@faos/sdk';

const client = new FaosClient({ apiKey: 'faos_sk_...' });

const response = await client.agents.invoke(
  'credit-risk-analyst',
  { query: 'Analyze Q1 2024 revenue trends' },
);

console.log(response.result);     // Record<string, unknown>
console.log(response.metadata);   // { model, durationMs, ... }
console.log(response.usage);      // { promptTokens, completionTokens, totalTokens }
console.log(response.requestId);  // For debugging
<PlaygroundButton code={"import { FaosClient } from '@faos/sdk';\n\nconst client = new FaosClient({ apiKey: 'faos_sk_...' });\n\nconst response = await client.agents.invoke(\n 'credit-risk-analyst',\n { query: 'Analyze Q1 2024 revenue trends' },\n);\n\nconsole.log(response.result); // Record<string, unknown>\nconsole.log(response.metadata); // { model, durationMs, ... }\nconsole.log(response.usage); // { promptTokens, completionTokens, totalTokens }\nconsole.log(response.requestId); // For debugging"} lang="typescript" />

Generic Type Inference​

The key DX feature: pass a generic parameter for fully typed results.

interface CreditAnalysis {
  insights: string[];
  riskScore: number;
  recommendation: string;
}

const res = await client.agents.invoke<CreditAnalysis>(
  'credit-risk-analyst',
  { query: 'Analyze Q1 2024' },
);

// All fully typed:
res.result.insights;      // string[]
res.result.riskScore;     // number
res.result.recommendation; // string
<PlaygroundButton code={"interface CreditAnalysis {\n insights: string[];\n riskScore: number;\n recommendation: string;\n}\n\nconst res = await client.agents.invoke<CreditAnalysis>(\n 'credit-risk-analyst',\n { query: 'Analyze Q1 2024' },\n);\n\n// All fully typed:\nres.result.insights; // string[]\nres.result.riskScore; // number\nres.result.recommendation; // string"} lang="typescript" />

Without a generic, result defaults to Record<string, unknown>.

Multi-Tenant Invocation​

const response = await client.agents.invoke(
  'credit-risk-analyst',
  { query: 'Analyze Q1' },
  { tenantId: 'tenant-abc123' },
);

A2A Format​

Auto-detected when task key is present in input:

// FAOS-native format
await client.agents.invoke('analyst', { query: '...' });

// A2A format — auto-detected
await client.agents.invoke('analyst', {
  task: { id: 'task-1', input: { query: '...' } },
});

Response Type​

interface FaosResponse<T = Record<string, unknown>> {
  result: T;
  metadata: ResponseMetadata;
  usage: TokenUsage;
  requestId: string;
}

interface TokenUsage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
}