Agents

Specialist agents with a standard input/output contract. Agents use the same /v1 capabilities, jobs, and artifacts as the rest of the platform.

GET /v1/agents

List registered specialists.

curl -s https://api.skilleo.org/v1/agents \
  -H "Authorization: Bearer $SKILLEO_API_KEY"

Each agent includes id, name, description, status, capability, input_contract, and output_contract.

GET /v1/agents/{id}

Return one specialist (e.g. /v1/agents/image.generator).

curl -s https://api.skilleo.org/v1/agents/image.generator \
  -H "Authorization: Bearer $SKILLEO_API_KEY"

Code	When
NOT_FOUND	Unknown agent id

POST /v1/agents/{id}/runs

Start an agent run. Returns 202 with an agt_ id.

Request body

Field	Type	Description
objective	string	Required. What to produce
inputs	array	Optional reference artifacts: {artifact_id, role}
constraints	object	Specialist-specific fields (e.g. prompt, width, height, steps)
budget	object	Optional max_cost_usd
available_capabilities	array	Optional allow-list; must include the agent's capability when set
compute_id	string	Optional execution target
endpoint_id	string	Optional execution target

Example

curl -s -X POST https://api.skilleo.org/v1/agents/image.generator/runs \
  -H "Authorization: Bearer $SKILLEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"objective":"A red cube product photo on white background","constraints":{"width":512,"height":512},"budget":{"max_cost_usd":1.0},"available_capabilities":["image.generate"]}'

GET /v1/agent-runs/{id}

Poll run status. When completed, data.result holds the standard output contract:

curl -s https://api.skilleo.org/v1/agent-runs/agt_abc123 \
  -H "Authorization: Bearer $SKILLEO_API_KEY"

Field	Description
status	completed or failed
artifacts	Output artifacts with id, role, type, mime_type
evidence	Trace objects (job id, prompt, input artifacts)
metrics	inference_ms, total_ms
cost	Estimated USD

First specialist: image.generator

Text-to-image specialist using the image.generate capability. Returns artifacts in the standard output contract.

SDK

run = client.agents.run(
    "image.generator",
    objective="A red cube on white",
    constraints={"width": 512},
)
done = client.agents.wait(run["id"])
artifact_id = done["data"]["result"]["artifacts"][0]["id"]
client.artifacts.save(artifact_id, "out.png")