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

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