Kortix Executor
Apps & Automationkortix-executorKortix Executor is an Agent Skill for apps & automation published in the kortix-ai/suna repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use the Kortix Executor to reach external systems from a session. Prefer the `kortix executor` CLI for agent work, use `@kortix/executor-sdk` for durable TypeScript workflows and reusable skills, and treat the `kortix executor mcp` server as an optional compatibility face. Load whenever the user asks the agent to act in an external app/API, inspect available connectors/tools, add/configure a connector, or work with `connectors:` in kortix.yaml.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/kortix-ai/suna/blob/HEAD/packages/starter/templates/base/.kortix/opencode/skills/kortix-executor/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/kortix-executor, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
The default agent interface is the kortix executor CLI:
kortix executor connectors- list usable connectors and their tools.kortix executor discover "<intent>"- search tools by natural-language need.kortix executor describe <connector>.<action>- inspect one tool schema.kortix executor call <connector> <action> '<json-args>'- run a tool.kortix executor add/rm/connect- manage connectors and setup links.
The same Executor core is also available as:
@kortix/executor-sdk- TypeScript client for multi-step workflows, reusable scripts, skills, agents, and app code.kortix executor mcp- optional stdio MCP server with stable meta-tools. Do not assume the MCP tools are present in the current tool list. Use the CLI first unless the current runtime explicitly exposes the MCP tools.
Every call goes through the Kortix Executor Gateway. The gateway resolves
credentials server-side, enforces sharing and policy, executes the upstream call,
and audits the result. The sandbox carries a Kortix session/user token such as
$KORTIX_EXECUTOR_TOKEN/$KORTIX_CLI_TOKEN; it does not carry raw third-party
API keys.
- Act in an external app/API - send an email, create a charge, post to Slack, create an issue, query an internal API, call a SaaS API, drive a connected computer, or inspect an inbox/thread.
- See what integrations/connectors/tools are available.
- Add or configure a connector, request a credential, or work with
connectors:inkortix.yaml. - Build a reusable integration workflow, script, skill, or agent that will call external systems repeatedly.
If the task is purely local (editing files, running tests, reading the repo), you do not need this skill.
- List available connectors:
kortix executor connectors
- Search by intent:
kortix executor discover "send an email"
- Inspect the exact input schema before calling an unfamiliar tool:
kortix executor describe email_email_inbox_bjgk.reply_message
- Run the tool:
kortix executor call email_email_inbox_bjgk reply_message \
'{"inbox_id":"[email protected]","message_id":"<message-id>","text":"Reply text"}'
call takes <connector> <action> <json-args>. The <action> is the part after
the connector slug in the tool path. For email_email_inbox_bjgk.reply_message,
the connector is email_email_inbox_bjgk and the action is reply_message.
For GraphQL tools, pass selected fields inside args.__select, for example:
kortix executor call internal_graph query.user \
'{"id":"1","__select":"id name email"}'
- Several dependent calls, loops, branching, retries, or pagination.
- A workflow you want to save as a script in the repo.
- A reusable skill/agent implementation that should have explicit code, tests, and typed inputs.
- Transforming or validating data between Executor calls.
- Persisting state, writing reports, or combining Executor calls with local files/database work.
For method signatures, error handling, and a reusable script pattern, read
references/executor-sdk.md.
Inside a Kortix sandbox, the CLI is still the fastest way to inspect the catalog. Once the shape is clear, write a TypeScript script around the SDK:
import { createExecutorClient } from '@kortix/executor-sdk';
const executor = createExecutorClient({
apiUrl: process.env.KORTIX_API_URL!,
token: process.env.KORTIX_CLI_TOKEN ?? process.env.KORTIX_EXECUTOR_TOKEN!,
projectId: process.env.KORTIX_PROJECT_ID,
});
const matches = await executor.discover('send an email', { limit: 5 });
const tool = await executor.describe(matches[0]!.tool);
if (!tool) throw new Error('email tool not found');
const result = await executor.call('email_email_inbox_bjgk', 'reply_message', {
inbox_id: '[email protected]',
message_id: '<message-id>',
text: 'Reply text',
});
if (!result.ok) throw new Error(`Executor call failed: ${result.reason ?? result.status ?? 'unknown'}`);
console.log(JSON.stringify(result, null, 2));
For project scripts, prefer bun run path/to/script.ts. Keep credentials out of
code; pass only Kortix auth/context from env and let the gateway resolve
third-party secrets.
kortix executor call github request '{
"method": "POST",
"url": "https://api.github.com/repos/kortix-ai/suna/issues/1234/comments",
"body": { "body": "Review note..." }
}'
request args: method, absolute url, optional JSON body, and optional
headers. The upstream status and response come back through the Executor
envelope. OpenAPI, HTTP, and GraphQL connectors normally expose their whole spec
as named tools, so they usually do not need request.
connectors:
- slug: stripe
name: Stripe API
provider: openapi
spec: https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json
auth:
type: bearer
# secret value entered through setup link, never in git
Providers:
pipedream- app slug + one-click OAuth; includes the genericrequestaction for full app API access.openapi,graphql,http- declared spec/endpoint/base URL plus auth.mcp- remote MCP server endpoint.channel- synthesized chat/email connectors such as Slack and AgentMail.computer- synthesized connected-machine connector.
Use the CLI to add and connect integrations:
kortix executor add github --provider pipedream --app github
kortix executor connect github
Surface the returned setup URL to the user. Never ask the user to paste raw
credentials into chat. For API-key style connectors, use setup-link flows
(request_secret via the optional MCP face when available, or the equivalent
Kortix connector/secret setup command when exposed by the CLI).
Connecting Slack is ONE command — do not use the executor for it. Slack is
a built-in channel (slack/kortix_slack are reserved slugs; executor add
rejects them). When the user asks to connect Slack, run:
kortix channels connect
On Kortix Cloud that prints a one-click "Add to Slack" install link — surface
the URL to the user and you are done. No Slack app to create, no manifest, no
bot token, no signing secret, no secret-intake link. After the user clicks
Allow, kortix channels status shows the connected workspace and the slack
CLI + kortix_slack.* tools work immediately. Only if connect itself reports
that one-click install is unavailable (self-host without the shared Slack app)
does the manual path apply — it walks you through kortix channels manifest +
kortix channels connect --manual.