IF Commons GitHub

toolCall

concept

A call of a tool in a run: what was decided, and a hash of its arguments, never the arguments

Model identityAgent. Written in commons/data/models/identity-agent/mod.ts:138. Identified by toolCallId.

Governance: attributes

argsHashtextrequired

A hash of its arguments

Becomes the column args_hash of tool_call.

Written at commons/data/models/identity-agent/mod.ts:145

argsSummarytextoptional

What it asked for, redacted by the caller, never the raw arguments

Becomes the column args_summary of tool_call.

Written at commons/data/models/identity-agent/mod.ts:146

callIndexintegerrequired

Which call of the run it is

Becomes the column call_index of tool_call.

Written at commons/data/models/identity-agent/mod.ts:142

callKeytextrequired

A hash of the run and the index, unique

Becomes the column call_key of tool_call.

Written at commons/data/models/identity-agent/mod.ts:157

completedAtinstantoptional

When it ended

Becomes the column completed_at of tool_call.

Written at commons/data/models/identity-agent/mod.ts:156

costMicrosintegeroptional

What it cost, in millionths of a currency unit

Becomes the column cost_micros of tool_call.

Written at commons/data/models/identity-agent/mod.ts:154

decisioncode of callDecisionrequired

What was decided about it

Becomes the column decision of tool_call.

Written at commons/data/models/identity-agent/mod.ts:143

denyReasontextoptional

Why it was refused

Becomes the column deny_reason of tool_call.

Written at commons/data/models/identity-agent/mod.ts:150

policyRefsstructuredoptional

The roles, policies and grants that decided

Becomes the column policy_refs of tool_call.

Written at commons/data/models/identity-agent/mod.ts:151

requestedAtinstantrequired

When it was asked for

Becomes the column requested_at of tool_call.

Written at commons/data/models/identity-agent/mod.ts:155

resourceIdtextoptional

The resource it was about

Becomes the column resource_id of tool_call.

Written at commons/data/models/identity-agent/mod.ts:148

resourceTypetextoptional

The kind of resource it was about

Becomes the column resource_type of tool_call.

Written at commons/data/models/identity-agent/mod.ts:147

resultHashtextoptional

A hash of its result

Becomes the column result_hash of tool_call.

Written at commons/data/models/identity-agent/mod.ts:149

statuscode of callStatusrequired

Where it is

Becomes the column status of tool_call.

Written at commons/data/models/identity-agent/mod.ts:144

tokensInintegeroptional

Tokens sent to the model

Becomes the column tokens_in of tool_call.

Written at commons/data/models/identity-agent/mod.ts:152

tokensOutintegeroptional

Tokens received from the model

Becomes the column tokens_out of tool_call.

Written at commons/data/models/identity-agent/mod.ts:153

toolCallIdidentifierrequired

What identifies the call, made by the application

Becomes the column tool_call_id of tool_call.

Written at commons/data/models/identity-agent/mod.ts:141

Governance: relationships

approvaloptional

The approval it was given To approvalRequest. Written at commons/data/models/identity-agent/mod.ts:138

runone

The run To agentRun. Written at commons/data/models/identity-agent/mod.ts:204

toolone

The tool To agentTool. Written at commons/data/models/identity-agent/mod.ts:138

Logical: the table

Projects to the table tool_call with the primary key tool_call_id.

ColumnTypeNullRoleFrom
approval_approval_request_idtexttruereferencetoolCall.approval
args_hashtextfalseattributetoolCall.argsHash
args_summarytexttrueattributetoolCall.argsSummary
call_indexintegerfalseattributetoolCall.callIndex
call_keytextfalseattributetoolCall.callKey
completed_attimestamptrueattributetoolCall.completedAt
cost_microsintegertrueattributetoolCall.costMicros
decisiontextfalseattributetoolCall.decision
deny_reasontexttrueattributetoolCall.denyReason
policy_refsjsontrueattributetoolCall.policyRefs
requested_attimestampfalseattributetoolCall.requestedAt
resource_idtexttrueattributetoolCall.resourceId
resource_typetexttrueattributetoolCall.resourceType
result_hashtexttrueattributetoolCall.resultHash
run_agent_run_run_idtextfalsereferencetoolCall.run
statustextfalseattributetoolCall.status
tokens_inintegertrueattributetoolCall.tokensIn
tokens_outintegertrueattributetoolCall.tokensOut
tool_agent_tool_idtextfalsereferencetoolCall.tool
tool_call_idtextfalseattributetoolCall.toolCallId

Physical: SQL

CREATE TABLE IF NOT EXISTS "tool_call" (
    "tool_call_id" VARCHAR NOT NULL PRIMARY KEY,
    "call_index" INTEGER NOT NULL,
    "decision" VARCHAR NOT NULL,
    "status" VARCHAR NOT NULL,
    "args_hash" VARCHAR NOT NULL,
    "args_summary" VARCHAR,
    "resource_type" VARCHAR,
    "resource_id" VARCHAR,
    "result_hash" VARCHAR,
    "deny_reason" VARCHAR,
    "policy_refs" JSON,
    "tokens_in" INTEGER,
    "tokens_out" INTEGER,
    "cost_micros" INTEGER,
    "requested_at" TIMESTAMPTZ NOT NULL,
    "completed_at" TIMESTAMPTZ,
    "call_key" VARCHAR NOT NULL,
    "run_agent_run_run_id" VARCHAR NOT NULL,
    "tool_agent_tool_id" VARCHAR NOT NULL,
    "approval_approval_request_id" VARCHAR,
    CONSTRAINT "tool_call_run_agent_run_run_id_fk" FOREIGN KEY ("run_agent_run_run_id") REFERENCES "agent_run" ("run_id"),
    CONSTRAINT "tool_call_tool_agent_tool_id_fk" FOREIGN KEY ("tool_agent_tool_id") REFERENCES "agent_tool" ("agent_tool_id"),
    CONSTRAINT "tool_call_approval_approval_request_id_fk" FOREIGN KEY ("approval_approval_request_id") REFERENCES "approval_request" ("approval_request_id"),
    CONSTRAINT "tool_call_call_key_uq" UNIQUE ("call_key"),
    CONSTRAINT "tool_call_decision_ck" CHECK ("decision" IN ('allowed', 'denied', 'approval_required', 'budget_exceeded')),
    CONSTRAINT "tool_call_status_ck" CHECK ("status" IN ('requested', 'running', 'succeeded', 'failed'))
);

Physical: the typed table

Read and written from TypeScript with the types the model gives: import { toolCall } from "@intellectual-frontiers/data/sql/typed/models". Generated in commons/data/sql/typed/models/identity-agent.auto.ts: do not edit.

import { from } from "@intellectual-frontiers/data/sql/typed";
import { toolCall } from "@intellectual-frontiers/data/sql/typed/models";

const rows = await from(toolCall).select((s) => ({ toolCallId: s.toolCall.toolCallId, callIndex: s.toolCall.callIndex })).run(runner);

Titles, headings, exports, tables, columns and requirements. Esc closes.