invoke()

client.invoke() sends messages to the agent graph and resolves with the final result. If the agent asks for a remote tool, the client runs your registered handler and calls the server again, repeating until the agent answers or recursion_limit is reached. For incremental output, use stream().

Endpoint: POST /v1/graph/invoke

Signature

invoke() takes an array of Message objects and an optional options object, and returns a promise of InvokeResult. It is a method of TenxGraphClient, so create a client first (see Client).

import { TenxGraphClient, Message } from '10xgraph-client';

// client.invoke(messages, options?) => Promise<InvokeResult>
invoke(
  messages: Message[],
  options?: {
    initial_state?: Record<string, any>;
    config?: Record<string, any>;
    recursion_limit?: number;
    response_granularity?: 'full' | 'partial' | 'low';
    onPartialResult?: InvokeCallback;
  }
): Promise<InvokeResult>

Parameters

The first parameter carries the conversation input and the second tunes the run. Only messages is required.

messages

messages is an array of Message objects. The last one is normally the user’s input, and you can add a system message before it. Each message is serialised before sending. If message_id is null or undefined, the payload uses "0" and the server assigns a real id.

import { Message } from '10xgraph-client';

// A system message sets the persona, the user message is the input
const systemMsg = Message.text_message('You are a concise assistant.', 'system');
const userMsg = Message.text_message('What is 2 + 2?');

options

All options are optional. The defaults below are the values the client applies when you omit the option.

Return value

invoke() resolves with an InvokeResult. The messages, state, context, summary and meta fields come from the last server response. all_messages collects everything across iterations.

recursion_limit_reached is computed from the iteration count, so it is also true when the final answer arrived exactly on the last allowed iteration. Check the last message for pending remote tool calls if you need to tell the two cases apart.

Use meta.thread_id to continue a conversation in a later call:

// First turn: the thread is created with the id you choose
const first = await client.invoke([Message.text_message('Hi')], {
  config: { thread_id: 'conv-001' },
});

// Second turn: reuse the id reported by the server
const followUp = await client.invoke([Message.text_message('Tell me more')], {
  config: { thread_id: first.meta.thread_id },
});

Response granularity

response_granularity decides which parts of the graph output the server includes. Messages are always returned; the rest depends on the value.

The client sends 'full' when you omit the option. The server’s own default is low, but a call through TenxGraphClient never relies on it.

Progress callback

onPartialResult receives an InvokePartialResult after each request, before any tool handlers run. It is the way to show progress during a multi-step run without switching to streaming. The client awaits the callback, so an async callback delays the next iteration.

interface InvokePartialResult {
  iteration: number;
  messages: Message[];
  state?: AgentState;
  context?: Message[];
  summary?: string | null;
  meta: InvokeMetadata;
  has_tool_calls: boolean; // the response contains remote tool calls
  is_final: boolean;       // no remote tool calls, this is the last iteration
}

type InvokeCallback = (partial: InvokePartialResult) => void | Promise<void>;

// Log progress while the agent works
const result = await client.invoke([Message.text_message('Weather in Paris?')], {
  onPartialResult(partial) {
    if (partial.has_tool_calls) {
      console.log(`Iteration ${partial.iteration}: running tools`);
    }
    if (partial.is_final) {
      console.log('Final answer received');
    }
  },
});

Remote tool call loop

The client resolves remote tool calls for you. When a response contains a remote_tool_call content block and a ToolExecutor is available (it is, on every TenxGraphClient), the client runs the matching handler and sends the results back.

1. The client posts your messages to /v1/graph/invoke.
2. If any response message holds a remote_tool_call block, the client passes those messages to its tool executor, which calls the handlers you registered with client.registerToolHandler().
3. The tool result messages are added to all_messages and posted to the same endpoint as the next request.
4. Steps 2 and 3 repeat until a response has no remote tool calls or recursion_limit is reached.

Only the first request carries initial_state. See Register remote tools for how to register handlers.

InvokeRequest

InvokeRequest is the body type of one request. You only need it if you call the endpoint yourself. The client adds messages in serialised form and fills the other fields from your options.

interface InvokeRequest {
  messages: any[];                  // serialised Message objects
  initial_state?: Record<string, any>;
  config?: Record<string, any>;
  recursion_limit?: number;
  response_granularity?: 'full' | 'partial' | 'low';
}

Examples

The examples assume a server running at http://localhost:8000.

Minimal invoke

This call sends one user message and prints the first content block of the first returned message.

import { TenxGraphClient, Message } from '10xgraph-client';

const client = new TenxGraphClient({ baseUrl: 'http://localhost:8000' });

const result = await client.invoke([
  Message.text_message('What is the capital of Japan?'),
]);

// Example output, the text depends on your agent
console.log(result.messages[0].content[0]);
// { type: 'text', text: 'The capital of Japan is Tokyo.' }

Chat on a persistent thread

Reusing one thread_id makes the server load the saved state, so the agent remembers earlier turns. This needs a checkpointer on the server.

import { TenxGraphClient, Message } from '10xgraph-client';

const client = new TenxGraphClient({ baseUrl: 'http://localhost:8000' });
const THREAD_ID = 'user-123-session-456';

async function chat(userInput: string): Promise<string> {
  const result = await client.invoke([Message.text_message(userInput)], {
    config: { thread_id: THREAD_ID },
    response_granularity: 'low', // messages only
  });

  // Pick the assistant's text block out of the returned messages
  const assistantMsg = result.messages.find((m) => m.role === 'assistant');
  const textBlock = assistantMsg?.content.find((b) => b.type === 'text');
  return (textBlock as { text?: string } | undefined)?.text ?? '';
}

await chat('Hello!');
console.log(await chat('What did I just say?')); // sees the previous turn

Seed the graph with initial state

initial_state sets state keys before the run. Use keys that exist in your graph’s state schema.

const result = await client.invoke([Message.text_message('Continue where we left off')], {
  initial_state: { user_preferences: { language: 'en', theme: 'dark' } },
  config: { thread_id: 'thread-789' },
});

Common errors

A non-2xx response throws a subclass of TenxGraphError, chosen by status code. See Errors for the full list and the fields on each error.

Related pages

• Invoke an agent walks through using invoke() in an app.
• Register remote tools explains handlers for the tool loop.
• stream() returns output incrementally.