> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

<Note>
  `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.
</Note>

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

<Warning>
  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
</Warning>

## 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`. | — |

```bash lines theme={null}
# 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.

```bash lines theme={null}
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`.

```bash lines theme={null}
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:

```bash lines theme={null}
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.

```bash lines theme={null}
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`.

```bash lines theme={null}
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