---
# @generated by sylphx-gen 0.1.0 from contracts@f99a9bda63ea35002f40ef41b07b570c1c970750996f232cbfb0ed12313637ab. Do not edit.
title: "Invoke tool on an agent session"
description: "`agents.agent_sessions.invoke_tool` (POST /v1/{name}:invoke-tool): Guest execution capability authentication, not an Access management key."
type: reference
product: agents
summary: "Guest execution capability authentication, not an Access management key."
updated: 2026-09-28
nav: false
---

Guest execution capability authentication, not an Access management key. Preserve any JSON tool result, including scalars and arrays.

**Not available yet.** Sylphx Agents is declared in the registry but no backend serves it: every call answers `501` with the problem code `UNIMPLEMENTED`.

- **Path** `POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:invoke-tool`
- **Scope** `agents:sessions`
- **Effect** `write` — a successful call changes state.
- **Collection** [agent_sessions](/docs/api/agent_sessions)

## Request

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | The name of the session whose pinned tools are used. Required. |
| `turn` | `int64` | The live turn whose execution capability authorizes the call. Required. |
| `tool` | `string` | The tool name in the session's pinned agent version. Required. |
| `arguments` | `struct` | The tool input, validated against its pinned input schema. Required. |
| `op_id` | `string` | The stable operation identifier, reused for idempotent tool-call retries. Required. |

## Response

The call answers with an empty object.

## Errors

- [`UNAUTHENTICATED`](/docs/api/errors/UNAUTHENTICATED) — No valid key or token was presented.
- [`PERMISSION_DENIED`](/docs/api/errors/PERMISSION_DENIED) — The key lacks the method's permission.
- [`INVALID_FIELD`](/docs/api/errors/INVALID_FIELD) — A field failed validation.

Every error arrives in the body [Errors](/docs/platform/errors) describes.

## Examples

**cURL**

```curl
curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/agent_sessions/agent-session:invoke-tool" \
  -H "Authorization: Bearer $SYLPHX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"arguments":{},"op_id":"…","tool":"…","turn":1}'
```

**TypeScript**

```ts
const response = await sylphx.agents.agentSessions.invokeTool({ arguments: {}, name: 'orgs/acme/projects/shop/envs/production/agent_sessions/agent-session', opId: '…', tool: '…', turn: 1 })
```

**Rust**

```rust
let mut req = sylphx::agents::InvokeToolRequest::default();
req.arguments = Some(Default::default());
req.name = "orgs/acme/projects/shop/envs/production/agent_sessions/agent-session".to_string();
req.op_id = "…".to_string();
req.tool = "…".to_string();
req.turn = 1;
let response = sx.agents().agent_sessions().invoke_tool(req).await?;
```

**CLI**

```bash
sylphx agents agent-sessions invoke-tool orgs/acme/projects/shop/envs/production/agent_sessions/agent-session
```

**MCP**

```json
{ "method_id": "agents.agent_sessions.invoke_tool", "args": {"arguments":{},"name":"orgs/acme/projects/shop/envs/production/agent_sessions/agent-session","op_id":"…","tool":"…","turn":1} }
```