Skill tasks

Overview

invoke_skill and poll_skill provide non-blocking skill task execution. invoke_skill sends a non-blocking request to the AgentKit skills sandbox via the A2A protocol, creates a skill task, and returns the initial task object immediately. poll_skill fetches the current status snapshot of a task by its task ID. Used together, they let you start a long-running skill workflow without blocking the agent’s reasoning and poll for status on demand. Compared to execute_skills:

Tool	Behavior	Return value
`execute_skills`	Sends the request, then polls until the task reaches a terminal state or times out, blocking the caller.	The task’s final output text string.
`invoke_skill`	Sends a non-blocking request and returns immediately without polling.	The initial task object (`dict`).
`poll_skill`	Sends a single status query without polling.	The current task object (`dict`).

Use cases:

The skill workflow takes a long time and you do not want to block a single tool call waiting for completion;
You need to perform other work after starting a skill task and check the result later;
You need custom control over how and when to poll.

invoke_skill and poll_skill reuse the sandbox infrastructure and credential configuration of execute_skills. Environment variables, Tool IDs, inbound identity credentials, and other prerequisites are the same as those described on the Code sandbox page.

Usage

Import path:

from veadk.tools.builtin_tools.invoke_skill import invoke_skill
from veadk.tools.builtin_tools.poll_skill import poll_skill

Register both tools on the Agent tools list. The agent can then call invoke_skill to start a skill task and poll_skill to query its status during reasoning.

skill_tasks_agent.py

import asyncio

from veadk import Agent, Runner
from veadk.memory.short_term_memory import ShortTermMemory
from veadk.tools.builtin_tools.invoke_skill import invoke_skill
from veadk.tools.builtin_tools.poll_skill import poll_skill

agent = Agent(
    name="skill_task_agent",
    instruction="Call skills to execute tasks for the user and query task status when needed.",
    skills=["space:your-skill-space-id"],
    skills_mode="skills_sandbox",
    tools=[invoke_skill, poll_skill],
)
runner = Runner(agent=agent, short_term_memory=ShortTermMemory())


async def main():
    response = await runner.run("Use the skill workflow to read the knowledge base and generate a summary")
    print(response)


if __name__ == "__main__":
    asyncio.run(main())

Task object

Both invoke_skill and poll_skill return an A2A task object (dict) containing the following key fields:

Field	Type	Description
`id`	`str`	Task ID, returned by `invoke_skill` and used as the `task_id` argument to `poll_skill`.
`status`	`dict`	Task status, containing a `state` field.
`status.state`	`str`	Current task state.
`kind`	`str`	Object type, always `task`.

Task states:

State	Description
`working`	The task is in progress and has not ended.
`completed`	The task completed successfully.
`failed`	The task failed.
`canceled`	The task was canceled.
`rejected`	The task was rejected.
`input-required`	The task requires additional input.
`auth-required`	The task requires authentication.

submitted and working indicate unfinished work, while unknown means the state is undetermined. completed, failed, canceled, and rejected end execution. input-required and auth-required need external action and are not success. VeADK waiting tools stop waiting at these two states, but the A2A protocol can allow later changes. Each poll_skill call queries the server again; its response is not guaranteed to be an immutable snapshot.

invoke_skill

Creates an A2A skill task and returns the initial task object. Sends a non-blocking message/send request without waiting for the task to complete.

def invoke_skill(
    workflow_prompt: str,
    tool_context: ToolContext = None,
    timeout: int = 1800,
) -> dict:
    ...

Parameter	Type	Default	Description
`workflow_prompt`	`str`	—	Skill workflow instruction.
`tool_context`	`ToolContext`	`None`	Tool runtime context, injected automatically by VeADK; required at call time.
`timeout`	`int`	`1800`	Creation-request waiting budget in seconds, from 1 to 1800; it does not automatically cancel the remote task at that time.

tool_context is marked optional in the signature but is required at call time; omitting it raises an error. VeADK injects it automatically during agent execution — you do not need to pass it manually.

poll_skill

Fetches the current status snapshot of an A2A skill task. Sends a tasks/get request and returns the task object.

def poll_skill(
    task_id: str,
    tool_context: ToolContext = None,
    timeout: int = 1800,
) -> dict:
    ...

Parameter	Type	Default	Description
`task_id`	`str`	—	Task ID, taken from the `id` field of the task object returned by `invoke_skill`.
`tool_context`	`ToolContext`	`None`	Tool runtime context, injected automatically by VeADK; required at call time.
`timeout`	`int`	`1800`	Request timeout in seconds. Must be between 1 and 1800.

Security

invoke_skill and poll_skill execute workflows in a remote skills sandbox. Code in the sandbox can access services reachable from the sandbox network and read or write files. Before running, confirm that the skill source is trusted and restrict the data, network, and permissions available to the sandbox. The inbound identity credential (credential key inbound_auth) is forwarded to the skills sandbox in the inbound_auth request header so the sandbox workflow runs under the original user identity; when the current request carries no inbound credential, the header is omitted and that user identity is not forwarded; valid cloud credentials and permissions are still required to access the sandbox. See Inbound authentication for the source and configuration of inbound identity credentials.

Context for task queries

invoke_skill still establishes a sandbox session and completes a network request before returning. Nonblocking means it does not wait for the whole workflow. Preserve the returned task id and query with the same Tool ID, user, and session context; another session is not guaranteed access to that task. Polling does not create a new task. Limit polling frequency and handle required input or authorization for input-required and auth-required, instead of repeatedly submitting the workflow. After completed, read the output or artifacts before delivering a result; an ID or state string is insufficient.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Overview

Usage

Task object

invoke_skill

poll_skill

Security

Context for task queries

​Overview

​Usage

​Task object

​invoke_skill

​poll_skill

​Security

​Context for task queries

Overview

Usage

Task object

invoke_skill

poll_skill

Security

Context for task queries