# Agent tool integration

Source: https://convergingthought.com/docs/integrations/agents

> Expose one learning tool with a trusted subject boundary and an inspectable asynchronous result.



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](/docs/integrations/learning) is the recommended starting point.

## Tool definition [#tool-definition]

The workspace SDK exports this function-style tool definition:

```json
{
  "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 helper [#workspace-helper]

```ts
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 tools [#long-running-tools]

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 inference [#continue-inference]

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 learning [#bound-autonomous-learning]

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](/docs/guides/agent-memory) for the product pattern, [Polling](/docs/sdk-reference/polling) for durable execution, and [machine-readable docs](/docs/integrations/agent-docs) to let coding agents discover the same contract as a human developer.