Dossier pubblico delle interfacce

Fatti finanziari citati, strutturati per agenti IA.

CLI + Skill e MCP sono le interfacce principali per gli agenti; REST offre il trasporto HTTPS e batch. Ogni risposta include metadati di stato e governance; i fatti restituiti sono associati all’evidenza della fonte e alla semantica temporale.

Le chiamate principali degli agenti usano CLI + Skill o MCP; REST offre il trasporto HTTPS e batch.

La scoperta precede l’esecuzione. Ogni chiamata, riuscita o rifiutata, resta strutturata, limitata e verificabile. — ARGUS / SYSTEM MAPUn percorso governato dall’inizio alla fine

Scegliere l’interfaccia adatta al tuo AI agent

Tutti e tre i percorsi di accesso entrano nella stessa CoreServiceBoundary. Le regole relative a Tenant, autorizzazioni, licenze, evidenze, provenienza e audit non cambiano in base al client.

01CLIOAuth · browser sign-in · JSON stdout

argus auth login
argus --base-url https://api.argusfa.com entity-resolve \
  --identifier-type lei \
  --identifier-value HWUPKR0MPOU8FGXBT394

Documentazione tecnica: CLI

02RESTOAuth Bearer · HTTPS · JSON · OpenAPI

# First run: argus auth login
import json
from urllib.request import Request, HTTPRedirectHandler, build_opener
from argus.cli.oauth import CliOAuthProfile

profile = CliOAuthProfile()
token = profile.client().access_token()
if token is None:
    raise RuntimeError("Run argus auth login first")

class NoRedirect(HTTPRedirectHandler):
    def redirect_request(self, *args, **kwargs):
        return None

request = Request(
    profile.api_base_url + "/v1/entity-resolve",
    data=json.dumps(json.loads(r'''{"identifier_type":"lei","identifier_value":"HWUPKR0MPOU8FGXBT394","purpose":"factual_lookup","requires_redistribution":false}''')).encode(),
    headers={"Authorization": f"Bearer {token}",
             "Content-Type": "application/json", "User-Agent": "Argus REST client"},
    method="POST",
)
with build_opener(NoRedirect()).open(request, timeout=30) as response:
    envelope = json.load(response)
    print(json.dumps(envelope, indent=2))

Documentazione tecnica: REST

03MCPPython 3.12+ · Argus 1.1.8+ · MCP SDK · Registro prima

# Installa una sola volta: use the official Argus installer.
# argus auth login --interface mcp
import asyncio
import json
from datetime import timedelta

from argus.cli.oauth import CliOAuthProfile
from mcp import ClientSession
from mcp.client.streamable_http import streamable_http_client
from mcp.shared._httpx_utils import create_mcp_http_client


def decode_tool_result(response):
    if response.isError:
        raise RuntimeError(response.content)
    if response.structuredContent is not None:
        return response.structuredContent
    text = next(block.text for block in response.content if block.type == "text")
    return json.loads(text)


async def main() -> None:
    tool_name = "entity_resolve"
    arguments = json.loads(r'''{"identifier_type":"lei","identifier_value":"HWUPKR0MPOU8FGXBT394","purpose":"factual_lookup","requires_redistribution":false}''')
    profile = CliOAuthProfile.from_environment().for_interface("mcp")
    token = profile.client().access_token()
    if token is None:
        raise RuntimeError("Run argus auth login --interface mcp first")

    async with (
        create_mcp_http_client(headers={"Authorization": f"Bearer {token}"}) as http,
        streamable_http_client(profile.audience, http_client=http) as (read, write, _),
    ):
        async with ClientSession(
            read,
            write,
            read_timeout_seconds=timedelta(seconds=30),
        ) as session:
            await session.initialize()
            listed_tools = {tool.name for tool in (await session.list_tools()).tools}
            registry = decode_tool_result(
                await session.call_tool("agent_tool_registry")
            )
            registry_tools = {tool["tool_name"] for tool in registry["tools"]}
            if tool_name not in listed_tools or tool_name not in registry_tools:
                raise RuntimeError(f"Lo strumento non è disponibile nel registro corrente: {tool_name}")

            response = await session.call_tool(
                tool_name,
                arguments=arguments,
            )
            payload = decode_tool_result(response)
            if payload.get("success") is not True:
                error = payload.get("error")
                audit_id = payload.get("audit_id")
                if audit_id is None and isinstance(error, dict):
                    audit_id = error.get("audit_id")
                raise RuntimeError(f"La richiesta Argus non è riuscita (audit_id={audit_id}): {error}")
            print(json.dumps(payload, indent=2, ensure_ascii=False))


asyncio.run(main())

Documentazione tecnica: MCP

Un percorso governato dall’inizio alla fine

La scoperta precede l’esecuzione. Ogni chiamata, riuscita o rifiutata, resta strutturata, limitata e verificabile.

01identityOAuth subject · scopes · purpose · as_of
02registryagent_tool_registry · scopes · allowed_purposes
03boundarytenant · permission · license · provenance · audit
04DataPackagefacts · source_evidence · known_time · quality · audit_id

Richieste di riferimento riutilizzabili

Accedi con OAuth prima di chiamare uno strumento. Queste richieste utilizzano un’entità giuridica GLEIF reale; verifica la copertura e le prove restituite prima di usare il risultato. Conserva le credenziali delle macchine non presidiate nel tuo ambiente per i segreti.

Collega un AI agent con OAuth interattivo; per l’automazione non presidiata usa un machine client o service account.
Leggi prima il registro e scegli uno strumento con ambiti e finalità compatibili con l’identità.
Usa CLI + Skill o MCP come interfacce principali per gli agenti; usa REST per il trasporto HTTPS e batch.
Chiama lo strumento con un orario as_of esplicito.
Verifica evidenza, qualità, licenza, restrizioni e audit_id prima di usare i fatti.

https://api.argusfa.com/v1/tool-registry

Convalidare il pacchetto, non solo il codice di stato

Il successo del trasporto non prova che un fatto sia utilizzabile. Controlla l’involucro governato e il DataPackage prima dell’automazione.

Qui viene mostrata solo la sintassi della richiesta. Usa identificativi reali, prove restituite da chiamate precedenti e un intervallo di tempo con copertura confermata. Questo esempio non dimostra un risultato aziendale completato in produzione.

DataPackage · company_fact_snapshot

{
  "success": true,
  "tool_name": "company_fact_snapshot",
  "output_format": "json",
  "audit_id": "audit_01JYEXAMPLE0000000000000000",
  "data_package_version": "company-fact-snapshot-cli-v1",
  "source_evidence": [
    {
      "evidence_id": "evidence:filing:1",
      "source_type": "regulatory_filing",
      "source_file_id": "filing:example-inc:2025-10k",
      "document_url": "https://regulator.example.test/filings/example-inc-2025-10k",
      "fragment_position": "char:1024-1080",
      "page_number": 42,
      "paragraph_position": null,
      "field_path": "filing.financials.revenue",
      "filing_time": "2026-06-15T09:00:00Z",
      "retrieved_at": "2026-06-16T09:30:00Z",
      "parser_version": "filing-parser-v1",
      "evidence_confidence": 0.99,
      "credibility_level": "regulatory_original",
      "pointer_type": "source_fragment",
      "content_trust": "untrusted_source_text",
      "mime_type": "text/plain",
      "source_object_sha256": null,
      "excerpt_boundary": "external_source_data",
      "is_conflicting": false,
      "conflict_group_id": null
    }
  ],
  "permission_result": {
    "allowed": true,
    "checked_at": "2026-06-16T10:00:00Z",
    "missing_permissions": [],
    "reason": "permission_allowed",
    "safe_alternative_tools": [
      "company_fact_snapshot",
      "filing_search",
      "source_evidence_lookup"
    ]
  },
  "license_status": "authorized",
  "output_restrictions": [
    "machine_readable_json",
    "cite_source_evidence"
  ],
  "result": {
    "package_type": "company_fact_snapshot",
    "package_version": "company-fact-snapshot-cli-v1",
    "generated_at": "2026-06-16T10:00:00Z",
    "request_subject": "company:example-inc",
    "caller_id": "service:customer-agent",
    "institution_id": "institution:customer",
    "request_purpose": "factual_lookup",
    "facts": [
      {
        "fact_id": "fact:revenue",
        "fact_type": "financial_metric",
        "field_name": "revenue",
        "value": 125000000,
        "evidence_ids": [
          "evidence:filing:1"
        ],
        "credibility_level": "regulatory_original",
        "extraction_method": "structured_source",
        "confidence": 0.99,
        "review_status": null
      }
    ],
    "sections": [],
    "source_evidence": [
      {
        "evidence_id": "evidence:filing:1",
        "source_type": "regulatory_filing",
        "source_file_id": "filing:example-inc:2025-10k",
        "document_url": "https://regulator.example.test/filings/example-inc-2025-10k",
        "fragment_position": "char:1024-1080",
        "page_number": 42,
        "paragraph_position": null,
        "field_path": "filing.financials.revenue",
        "filing_time": "2026-06-15T09:00:00Z",
        "retrieved_at": "2026-06-16T09:30:00Z",
        "parser_version": "filing-parser-v1",
        "evidence_confidence": 0.99,
        "credibility_level": "regulatory_original",
        "pointer_type": "source_fragment",
        "content_trust": "untrusted_source_text",
        "mime_type": "text/plain",
        "source_object_sha256": null,
        "excerpt_boundary": "external_source_data",
        "is_conflicting": false,
        "conflict_group_id": null
      }
    ],
    "data_period": {
      "start": "2025-01-01T00:00:00Z",
      "end": "2025-12-31T23:59:59Z"
    },
    "filing_time": "2026-06-15T09:00:00Z",
    "known_time": "2026-06-16T09:30:00Z",
    "revision_time": null,
    "invocation_time": "2026-06-16T10:00:00Z",
    "data_quality": {
      "quality_level": "high",
      "issues": [],
      "requires_human_review": false
    },
    "credibility_level": "regulatory_original",
    "data_license": {
      "license_id": "public-disclosure-v1",
      "source": "regulatory_filing",
      "status": "authorized",
      "allowed_uses": [
        "factual_lookup",
        "audit_reproduction"
      ],
      "prohibited_uses": [
        "restricted_redistribution"
      ],
      "redistribution": "restricted",
      "authorized_institutions": [
        "institution:customer"
      ],
      "restricted_fields": []
    },
    "allowed_uses": [
      "factual_lookup",
      "audit_reproduction"
    ],
    "prohibited_uses": [
      "restricted_redistribution"
    ],
    "output_restrictions": [
      "machine_readable_json",
      "cite_source_evidence"
    ],
    "structured_output_flags": {},
    "audit_id": "audit_01JYEXAMPLE0000000000000000",
    "output_policy_version": "[email protected]"
  }
}

Strumenti

Il registro pubblico degli strumenti definisce attualmente 53 strumenti governati. Questi record sono generati dagli stessi dati autorevoli della directory degli strumenti.

01
company_fact_snapshot
Snapshot dei Fatti della Società
Restituire i fatti della società divulgati come DataPackage strutturato.
REST
/v1/company-fact-snapshot
MCP
company_fact_snapshot
Contratto di ritorno
CliToolEnvelope JSON with nested DataPackage result
02
point_in_time_snapshot
Snapshot Point-In-Time
Restituire uno snapshot di società as-of-safe.
REST
/v1/point-in-time-snapshot
MCP
point_in_time_snapshot
Contratto di ritorno
CliToolEnvelope JSON with nested DataPackage result
03
evidence_gap_report
Rapporto delle lacune di evidenze
Restituire le classificazioni con evidenze, mancanti, di bassa qualità, conflittuali e bloccate dalla licenza.
REST
/v1/evidence-gap-report
MCP
evidence_gap_report
Contratto di ritorno
CliToolEnvelope JSON with nested DataPackage result
04
agent_data_preflight
Preflight dei Dati dell'Agent
Restituire i metadati di preflight di autorizzazione, licenza, campo, intervallo temporale e target_tool.
REST
/v1/agent-data-preflight
MCP
agent_data_preflight
Contratto di ritorno
CliToolEnvelope JSON with nested agent_data_preflight_result DataPackage

Strumenti: 53

Fiducia

Argus offre un’infrastruttura fattuale con limiti visibili. Rifiuti, restrizioni, freschezza, licenza e revisione umana restano nel risultato.

[POLICY]Argus non genera decisioni di investimento né ordini, ma non limita l’analisi e l’output indipendenti dell’agente client con dati ottenuti legalmente.

Fiducia

Continuare con una guida autorevole

Inizia dalla guida alla prima richiesta, consulta tutti gli strumenti oppure apri la documentazione dell’interfaccia del tuo AI agent.

Scegliere l’interfaccia adatta al tuo AI agent

Un percorso governato dall’inizio alla fine

Richieste di riferimento riutilizzabili

Convalidare il pacchetto, non solo il codice di stato

Strumenti

Snapshot dei Fatti della Società

Snapshot Point-In-Time

Rapporto delle lacune di evidenze

Preflight dei Dati dell'Agent

Fiducia

Continuare con una guida autorevole