Agent tool integration

An agent can call internalize through a tool registered in your application. Your handler translates that call into POST /v1/internalizations, persists the receipt, and returns the actual outcome. The Chat Completions API supports function-call messages, while your runtime executes the handlers. There is no hosted MCP endpoint. The subject-bound learning guide is the recommended starting point.

Tool definitionCopy Anchor Link

The workspace SDK exports this function-style tool definition:

{
  "type": "function",
  "function": {
    "name": "internalize",
    "description": "Learn knowledge into this subject's model adapter. Submit once, wait for completion, and inspect activation before relying on it.",
    "parameters": {
      "type": "object",
      "properties": {
        "subject_id": { "type": "string" },
        "content": { "type": "string" }
      },
      "required": ["subject_id", "content"],
      "additionalProperties": false
    }
  }
}

Adapt the outer registration format to your agent runtime. The public endpoint still enforces content length and subject format. A valid tool JSON object is not itself authorization to train the named subject.

For a single-user assistant, you can omit subject selection from the model-facing tool and inject the authorized subject server-side. For a multi-workspace agent, check the selected subject against the caller's explicit access before submission.

Workspace helperCopy Anchor Link

import { InternalizeClient } from "@internalize/sdk";
import { executeInternalize } from "@internalize/sdk/tool";

const client = new InternalizeClient({
  baseUrl: "https://convergingthought.com",
  apiKey: process.env.INTERNALIZE_API_KEY!,
});

const result = await executeInternalize(
  client,
  {
    subject_id: "authorized-workspace-42",
    content: "The approved knowledge this workspace has chosen to retain.",
  },
  "durable-tool-invocation-001",
  5_000_000,
);

The third argument is the stable invocation identity; the fourth is the application-set maximum charge in micro-USD. It must meet the idempotency-key format. Persist it in your runtime rather than generating a new one whenever a worker retries the same tool execution.

The helper requests automatic activation, waits, and returns job_id, status, activated, version_id, and error. It does not include validation totals in that compact result; read the job if the agent or application needs them. The helper can throw on HTTP errors, polling timeout, or reconciliation.

Long-running toolsCopy Anchor Link

If your runtime cannot keep a tool handler open, use client.internalize directly, save the job ID, and return a structured pending result. Schedule later observation and deliver completion through your application's normal workflow. Do not tell the agent that the memory is active merely because the POST returned 202.

A useful result vocabulary distinguishes pending, learned-and-active, learned-but-needs-activation, rejected, failed, and needs-investigation. These application labels should map to the actual job fields rather than replace them in stored records.

Continue inferenceCopy Anchor Link

After successful activation, use the same subject for subsequent inference. The original passage can be omitted from the prompt. Continue supplying the new question and any conversation context needed for the current task.

The agent should inspect whether the intended version became active before relying on it. A conflict can leave a valid candidate saved while another version serves requests. Do not let an automatic loop overwrite the competing release without an application policy.

Bound autonomous learningCopy Anchor Link

Select meaningful, authorized knowledge rather than internalizing every tool result or chat turn. Keep provenance outside the adapter, serialize dependent updates, and evaluate retained behavior after changes. Each successful saved call has a cost even when manual activation is deferred.

Use Agent memory for the product pattern, Polling for durable execution, and machine-readable docs to let coding agents discover the same contract as a human developer.