Skip to main content

SDK methods and the katonic command

This page lists what the Python SDK, katonic-sdk 7.0.18, can do: the client's methods by area, the offline authoring modules, and the katonic command that ships with the package. The Python SDK covers installing it and the first call.

Who can use it: anyone with a kapi_ API key from the Developer Hub. Each method needs the matching scope on the key; a call without it comes back as HTTP 403 and raises KatonicAPIError.

The client's methods​

KatonicClient is async: every method is a coroutine you await inside async with KatonicClient() as k:.

AreaMethods
Agentslist_agents, get_agent, create_agent, update_agent, publish_agent
Chat and sessionschat, chat_stream, create_session, list_sessions, get_history, delete_session, submit_feedback
Modelslist_models, get_model, completions (OpenAI-compatible)
Knowledgelist_sources, create_source, upload_documents, ingest, sync_source, search
Knowledge graphload_graph, get_graph_schema, query_graph
Graph schemaslist_ontologies, create_ontology, get_ontology, update_ontology, publish_ontology, new_ontology_version, delete_ontology, validate_ontology, discover_ontology, list_source_ontologies, attach_ontology, detach_ontology, set_ontology_mode, baseline_ontology_violations
Evaluationlist_datasets, upload_dataset, run_evaluation, get_evaluation, poll_evaluation, compare_evaluations
Prompt optimizationoptimize_prompt, get_optimization, poll_optimization
Data flywheelingest_traces, get_quality_trend, build_flywheel_dataset
Skillslist_skills, get_skill, import_skills
Toolslist_tools, execute_tool
Guardrailsevaluate_guardrails
Usage and costget_usage, get_analytics_usage, get_cost_breakdown

A key that runs every method needs these scopes: chat, completions, search, documents, knowledge:sync, agents:read, agents:create, agents:update, eval:read, evaluations:create, prompt_optimization:create (which also covers the data flywheel), tools, models:read, guardrails:evaluate and usage:read. A Builder cannot put models:read or usage:read on a key without the grants The Python SDK names.

poll_evaluation waits up to 300 seconds by default and poll_optimization up to 600, then raise TimeoutError. execute_tool takes the MCP server's name, then the tool name, then the arguments.

Calls a stock platform refuses​

Deleting a graph schema (delete_ontology) reaches the platform and is refused for every key, whatever its scopes: the knowledge service does not let the public API delete a schema. Delete a draft schema in Studio.

Creating a knowledge source, uploading documents and authoring graph schemas work, provided the key carries the Documents scope and its owner may create knowledge sources.

Offline authoring​

The rest of the package builds an agent's configuration on your machine, with no platform:

  • katonic.gateway, katonic.knowledge, katonic.guardrails and katonic.tools build an agent's bindings: its model, knowledge sources, guardrail profile and tools.
  • katonic.compose wires sub-agents into one workflow: a coordinator, a sequential pipeline, a parallel fan-out, a router or a mix.
  • katonic.scaffold writes a blueprint package.
  • katonic.evaluate writes local evaluation datasets and configurations.
  • katonic.connectors is the base class for a custom knowledge connector.

The katonic command​

Installing the SDK puts a katonic command on your path. It reads KATONIC_API_KEY and KATONIC_BASE_URL first, then the values katonic login saved in a .katonic folder in your home directory. Set the base URL one way or the other: without it the client calls a local address.

CommandWhat it does
katonic loginSaves an API key and base URL, with --key and --url or by asking.
katonic agents list, get <id>, create <name>, chat <agent-id> "<message>"Agent calls.
katonic sessions list, history <session-id>Session calls.
katonic skills list, get, export, import <paths>The skill library; import takes SKILL.md files or folders.
katonic search "<query>"Knowledge search, --top-k results (5 by default).
katonic eval run <agent-id> <dataset-id>, eval compare <run-a> <run-b>Starts an evaluation and waits for it, or compares two runs.
katonic optimize <agent-id> <dataset-id>Starts a prompt optimization.
katonic flywheel trend <agent-id>The agent's quality trend.
katonic tools list, tools exec <server> <tool> '<json>'Lists tools, or runs one.
katonic models list, katonic usageModels, and usage.
katonic compose, katonic scaffoldThe offline authoring commands.

katonic --help lists every option. Add --verbose to see the full error when a command fails. The katonic-admin command is a different tool for operators; see The Katonic CLI.

Describes the platform as of .

Was this page helpful?