<!-- Sema documentation — std.agents
     Sema is a new AI-native, neurosymbolic programming language most models
     have not been trained on. Full corpus: https://sema.49.12.246.95.sslip.io/llms-full.txt
     Install language support: https://sema.49.12.246.95.sslip.io/install-skill/ -->

# std.agents

> Reflected API reference for the Sema standard-library module std.agents.

> Generated by `sema doc` from `stdlib/sema/agents.sema`. Import with `from std.agents import …`. For a narrative introduction see [std.agents](/stdlib/agents/).

# `agents`

Typed specifications, envelopes, pools, and domain-neutral role presets.

Models and tools are injected by the caller. Presets create validated data;
`Agent.build(spec, under=envelope)` performs the governed runtime admission.

# `struct AgentSpec`

**Fields**

| field | type | descriptor |
|---|---|---|
| `name` | `str` |  |
| `input_type` | `str` |  |
| `output_type` | `str` |  |
| `sem` | `str` |  |
| `model` | `str` |  |
| `tools` | `list[any]` |  |
| `completion` | `str` |  |
| `model_calls` | `int` |  |
| `tokens` | `int` |  |

# `struct AgentEnvelope`

**Fields**

| field | type | descriptor |
|---|---|---|
| `input_type` | `str` |  |
| `output_type` | `str` |  |
| `allowed_models` | `list[str]` |  |
| `tools` | `list[any]` |  |
| `max_model_calls` | `int` |  |
| `max_tokens` | `int` |  |
| `max_children` | `int` |  |
| `max_spawn_depth` | `int` |  |

# `struct AgentPool`

**Fields**

| field | type | descriptor |
|---|---|---|
| `envelope` | `AgentEnvelope[I, O]` |  |
| `agents` | `list[any]` |  |

# `struct ArtifactRef`

**Fields**

| field | type | descriptor |
|---|---|---|
| `digest` | `str` |  |
| `media_type` | `str` |  |
| `value_type` | `str` |  |
| `provenance` | `list[str]` |  |

# `struct WorkUnit`

**Fields**

| field | type | descriptor |
|---|---|---|
| `id` | `str` |  |
| `parent` | `str` |  |
| `dependencies` | `list[str]` |  |
| `status` | `str` |  |
| `artifact` | `str` |  |
| `stall_reason` | `str` |  |

# `struct CircuitRun`

**Fields**

| field | type | descriptor |
|---|---|---|
| `run_id` | `str` |  |
| `circuit` | `str` |  |
| `status` | `str` |  |
| `result` | `T` |  |
| `work` | `list[WorkUnit]` |  |

# `enum WorkStatus`

**Variants**

- `pending`
- `running`
- `awaiting_signal`
- `suspended`
- `complete`
- `failed`
- `cancelled`

# `def role_spec`

```sema
def role_spec[I, O](name: str, input_type: str, output_type: str, purpose: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `name` | `str` |
| `input_type` | `str` |
| `output_type` | `str` |
| `purpose` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Researcher`

```sema
def Researcher[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Architect`

```sema
def Architect[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Orchestrator`

```sema
def Orchestrator[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Reviewer`

```sema
def Reviewer[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Verifier`

```sema
def Verifier[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Writer`

```sema
def Writer[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Monitor`

```sema
def Monitor[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Explorer`

```sema
def Explorer[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Engineer`

```sema
def Engineer[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`

# `def Hardener`

```sema
def Hardener[I, O](input_type: str, output_type: str, model: str, tools: list[any], model_calls: int, tokens: int) -> AgentSpec[I, O] !{}
```

**Parameters**

| name | type |
|---|---|
| `input_type` | `str` |
| `output_type` | `str` |
| `model` | `str` |
| `tools` | `list[any]` |
| `model_calls` | `int` |
| `tokens` | `int` |

**Returns** `AgentSpec[I, O]`

**Effects** `!{}`