Invoke a runtime

The invoke command group sends one request to a deployed Runtime. By default it reads the Runtime endpoint, version, authentication, and A2A settings from agentkit.yaml in the current directory. You can also target a Runtime directly with --runtime-id or --endpoint.

agentkit invoke "hello" is normalized to agentkit invoke run "hello" for compatibility. This reference uses invoke run as the explicit form. -ak is also normalized to --apikey for Python SDK-style arguments.

Before invoking, confirm the runtime is ready and obtain its API key or user token. --runtime-id also requires management credentials; use --endpoint when you already have the address and invocation credentials

Messages and payloads are sent to the runtime and its models or tools and may incur usage charges. Keep restricted data out of test requests. Fixed default session identifiers suit examples; supply a different session_id for independent sessions

invoke run

Send a message or custom JSON payload to a Runtime. With a plain message, the CLI sends { "prompt": "<message>" }. With --payload, it sends the parsed JSON value unchanged. Every request includes default user_id: agentkit_user and session_id: agentkit_sample_session context headers. To customize the user or session identifier, pass those fields through --headers to override the defaults.

Flag / Argument	Description	Default
`[message]`	User message to send; mutually exclusive with `--payload`.	—
`--config-file <path>`	Read a specific lifecycle config file; mutually exclusive with `--runtime-id` and `--endpoint`.	`agentkit.yaml` in the current directory
`-p, --payload <json>`	JSON payload to send; use it for fields such as `state_delta` or JSON-RPC requests.	—
`-h, --headers <json>`	JSON headers to send with the request; every value must be a string.	—
`-r, --runtime-id <id>`	Directly invoke a Runtime ID, resolving its endpoint and authentication through the control plane.	—
`-e, --endpoint <url>`	Directly invoke a Runtime endpoint.	—
`--region <region>`	Region used when resolving `--runtime-id`.	Auto-sense
`--a2a`	Force A2A JSON-RPC transport in direct invocation mode.	`false`
`--show-reasoning`	Print LangChain `reasoning_content` during streaming.	`false`
`--raw`	Print raw streaming events or the raw JSON response; errors are printed without interactive decorations.	`false`
`--apikey <key>`	Explicit bearer API key; available with `--endpoint` and mutually exclusive with `--runtime-id`.	—

# Read agentkit.yaml in the current directory
agentkit invoke run "Hello, introduce yourself"

# Compatibility shorthand, equivalent to the previous command
agentkit invoke "Hello, introduce yourself"

Target Resolution

When neither --runtime-id nor --endpoint is passed, the CLI reads agentkit.yaml:

launch_type: local invokes http://127.0.0.1:<invoke_port>;
cloud deployments prefer the saved runtime_endpoint and authentication fields from the config;
if the config only has runtime_id, the CLI queries the control plane for the current version endpoint and authentication;
when agent_type or template_type contains a2a, the CLI automatically uses A2A transport.

agentkit invoke run "Check deployment status" --config-file ./agentkit.staging.yaml

With --runtime-id, the CLI uses management credentials to query the Runtime’s current or selected version. This mode automatically uses resolvable key_auth credentials; for a custom_jwt Runtime, pass the OAuth token through --headers.

agentkit invoke run "hello" \
  --runtime-id <runtime-id> \
  --headers '{"Authorization":"Bearer <oauth-token>","session_id":"session-1"}'

With --endpoint, the CLI does not query the control plane, so you must provide authentication explicitly:

agentkit invoke run \
  --payload '{"prompt":"hello","state_delta":{"locale":"en"}}' \
  --endpoint https://runtime.example.com \
  --apikey <api-key>

Transport And Output

The CLI tries POST /invoke first. If that endpoint returns 404 or 405, it detects ADK /run_sse; if the target exposes an A2A AgentCard, it uses A2A JSON-RPC. Passing --a2a, or passing a --payload that contains jsonrpc: "2.0", uses A2A JSON-RPC directly. By default, output is extracted as answer text from streaming events. --raw prints raw events or the raw response for scripts. Without --raw, reasoning chunks produce a short hint; pass --show-reasoning to print the reasoning text.

agentkit invoke run "Show your reasoning and answer" \
  --runtime-id <runtime-id> \
  --show-reasoning

agentkit invoke run --payload '{"jsonrpc":"2.0","method":"message/stream","params":{"message":{"role":"user","parts":[{"kind":"text","text":"hello"}]}},"id":1}' \
  --endpoint https://a2a.example.com \
  --headers '{"Authorization":"Bearer <token>"}' \
  --raw

custom_jwt Authentication

A custom_jwt Runtime requires the request to carry a user OAuth token. For Runtime access resolved through --runtime-id or the config file, the CLI does not automatically inject the login session’s id_token into generic invoke run requests; pass Authorization explicitly through --headers.

agentkit login --identity-only <sso-address>

agentkit invoke run "hello" \
  --runtime-id <custom-jwt-runtime-id> \
  --headers '{"Authorization":"Bearer <oauth-token>"}'

Identity-only login saves the OIDC session without creating AgentKit management credentials. If you also need to resolve a Runtime through --runtime-id, configure AK/SK separately or use regular agentkit login to obtain STS credentials.

Troubleshooting

Symptom	Check
Runtime not found or empty results	Verify `--provider`, `--region`, Runtime ID, and the management credential’s account
Authentication failure	Check `key_auth` versus `custom_jwt` and the validity of the API key or token
Request succeeds without the expected answer	Inspect `--raw` output, runtime logs, and model settings
Help flag reports an error	Use `agentkit invoke run --help`; `-h` means `--headers` for this command

--show-reasoning only displays reasoning fields present in the response; it does not make a model generate or disclose additional information

Getting Started

AI-Friendly

Command reference

invoke run

Target Resolution

Transport And Output

custom_jwt Authentication

Troubleshooting