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:.
| Area | Methods |
|---|---|
| Agents | list_agents, get_agent, create_agent, update_agent, publish_agent |
| Chat and sessions | chat, chat_stream, create_session, list_sessions, get_history, delete_session, submit_feedback |
| Models | list_models, get_model, completions (OpenAI-compatible) |
| Knowledge | list_sources, create_source, upload_documents, ingest, sync_source, search |
| Knowledge graph | load_graph, get_graph_schema, query_graph |
| Graph schemas | list_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 |
| Evaluation | list_datasets, upload_dataset, run_evaluation, get_evaluation, poll_evaluation, compare_evaluations |
| Prompt optimization | optimize_prompt, get_optimization, poll_optimization |
| Data flywheel | ingest_traces, get_quality_trend, build_flywheel_dataset |
| Skills | list_skills, get_skill, import_skills |
| Tools | list_tools, execute_tool |
| Guardrails | evaluate_guardrails |
| Usage and cost | get_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.guardrailsandkatonic.toolsbuild an agent's bindings: its model, knowledge sources, guardrail profile and tools.katonic.composewires sub-agents into one workflow: a coordinator, a sequential pipeline, a parallel fan-out, a router or a mix.katonic.scaffoldwrites a blueprint package.katonic.evaluatewrites local evaluation datasets and configurations.katonic.connectorsis 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.
| Command | What it does |
|---|---|
katonic login | Saves 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 usage | Models, and usage. |
katonic compose, katonic scaffold | The 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.