sam task

Overview

The sam task command sends tasks to the webui gateway and receives streaming responses via Server-Sent Events (SSE).

Syntax

sam task <SUBCOMMAND> [OPTIONS]

Description

The task command provides two ways to interact with SAM agents:

send: Send tasks to a running SAM instance
run: Start SAM, send a task, and stop (all-in-one command)

Both subcommands support file attachments, session continuity, artifact downloads, and STIM (Solace Task Interaction Model) file generation.

Subcommands

sam task send

Send a task to a running webui gateway and stream the response.

Syntax

sam task send <MESSAGE> [OPTIONS]

Arguments

MESSAGE

string

required

The prompt text to send to the agent.

Options

-u, --url

string

default:"http://localhost:8000"

Base URL of the webui gateway.Can be set via environment variable: SAM_WEBUI_URL

-a, --agent

string

default:"orchestrator"

Target agent name.Can be set via environment variable: SAM_AGENT

-s, --session-id

string

Session ID for context continuity. Generates new if not provided.

-t, --token

string

Bearer token for authentication.Can be set via environment variable: SAM_AUTH_TOKEN

-f, --file

path[]

File(s) to attach. Can be used multiple times.Example: -f doc1.pdf -f doc2.txt

--timeout

integer

default:"120"

Timeout in seconds for SSE connection.

-o, --output-dir

path

Output directory for artifacts and logs.Default: /tmp/sam-task-{taskId}

-q, --quiet

boolean

default:"false"

Suppress streaming output, only show final result.

--no-stim

boolean

default:"false"

Do not fetch the STIM file on completion.

--debug

boolean

default:"false"

Enable debug output.

Examples

Basic usage:

sam task send "What is the weather today?"

Specify agent:

sam task send "Analyze this data" --agent data_analyst

With file attachment:

sam task send "Summarize this document" --file ./document.pdf

Continue from previous session:

sam task send "What did we discuss?" --session-id abc-123

Custom URL with authentication:

sam task send "Hello" --url https://mygateway.com --token $MY_TOKEN

Multiple files and custom output:

sam task send "Compare these files" \
  --file file1.txt \
  --file file2.txt \
  --output-dir ./results

Quiet mode (final result only):

sam task send "Generate report" --quiet

Output

Normal mode (streaming):

Task ID: task-abc123
Session ID: session-xyz789  (use with --session-id to continue)

[Agent response streams here in real-time]

Completed in 12.5s

Artifacts saved to: /tmp/sam-task-abc123
  - artifact1.pdf
  - artifact2.json

STIM file: /tmp/sam-task-abc123/task-abc123.stim

Quiet mode:

[Final agent response only]

Debug mode:

[DEBUG] Target URL: http://localhost:8000
[DEBUG] Fetching available agents...
[DEBUG] Found 3 agents
[DEBUG] Resolved agent name: orchestrator
[Task execution output]

sam task run

Start SAM, send a task, stream the response, and stop.

Syntax

sam task run <MESSAGE> [OPTIONS]

Arguments

MESSAGE

string

required

The prompt text to send to the agent.

Options

Includes all options from sam task send plus:

-c, --config

path[]

YAML config files or directories. Can be used multiple times.Defaults to configs/ directory.

-s, --skip

string[]

File name(s) to exclude from configs (e.g., -s my_agent.yaml).

--timeout

integer

default:"300"

Timeout in seconds for task execution (note: different default from send).

--startup-timeout

integer

default:"60"

Timeout in seconds for agent readiness.

--system-env

boolean

default:"false"

Use system environment variables only; do not load .env file.

Examples

Basic usage with default configs:

sam task run "What agents are available?"

Specify config files:

sam task run "Hello" \
  -c examples/agents/orchestrator.yaml \
  -c examples/gateways/webui.yaml

With file attachment:

sam task run "Summarize this document" \
  --file ./document.pdf \
  -c configs/

Target specific agent:

sam task run "Analyze data" \
  --agent data_analyst \
  -c configs/

Custom startup timeout:

sam task run "Hello" \
  --startup-timeout 120 \
  -c configs/

Skip specific config files:

sam task run "Test" \
  -c configs/ \
  -s test_agent.yaml \
  -s experimental.yaml

Output

Starting SAM with 3 config file(s)...
SAM started.
Waiting for agents (timeout: 60s)...
Agents ready: orchestrator, data_analyst, web_scraper

Task ID: task-abc123
Session ID: session-xyz789

[Agent response streams here]

Completed in 15.3s

Artifacts saved to: /tmp/sam-task-run-abc123
STIM file: /tmp/sam-task-run-abc123/task-abc123.stim

Stopping SAM...
Done.

Agent Readiness

The sam task run command implements an agent readiness algorithm:

Poll /api/v1/agentCards until at least one agent is detected
Wait 2 seconds for stabilization (allows all agents to register)
Poll again to get the final agent list
Verify the target agent exists
Proceed with task execution

This ensures all agents are fully initialized before sending tasks.

Session Management

Sessions allow multi-turn conversations with agents:

# First interaction
sam task send "What is 2+2?"
# Output: Session ID: session-abc123

# Follow-up using same session
sam task send "Multiply that by 3" --session-id session-abc123

Session IDs are:

Auto-generated if not provided
Displayed in the output after each task
Used to maintain conversation context

File Attachments

Attach files to provide context to agents:

sam task send "Analyze this" \
  --file data.csv \
  --file report.pdf \
  --file image.png

Supported file types depend on the agent’s configuration and tools.

Artifacts

Agents can generate artifacts (files, images, data) during task execution:

Automatically downloaded to output directory

Output directory structure:

/tmp/sam-task-abc123/
├── artifacts/
│   ├── chart.png
│   └── report.pdf
└── task-abc123.stim

STIM Files

STIM (Solace Task Interaction Model) files capture the complete task interaction:

Contains full request/response history
Includes metadata, artifacts, and events
Saved as {taskId}.stim in output directory
Skip generation with --no-stim flag

Authentication

For protected gateways, provide a bearer token:

# Via flag
sam task send "Hello" --token eyJhbGci...

# Via environment variable
export SAM_AUTH_TOKEN=eyJhbGci...
sam task send "Hello"

Exit Codes

0: Task completed successfully
1: Error (connection failed, agent not found, timeout, etc.)

Implementation Details

Implemented in:

Send: /home/daytona/workspace/source/cli/commands/task_cmd/send.py
Run: /home/daytona/workspace/source/cli/commands/task_cmd/run.py

Uses:

SSE (Server-Sent Events) for streaming responses
httpx for async HTTP operations
SAMRunner for process management (run command)

Troubleshooting

Error: Failed to connect

Cause: Gateway not running or wrong URL Solution:

# Verify gateway is running
sam run configs/gateways/webui.yaml

# Or use correct URL
sam task send "Hello" --url http://correct-host:8000

Error: Agent not found

Cause: Specified agent doesn’t exist Solution:

# List available agents
sam task send "list agents" --agent orchestrator

# Or check agent names in configs
grep "name:" configs/agents/*.yaml

Timeout waiting for agents

Cause: Agents taking too long to start Solution:

# Increase startup timeout
sam task run "Hello" --startup-timeout 120

# Check logs for startup issues
cat /tmp/sam-task-run-*/sam.log

CLI Commands

Agent API

Gateway API

Workflow API

A2A Protocol

Overview

Syntax

Description

Subcommands

sam task send

Syntax

Arguments

Options

Examples

Output

sam task run

Syntax

Arguments

Options

Examples

Output

Agent Readiness

Session Management

File Attachments

Artifacts

STIM Files

Authentication

Exit Codes

Implementation Details

Troubleshooting

Error: Failed to connect

Error: Agent not found

Timeout waiting for agents

See Also

Build docs developers (and LLMs) love

CLI Commands

Agent API

Gateway API

Workflow API

A2A Protocol

​Overview

​Syntax

​Description

​Subcommands

​sam task send

​Syntax

​Arguments

​Options

​Examples

​Output

​sam task run

​Syntax

​Arguments

​Options

​Examples

​Output

​Agent Readiness

​Session Management

​File Attachments

​Artifacts

​STIM Files

​Authentication

​Exit Codes

​Implementation Details

​Troubleshooting

​Error: Failed to connect

​Error: Agent not found

​Timeout waiting for agents

​See Also

Build docs developers (and LLMs) love

Overview

Syntax

Description

Subcommands

sam task send

Syntax

Arguments

Options

Examples

Output

sam task run

Syntax

Arguments

Options

Examples

Output

Agent Readiness

Session Management

File Attachments

Artifacts

STIM Files

Authentication

Exit Codes

Implementation Details

Troubleshooting

Error: Failed to connect

Error: Agent not found

Timeout waiting for agents

See Also