Dossiê público de interfaces

Factos financeiros citados, estruturados para agentes de IA.

CLI + Skill e MCP são as interfaces principais para agentes; REST fornece transporte HTTPS e em lote. Cada resposta inclui metadados de estado e governação; os factos devolvidos estão associados a evidência de origem e semântica temporal.

As chamadas principais dos agentes usam CLI + Skill ou MCP; REST fornece transporte HTTPS e em lote.

A descoberta precede a execução. Cada chamada, aceite ou recusada, permanece estruturada, limitada e auditável. — ARGUS / SYSTEM MAPUm percurso governado de ponta a ponta

Escolha a interface adequada ao seu AI agent

As três rotas de acesso entram na mesma CoreServiceBoundary. As regras de Tenant, permissões, licenças, evidências, proveniência e auditoria não mudam conforme o cliente.

01CLIOAuth · browser sign-in · JSON stdout

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

Documentação técnica: 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))

Documentação técnica: REST

03MCPPython 3.12+ · Argus 1.1.8+ · MCP SDK · Registo primeiro

# Instalar apenas uma vez: 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"A ferramenta não está disponível no registo atual: {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"A solicitação do Argus falhou (audit_id={audit_id}): {error}")
            print(json.dumps(payload, indent=2, ensure_ascii=False))


asyncio.run(main())

Documentação técnica: MCP

Um percurso governado de ponta a ponta

A descoberta precede a execução. Cada chamada, aceite ou recusada, permanece estruturada, limitada e auditável.

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

Pedidos de referência reutilizáveis

Inicie sessão com OAuth antes de chamar uma ferramenta. Estas solicitações usam uma entidade jurídica real da GLEIF; verifique a cobertura e as evidências retornadas antes de usar o resultado. Guarde as credenciais das máquinas não supervisionadas no seu ambiente de segredos.

Ligue um AI agent com OAuth interativo; para automação sem supervisão use um machine client ou service account.
Leia primeiro o registo e escolha uma ferramenta cujos escopos e finalidade correspondam à identidade.
Use CLI + Skill ou MCP como interfaces principais para agentes; use REST para transporte HTTPS e em lote.
Chame a ferramenta com uma hora as_of explícita.
Valide evidência, qualidade, licença, restrições e audit_id antes de usar os factos.

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

Valide o pacote, não apenas o código de estado

O sucesso do transporte não prova que um facto é utilizável. Verifique o invólucro governado e o DataPackage antes da automatização.

Aqui é mostrada apenas a sintaxe da solicitação. Use identificadores reais, evidências retornadas por chamadas anteriores e um intervalo de tempo com cobertura confirmada. Este exemplo não demonstra um resultado de negócio concluído em produção.

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]"
  }
}

Ferramentas

O registo público de ferramentas define atualmente 53 ferramentas governadas. Estes registos são gerados a partir dos mesmos dados autoritativos do diretório.

01
company_fact_snapshot
Snapshot de Factos de Empresa
Devolver factos divulgados da empresa como um DataPackage estruturado.
REST
/v1/company-fact-snapshot
MCP
company_fact_snapshot
Contrato de retorno
CliToolEnvelope JSON with nested DataPackage result
02
point_in_time_snapshot
Snapshot Point-In-Time
Devolver um snapshot de empresa as-of-safe.
REST
/v1/point-in-time-snapshot
MCP
point_in_time_snapshot
Contrato de retorno
CliToolEnvelope JSON with nested DataPackage result
03
evidence_gap_report
Relatório de lacunas de evidência
Devolve classificações com evidência, sem evidência, de baixa qualidade, conflitantes e bloqueadas por licença.
REST
/v1/evidence-gap-report
MCP
evidence_gap_report
Contrato de retorno
CliToolEnvelope JSON with nested DataPackage result
04
agent_data_preflight
Pré-verificação de Dados de Agent
Devolver metadados de pré-verificação de permissão, licença, campo, intervalo de tempo e target_tool.
REST
/v1/agent-data-preflight
MCP
agent_data_preflight
Contrato de retorno
CliToolEnvelope JSON with nested agent_data_preflight_result DataPackage

Ferramentas: 53

Confiança

O Argus fornece infraestrutura factual com limites visíveis. Recusas, restrições, atualidade, licença e revisão humana permanecem no resultado.

[POLICY]O Argus não gera decisões de investimento nem ordens, mas não limita a análise e saída independentes do agente cliente com dados obtidos legalmente.

Confiança

Continue com um guia autoritativo

Comece pelo guia do primeiro pedido, consulte todas as ferramentas ou abra a documentação da interface do seu AI agent.

Escolha a interface adequada ao seu AI agent

Um percurso governado de ponta a ponta

Pedidos de referência reutilizáveis

Valide o pacote, não apenas o código de estado

Ferramentas

Snapshot de Factos de Empresa

Snapshot Point-In-Time

Relatório de lacunas de evidência

Pré-verificação de Dados de Agent

Confiança

Continue com um guia autoritativo