Every export of agentc_http for Python components.
from agentc_http import Client, Json, Requestagentc_http provides an asynchronous HTTP client. Requests use the runtime's egress policy and
limits.
Create and send requests with shared defaults.
A request before client defaults are applied.
A single-use awaitable request.
The response head and body.
Read or stream a response body once.
An immutable, case-insensitive header mapping.
A JSON request body.
A form-encoded request body.
Use an absolute URL with a client that has no base_url, or use relative URLs with a client that
has one. A base URL is treated as a directory, so https://api.example.com/v1 and /users produce
https://api.example.com/v1/users.
from agentc_http import Client
client = Client(base_url="https://api.example.com/v1")
async with client.get("/users", params={"active": True}) as response:
response.raise_for_status()
users = await response.body.json()A PendingResponse is single-use. async with closes an unread response body when the block exits.
When awaiting directly, call response.close() if the body will not be consumed.
Client(
*,
base_url: str | None = None,
headers: HeaderTypes | None = None,
params: QueryParams | None = None,
timeout: float | None = None,
)Client headers and query parameters are defaults. Request values replace defaults with the same name, including all repeated values for that name. Query parameters are appended after a query already present in the URL. A request timeout can shorten the runtime's configured whole-request deadline but cannot extend it.
get, head, and options accept url, params, headers, and timeout. delete, post, put,
and patch also accept body. send(request) applies the same defaults to an explicit Request.
| Value | Encoding | Default Content-Type |
|---|---|---|
bytes | unchanged | none |
str | UTF-8 | text/plain; charset=utf-8 |
Json(value) | JSON | application/json |
Form(fields) | form URL encoding | application/x-www-form-urlencoded |
AsyncIterable[bytes] | streamed chunks | none |
An explicit Content-Type header wins. A streamed body can be sent once.
Response exposes status, reason, is_success, url, headers, request, and body.
raise_for_status() returns the same response for a successful status and raises HTTPStatusError
otherwise. close() releases an unread body.
ResponseBody.read(), text(), and json() consume the full body. Iterating the body yields byte
chunks. text_chunks() yields incrementally decoded text and lines() yields universal-newline
lines. Only one consuming operation may start. consumed and closed report the shared body state.
Headers implements Mapping[str, str]. Lookup is case-insensitive. get_list(name) returns every
value for one name, while multi_items() returns every name-value pair including repeats.
Query parameters accept a mapping or a sequence of pairs. Booleans encode as true or false,
None as an empty value, and a sequence value repeats its key.
HTTPError
├── RequestError
│ ├── TransportError
│ │ └── TimeoutException
│ ├── RequestDenied
│ ├── TooManyRedirects
│ └── InvalidRequest
└── ResponseError
├── HTTPStatusError
├── DecodingError
└── ResponseTooLarge
RuntimeError
└── BodyError
├── BodyConsumed
└── BodyClosedRequest failures retain the originating Request. Status and response-body failures retain the
originating Response. Catch HTTPError for all HTTP-client failures, or catch the narrower class
when recovery depends on the failure type.
Client(
*,
base_url: str | None = None,
headers: HeaderTypes | None = None,
params: QueryParams | None = None,
timeout: float | None = None,
)Creates a client with optional defaults. base_url must be an absolute URL without a query or
fragment. The following methods return a PendingResponse and do not send until it is used:
send(request: Request) -> PendingResponse
get(url: str, *, params=None, headers=None, timeout=None) -> PendingResponse
head(url: str, *, params=None, headers=None, timeout=None) -> PendingResponse
options(url: str, *, params=None, headers=None, timeout=None) -> PendingResponse
delete(url: str, *, params=None, headers=None, body=None, timeout=None) -> PendingResponse
post(url: str, *, params=None, headers=None, body=None, timeout=None) -> PendingResponse
put(url: str, *, params=None, headers=None, body=None, timeout=None) -> PendingResponse
patch(url: str, *, params=None, headers=None, body=None, timeout=None) -> PendingResponseRequest(
method: str,
url: str,
*,
params: QueryParams | None = None,
headers: HeaderTypes | None = None,
body: Body | None = None,
timeout: float | None = None,
)The method is normalized to uppercase. A relative URL is valid when the request will be sent by a client with a base URL.
response = await pending
async with pending as response: ...Both forms send the request and yield a Response. Each pending response may be used once.
raise_for_status() -> Response
async def close() -> NoneThe response supports async with and closes its body on exit.
async for chunk in body: ... # bytes
body.text_chunks() -> AsyncIterator[str]
body.lines() -> AsyncIterator[str]
await body.read() -> bytes
await body.text() -> str
await body.json() -> Anytext() and the text iterators use the response Content-Type charset. A missing or unknown
charset defaults to UTF-8, and malformed input uses replacement characters. json() reads JSON
from the response bytes and does not use the text charset.
Headers(headers: HeaderTypes | None = None)
headers[name: str] -> str
headers.get_list(name: str) -> list[str]
headers.multi_items() -> list[tuple[str, str]]Headers is an immutable Mapping[str, str]. It also supports iteration, length, membership,
and the usual mapping methods.
Json(value: Any)Wraps a JSON-compatible value as a request body.
Form(fields: QueryParams)Wraps fields as a form-encoded request body.
class HTTPError(Exception): ...The base class for request and response failures.
class RequestError(HTTPError): ...The original request object.
class TransportError(RequestError): ...A connection or transport failure.
class TimeoutException(TransportError): ...The request exceeded its deadline.
class RequestDenied(RequestError): ...The egress policy refused the request.
The name of the policy that refused the request.
The policy's reason for refusing the request.
class TooManyRedirects(RequestError): ...The request exceeded the redirect limit.
class InvalidRequest(RequestError): ...The client could not build or send the request as supplied.
class ResponseError(HTTPError): ...The original response object.
class HTTPStatusError(ResponseError): ...Raised by Response.raise_for_status() when the status is not successful.
class DecodingError(ResponseError): ...The response body could not be decoded as the requested value.
class ResponseTooLarge(ResponseError): ...The response body exceeded the configured size limit.
The response body limit in bytes.
class BodyError(RuntimeError): ...The base class for body lifecycle errors. It does not carry a request or response.
class BodyConsumed(BodyError): ...The body has already been consumed or a second read has started.
class BodyClosed(BodyError): ...The body was closed before or during consumption.
See HTTP for egress policy and limits, and network for their configuration.
© 2026 pogue.dev. All rights reserved.
CC BY 4.0