Invoke Agents and Track Tasks¶

Use the AI Studio SDK to send text to a selected agent and retain the returned task identifier and turn identifier. Subsequent queries, cancellations, subscription resumptions, or supplemental inputs all use these identifiers; do not mix them with workflow runs or other task resources.

Task workflow¶

Select an agent in the target workspace and prepare a text message, message ID, and invocation tracking ID.
After submitting the message, obtain the current task ID and turn ID from the response payload.
Use the task ID to query, cancel, or resume subscription to the task; when the agent requests supplemental input, provide the task ID, turn ID, and answers together.

A submitted message does not mean the task is complete. Preserve these two server-returned identifiers and determine next steps based on query results or streaming updates.

Prerequisites¶

Required item	Role on this page
Client context bound to the target workspace	Identify the workspace scope of the agent invocation.
Agent code or agent ID	Select the agent receiving the message.
Text message, message ID, and invocation tracking ID	Submit a message that can be correlated by the caller.

Submit a text message¶

Upon successful submission, the example reads the task ID and turn ID from the response. Retain them; do not generate alternative values for subsequent operations.

func submitText(ctx context.Context, workspace *sdk.WorkspaceHandle, agentCode, messageID, prompt string, requestID any) (string, string, error) {
	agent, err := workspace.AgentByCode(agentCode)
	if err != nil {
		return "", "", err
	}
	submitted, err := agent.SendText(ctx, sdk.AgentTextMessage{
		RequestID: requestID, MessageID: messageID, Text: prompt,
	})
	if err != nil {
		return "", "", err
	}
	taskID, err := sdk.AgentA2ATaskID(submitted)
	if err != nil {
		return "", "", err
	}
	turnID, err := sdk.AgentA2ATurnID(submitted)
	if err != nil {
		return "", "", err
	}
	return taskID, turnID, nil
}

Python

def submit_text(workspace, agent_code, message_id, prompt, request_id):
    agent = workspace.agent_by_code(agent_code)
    submitted = agent.send_text(
        sdk.AgentTextMessage(
            request_id=request_id, message_id=message_id, text=prompt
        )
    )
    task_id = sdk.agent_a2a_task_id(submitted)
    turn_id = sdk.agent_a2a_turn_id(submitted)
    return task_id, turn_id

Continue the task with returned identifiers¶

Querying, cancelling, and resuming subscriptions require only the task ID returned by the same agent. When the agent requests supplemental input, the turn ID from the same response and at least one answer are also required.

The following example queries the current task using the task ID saved in the previous step. It returns the current protocol response and does not imply that the task has completed.

func getTask(ctx context.Context, agent *sdk.AgentHandle, taskID string, requestID any) (*sdk.AgentA2AResult, error) {
	return agent.GetTask(ctx, sdk.AgentTaskRequest{
		RequestID: requestID,
		TaskID:    taskID,
	})
}

Python

def get_task(agent, task_id, request_id):
    return agent.get_task(
        sdk.AgentTaskRequest(task_id=task_id, request_id=request_id)
    )

Limitations¶

Streaming responses or resumed subscriptions return an active read stream. Go callers should close the response body after reading; stopping local reads does not cancel the agent task on the server.

Messages and supplemental inputs may contain business data. Do not write credentials, connection secrets, or sensitive values into messages, logs, or error outputs.

Next steps¶

When calling HTTP endpoints, refer to the agent invocation endpoints in the API Reference.

Last updated on Sep 3, 2026